{"id":17377125,"url":"https://github.com/HKUDS/LightRAG","last_synced_at":"2025-02-27T06:30:26.406Z","repository":{"id":257827159,"uuid":"866513204","full_name":"HKUDS/LightRAG","owner":"HKUDS","description":"\"LightRAG: Simple and Fast Retrieval-Augmented Generation\"","archived":false,"fork":false,"pushed_at":"2025-02-25T18:40:17.000Z","size":15747,"stargazers_count":12183,"open_issues_count":73,"forks_count":1696,"subscribers_count":109,"default_branch":"main","last_synced_at":"2025-02-25T19:35:27.523Z","etag":null,"topics":["genai","gpt","gpt-4","graphrag","knowledge-graph","large-language-models","llm","rag","retrieval-augmented-generation"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2410.05779","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HKUDS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-02T11:57:54.000Z","updated_at":"2025-02-25T18:40:25.000Z","dependencies_parsed_at":"2024-10-26T09:38:56.712Z","dependency_job_id":"4066555e-f296-42b1-bea2-d7199c87d4db","html_url":"https://github.com/HKUDS/LightRAG","commit_stats":null,"previous_names":["hkuds/lightrag"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FLightRAG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FLightRAG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FLightRAG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FLightRAG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HKUDS","download_url":"https://codeload.github.com/HKUDS/LightRAG/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240989539,"owners_count":19889706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["genai","gpt","gpt-4","graphrag","knowledge-graph","large-language-models","llm","rag","retrieval-augmented-generation"],"created_at":"2024-10-16T05:01:02.348Z","updated_at":"2025-02-27T06:30:26.390Z","avatar_url":"https://github.com/HKUDS.png","language":"Python","funding_links":[],"categories":["LLM Frameworks","🔍 RAG とナレッジ","8. Project Memory \u0026 Knowledge Bases","A01_文本生成_文本对话","Python","**Section 1: RAG, LlamaIndex, and Vector Storage**","2024.10","知识库 RAG","Industry Strength Information Retrieval","Software","Tools","Repos","开源工具","5. Retrieval-Augmented Generation (RAG) \u0026 Knowledge","Open-source repos","6. RAG Pipelines","Knowledge Graphs and Memory","RAG / knowledge system","Orchestration","🏆 القائمة الكاملة Top 200"],"sub_categories":["その他の標準","大语言对话模型及数据","**RAG Solution Design \u0026 Application**","LightRAG【蜘蛛侠】","RAG","Retrieval-Augmented Generation","RAG框架","Rust","Benchmark Reality Check (real-world tool use)"],"readme":"\u003ccenter\u003e\u003ch2\u003e🚀 LightRAG: Simple and Fast Retrieval-Augmented Generation\u003c/h2\u003e\u003c/center\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ctable border=\"0\" width=\"100%\"\u003e\n\u003ctr\u003e\n\u003ctd width=\"100\" align=\"center\"\u003e\n\u003cimg src=\"./assets/logo.png\" width=\"80\" height=\"80\" alt=\"lightrag\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cdiv\u003e\n \u003cp\u003e\n \u003ca href='https://lightrag.github.io'\u003e\u003cimg src='https://img.shields.io/badge/Project-Page-Green'\u003e\u003c/a\u003e\n \u003ca href='https://youtu.be/oageL-1I0GE'\u003e\u003cimg src='https://badges.aleen42.com/src/youtube.svg'\u003e\u003c/a\u003e\n \u003ca href='https://arxiv.org/abs/2410.05779'\u003e\u003cimg src='https://img.shields.io/badge/arXiv-2410.05779-b31b1b'\u003e\u003c/a\u003e\n \u003ca href='https://learnopencv.com/lightrag'\u003e\u003cimg src='https://img.shields.io/badge/LearnOpenCV-blue'\u003e\u003c/a\u003e\n \u003c/p\u003e\n \u003cp\u003e\n \u003cimg src='https://img.shields.io/github/stars/hkuds/lightrag?color=green\u0026style=social' /\u003e\n \u003cimg src=\"https://img.shields.io/badge/python-3.10-blue\"\u003e\n \u003ca href=\"https://pypi.org/project/lightrag-hku/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/lightrag-hku.svg\"\u003e\u003c/a\u003e\n \u003ca href=\"https://pepy.tech/project/lightrag-hku\"\u003e\u003cimg src=\"https://static.pepy.tech/badge/lightrag-hku/month\"\u003e\u003c/a\u003e\n \u003c/p\u003e\n \u003cp\u003e\n \u003ca href='https://discord.gg/yF2MmDJyGJ'\u003e\u003cimg src='https://discordapp.com/api/guilds/1296348098003734629/widget.png?style=shield'\u003e\u003c/a\u003e\n \u003ca href='https://github.com/HKUDS/LightRAG/issues/285'\u003e\u003cimg src='https://img.shields.io/badge/群聊-wechat-green'\u003e\u003c/a\u003e\n \u003c/p\u003e\n\u003c/div\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cdiv align=\"center\"\u003e\nThis repository hosts the code of LightRAG. The structure of this code is based on \u003ca href=\"https://github.com/gusye1234/nano-graphrag\"\u003enano-graphrag\u003c/a\u003e.\n\n\u003cimg src=\"https://i-blog.csdnimg.cn/direct/b2aaf634151b4706892693ffb43d9093.png\" width=\"800\" alt=\"LightRAG Diagram\"\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/br\u003e\n\n\n\u003cdetails\u003e\n \u003csummary style=\"font-size: 1.4em; font-weight: bold; cursor: pointer; display: list-item;\"\u003e\n 🎉 News\n \u003c/summary\u003e\n\n\n- [x] [2025.02.05]🎯📢Our team has released [VideoRAG](https://github.com/HKUDS/VideoRAG) understanding extremely long-context videos.\n- [x] [2025.01.13]🎯📢Our team has released [MiniRAG](https://github.com/HKUDS/MiniRAG) making RAG simpler with small models.\n- [x] [2025.01.06]🎯📢You can now [use PostgreSQL for Storage](#using-postgresql-for-storage).\n- [x] [2024.12.31]🎯📢LightRAG now supports [deletion by document ID](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete).\n- [x] [2024.11.25]🎯📢LightRAG now supports seamless integration of [custom knowledge graphs](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#insert-custom-kg), empowering users to enhance the system with their own domain expertise.\n- [x] [2024.11.19]🎯📢A comprehensive guide to LightRAG is now available on [LearnOpenCV](https://learnopencv.com/lightrag). Many thanks to the blog author.\n- [x] [2024.11.12]🎯📢LightRAG now supports [Oracle Database 23ai for all storage types (KV, vector, and graph)](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_oracle_demo.py).\n- [x] [2024.11.11]🎯📢LightRAG now supports [deleting entities by their names](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete).\n- [x] [2024.11.09]🎯📢Introducing the [LightRAG Gui](https://lightrag-gui.streamlit.app), which allows you to insert, query, visualize, and download LightRAG knowledge.\n- [x] [2024.11.04]🎯📢You can now [use Neo4J for Storage](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#using-neo4j-for-storage).\n- [x] [2024.10.29]🎯📢LightRAG now supports multiple file types, including PDF, DOC, PPT, and CSV via `textract`.\n- [x] [2024.10.20]🎯📢We've added a new feature to LightRAG: Graph Visualization.\n- [x] [2024.10.18]🎯📢We've added a link to a [LightRAG Introduction Video](https://youtu.be/oageL-1I0GE). Thanks to the author!\n- [x] [2024.10.17]🎯📢We have created a [Discord channel](https://discord.gg/yF2MmDJyGJ)! Welcome to join for sharing and discussions! 🎉🎉\n- [x] [2024.10.16]🎯📢LightRAG now supports [Ollama models](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)!\n- [x] [2024.10.15]🎯📢LightRAG now supports [Hugging Face models](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)!\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary style=\"font-size: 1.4em; font-weight: bold; cursor: pointer; display: list-item;\"\u003e\n Algorithm Flowchart\n \u003c/summary\u003e\n\n![LightRAG Indexing Flowchart](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-VectorDB-Json-KV-Store-Indexing-Flowchart-scaled.jpg)\n*Figure 1: LightRAG Indexing Flowchart - Img Caption : [Source](https://learnopencv.com/lightrag/)*\n![LightRAG Retrieval and Querying Flowchart](https://learnopencv.com/wp-content/uploads/2024/11/LightRAG-Querying-Flowchart-Dual-Level-Retrieval-Generation-Knowledge-Graphs-scaled.jpg)\n*Figure 2: LightRAG Retrieval and Querying Flowchart - Img Caption : [Source](https://learnopencv.com/lightrag/)*\n\n\u003c/details\u003e\n\n## Install\n\n* Install from source (Recommend)\n\n```bash\ncd LightRAG\npip install -e .\n```\n* Install from PyPI\n```bash\npip install lightrag-hku\n```\n\n## Quick Start\n* [Video demo](https://www.youtube.com/watch?v=g21royNJ4fw) of running LightRAG locally.\n* All the code can be found in the `examples`.\n* Set OpenAI API key in environment if using OpenAI models: `export OPENAI_API_KEY=\"sk-...\".`\n* Download the demo text \"A Christmas Carol by Charles Dickens\":\n```bash\ncurl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt \u003e ./book.txt\n```\n\n## Query\n\nUse the below Python snippet (in a script) to initialize LightRAG and perform queries:\n\n```python\nimport os\nfrom lightrag import LightRAG, QueryParam\nfrom lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed\n\nrag = LightRAG(\n working_dir=\"your/path\",\n embedding_func=openai_embed,\n llm_model_func=gpt_4o_mini_complete\n)\n\n# Insert text\nrag.insert(\"Your text\")\n\n# Perform naive search\nmode=\"naive\"\n# Perform local search\nmode=\"local\"\n# Perform global search\nmode=\"global\"\n# Perform hybrid search\nmode=\"hybrid\"\n# Mix mode Integrates knowledge graph and vector retrieval.\nmode=\"mix\"\n\nrag.query(\n \"What are the top themes in this story?\",\n param=QueryParam(mode=mode)\n)\n```\n\n### Query Param\n\n```python\nclass QueryParam:\n mode: Literal[\"local\", \"global\", \"hybrid\", \"naive\", \"mix\"] = \"global\"\n \"\"\"Specifies the retrieval mode:\n - \"local\": Focuses on context-dependent information.\n - \"global\": Utilizes global knowledge.\n - \"hybrid\": Combines local and global retrieval methods.\n - \"naive\": Performs a basic search without advanced techniques.\n - \"mix\": Integrates knowledge graph and vector retrieval. Mix mode combines knowledge graph and vector search:\n - Uses both structured (KG) and unstructured (vector) information\n - Provides comprehensive answers by analyzing relationships and context\n - Supports image content through HTML img tags\n - Allows control over retrieval depth via top_k parameter\n \"\"\"\n only_need_context: bool = False\n \"\"\"If True, only returns the retrieved context without generating a response.\"\"\"\n response_type: str = \"Multiple Paragraphs\"\n \"\"\"Defines the response format. Examples: 'Multiple Paragraphs', 'Single Paragraph', 'Bullet Points'.\"\"\"\n top_k: int = 60\n \"\"\"Number of top items to retrieve. Represents entities in 'local' mode and relationships in 'global' mode.\"\"\"\n max_token_for_text_unit: int = 4000\n \"\"\"Maximum number of tokens allowed for each retrieved text chunk.\"\"\"\n max_token_for_global_context: int = 4000\n \"\"\"Maximum number of tokens allocated for relationship descriptions in global retrieval.\"\"\"\n max_token_for_local_context: int = 4000\n \"\"\"Maximum number of tokens allocated for entity descriptions in local retrieval.\"\"\"\n ...\n```\n\n\u003e default value of Top_k can be change by environment variables TOP_K.\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eUsing Open AI-like APIs\u003c/b\u003e \u003c/summary\u003e\n\n* LightRAG also supports Open AI-like chat/embeddings APIs:\n```python\nasync def llm_model_func(\n prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs\n) -\u003e str:\n return await openai_complete_if_cache(\n \"solar-mini\",\n prompt,\n system_prompt=system_prompt,\n history_messages=history_messages,\n api_key=os.getenv(\"UPSTAGE_API_KEY\"),\n base_url=\"https://api.upstage.ai/v1/solar\",\n **kwargs\n )\n\nasync def embedding_func(texts: list[str]) -\u003e np.ndarray:\n return await openai_embed(\n texts,\n model=\"solar-embedding-1-large-query\",\n api_key=os.getenv(\"UPSTAGE_API_KEY\"),\n base_url=\"https://api.upstage.ai/v1/solar\"\n )\n\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=llm_model_func,\n embedding_func=EmbeddingFunc(\n embedding_dim=4096,\n max_token_size=8192,\n func=embedding_func\n )\n)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eUsing Hugging Face Models\u003c/b\u003e \u003c/summary\u003e\n\n* If you want to use Hugging Face models, you only need to set LightRAG as follows:\n\nSee `lightrag_hf_demo.py`\n\n```python\nfrom lightrag.llm import hf_model_complete, hf_embed\nfrom transformers import AutoModel, AutoTokenizer\nfrom lightrag.utils import EmbeddingFunc\n\n# Initialize LightRAG with Hugging Face model\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=hf_model_complete, # Use Hugging Face model for text generation\n llm_model_name='meta-llama/Llama-3.1-8B-Instruct', # Model name from Hugging Face\n # Use Hugging Face embedding function\n embedding_func=EmbeddingFunc(\n embedding_dim=384,\n max_token_size=5000,\n func=lambda texts: hf_embed(\n texts,\n tokenizer=AutoTokenizer.from_pretrained(\"sentence-transformers/all-MiniLM-L6-v2\"),\n embed_model=AutoModel.from_pretrained(\"sentence-transformers/all-MiniLM-L6-v2\")\n )\n ),\n)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eUsing Ollama Models\u003c/b\u003e \u003c/summary\u003e\n\n### Overview\nIf you want to use Ollama models, you need to pull model you plan to use and embedding model, for example `nomic-embed-text`.\n\nThen you only need to set LightRAG as follows:\n\n```python\nfrom lightrag.llm.ollama import ollama_model_complete, ollama_embed\nfrom lightrag.utils import EmbeddingFunc\n\n# Initialize LightRAG with Ollama model\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=ollama_model_complete, # Use Ollama model for text generation\n llm_model_name='your_model_name', # Your model name\n # Use Ollama embedding function\n embedding_func=EmbeddingFunc(\n embedding_dim=768,\n max_token_size=8192,\n func=lambda texts: ollama_embed(\n texts,\n embed_model=\"nomic-embed-text\"\n )\n ),\n)\n```\n\n### Increasing context size\nIn order for LightRAG to work context should be at least 32k tokens. By default Ollama models have context size of 8k. You can achieve this using one of two ways:\n\n#### Increasing the `num_ctx` parameter in Modelfile.\n\n1. Pull the model:\n```bash\nollama pull qwen2\n```\n\n2. Display the model file:\n```bash\nollama show --modelfile qwen2 \u003e Modelfile\n```\n\n3. Edit the Modelfile by adding the following line:\n```bash\nPARAMETER num_ctx 32768\n```\n\n4. Create the modified model:\n```bash\nollama create -f Modelfile qwen2m\n```\n\n#### Setup `num_ctx` via Ollama API.\nTiy can use `llm_model_kwargs` param to configure ollama:\n\n```python\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=ollama_model_complete, # Use Ollama model for text generation\n llm_model_name='your_model_name', # Your model name\n llm_model_kwargs={\"options\": {\"num_ctx\": 32768}},\n # Use Ollama embedding function\n embedding_func=EmbeddingFunc(\n embedding_dim=768,\n max_token_size=8192,\n func=lambda texts: ollama_embedding(\n texts,\n embed_model=\"nomic-embed-text\"\n )\n ),\n)\n```\n#### Low RAM GPUs\n\nIn order to run this experiment on low RAM GPU you should select small model and tune context window (increasing context increase memory consumption). For example, running this ollama example on repurposed mining GPU with 6Gb of RAM required to set context size to 26k while using `gemma2:2b`. It was able to find 197 entities and 19 relations on `book.txt`.\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eLlamaIndex\u003c/b\u003e \u003c/summary\u003e\n\nLightRAG supports integration with LlamaIndex.\n\n1. **LlamaIndex** (`llm/llama_index_impl.py`):\n - Integrates with OpenAI and other providers through LlamaIndex\n - See [LlamaIndex Documentation](lightrag/llm/Readme.md) for detailed setup and examples\n\n### Example Usage\n\n```python\n# Using LlamaIndex with direct OpenAI access\nfrom lightrag import LightRAG\nfrom lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed\nfrom llama_index.embeddings.openai import OpenAIEmbedding\nfrom llama_index.llms.openai import OpenAI\n\nrag = LightRAG(\n working_dir=\"your/path\",\n llm_model_func=llama_index_complete_if_cache, # LlamaIndex-compatible completion function\n embedding_func=EmbeddingFunc( # LlamaIndex-compatible embedding function\n embedding_dim=1536,\n max_token_size=8192,\n func=lambda texts: llama_index_embed(texts, embed_model=embed_model)\n ),\n)\n```\n\n#### For detailed documentation and examples, see:\n- [LlamaIndex Documentation](lightrag/llm/Readme.md)\n- [Direct OpenAI Example](examples/lightrag_llamaindex_direct_demo.py)\n- [LiteLLM Proxy Example](examples/lightrag_llamaindex_litellm_demo.py)\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eConversation History Support\u003c/b\u003e \u003c/summary\u003e\n\nLightRAG now supports multi-turn dialogue through the conversation history feature. Here's how to use it:\n\n```python\nfrom lightrag import LightRAG, QueryParam\n\n# Initialize LightRAG\nrag = LightRAG(working_dir=WORKING_DIR)\n\n# Create conversation history\nconversation_history = [\n {\"role\": \"user\", \"content\": \"What is the main character's attitude towards Christmas?\"},\n {\"role\": \"assistant\", \"content\": \"At the beginning of the story, Ebenezer Scrooge has a very negative attitude towards Christmas...\"},\n {\"role\": \"user\", \"content\": \"How does his attitude change?\"}\n]\n\n# Create query parameters with conversation history\nquery_param = QueryParam(\n mode=\"mix\", # or any other mode: \"local\", \"global\", \"hybrid\"\n conversation_history=conversation_history, # Add the conversation history\n history_turns=3 # Number of recent conversation turns to consider\n)\n\n# Make a query that takes into account the conversation history\nresponse = rag.query(\n \"What causes this change in his character?\",\n param=query_param\n)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eCustom Prompt Support\u003c/b\u003e \u003c/summary\u003e\n\nLightRAG now supports custom prompts for fine-tuned control over the system's behavior. Here's how to use it:\n\n```python\nfrom lightrag import LightRAG, QueryParam\n\n# Initialize LightRAG\nrag = LightRAG(working_dir=WORKING_DIR)\n\n# Create query parameters\nquery_param = QueryParam(\n mode=\"hybrid\", # or other mode: \"local\", \"global\", \"hybrid\", \"mix\" and \"naive\"\n)\n\n# Example 1: Using the default system prompt\nresponse_default = rag.query(\n \"What are the primary benefits of renewable energy?\",\n param=query_param\n)\nprint(response_default)\n\n# Example 2: Using a custom prompt\ncustom_prompt = \"\"\"\nYou are an expert assistant in environmental science. Provide detailed and structured answers with examples.\n---Conversation History---\n{history}\n\n---Knowledge Base---\n{context_data}\n\n---Response Rules---\n\n- Target format and length: {response_type}\n\"\"\"\nresponse_custom = rag.query(\n \"What are the primary benefits of renewable energy?\",\n param=query_param,\n system_prompt=custom_prompt # Pass the custom prompt\n)\nprint(response_custom)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eSeparate Keyword Extraction\u003c/b\u003e \u003c/summary\u003e\n\nWe've introduced a new function `query_with_separate_keyword_extraction` to enhance the keyword extraction capabilities. This function separates the keyword extraction process from the user's prompt, focusing solely on the query to improve the relevance of extracted keywords.\n\n##### How It Works?\nThe function operates by dividing the input into two parts:\n- `User Query`\n- `Prompt`\n\nIt then performs keyword extraction exclusively on the `user query`. This separation ensures that the extraction process is focused and relevant, unaffected by any additional language in the `prompt`. It also allows the `prompt` to serve purely for response formatting, maintaining the intent and clarity of the user's original question.\n\n##### Usage Example\nThis `example` shows how to tailor the function for educational content, focusing on detailed explanations for older students.\n\n```python\nrag.query_with_separate_keyword_extraction(\n query=\"Explain the law of gravity\",\n prompt=\"Provide a detailed explanation suitable for high school students studying physics.\",\n param=QueryParam(mode=\"hybrid\")\n)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eInsert Custom KG\u003c/b\u003e \u003c/summary\u003e\n\n```python\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=llm_model_func,\n embedding_func=EmbeddingFunc(\n embedding_dim=embedding_dimension,\n max_token_size=8192,\n func=embedding_func,\n ),\n)\n\ncustom_kg = {\n \"entities\": [\n {\n \"entity_name\": \"CompanyA\",\n \"entity_type\": \"Organization\",\n \"description\": \"A major technology company\",\n \"source_id\": \"Source1\"\n },\n {\n \"entity_name\": \"ProductX\",\n \"entity_type\": \"Product\",\n \"description\": \"A popular product developed by CompanyA\",\n \"source_id\": \"Source1\"\n }\n ],\n \"relationships\": [\n {\n \"src_id\": \"CompanyA\",\n \"tgt_id\": \"ProductX\",\n \"description\": \"CompanyA develops ProductX\",\n \"keywords\": \"develop, produce\",\n \"weight\": 1.0,\n \"source_id\": \"Source1\"\n }\n ],\n \"chunks\": [\n {\n \"content\": \"ProductX, developed by CompanyA, has revolutionized the market with its cutting-edge features.\",\n \"source_id\": \"Source1\",\n },\n {\n \"content\": \"PersonA is a prominent researcher at UniversityB, focusing on artificial intelligence and machine learning.\",\n \"source_id\": \"Source2\",\n },\n {\n \"content\": \"None\",\n \"source_id\": \"UNKNOWN\",\n },\n ],\n}\n\nrag.insert_custom_kg(custom_kg)\n```\n\u003c/details\u003e\n\n## Insert\n\n#### Basic Insert\n\n```python\n# Basic Insert\nrag.insert(\"Text\")\n```\n\n\u003cdetails\u003e\n \u003csummary\u003e \u003cb\u003e Batch Insert \u003c/b\u003e\u003c/summary\u003e\n\n```python\n# Basic Batch Insert: Insert multiple texts at once\nrag.insert([\"TEXT1\", \"TEXT2\",...])\n\n# Batch Insert with custom batch size configuration\nrag = LightRAG(\n working_dir=WORKING_DIR,\n addon_params={\n \"insert_batch_size\": 20 # Process 20 documents per batch\n }\n)\nrag.insert([\"TEXT1\", \"TEXT2\", \"TEXT3\", ...]) # Documents will be processed in batches of 20\n```\n\nThe `insert_batch_size` parameter in `addon_params` controls how many documents are processed in each batch during insertion. This is useful for:\n- Managing memory usage with large document collections\n- Optimizing processing speed\n- Providing better progress tracking\n- Default value is 10 if not specified\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003e \u003cb\u003e Insert with ID \u003c/b\u003e\u003c/summary\u003e\n\nIf you want to provide your own IDs for your documents, number of documents and number of IDs must be the same.\n\n```python\n# Insert single text, and provide ID for it\nrag.insert(\"TEXT1\", ids=[\"ID_FOR_TEXT1\"])\n\n# Insert multiple texts, and provide IDs for them\nrag.insert([\"TEXT1\", \"TEXT2\",...], ids=[\"ID_FOR_TEXT1\", \"ID_FOR_TEXT2\"])\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003e\u003cb\u003eIncremental Insert\u003c/b\u003e\u003c/summary\u003e\n\n```python\n# Incremental Insert: Insert new documents into an existing LightRAG instance\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=llm_model_func,\n embedding_func=EmbeddingFunc(\n embedding_dim=embedding_dimension,\n max_token_size=8192,\n func=embedding_func,\n ),\n)\n\nwith open(\"./newText.txt\") as f:\n rag.insert(f.read())\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003e\u003cb\u003eInsert using Pipeline\u003c/b\u003e\u003c/summary\u003e\n\nThe `apipeline_enqueue_documents` and `apipeline_process_enqueue_documents` functions allow you to perform incremental insertion of documents into the graph.\n\nThis is useful for scenarios where you want to process documents in the background while still allowing the main thread to continue executing.\n\nAnd using a routine to process news documents.\n\n```python\nrag = LightRAG(..)\nawait rag.apipeline_enqueue_documents(input)\n# Your routine in loop\nawait rag.apipeline_process_enqueue_documents(input)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003e\u003cb\u003eInsert Multi-file Type Support\u003c/b\u003e\u003c/summary\u003e\n\nThe `textract` supports reading file types such as TXT, DOCX, PPTX, CSV, and PDF.\n\n```python\nimport textract\n\nfile_path = 'TEXT.pdf'\ntext_content = textract.process(file_path)\n\nrag.insert(text_content.decode('utf-8'))\n```\n\u003c/details\u003e\n\n## Storage\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eUsing Neo4J for Storage\u003c/b\u003e \u003c/summary\u003e\n\n* For production level scenarios you will most likely want to leverage an enterprise solution\n* for KG storage. Running Neo4J in Docker is recommended for seamless local testing.\n* See: https://hub.docker.com/_/neo4j\n\n```python\nexport NEO4J_URI=\"neo4j://localhost:7687\"\nexport NEO4J_USERNAME=\"neo4j\"\nexport NEO4J_PASSWORD=\"password\"\n\n# When you launch the project be sure to override the default KG: NetworkX\n# by specifying kg=\"Neo4JStorage\".\n\n# Note: Default settings use NetworkX\n# Initialize LightRAG with Neo4J implementation.\nWORKING_DIR = \"./local_neo4jWorkDir\"\n\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=gpt_4o_mini_complete, # Use gpt_4o_mini_complete LLM model\n graph_storage=\"Neo4JStorage\", #\u003c-----------override KG default\n log_level=\"DEBUG\" #\u003c-----------override log_level default\n)\n```\nsee test_neo4j.py for a working example.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eUsing PostgreSQL for Storage\u003c/b\u003e \u003c/summary\u003e\n\nFor production level scenarios you will most likely want to leverage an enterprise solution. PostgreSQL can provide a one-stop solution for you as KV store, VectorDB (pgvector) and GraphDB (apache AGE).\n* PostgreSQL is lightweight,the whole binary distribution including all necessary plugins can be zipped to 40MB: Ref to [Windows Release](https://github.com/ShanGor/apache-age-windows/releases/tag/PG17%2Fv1.5.0-rc0) as it is easy to install for Linux/Mac.\n* If you prefer docker, please start with this image if you are a beginner to avoid hiccups (DO read the overview): https://hub.docker.com/r/shangor/postgres-for-rag\n* How to start? Ref to: [examples/lightrag_zhipu_postgres_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_zhipu_postgres_demo.py)\n* Create index for AGE example: (Change below `dickens` to your graph name if necessary)\n ```sql\n load 'age';\n SET search_path = ag_catalog, \"$user\", public;\n CREATE INDEX CONCURRENTLY entity_p_idx ON dickens.\"Entity\" (id);\n CREATE INDEX CONCURRENTLY vertex_p_idx ON dickens.\"_ag_label_vertex\" (id);\n CREATE INDEX CONCURRENTLY directed_p_idx ON dickens.\"DIRECTED\" (id);\n CREATE INDEX CONCURRENTLY directed_eid_idx ON dickens.\"DIRECTED\" (end_id);\n CREATE INDEX CONCURRENTLY directed_sid_idx ON dickens.\"DIRECTED\" (start_id);\n CREATE INDEX CONCURRENTLY directed_seid_idx ON dickens.\"DIRECTED\" (start_id,end_id);\n CREATE INDEX CONCURRENTLY edge_p_idx ON dickens.\"_ag_label_edge\" (id);\n CREATE INDEX CONCURRENTLY edge_sid_idx ON dickens.\"_ag_label_edge\" (start_id);\n CREATE INDEX CONCURRENTLY edge_eid_idx ON dickens.\"_ag_label_edge\" (end_id);\n CREATE INDEX CONCURRENTLY edge_seid_idx ON dickens.\"_ag_label_edge\" (start_id,end_id);\n create INDEX CONCURRENTLY vertex_idx_node_id ON dickens.\"_ag_label_vertex\" (ag_catalog.agtype_access_operator(properties, '\"node_id\"'::agtype));\n create INDEX CONCURRENTLY entity_idx_node_id ON dickens.\"Entity\" (ag_catalog.agtype_access_operator(properties, '\"node_id\"'::agtype));\n CREATE INDEX CONCURRENTLY entity_node_id_gin_idx ON dickens.\"Entity\" using gin(properties);\n ALTER TABLE dickens.\"DIRECTED\" CLUSTER ON directed_sid_idx;\n\n -- drop if necessary\n drop INDEX entity_p_idx;\n drop INDEX vertex_p_idx;\n drop INDEX directed_p_idx;\n drop INDEX directed_eid_idx;\n drop INDEX directed_sid_idx;\n drop INDEX directed_seid_idx;\n drop INDEX edge_p_idx;\n drop INDEX edge_sid_idx;\n drop INDEX edge_eid_idx;\n drop INDEX edge_seid_idx;\n drop INDEX vertex_idx_node_id;\n drop INDEX entity_idx_node_id;\n drop INDEX entity_node_id_gin_idx;\n ```\n* Known issue of the Apache AGE: The released versions got below issue:\n \u003e You might find that the properties of the nodes/edges are empty.\n \u003e It is a known issue of the release version: https://github.com/apache/age/pull/1721\n \u003e\n \u003e You can Compile the AGE from source code and fix it.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eUsing Faiss for Storage\u003c/b\u003e \u003c/summary\u003e\n\n- Install the required dependencies:\n```\npip install faiss-cpu\n```\nYou can also install `faiss-gpu` if you have GPU support.\n\n- Here we are using `sentence-transformers` but you can also use `OpenAIEmbedding` model with `3072` dimensions.\n\n```\nasync def embedding_func(texts: list[str]) -\u003e np.ndarray:\n model = SentenceTransformer('all-MiniLM-L6-v2')\n embeddings = model.encode(texts, convert_to_numpy=True)\n return embeddings\n\n# Initialize LightRAG with the LLM model function and embedding function\n rag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=llm_model_func,\n embedding_func=EmbeddingFunc(\n embedding_dim=384,\n max_token_size=8192,\n func=embedding_func,\n ),\n vector_storage=\"FaissVectorDBStorage\",\n vector_db_storage_cls_kwargs={\n \"cosine_better_than_threshold\": 0.3 # Your desired threshold\n }\n )\n```\n\n\u003c/details\u003e\n\n## Delete\n\n```python\n\nrag = LightRAG(\n working_dir=WORKING_DIR,\n llm_model_func=llm_model_func,\n embedding_func=EmbeddingFunc(\n embedding_dim=embedding_dimension,\n max_token_size=8192,\n func=embedding_func,\n ),\n)\n\n# Delete Entity: Deleting entities by their names\nrag.delete_by_entity(\"Project Gutenberg\")\n\n# Delete Document: Deleting entities and relationships associated with the document by doc id\nrag.delete_by_doc_id(\"doc_id\")\n```\n\n## LightRAG init parameters\n\n\u003cdetails\u003e\n\u003csummary\u003e Parameters \u003c/summary\u003e\n\n| **Parameter** | **Type** | **Explanation** | **Default** |\n|----------------------------------------------| --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|\n| **working\\_dir** | `str` | Directory where the cache will be stored | `lightrag_cache+timestamp` |\n| **kv\\_storage** | `str` | Storage type for documents and text chunks. Supported types: `JsonKVStorage`, `OracleKVStorage` | `JsonKVStorage` |\n| **vector\\_storage** | `str` | Storage type for embedding vectors. Supported types: `NanoVectorDBStorage`, `OracleVectorDBStorage` | `NanoVectorDBStorage` |\n| **graph\\_storage** | `str` | Storage type for graph edges and nodes. Supported types: `NetworkXStorage`, `Neo4JStorage`, `OracleGraphStorage` | `NetworkXStorage` |\n| **log\\_level** | | Log level for application runtime | `logging.DEBUG` |\n| **chunk\\_token\\_size** | `int` | Maximum token size per chunk when splitting documents | `1200` |\n| **chunk\\_overlap\\_token\\_size** | `int` | Overlap token size between two chunks when splitting documents | `100` |\n| **tiktoken\\_model\\_name** | `str` | Model name for the Tiktoken encoder used to calculate token numbers | `gpt-4o-mini` |\n| **entity\\_extract\\_max\\_gleaning** | `int` | Number of loops in the entity extraction process, appending history messages | `1` |\n| **entity\\_summary\\_to\\_max\\_tokens** | `int` | Maximum token size for each entity summary | `500` |\n| **node\\_embedding\\_algorithm** | `str` | Algorithm for node embedding (currently not used) | `node2vec` |\n| **node2vec\\_params** | `dict` | Parameters for node embedding | `{\"dimensions\": 1536,\"num_walks\": 10,\"walk_length\": 40,\"window_size\": 2,\"iterations\": 3,\"random_seed\": 3,}` |\n| **embedding\\_func** | `EmbeddingFunc` | Function to generate embedding vectors from text | `openai_embed` |\n| **embedding\\_batch\\_num** | `int` | Maximum batch size for embedding processes (multiple texts sent per batch) | `32` |\n| **embedding\\_func\\_max\\_async** | `int` | Maximum number of concurrent asynchronous embedding processes | `16` |\n| **llm\\_model\\_func** | `callable` | Function for LLM generation | `gpt_4o_mini_complete` |\n| **llm\\_model\\_name** | `str` | LLM model name for generation | `meta-llama/Llama-3.2-1B-Instruct` |\n| **llm\\_model\\_max\\_token\\_size** | `int` | Maximum token size for LLM generation (affects entity relation summaries) | `32768`（default value changed by env var MAX_TOKENS) |\n| **llm\\_model\\_max\\_async** | `int` | Maximum number of concurrent asynchronous LLM processes | `16`（default value changed by env var MAX_ASYNC) |\n| **llm\\_model\\_kwargs** | `dict` | Additional parameters for LLM generation | |\n| **vector\\_db\\_storage\\_cls\\_kwargs** | `dict` | Additional parameters for vector database, like setting the threshold for nodes and relations retrieval. | cosine_better_than_threshold: 0.2（default value changed by env var COSINE_THRESHOLD) |\n| **enable\\_llm\\_cache** | `bool` | If `TRUE`, stores LLM results in cache; repeated prompts return cached responses | `TRUE` |\n| **enable\\_llm\\_cache\\_for\\_entity\\_extract** | `bool` | If `TRUE`, stores LLM results in cache for entity extraction; Good for beginners to debug your application | `TRUE` |\n| **addon\\_params** | `dict` | Additional parameters, e.g., `{\"example_number\": 1, \"language\": \"Simplified Chinese\", \"entity_types\": [\"organization\", \"person\", \"geo\", \"event\"], \"insert_batch_size\": 10}`: sets example limit, output language, and batch size for document processing | `example_number: all examples, language: English, insert_batch_size: 10` |\n| **convert\\_response\\_to\\_json\\_func** | `callable` | Not used | `convert_response_to_json` |\n| **embedding\\_cache\\_config** | `dict` | Configuration for question-answer caching. Contains three parameters:\u003cbr\u003e- `enabled`: Boolean value to enable/disable cache lookup functionality. When enabled, the system will check cached responses before generating new answers.\u003cbr\u003e- `similarity_threshold`: Float value (0-1), similarity threshold. When a new question's similarity with a cached question exceeds this threshold, the cached answer will be returned directly without calling the LLM.\u003cbr\u003e- `use_llm_check`: Boolean value to enable/disable LLM similarity verification. When enabled, LLM will be used as a secondary check to verify the similarity between questions before returning cached answers. | Default: `{\"enabled\": False, \"similarity_threshold\": 0.95, \"use_llm_check\": False}` |\n|**log\\_dir** | `str` | Directory to store logs. | `./` |\n\n\u003c/details\u003e\n\n## Error Handling\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to view error handling details\u003c/summary\u003e\n\nThe API includes comprehensive error handling:\n- File not found errors (404)\n- Processing errors (500)\n- Supports multiple file encodings (UTF-8 and GBK)\n\u003c/details\u003e\n\n## API\nLightRag can be installed with API support to serve a Fast api interface to perform data upload and indexing/Rag operations/Rescan of the input folder etc..\n\n[LightRag API](lightrag/api/README.md)\n\n## Graph Visualization\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eGraph visualization with html\u003c/b\u003e \u003c/summary\u003e\n\n* The following code can be found in `examples/graph_visual_with_html.py`\n\n```python\nimport networkx as nx\nfrom pyvis.network import Network\n\n# Load the GraphML file\nG = nx.read_graphml('./dickens/graph_chunk_entity_relation.graphml')\n\n# Create a Pyvis network\nnet = Network(notebook=True)\n\n# Convert NetworkX graph to Pyvis network\nnet.from_nx(G)\n\n# Save and display the network\nnet.show('knowledge_graph.html')\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eGraph visualization with Neo4\u003c/b\u003e \u003c/summary\u003e\n\n\n* The following code can be found in `examples/graph_visual_with_neo4j.py`\n\n```python\nimport os\nimport json\nfrom lightrag.utils import xml_to_json\nfrom neo4j import GraphDatabase\n\n# Constants\nWORKING_DIR = \"./dickens\"\nBATCH_SIZE_NODES = 500\nBATCH_SIZE_EDGES = 100\n\n# Neo4j connection credentials\nNEO4J_URI = \"bolt://localhost:7687\"\nNEO4J_USERNAME = \"neo4j\"\nNEO4J_PASSWORD = \"your_password\"\n\ndef convert_xml_to_json(xml_path, output_path):\n \"\"\"Converts XML file to JSON and saves the output.\"\"\"\n if not os.path.exists(xml_path):\n print(f\"Error: File not found - {xml_path}\")\n return None\n\n json_data = xml_to_json(xml_path)\n if json_data:\n with open(output_path, 'w', encoding='utf-8') as f:\n json.dump(json_data, f, ensure_ascii=False, indent=2)\n print(f\"JSON file created: {output_path}\")\n return json_data\n else:\n print(\"Failed to create JSON data\")\n return None\n\ndef process_in_batches(tx, query, data, batch_size):\n \"\"\"Process data in batches and execute the given query.\"\"\"\n for i in range(0, len(data), batch_size):\n batch = data[i:i + batch_size]\n tx.run(query, {\"nodes\": batch} if \"nodes\" in query else {\"edges\": batch})\n\ndef main():\n # Paths\n xml_file = os.path.join(WORKING_DIR, 'graph_chunk_entity_relation.graphml')\n json_file = os.path.join(WORKING_DIR, 'graph_data.json')\n\n # Convert XML to JSON\n json_data = convert_xml_to_json(xml_file, json_file)\n if json_data is None:\n return\n\n # Load nodes and edges\n nodes = json_data.get('nodes', [])\n edges = json_data.get('edges', [])\n\n # Neo4j queries\n create_nodes_query = \"\"\"\n UNWIND $nodes AS node\n MERGE (e:Entity {id: node.id})\n SET e.entity_type = node.entity_type,\n e.description = node.description,\n e.source_id = node.source_id,\n e.displayName = node.id\n REMOVE e:Entity\n WITH e, node\n CALL apoc.create.addLabels(e, [node.entity_type]) YIELD node AS labeledNode\n RETURN count(*)\n \"\"\"\n\n create_edges_query = \"\"\"\n UNWIND $edges AS edge\n MATCH (source {id: edge.source})\n MATCH (target {id: edge.target})\n WITH source, target, edge,\n CASE\n WHEN edge.keywords CONTAINS 'lead' THEN 'lead'\n WHEN edge.keywords CONTAINS 'participate' THEN 'participate'\n WHEN edge.keywords CONTAINS 'uses' THEN 'uses'\n WHEN edge.keywords CONTAINS 'located' THEN 'located'\n WHEN edge.keywords CONTAINS 'occurs' THEN 'occurs'\n ELSE REPLACE(SPLIT(edge.keywords, ',')[0], '\\\"', '')\n END AS relType\n CALL apoc.create.relationship(source, relType, {\n weight: edge.weight,\n description: edge.description,\n keywords: edge.keywords,\n source_id: edge.source_id\n }, target) YIELD rel\n RETURN count(*)\n \"\"\"\n\n set_displayname_and_labels_query = \"\"\"\n MATCH (n)\n SET n.displayName = n.id\n WITH n\n CALL apoc.create.setLabels(n, [n.entity_type]) YIELD node\n RETURN count(*)\n \"\"\"\n\n # Create a Neo4j driver\n driver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USERNAME, NEO4J_PASSWORD))\n\n try:\n # Execute queries in batches\n with driver.session() as session:\n # Insert nodes in batches\n session.execute_write(process_in_batches, create_nodes_query, nodes, BATCH_SIZE_NODES)\n\n # Insert edges in batches\n session.execute_write(process_in_batches, create_edges_query, edges, BATCH_SIZE_EDGES)\n\n # Set displayName and labels\n session.run(set_displayname_and_labels_query)\n\n except Exception as e:\n print(f\"Error occurred: {e}\")\n\n finally:\n driver.close()\n\nif __name__ == \"__main__\":\n main()\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cb\u003eGraphml 3d visualizer\u003c/b\u003e \u003c/summary\u003e\n\nLightRag can be installed with Tools support to add extra tools like the graphml 3d visualizer.\n\n[LightRag Visualizer](lightrag/tools/lightrag_visualizer/README.md)\n\n\u003c/details\u003e\n\n## Evaluation\n### Dataset\nThe dataset used in LightRAG can be downloaded from [TommyChien/UltraDomain](https://huggingface.co/datasets/TommyChien/UltraDomain).\n\n### Generate Query\nLightRAG uses the following prompt to generate high-level queries, with the corresponding code in `example/generate_query.py`.\n\n\u003cdetails\u003e\n\u003csummary\u003e Prompt \u003c/summary\u003e\n\n```python\nGiven the following description of a dataset:\n\n{description}\n\nPlease identify 5 potential users who would engage with this dataset. For each user, list 5 tasks they would perform with this dataset. Then, for each (user, task) combination, generate 5 questions that require a high-level understanding of the entire dataset.\n\nOutput the results in the following structure:\n- User 1: [user description]\n - Task 1: [task description]\n - Question 1:\n - Question 2:\n - Question 3:\n - Question 4:\n - Question 5:\n - Task 2: [task description]\n ...\n - Task 5: [task description]\n- User 2: [user description]\n ...\n- User 5: [user description]\n ...\n```\n\u003c/details\u003e\n\n### Batch Eval\nTo evaluate the performance of two RAG systems on high-level queries, LightRAG uses the following prompt, with the specific code available in `example/batch_eval.py`.\n\n\u003cdetails\u003e\n\u003csummary\u003e Prompt \u003c/summary\u003e\n\n```python\n---Role---\nYou are an expert tasked with evaluating two answers to the same question based on three criteria: **Comprehensiveness**, **Diversity**, and **Empowerment**.\n---Goal---\nYou will evaluate two answers to the same question based on three criteria: **Comprehensiveness**, **Diversity**, and **Empowerment**.\n\n- **Comprehensiveness**: How much detail does the answer provide to cover all aspects and details of the question?\n- **Diversity**: How varied and rich is the answer in providing different perspectives and insights on the question?\n- **Empowerment**: How well does the answer help the reader understand and make informed judgments about the topic?\n\nFor each criterion, choose the better answer (either Answer 1 or Answer 2) and explain why. Then, select an overall winner based on these three categories.\n\nHere is the question:\n{query}\n\nHere are the two answers:\n\n**Answer 1:**\n{answer1}\n\n**Answer 2:**\n{answer2}\n\nEvaluate both answers using the three criteria listed above and provide detailed explanations for each criterion.\n\nOutput your evaluation in the following JSON format:\n\n{{\n \"Comprehensiveness\": {{\n \"Winner\": \"[Answer 1 or Answer 2]\",\n \"Explanation\": \"[Provide explanation here]\"\n }},\n \"Empowerment\": {{\n \"Winner\": \"[Answer 1 or Answer 2]\",\n \"Explanation\": \"[Provide explanation here]\"\n }},\n \"Overall Winner\": {{\n \"Winner\": \"[Answer 1 or Answer 2]\",\n \"Explanation\": \"[Summarize why this answer is the overall winner based on the three criteria]\"\n }}\n}}\n```\n\u003c/details\u003e\n\n### Overall Performance Table\n\n| | **Agriculture** | | **CS** | | **Legal** | | **Mix** | |\n|----------------------|-------------------------|-----------------------|-----------------------|-----------------------|-----------------------|-----------------------|-----------------------|-----------------------|\n| | NaiveRAG | **LightRAG** | NaiveRAG | **LightRAG** | NaiveRAG | **LightRAG** | NaiveRAG | **LightRAG** |\n| **Comprehensiveness** | 32.4% | **67.6%** | 38.4% | **61.6%** | 16.4% | **83.6%** | 38.8% | **61.2%** |\n| **Diversity** | 23.6% | **76.4%** | 38.0% | **62.0%** | 13.6% | **86.4%** | 32.4% | **67.6%** |\n| **Empowerment** | 32.4% | **67.6%** | 38.8% | **61.2%** | 16.4% | **83.6%** | 42.8% | **57.2%** |\n| **Overall** | 32.4% | **67.6%** | 38.8% | **61.2%** | 15.2% | **84.8%** | 40.0% | **60.0%** |\n| | RQ-RAG | **LightRAG** | RQ-RAG | **LightRAG** | RQ-RAG | **LightRAG** | RQ-RAG | **LightRAG** |\n| **Comprehensiveness** | 31.6% | **68.4%** | 38.8% | **61.2%** | 15.2% | **84.8%** | 39.2% | **60.8%** |\n| **Diversity** | 29.2% | **70.8%** | 39.2% | **60.8%** | 11.6% | **88.4%** | 30.8% | **69.2%** |\n| **Empowerment** | 31.6% | **68.4%** | 36.4% | **63.6%** | 15.2% | **84.8%** | 42.4% | **57.6%** |\n| **Overall** | 32.4% | **67.6%** | 38.0% | **62.0%** | 14.4% | **85.6%** | 40.0% | **60.0%** |\n| | HyDE | **LightRAG** | HyDE | **LightRAG** | HyDE | **LightRAG** | HyDE | **LightRAG** |\n| **Comprehensiveness** | 26.0% | **74.0%** | 41.6% | **58.4%** | 26.8% | **73.2%** | 40.4% | **59.6%** |\n| **Diversity** | 24.0% | **76.0%** | 38.8% | **61.2%** | 20.0% | **80.0%** | 32.4% | **67.6%** |\n| **Empowerment** | 25.2% | **74.8%** | 40.8% | **59.2%** | 26.0% | **74.0%** | 46.0% | **54.0%** |\n| **Overall** | 24.8% | **75.2%** | 41.6% | **58.4%** | 26.4% | **73.6%** | 42.4% | **57.6%** |\n| | GraphRAG | **LightRAG** | GraphRAG | **LightRAG** | GraphRAG | **LightRAG** | GraphRAG | **LightRAG** |\n| **Comprehensiveness** | 45.6% | **54.4%** | 48.4% | **51.6%** | 48.4% | **51.6%** | **50.4%** | 49.6% |\n| **Diversity** | 22.8% | **77.2%** | 40.8% | **59.2%** | 26.4% | **73.6%** | 36.0% | **64.0%** |\n| **Empowerment** | 41.2% | **58.8%** | 45.2% | **54.8%** | 43.6% | **56.4%** | **50.8%** | 49.2% |\n| **Overall** | 45.2% | **54.8%** | 48.0% | **52.0%** | 47.2% | **52.8%** | **50.4%** | 49.6% |\n\n## Reproduce\nAll the code can be found in the `./reproduce` directory.\n\n### Step-0 Extract Unique Contexts\nFirst, we need to extract unique contexts in the datasets.\n\n\u003cdetails\u003e\n\u003csummary\u003e Code \u003c/summary\u003e\n\n```python\ndef extract_unique_contexts(input_directory, output_directory):\n\n os.makedirs(output_directory, exist_ok=True)\n\n jsonl_files = glob.glob(os.path.join(input_directory, '*.jsonl'))\n print(f\"Found {len(jsonl_files)} JSONL files.\")\n\n for file_path in jsonl_files:\n filename = os.path.basename(file_path)\n name, ext = os.path.splitext(filename)\n output_filename = f\"{name}_unique_contexts.json\"\n output_path = os.path.join(output_directory, output_filename)\n\n unique_contexts_dict = {}\n\n print(f\"Processing file: {filename}\")\n\n try:\n with open(file_path, 'r', encoding='utf-8') as infile:\n for line_number, line in enumerate(infile, start=1):\n line = line.strip()\n if not line:\n continue\n try:\n json_obj = json.loads(line)\n context = json_obj.get('context')\n if context and context not in unique_contexts_dict:\n unique_contexts_dict[context] = None\n except json.JSONDecodeError as e:\n print(f\"JSON decoding error in file {filename} at line {line_number}: {e}\")\n except FileNotFoundError:\n print(f\"File not found: {filename}\")\n continue\n except Exception as e:\n print(f\"An error occurred while processing file {filename}: {e}\")\n continue\n\n unique_contexts_list = list(unique_contexts_dict.keys())\n print(f\"There are {len(unique_contexts_list)} unique `context` entries in the file {filename}.\")\n\n try:\n with open(output_path, 'w', encoding='utf-8') as outfile:\n json.dump(unique_contexts_list, outfile, ensure_ascii=False, indent=4)\n print(f\"Unique `context` entries have been saved to: {output_filename}\")\n except Exception as e:\n print(f\"An error occurred while saving to the file {output_filename}: {e}\")\n\n print(\"All files have been processed.\")\n\n```\n\u003c/details\u003e\n\n### Step-1 Insert Contexts\nFor the extracted contexts, we insert them into the LightRAG system.\n\n\u003cdetails\u003e\n\u003csummary\u003e Code \u003c/summary\u003e\n\n```python\ndef insert_text(rag, file_path):\n with open(file_path, mode='r') as f:\n unique_contexts = json.load(f)\n\n retries = 0\n max_retries = 3\n while retries \u003c max_retries:\n try:\n rag.insert(unique_contexts)\n break\n except Exception as e:\n retries += 1\n print(f\"Insertion failed, retrying ({retries}/{max_retries}), error: {e}\")\n time.sleep(10)\n if retries == max_retries:\n print(\"Insertion failed after exceeding the maximum number of retries\")\n```\n\u003c/details\u003e\n\n### Step-2 Generate Queries\n\nWe extract tokens from the first and the second half of each context in the dataset, then combine them as dataset descriptions to generate queries.\n\n\u003cdetails\u003e\n\u003csummary\u003e Code \u003c/summary\u003e\n\n```python\ntokenizer = GPT2Tokenizer.from_pretrained('gpt2')\n\ndef get_summary(context, tot_tokens=2000):\n tokens = tokenizer.tokenize(context)\n half_tokens = tot_tokens // 2\n\n start_tokens = tokens[1000:1000 + half_tokens]\n end_tokens = tokens[-(1000 + half_tokens):1000]\n\n summary_tokens = start_tokens + end_tokens\n summary = tokenizer.convert_tokens_to_string(summary_tokens)\n\n return summary\n```\n\u003c/details\u003e\n\n### Step-3 Query\nFor the queries generated in Step-2, we will extract them and query LightRAG.\n\n\u003cdetails\u003e\n\u003csummary\u003e Code \u003c/summary\u003e\n\n```python\ndef extract_queries(file_path):\n with open(file_path, 'r') as f:\n data = f.read()\n\n data = data.replace('**', '')\n\n queries = re.findall(r'- Question \\d+: (.+)', data)\n\n return queries\n```\n\u003c/details\u003e\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#HKUDS/LightRAG\u0026Date\"\u003e\n \u003cpicture\u003e\n \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=HKUDS/LightRAG\u0026type=Date\u0026theme=dark\" /\u003e\n \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=HKUDS/LightRAG\u0026type=Date\" /\u003e\n \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=HKUDS/LightRAG\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## Contribution\n\nThank you to all our contributors!\n\n\u003ca href=\"https://github.com/HKUDS/LightRAG/graphs/contributors\"\u003e\n \u003cimg src=\"https://contrib.rocks/image?repo=HKUDS/LightRAG\" /\u003e\n\u003c/a\u003e\n\n## 🌟Citation\n\n```python\n@article{guo2024lightrag,\ntitle={LightRAG: Simple and Fast Retrieval-Augmented Generation},\nauthor={Zirui Guo and Lianghao Xia and Yanhua Yu and Tu Ao and Chao Huang},\nyear={2024},\neprint={2410.05779},\narchivePrefix={arXiv},\nprimaryClass={cs.IR}\n}\n```\n**Thank you for your interest in our work!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHKUDS%2FLightRAG","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHKUDS%2FLightRAG","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHKUDS%2FLightRAG/lists"}