HKUDS/LightRAG

## 🎉 新闻 - [2025.11]🎯[新功能]: 集成 **RAGAS 用于评估** 和 **Langfuse 用于追踪**。更新了 API 以在查询结果中返回检索到的上下文，以支持上下文精度指标。 - [2025.10]🎯[扩展性增强]: 消除了处理瓶颈，以**高效支持大规模数据集**。 - [2025.09]🎯[新功能] 提高了 **开源 LLMs**（如 Qwen3-30B-A3B）的知识图谱提取准确性。 - [2025.08]🎯[新功能] 现已支持 **Reranker**，显著提升了混合查询的性能（设置为默认查询模式）。 - [2025.08]🎯[新功能] 增加了**文档删除**功能，并自动重新生成 KG 以确保最佳的查询性能。 - [2025.06]🎯[新发布] 我们的团队发布了 [RAG-Anything](https://github.com/HKUDS/RAG-Anything) —— 一个**多模态 RAG 一站式系统**，用于无缝处理文本、图像、表格和公式。 - [2025.06]🎯[新功能] LightRAG 现在通过 [RAG-Anything](https://github.com/HKUDS/RAG-Anything) 集成支持全面的多模态数据处理，实现了跨多种格式（包括 PDF、图像、Office 文档、表格和公式）的无缝文档解析和 RAG 能力。详情请参阅新的[多模态部分](https://github.com/HKUDS/LightRAG/?tab=readme-ov-file#multimodal-document-processing-rag-anything-integration)。 - [2025.03]🎯[新功能] LightRAG 现在支持引用功能，实现了正确的来源归属和增强的文档可追溯性。 - [2025.02]🎯[新功能] 您现在可以使用 MongoDB 作为一站式存储解决方案，实现统一的数据管理。 - [2025.02]🎯[新发布] 我们的团队发布了 [VideoRAG](https://github.com/HKUDS/VideoRAG)-一个用于理解超长上下文视频的 RAG 系统 - [2025.01]🎯[新发布] 我们的团队发布了 [MiniRAG](https://github.com/HKUDS/MiniRAG)，使用小模型让 RAG 更简单。 - [2025.01]🎯您现在可以使用 PostgreSQL 作为一站式存储解决方案进行数据管理。 - [2024.11]🎯[新资源] [LearnOpenCV](https://learnopencv.com/lightrag) 上现在提供了 LightRAG 的综合指南。—— 探索深入的教程和最佳实践。非常感谢博客作者的精彩贡献！ - [2024.11]🎯[新功能] 推出 LightRAG WebUI —— 一个允许您通过直观的基于 Web 的仪表板插入、查询和可视化 LightRAG 知识的界面。 - [2024.11]🎯[新功能] 您现在可以[使用 Neo4J 进行存储](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#using-neo4j-for-storage)-启用图数据库支持。 - [2024.10]🎯[新功能] 我们添加了 [LightRAG 介绍视频](https://youtu.be/oageL-1I0GE)的链接。—— LightRAG 功能的演示。感谢作者的精彩贡献！ - [2024.10]🎯[新频道] 我们创建了一个 [Discord 频道](https://discord.gg/yF2MmDJyGJ)！💬 欢迎加入我们的社区进行分享、讨论和协作！ 🎉🎉 - [2024.10]🎯[新功能] LightRAG 现在支持 [Ollama 模型](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#quick-start)！

算法流程图

 *图 1: LightRAG 索引流程图 - 图片说明 : [来源](https://learnopencv.com/lightrag/)*  *图 2: LightRAG 检索和查询流程图 - 图片说明 : [来源](https://learnopencv.com/lightrag/)*

## 安装 ### 安装 LightRAG Server LightRAG Server 旨在提供 Web UI 和 API 支持。Web UI 促进文档索引、知识图谱探索和简单的 RAG 查询界面。LightRAG Server 还提供 Ollama 兼容接口，旨在将 LightRAG 模拟为 Ollama 聊天模型。这允许 AI 聊天机器人（如 Open WebUI）轻松访问 LightRAG。 * 从 PyPI 安装 ``` ### 使用 uv 安装 LightRAG Server 作为工具（推荐） uv tool install "lightrag-hku[api]" ### 或者使用 pip # python -m venv .venv # source .venv/bin/activate # Windows: .venv\Scripts\activate # pip install "lightrag-hku[api]" ### 构建前端产物 cd lightrag_webui bun install --frozen-lockfile bun run build cd .. # 设置 env 文件 # 通过从 GitHub 仓库根目录下载获取 env.example 文件 # 或者从本地源代码检出中复制它。 cp env.example .env # Update the .env with your LLM and embedding configurations # 启动服务器 lightrag-server ``` * 从源码安装 ``` git clone https://github.com/HKUDS/LightRAG.git cd LightRAG # 使用 uv（推荐） # 注意：uv sync 会自动在 .venv/ 中创建虚拟环境 uv sync --extra api source .venv/bin/activate # Activate the virtual environment (Linux/macOS) # 或者在 Windows 上：.venv\Scripts\activate ### 或者使用 pip 配合虚拟环境 # python -m venv .venv # source .venv/bin/activate # Windows: .venv\Scripts\activate # pip install -e ".[api]" # 构建前端产物 cd lightrag_webui bun install --frozen-lockfile bun run build cd .. # 设置 env 文件 cp env.example .env # Update the .env with your LLM and embedding configurations # 启动 API-WebUI 服务器 lightrag-server ``` * 使用 Docker Compose 启动 LightRAG Server ``` git clone https://github.com/HKUDS/LightRAG.git cd LightRAG cp env.example .env # Update the .env with your LLM and embedding configurations # 在 .env 中修改 LLM 和 Embedding 设置 docker compose up ``` ### 使用设置工具创建 .env 文件 无需手动编辑 `env.example`，请使用交互式设置向导来生成配置好的 `.env`，并在需要时生成 `docker-compose.final.yml`： ``` make env-base # Required first step: LLM, embedding, reranker make env-storage # Optional: storage backends and database services make env-server # Optional: server port, auth, and SSL make env-base-rewrite # Optional: force-regenerate wizard-managed compose services make env-storage-rewrite # Optional: force-regenerate wizard-managed compose services make env-security-check # Optional: audit the current .env for security risks ``` 有关每个目标的完整说明，请参阅 [docs/InteractiveSetup.md](./docs/InteractiveSetup.md)。 设置向导仅更新配置；请在部署前单独运行 `make env-security-check` 以审计 当前 `.env` 的安全风险。 默认情况下，重新运行设置会保留未更改的向导管理 compose 服务块；仅在需要从捆绑模板重建这些托管块时使用 `*-rewrite` 目标。 ### 安装 LightRAG Core * 从源码安装（推荐） ``` cd LightRAG # 注意：uv sync 会自动在 .venv/ 中创建虚拟环境 uv sync source .venv/bin/activate # Activate the virtual environment (Linux/macOS) # 或者在 Windows 上：.venv\Scripts\activate # 或者：pip install -e . ``` * 从 PyPI 安装 ``` uv pip install lightrag-hku # 或者：pip install lightrag-hku ``` ## 快速开始 ### LightRAG 的 LLM 和技术栈要求 LightRAG 对大型语言模型 (LLMs) 能力的要求显著高于传统 RAG，因为它需要 LLM 从文档中执行实体关系提取任务。配置适当的 Embedding 和 Reranker 模型对于提高查询性能也至关重要。 - **LLM 选择**: - 建议使用至少 320 亿 (32B) 参数的 LLM。 - 上下文长度应至少为 32KB，推荐 64KB。 - 不建议在文档索引阶段选择推理模型。 - 在查询阶段，建议选择比索引阶段使用的模型能力更强的模型，以获得更好的查询结果。 - **Embedding 模型**: - 高性能的 Embedding 模型对 RAG 至关重要。 - 我们建议使用主流的多语言 Embedding 模型，例如：`BAAI/bge-m3` 和 `text-embedding-3-large`。 - **重要提示**: Embedding 模型必须在文档索引之前确定，并且在文档查询阶段必须使用相同的模型。对于某些存储方案（例如 PostgreSQL），必须在初始创建表时定义向量维度。因此，在更改 Embedding 模型时，需要删除现有的向量相关表，并允许 LightRAG 使用新的维度重新创建它们。 - **Reranker 模型配置**: - 配置 Reranker 模型可以显著增强 LightRAG 的检索性能。 - 启用 Reranker 模型后，建议将 "mix mode" 设置为默认查询模式。 - 我们建议使用主流的 Reranker 模型，例如：`BAAI/bge-reranker-v2-m3` 或 Jina 等服务提供的模型。 ### LightRAG Server 快速开始 * 有关 LightRAG Server 的更多信息，请参阅 [LightRAG Server](./lightrag/api/README.md)。 ### LightRAG core 快速开始 要开始使用 LightRAG core，请参考 `examples` 文件夹中可用的示例代码。此外，还提供了[视频演示](https://www.youtube.com/watch?v=g21royNJ4fw)来指导您完成本地设置过程。如果您已经拥有 OpenAI API key，您可以立即运行演示： ``` ### 你应该在项目文件夹中运行演示代码 cd LightRAG ### 提供你的 OpenAI API-KEY export OPENAI_API_KEY="sk-...your_opeai_key..." ### 下载查尔斯·狄更斯的演示文档 "A Christmas Carol" curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt ### 运行演示代码 python examples/lightrag_openai_demo.py ``` 有关流式响应实现示例，请参阅 `examples/lightrag_openai_compatible_demo.py`。在执行之前，请确保相应地修改示例代码的 LLM 和 Embedding 配置。 **注意 1**: 运行演示程序时，请注意不同的测试脚本可能使用不同的 Embedding 模型。如果您切换到不同的 Embedding 模型，必须清除数据目录 (`./dickens`)；否则，程序可能会遇到错误。如果您希望保留 LLM 缓存，可以在清除数据目录的同时保留 `kv_store_llm_response_cache.json` 文件。 **注意 2**: 只有 `lightrag_openai_demo.py` 和 `lightrag_openai_compatible_demo.py` 是官方支持的示例代码。其他示例文件是社区贡献的，尚未经过全面的测试和优化。 ## 使用 LightRAG Core 编程 ### ⚠️ 重要: 初始化要求 **LightRAG 在使用前需要显式初始化。** 您必须在创建 LightRAG 实例后调用 `await rag.initialize_storages()`，否则将遇到错误。 ### 一个简单的程序 使用下面的 Python 代码片段初始化 LightRAG，向其插入文本，并执行查询： ``` import os import asyncio from lightrag import LightRAG, QueryParam from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed from lightrag.utils import setup_logger setup_logger("lightrag", level="INFO") WORKING_DIR = "./rag_storage" if not os.path.exists(WORKING_DIR): os.mkdir(WORKING_DIR) async def initialize_rag(): rag = LightRAG( working_dir=WORKING_DIR, embedding_func=openai_embed, llm_model_func=gpt_4o_mini_complete, ) # IMPORTANT: Both initialization calls are required! await rag.initialize_storages() # Initialize storage backends return rag async def main(): try: # Initialize RAG instance rag = await initialize_rag() await rag.ainsert("Your text") # Perform hybrid search mode = "hybrid" print( await rag.aquery( "What are the top themes in this story?", param=QueryParam(mode=mode) ) ) except Exception as e: print(f"An error occurred: {e}") finally: if rag: await rag.finalize_storages() if __name__ == "__main__": asyncio.run(main()) ``` 上述代码片段的重要说明： - 在运行脚本之前导出您的 OPENAI_API_KEY 环境变量。 - 该程序使用 LightRAG 的默认存储设置，因此所有数据将持久化到 WORKING_DIR/rag_storage。 - 该程序仅演示了初始化 LightRAG 对象的最简单方法：注入 Embedding 和 LLM 函数，并在创建 LightRAG 对象后初始化存储和 pipeline 状态。 ### LightRAG 初始化参数 LightRAG 初始化参数的完整列表：

参数

| **参数** | **类型** | **说明** | **默认值** | | -------------- | ---------- | ----------------- | ------------- | | **working_dir** | `str` | 存储缓存的目录 | `lightrag_cache+timestamp` | | **workspace** | str | 用于不同 LightRAG 实例之间数据隔离的工作区名称 | | | **kv_storage** | `str` | 文档和文本块的存储类型。支持的类型: `JsonKVStorage`,`PGKVStorage`,`RedisKVStorage`,`MongoKVStorage`,`OpenSearchKVStorage` | `JsonKVStorage` | | **vector_storage** | `str` | Embedding 向量的存储类型。支持的类型: `NanoVectorDBStorage`,`PGVectorStorage`,`MilvusVectorDBStorage`,`ChromaVectorDBStorage`,`FaissVectorDBStorage`,`MongoVectorDBStorage`,`QdrantVectorDBStorage`,`OpenSearchVectorDBStorage` | `NanoVectorDBStorage` | | **graph_storage** | `str` | 图边和节点的存储类型。支持的类型: `NetworkXStorage`,`Neo4JStorage`,`PGGraphStorage`,`AGEStorage`,`OpenSearchGraphStorage` | `NetworkXStorage` | | **doc_status_storage** | `str` | 文档处理状态的存储类型。支持的类型: `JsonDocStatusStorage`,`PGDocStatusStorage`,`MongoDocStatusStorage`,`OpenSearchDocStatusStorage` | `JsonDocStatusStorage` | | **chunk_token_size** | `int` | 拆分文档时每个块的最大 token 大小 | `1200` | | **chunk_overlap_token_size** | `int` | 拆分文档时两个块之间的重叠 token 大小 | `100` | | **tokenizer** | `Tokenizer` | 用于遵循 `TokenizerInterface` 协议的 .encode() 和 .decode() 函数将文本转换为 token (数字) 并转换回来的函数。如果不指定，它将使用默认的 Tiktoken tokenizer。 | `TiktokenTokenizer` | | **tiktoken_model_name** | `str` | 如果您使用的是默认 Tiktoken tokenizer，这是要使用的特定 Tiktoken 模型的名称。如果您提供自己的 tokenizer，则忽略此设置。 | `gpt-4o-mini` | | **entity_extract_max_gleaning** | `int` | 实体提取过程中的循环次数，追加历史消息 | `1` | | **node_embedding_algorithm** | `str` | 节点嵌入算法（当前未使用） | `node2vec` | | **node2vec_params** | `dict` | 节点嵌入的参数 | `{"dimensions": 1536,"num_walks": 10,"walk_length": 40,"window_size": 2,"iterations": 3,"random_seed": 3,}` | | **embedding_func** | `EmbeddingFunc` | 从文本生成 Embedding 向量的函数 | `openai_embed` | | **embedding_batch_num** | `int` | Embedding 处理的最大批大小（每批发送多个文本） | `32` | | **embedding_func_max_async** | `int` | 并发异步 Embedding 处理的最大数量 | `16` | | **llm_model_func** | `callable` | 用于 LLM 生成的函数 | `gpt_4o_mini_complete` | | **llm_model_name** | `str` | 用于生成的 LLM 型名称 | `meta-llama/Llama-3.2-1B-Instruct` | | **summary_context_size** | `int` | 发送给 LLM 用于实体关系合并生成摘要的最大 token | `10000`（由环境变量 SUMMARY_CONTEXT_SIZE 配置） | | **summary_max_tokens** | `int` | 实体/关系描述的最大 token 大小 | `500`（由环境变量 SUMMARY_MAX_TOKENS 配置） | | **llm_model_max_async** | `int` | 并发异步 LLM 进程的最大数量 | `4`（默认值由环境变量 MAX_ASYNC 更改） | | **llm_model_kwargs** | `dict` | LLM 生成的附加参数 | | | **vector_db_storage_cls_kwargs** | `dict` | 向量数据库的附加参数，例如设置节点和关系检索的阈值 | cosine_better_than_threshold: 0.2（默认值由环境变量 COSINE_THRESHOLD 更改） | | **enable_llm_cache** | `bool` | 如果为 `TRUE`，则将 LLM 结果存储在缓存中；重复的提示返回缓存的响应 | `TRUE` | | **enable_llm_cache_for_entity_extract** | `bool` | 如果为 `TRUE`，则将实体提取的 LLM 结果存储在缓存中；适合初学者调试您的应用程序 | `TRUE` | | **addon_params** | `dict` | 附加参数，例如，`{"language": "Simplified Chinese", "entity_types": ["organization", "person", "location", "event"]}`：设置示例限制，实体/关系提取输出语言 | language: English` | | **embedding_cache_config** | `dict` | 问答缓存配置。包含三个参数：`enabled`：启用/禁用缓存查找功能的布尔值。启用后，系统将在生成新答案之前检查缓存的响应。`similarity_threshold`：浮点值 (0-1)，相似度阈值。当新问题与缓存问题的相似度超过此阈值时，将直接返回缓存的答案，而无需调用 LLM。`use_llm_check`：启用/禁用 LLM 相似度验证的布尔值。启用后，LLM 将用作二次检查，以在返回缓存答案之前验证问题之间的相似度。 | 默认值: `{"enabled": False, "similarity_threshold": 0.95, "use_llm_check": False}` |

### Query Param 使用 QueryParam 来控制您的查询行为： ``` class QueryParam: """Configuration parameters for query execution in LightRAG.""" mode: Literal["local", "global", "hybrid", "naive", "mix", "bypass"] = "global" """Specifies the retrieval mode: - "local": Focuses on context-dependent information. - "global": Utilizes global knowledge. - "hybrid": Combines local and global retrieval methods. - "naive": Performs a basic search without advanced techniques. - "mix": Integrates knowledge graph and vector retrieval. """ only_need_context: bool = False """If True, only returns the retrieved context without generating a response.""" only_need_prompt: bool = False """If True, only returns the generated prompt without producing a response.""" response_type: str = "Multiple Paragraphs" """Defines the response format. Examples: 'Multiple Paragraphs', 'Single Paragraph', 'Bullet Points'.""" stream: bool = False """If True, enables streaming output for real-time responses.""" top_k: int = int(os.getenv("TOP_K", "60")) """Number of top items to retrieve. Represents entities in 'local' mode and relationships in 'global' mode.""" chunk_top_k: int = int(os.getenv("CHUNK_TOP_K", "20")) """Number of text chunks to retrieve initially from vector search and keep after reranking. If None, defaults to top_k value. """ max_entity_tokens: int = int(os.getenv("MAX_ENTITY_TOKENS", "6000")) """Maximum number of tokens allocated for entity context in unified token control system.""" max_relation_tokens: int = int(os.getenv("MAX_RELATION_TOKENS", "8000")) """Maximum number of tokens allocated for relationship context in unified token control system.""" max_total_tokens: int = int(os.getenv("MAX_TOTAL_TOKENS", "30000")) """Maximum total tokens budget for the entire query context (entities + relations + chunks + system prompt).""" # History messages are only sent to LLM for context, not used for retrieval conversation_history: list[dict[str, str]] = field(default_factory=list) """Stores past conversation history to maintain context. Format: [{"role": "user/assistant", "content": "message"}]. """ # Deprecated (ids filter lead to potential hallucination effects) ids: list[str] | None = None """List of ids to filter the results.""" model_func: Callable[..., object] | None = None """Optional override for the LLM model function to use for this specific query. If provided, this will be used instead of the global model function. This allows using different models for different query modes. """ user_prompt: str | None = None """User-provided prompt for the query. Addition instructions for LLM. If provided, this will be inject into the prompt template. It's purpose is the let user customize the way LLM generate the response. """ enable_rerank: bool = True """Enable reranking for retrieved text chunks. If True but no rerank model is configured, a warning will be issued. Default is True to enable reranking when rerank model is available. """ ``` ### LLM 和 Embedding 注入 LightRAG 需要利用 LLM 和 Embedding 模型来完成文档索引和查询任务。在初始化阶段，有必要将相关模型的调用方法注入到 LightRAG 中：

使用类 OpenAI API

* LightRAG 还支持类 OpenAI 的 chat/embeddings API： ``` import os import numpy as np from lightrag.utils import wrap_embedding_func_with_attrs from lightrag.llm.openai import openai_complete_if_cache, openai_embed async def llm_model_func( prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs ) -> str: return await openai_complete_if_cache( "solar-mini", prompt, system_prompt=system_prompt, history_messages=history_messages, api_key=os.getenv("UPSTAGE_API_KEY"), base_url="https://api.upstage.ai/v1/solar", **kwargs ) @wrap_embedding_func_with_attrs(embedding_dim=4096, max_token_size=8192, model_name="solar-embedding-1-large-query") async def embedding_func(texts: list[str]) -> np.ndarray: return await openai_embed.func( texts, model="solar-embedding-1-large-query", api_key=os.getenv("UPSTAGE_API_KEY"), base_url="https://api.upstage.ai/v1/solar" ) async def initialize_rag(): rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=llm_model_func, embedding_func=embedding_func # Pass the decorated function directly ) await rag.initialize_storages() return rag ```

使用 Hugging Face 模型

* 如果您想使用 Hugging Face 模型，您只需要按如下方式设置 LightRAG： 见 `lightrag_hf_demo.py` ``` from functools import partial from transformers import AutoTokenizer, AutoModel # 预加载 tokenizer 和模型 tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") embed_model = AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") # 使用 Hugging Face 模型初始化 LightRAG rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=hf_model_complete, # Use Hugging Face model for text generation llm_model_name='meta-llama/Llama-3.1-8B-Instruct', # Model name from Hugging Face # Use Hugging Face embedding function embedding_func=EmbeddingFunc( embedding_dim=384, max_token_size=2048, model_name="sentence-transformers/all-MiniLM-L6-v2", func=partial( hf_embed.func, # Use .func to access the unwrapped function tokenizer=tokenizer, embed_model=embed_model ) ), ) ```

使用 Ollama 模型

**概述** 如果您想使用 Ollama 模型，您需要拉取您计划使用的模型和 Embedding 模型，例如 `nomic-embed-text`。 然后您只需要按如下方式设置 LightRAG： ``` import numpy as np from lightrag.utils import wrap_embedding_func_with_attrs from lightrag.llm.ollama import ollama_model_complete, ollama_embed @wrap_embedding_func_with_attrs(embedding_dim=768, max_token_size=8192, model_name="nomic-embed-text") async def embedding_func(texts: list[str]) -> np.ndarray: return await ollama_embed.func(texts, embed_model="nomic-embed-text") # 使用 Ollama 模型初始化 LightRAG rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=ollama_model_complete, # Use Ollama model for text generation llm_model_name='your_model_name', # Your model name embedding_func=embedding_func, # Pass the decorated function directly ) ``` * **增加上下文大小** 为了使 LightRAG 工作，上下文应至少为 32k token。默认情况下，Ollama 模型的上下文大小为 8k。您可以通过以下两种方式之一来实现： * **在 Modelfile 中增加 `num_ctx` 参数** 1. 拉取模型： ``` ollama pull qwen2 ``` 2. 显示模型文件： ``` ollama show --modelfile qwen2 > Modelfile ``` 3. 通过添加以下行来编辑 Modelfile： ``` PARAMETER num_ctx 32768 ``` 4. 创建修改后的模型： ``` ollama create -f Modelfile qwen2m ``` * **通过 Ollama API 设置 `num_ctx`** 您可以使用 `llm_model_kwargs` 参数来配置 ollama： ``` import numpy as np from lightrag.utils import wrap_embedding_func_with_attrs from lightrag.llm.ollama import ollama_model_complete, ollama_embed @wrap_embedding_func_with_attrs(embedding_dim=768, max_token_size=8192, model_name="nomic-embed-text") async def embedding_func(texts: list[str]) -> np.ndarray: return await ollama_embed.func(texts, embed_model="nomic-embed-text") rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=ollama_model_complete, # Use Ollama model for text generation llm_model_name='your_model_name', # Your model name llm_model_kwargs={"options": {"num_ctx": 32768}}, embedding_func=embedding_func, # Pass the decorated function directly ) ``` * **低显存 GPU** 为了在低显存 GPU 上运行此实验，您应该选择小模型并调整上下文窗口（增加上下文会增加内存消耗）。例如，在具有 6Gb RAM 的翻新矿卡上运行此 ollama 示例时，需要在使用 `gemma2:2b` 时将上下文大小设置为 26k。它在 `book.txt` 上能够找到 197 个实体和 19 个关系。

LlamaIndex

LightRAG 支持与 LlamaIndex 集成 (`llm/llama_index_impl.py`)： - 通过 LlamaIndex 与 OpenAI 和其他提供商集成 - 有关详细设置，请参阅 [LlamaIndex 文档](https://developers.llamaindex.ai/python/framework/) 或 [示例](examples/unofficial-sample/) **示例用法** ``` # 使用 LlamaIndex 直接访问 OpenAI import asyncio from lightrag import LightRAG from lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed from llama_index.embeddings.openai import OpenAIEmbedding from llama_index.llms.openai import OpenAI from lightrag.utils import setup_logger # 为 LightRAG 设置日志处理器 setup_logger("lightrag", level="INFO") async def initialize_rag(): rag = LightRAG( working_dir="your/path", llm_model_func=llama_index_complete_if_cache, # LlamaIndex-compatible completion function embedding_func=EmbeddingFunc( # LlamaIndex-compatible embedding function embedding_dim=1536, max_token_size=2048, model_name=embed_model, func=partial(llama_index_embed.func, embed_model=embed_model) # Use .func to access the unwrapped function ), ) await rag.initialize_storages() return rag def main(): # Initialize RAG instance rag = asyncio.run(initialize_rag()) with open("./book.txt", "r", encoding="utf-8") as f: rag.insert(f.read()) # Perform naive search print( rag.query("What are the top themes in this story?", param=QueryParam(mode="naive")) ) # Perform local search print( rag.query("What are the top themes in this story?", param=QueryParam(mode="local")) ) # Perform global search print( rag.query("What are the top themes in this story?", param=QueryParam(mode="global")) ) # Perform hybrid search print( rag.query("What are the top themes in this story?", param=QueryParam(mode="hybrid")) ) if __name__ == "__main__": main() ``` **有关详细的文档和示例，请参阅：** - [LlamaIndex 文档](https://developers.llamaindex.ai/python/framework/) - [Direct OpenAI Example](examples/unofficial-sample/lightrag_llamaindex_direct_demo.py) - [LiteLLM Proxy Example](examples/unofficial-sample/lightrag_llamaindex_litellm_demo.py) - [LiteLLM Proxy with Opik Example](examples/unofficial-sample/lightrag_llamaindex_litellm_opik_demo.py)

使用 Azure OpenAI 模型

如果您想使用 Azure OpenAI 模型，您只需要按如下方式设置 LightRAG： ``` import os import numpy as np from lightrag.utils import wrap_embedding_func_with_attrs from lightrag.llm.azure_openai import azure_openai_complete_if_cache, azure_openai_embed # 配置生成模型 async def llm_model_func( prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs ) -> str: return await azure_openai_complete_if_cache( prompt, system_prompt=system_prompt, history_messages=history_messages, api_key=os.getenv("AZURE_OPENAI_API_KEY"), azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), api_version=os.getenv("AZURE_OPENAI_API_VERSION"), deployment_name=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"), **kwargs ) # 配置 embedding 模型 @wrap_embedding_func_with_attrs( embedding_dim=1536, max_token_size=8192, model_name=os.getenv("AZURE_OPENAI_EMBEDDING_MODEL") ) async def embedding_func(texts: list[str]) -> np.ndarray: return await azure_openai_embed.func( texts, api_key=os.getenv("AZURE_OPENAI_API_KEY"), azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), api_version=os.getenv("AZURE_OPENAI_API_VERSION"), deployment_name=os.getenv("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ) rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=llm_model_func, embedding_func=embedding_func ) ```

使用 Google Gemini 模型

如果您想使用 Google Gemini 模型，您只需要按如下方式设置 LightRAG： ``` import os import numpy as np from lightrag.utils import wrap_embedding_func_with_attrs from lightrag.llm.gemini import gemini_model_complete, gemini_embed # 配置生成模型 async def llm_model_func( prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs ) -> str: return await gemini_model_complete( prompt, system_prompt=system_prompt, history_messages=history_messages, api_key=os.getenv("GEMINI_API_KEY"), model_name="gemini-2.0-flash", **kwargs ) # 配置 embedding 模型 @wrap_embedding_func_with_attrs( embedding_dim=768, max_token_size=2048, model_name="models/text-embedding-004" ) async def embedding_func(texts: list[str]) -> np.ndarray: return await gemini_embed.func( texts, api_key=os.getenv("GEMINI_API_KEY"), model="models/text-embedding-004" ) rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=llm_model_func, llm_model_name="gemini-2.0-flash", embedding_func=embedding_func ) ```

### Rerank 函数注入 为了提高检索质量，可以基于更有效的相关性评分模型对文档进行重新排序。`rerank.py` 文件提供了三个 Reranker 提供商驱动函数： * **Cohere / vLLM**: `cohere_rerank` * **Jina AI**: `jina_rerank` * **Aliyun**: `ali_rerank` 您可以将这些函数之一注入到 LightRAG 对象的 `rerank_model_func` 属性中。这将启用 LightRAG 的查询功能，使用注入的函数对检索到的文本块进行重新排序。有关详细用法，请参阅 `examples/rerank_example.py` 文件。 ### 用户提示 vs. 查询 在使用 LightRAG 进行内容查询时，避免将搜索过程与无关的输出处理结合起来，因为这会显著影响查询效果。Query Param 中的 `user_prompt` 参数专门设计用于解决此问题 —— 它不参与 RAG 检索阶段，而是指导 LLM 在查询完成后如何处理检索到的结果。使用方法如下： ``` # 创建查询参数 query_param = QueryParam( mode = "hybrid", # Other modes：local, global, hybrid, mix, naive user_prompt = "For diagrams, use mermaid format with English/Pinyin node names and Chinese display labels", ) # 查询与处理 response_default = rag.query( "Please draw a character relationship diagram for Scrooge", param=query_param ) print(response_default) ``` ### 插入

基本插入

``` # 基本插入 rag.insert("Text") ```

批量插入

``` # 基本批量插入：一次插入多个文本 rag.insert(["TEXT1", "TEXT2",...]) # 带有自定义批量大小配置的批量插入 rag = LightRAG( ... working_dir=WORKING_DIR, max_parallel_insert = 4 ) rag.insert(["TEXT1", "TEXT2", "TEXT3", ...]) # Documents will be processed in batches of 4 ``` `max_parallel_insert` 参数决定了文档索引 pipeline 中并发处理的文档数量。如果未指定，默认值为 **2**。我们建议将此设置保持在 **10 以下**，因为性能瓶颈通常在于 LLM (大型语言模型) 的处理。

带 ID 插入

如果您想为您的文档提供自己的 ID，文档数量和 ID 数量必须相同。 ``` # 插入单个文本，并为其提供 ID rag.insert("TEXT1", ids=["ID_FOR_TEXT1"]) # 插入多个文本，并为它们提供 ID rag.insert(["TEXT1", "TEXT2",...], ids=["ID_FOR_TEXT1", "ID_FOR_TEXT2"]) ```

使用 Pipeline 插入

`apipeline_enqueue_documents` 和 `apipeline_process_enqueue_documents` 函数允许您将文档增量插入到图中。这对于您希望在后台处理文档同时仍允许主线程继续执行的场景非常有用。 ``` rag = LightRAG(..) await rag.apipeline_enqueue_documents(input) # 循环中的例程 await rag.apipeline_process_enqueue_documents(input) ```

插入多文件类型支持

`textract` 支持读取 TXT、DOCX、PPTX、CSV 和 PDF 等文件类型。 ``` import textract file_path = 'TEXT.pdf' text_content = textract.process(file_path) rag.insert(text_content.decode('utf-8')) ```

引用功能

通过提供文件路径，系统确保可以将来源追溯回其原始文档。 ``` # 定义文档及其文件路径 documents = ["Document content 1", "Document content 2"] file_paths = ["path/to/doc1.txt", "path/to/doc2.txt"] # 插入带有文件路径的文档 rag.insert(documents, file_paths=file_paths) ```

### 存储 LightRAG 出于不同目的使用 4 种类型的存储： * KV_STORAGE: LLM 响应缓存，文本块，文档信息 * VECTOR_STORAGE: 实体向量，关系向量，块向量 * GRAPH_STORAGE: 实体关系图 * DOC_STATUS_STORAGE: 文档索引状态 每种存储类型都有几种实现： * KV_STORAGE 支持的实现： ``` JsonKVStorage JsonFile (default) PGKVStorage Postgres RedisKVStorage Redis MongoKVStorage MongoDB OpenSearchKVStorage OpenSearch ``` * GRAPH_STORAGE 支持的实现： ``` NetworkXStorage NetworkX (default) Neo4JStorage Neo4J PGGraphStorage PostgreSQL with AGE plugin MemgraphStorage Memgraph OpenSearchGraphStorage OpenSearch ``` * VECTOR_STORAGE 支持的实现： ``` NanoVectorDBStorage NanoVector (default) PGVectorStorage Postgres MilvusVectorDBStorage Milvus FaissVectorDBStorage Faiss QdrantVectorDBStorage Qdrant MongoVectorDBStorage MongoDB OpenSearchVectorDBStorage OpenSearch ``` * DOC_STATUS_STORAGE: 支持的实现： ``` JsonDocStatusStorage JsonFile (default) PGDocStatusStorage Postgres MongoDocStatusStorage MongoDB OpenSearchDocStatusStorage OpenSearch ``` 每种存储类型的示例连接配置可以在存储库的 `env.example` 文件中找到。连接字符串中的数据库实例需要您事先在数据库服务器上创建。LightRAG 仅负责在数据库实例内创建表，而不负责创建数据库实例本身。如果使用 Redis 作为存储，请记住为 Redis 配置自动数据持久化规则，否则 Redis 服务重启后数据将丢失。如果使用 PostgreSQL，建议使用 16.6 或更高版本。

使用 Neo4J 存储

* 对于生产级场景，您很可能希望利用企业解决方案 * 进行 KG 存储。推荐在 Docker 中运行 Neo4J，以实现无缝的本地测试。 * 参见：https://hub.docker.com/_/neo4j ``` export NEO4J_URI="neo4j://localhost:7687" export NEO4J_USERNAME="neo4j" export NEO4J_PASSWORD="password" export NEO4J_DATABASE="neo4j" #<----------- If you are using community edition neo4j docker image. # 为 LightRAG 设置日志记录器 setup_logger("lightrag", level="INFO") # 当你启动项目时，务必通过指定 graph_storage="Neo4JStorage" 来覆盖默认的 KG。 # 使用 Neo4J 实现初始化 LightRAG。 async def initialize_rag(): rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=gpt_4o_mini_complete, # Use gpt_4o_mini_complete LLM model graph_storage="Neo4JStorage", #<-----------override KG default ) # Initialize database connections await rag.initialize_storages() # Initialize pipeline status for document processing return rag ``` 有关工作示例，请参见 test_neo4j.py。

使用 PostgreSQL 存储

对于生产级场景，您很可能希望利用企业解决方案。PostgreSQL 可以为您提供一站式解决方案，作为 KV 存储、VectorDB (pgvector) 和 GraphDB (apache AGE)。支持 PostgreSQL 版本 16.6 或更高版本。 * PostgreSQL 轻量级，包括所有必要插件在内的整个二进制分发版可以压缩到 40MB：参考 [Windows 版本](https://github.com/ShanGor/apache-age-windows/releases/tag/PG17%2Fv1.5.0-rc0)，因为它易于在 Linux/Mac 上安装。 * 如果您更喜欢 docker，如果您是初学者，请从此镜像开始，以避免遇到问题（默认用户密码：rag/rag）：https://hub.docker.com/r/gzdaniel/postgres-for-rag * 如何开始？参考：[examples/lightrag_gemini_postgres_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_gemini_postgres_demo.py) * 对于高性能图数据库需求，推荐使用 Neo4j，因为 Apache AGE 的性能竞争力不强。

使用 Faiss 存储

在使用 Faiss 向量数据库之前，您必须手动安装 `faiss-cpu` 或 `faiss-gpu`。 - 安装所需的依赖项： ``` pip install faiss-cpu ``` 如果您有 GPU 支持，也可以安装 `faiss-gpu`。 - 这里我们使用 `sentence-transformers`，但您也可以使用 `3072` 维度的 `OpenAIEmbedding` 模型。 ``` async def embedding_func(texts: list[str]) -> np.ndarray: model = SentenceTransformer('all-MiniLM-L6-v2') embeddings = model.encode(texts, convert_to_numpy=True) return embeddings # 使用 LLM 模型函数和 embedding 函数初始化 LightRAG rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=llm_model_func, embedding_func=EmbeddingFunc( embedding_dim=384, max_token_size=2048, model_name="all-MiniLM-L6-v2", func=embedding_func, ), vector_storage="FaissVectorDBStorage", vector_db_storage_cls_kwargs={ "cosine_better_than_threshold": 0.3 # Your desired threshold } ) ```

使用 Memgraph 进行存储

* Memgraph 是一个高性能的内存图数据库，兼容 Neo4j Bolt 协议。 * 您可以使用 Docker 在本地运行 Memgraph 以便轻松测试： * 参见：https://memgraph.com/download ``` export MEMGRAPH_URI="bolt://localhost:7687" # 为 LightRAG 设置日志记录器 setup_logger("lightrag", level="INFO") # 当你启动项目时，覆盖默认的 KG：NetworkX # 通过指定 kg="MemgraphStorage"。 # 注意：默认设置使用 NetworkX # 使用 Memgraph 实现初始化 LightRAG。 async def initialize_rag(): rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=gpt_4o_mini_complete, # Use gpt_4o_mini_complete LLM model graph_storage="MemgraphStorage", #<-----------override KG default ) # Initialize database connections await rag.initialize_storages() # Initialize pipeline status for document processing return rag ```

使用 Milvus 进行向量存储

Milvus 是一个高性能、可扩展的向量数据库，用于生产级向量存储。LightRAG 提供了三种配置 Milvus 的方法，外加支持可配置的索引类型以优化性能和内存使用。 ### 支持的索引类型 - `AUTOINDEX` (默认): Milvus 自动选择最佳索引 - `HNSW`: Hierarchical Navigable Small World graph，用于高召回率 - `HNSW_SQ`: 带有标量量化的 HNSW，用于节省内存（需要 Milvus 2.6.8+） - `HNSW_PQ`, `HNSW_PRQ`: 带有乘积/乘积残差量化的 HNSW - `IVF_FLAT`, `IVF_SQ8`, `IVF_PQ`: 倒排文件系列索引 - `DISKANN`: 基于磁盘的近似最近邻 - `SCANN`: 可扩展最近邻 ### 支持的度量类型 `COSINE` (默认), `L2`, `IP` ### 配置方法 1 — 环境变量（`.env` 文件） 最适用于：**LightRAG Server 部署和 Docker/k8s 设置**。 ``` # 连接 MILVUS_URI=http://localhost:19530 MILVUS_DB_NAME=lightrag # MILVUS_USER=root # MILVUS_PASSWORD=your_password # MILVUS_TOKEN=your_token # 存储选择 LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage # Index 配置（均为可选 —— 适用合理的默认值） MILVUS_INDEX_TYPE=HNSW # Default: AUTOINDEX MILVUS_METRIC_TYPE=COSINE # Default: COSINE MILVUS_HNSW_M=16 # Default: 16, range [2-2048] MILVUS_HNSW_EF_CONSTRUCTION=360 # Default: 360 MILVUS_HNSW_EF=200 # Default: 200 # HNSW_SQ 选项（需要 Milvus 2.6.8+） # MILVUS_INDEX_TYPE=HNSW_SQ # MILVUS_HNSW_SQ_TYPE=SQ8 # SQ4U, SQ6, SQ8, BF16, FP16 # MILVUS_HNSW_SQ_REFINE=false # 启用细化 # MILVUS_HNSW_SQ_REFINE_TYPE=FP32 # 细化精度 # MILVUS_HNSW_SQ_REFINE_K=10 # 细化扩展因子 # IVF 选项 # MILVUS_IVF_NLIST=1024 # MILVUS_IVF_NPROBE=16 ``` 然后在 Python 代码中： ``` from lightrag import LightRAG async def initialize_rag(): rag = LightRAG( working_dir="./rag_storage", llm_model_func=..., embedding_func=..., vector_storage="MilvusVectorDBStorage", ) await rag.initialize_storages() return rag ``` ### 配置方法 2 — `vector_db_storage_cls_kwargs` (Python SDK) 最适用于：**Python SDK / 框架集成**，您希望所有配置都在代码中。 ``` from lightrag import LightRAG async def initialize_rag(): rag = LightRAG( working_dir="./rag_storage", llm_model_func=..., embedding_func=..., vector_storage="MilvusVectorDBStorage", vector_db_storage_cls_kwargs={ "milvus_uri": "http://localhost:19530", "milvus_db_name": "lightrag", "index_type": "HNSW", "metric_type": "COSINE", "hnsw_m": 16, "hnsw_ef_construction": 360, "hnsw_ef": 200, "cosine_better_than_threshold": 0.2, }, ) await rag.initialize_storages() return rag ``` ### 配置方法 3 — `config.ini` (遗留) 仅连接参数；索引设置使用环境变量或 kwargs。 ``` [milvus] uri = http://localhost:19530 db_name = lightrag # user = root # password = your_password # token = your_token ``` ### 配置优先级 | 设置 | 第 1 (最高) | 第 2 | 第 3 (最低) | |---|---|---|---| | 连接 (`uri`, …) | `vector_db_storage_cls_kwargs` 环境变量 | `config.ini` | | 索引 (`index_type`, …) | `vector_db_storage_cls_kwargs` | 环境变量 | 默认值 | ### HNSW_SQ 压缩权衡 | SQ 类型 | 压缩率 | 精度 | 备注 | |---|---|---|---| | `SQ4U` | ~8× | 较低 | 节省内存最佳 | | `SQ6` | ~5.3× | 平衡 | 良好的权衡 | | `SQ8` | ~4× | 良好 | **推荐** | | `BF16` / `FP16` | ~2× | 高 | 接近无损 | **版本要求：** - HNSW_SQ 索引类型需要 **Milvus 2.6.8 或更高版本** - LightRAG 将自动验证服务器版本，如果不满足要求将引发错误 - 其他索引类型适用于 Milvus 2.0+ **向后兼容性：** - 如果未提供索引配置，LightRAG 使用 AUTOINDEX（Milvus 默认行为） - 现有集合不受影响；索引配置仅适用于新创建的集合 有关完整的配置选项，请参阅 `env.example` 和 `docs/MilvusConfigurationGuide.md`。

使用 MongoDB 存储

MongoDB 为 LightRAG 提供一站式存储解决方案。MongoDB 提供原生的 KV 存储和向量存储。LightRAG 使用 MongoDB 集合来实现简单的图存储。`MongoVectorDBStorage` 需要具有 Atlas Search / Vector Search 支持的 MongoDB 部署，例如 MongoDB Atlas 或 Atlas local。设置向导捆绑的本地 Docker MongoDB 服务是 MongoDB Community Edition，因此它可用于 KV/graph/doc-status 存储，但不能用于 `MongoVectorDBStorage`。

使用 Redis 存储

LightRAG 支持使用 Redis 作为 KV 存储。使用 Redis 存储时，应注意持久化配置和内存使用配置。以下是推荐的 Redis 配置： ``` save 900 1 save 300 10 save 60 1000 stop-writes-on-bgsave-error yes maxmemory 4gb maxmemory-policy noeviction maxclients 500 ``` 当交互式设置管理本地 Redis 容器时，它会在 `./data/config/redis.conf` 暂存一个用户可编辑的配置，并将其挂载到容器中。设置在重新运行时会保留该文件，以便可以在不丢失手动编辑的情况下调整本地 Redis 调优。

使用 OpenSearch 存储

OpenSearch 为所有四种 LightRAG 存储类型（KV、Vector、Graph、DocStatus）提供统一的存储解决方案。它提供原生的 k-NN 向量搜索、全文搜索和水平可扩展性 —— 所有这些都无需云专属限制。 * **要求**: 启用了 k-NN 插件的 OpenSearch 3.x 或更高版本。 使用 Docker 安装（不带插件）： ``` docker run -d -p 9200:9200 -e "discovery.type=single-node" \ -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=" \ opensearchproject/opensearch:latest ``` 使用 Docker Compose 安装（推荐，带插件）： ``` curl -O https://raw.githubusercontent.com/opensearch-project/opensearch-build/main/docker/release/dockercomposefiles/docker-compose-3.x.yml # 启动 OpenSearch 集群 OPENSEARCH_INITIAL_ADMIN_PASSWORD= docker-compose -f docker-compose-3.x.yml up -d ``` * **配置**: 设置环境变量（完整列表见 `env.example`）： ``` export OPENSEARCH_HOSTS=localhost:9200 export OPENSEARCH_USER=admin export OPENSEARCH_PASSWORD= export OPENSEARCH_USE_SSL=true export OPENSEARCH_VERIFY_CERTS=false ``` * **用法**： ``` rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=your_llm_func, embedding_func=your_embed_func, kv_storage="OpenSearchKVStorage", doc_status_storage="OpenSearchDocStatusStorage", graph_storage="OpenSearchGraphStorage", vector_storage="OpenSearchVectorDBStorage", ) ``` * **图遍历**: 当具有 PPL 支持的 OpenSearch SQL 插件可用时，图查询通过 `graphlookup` 命令使用服务端 BFS 以获得最佳性能。否则，它会回退到客户端批处理 BFS。这会在启动时自动检测，或者可以通过 `OPENSEARCH_USE_PPL_GRAPHLOOKUP=true|false` 强制执行。 * **集成测试**: 要针对实时 OpenSearch 集群运行集成测试： 1. 使用 Docker Compose 启动 OpenSearch（下载 [`docker-compose-3.x.yml`](https://raw.githubusercontent.com/opensearch-project/opensearch-build/main/docker/release/dockercomposefiles/docker-compose-3.x.yml))： ``` OPENSEARCH_INITIAL_ADMIN_PASSWORD= docker-compose -f docker-compose-3.x.yml up -d ``` 2. 验证集群是否正在运行： ``` curl -sk -u admin: https://localhost:9200 curl -sk -u admin: https://localhost:9200/_cat/plugins?v ``` 3. 运行单元测试（不需要 OpenSearch —— 使用模拟）： ``` python -m pytest tests/test_opensearch_storage.py -v ``` 4. 针对实时集群运行 OpenSearch 存储演示： ``` export OPENSEARCH_HOSTS=localhost:9200 export OPENSEARCH_USER=admin export OPENSEARCH_PASSWORD= export OPENSEARCH_USE_SSL=true export OPENSEARCH_VERIFY_CERTS=false python examples/opensearch_storage_demo.py ``` 5. 运行完整的 OpenAI + OpenSearch 演示（需要 `OPENAI_API_KEY`）： ``` export OPENAI_API_KEY=your-api-key python examples/lightrag_openai_opensearch_graph_demo.py ``` 6. 通过 LightRAG WebUI 或独立 HTML 可视化知识图谱： 需要在启动 LightRAG Server 之前[构建前端产物](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/README.md)。 ``` # 使用 OpenSearch Storage 启动 lightrag-server LIGHTRAG_KV_STORAGE=OpenSearchKVStorage \ LIGHTRAG_DOC_STATUS_STORAGE=OpenSearchDocStatusStorage \ LIGHTRAG_GRAPH_STORAGE=OpenSearchGraphStorage \ LIGHTRAG_VECTOR_STORAGE=OpenSearchVectorDBStorage \ LLM_BINDING=openai \ EMBEDDING_BINDING=openai \ EMBEDDING_MODEL=text-embedding-3-large \ EMBEDDING_DIM=3072 \ OPENAI_API_KEY=your-api-key \ lightrag-server # 通过 LightRAG WebUI 显示知识图谱 python examples/graph_visual_with_opensearch.py # 打开 http://localhost:9621/webui/ -> Knowledge Graph # 或者生成独立的 HTML 文件 python examples/graph_visual_with_opensearch.py --html ```

### LightRAG 实例之间的数据隔离 `workspace` 参数确保不同 LightRAG 实例之间的数据隔离。一旦初始化，`workspace` 是不可变的，无法更改。以下是针对不同类型存储实现工作区的方式： - **对于基于本地文件的数据库，数据隔离是通过工作区子目录实现的：** `JsonKVStorage`, `JsonDocStatusStorage`, `NetworkXStorage`, `NanoVectorDBStorage`, `FaissVectorDBStorage`。 - **对于在集合中存储数据的数据库，它是通过向集合名称添加工作区前缀来完成的：** `RedisKVStorage`, `RedisDocStatusStorage`, `MilvusVectorDBStorage`, `MongoKVStorage`, `MongoDocStatusStorage`, `MongoVectorDBStorage`, `MongoGraphStorage`, `PGGraphStorage`。 - **对于 Qdrant 向量数据库，数据隔离是通过基于 payload 的分区实现的（Qdrant 推荐的多租户方法）：** `QdrantVectorDBStorage` 使用带有 payload 过滤的共享集合，以实现无限的工作区可扩展性。 - **对于关系数据库，数据隔离是通过向表中添加 `workspace` 字段以进行逻辑数据分离来实现的：** `PGKVStorage`, `PGVectorStorage`, `PGDocStatusStorage`。 - **对于 Neo4j 图数据库，逻辑数据隔离是通过标签实现的：** `Neo4JStorage` - **对于 OpenSearch，数据隔离是通过索引名称前缀实现的：** `OpenSearchKVStorage`, `OpenSearchDocStatusStorage`, `OpenSearchGraphStorage`, `OpenSearchVectorDBStorage` 为了保持与遗留数据的兼容性，当未配置工作区时，PostgreSQL 非图存储的默认工作区为 `default`，对于 PostgreSQL AGE 图存储为 null，对于 Neo4j 图存储为 `base`。对于所有外部存储，系统提供专用的工作区环境变量来覆盖通用的 `WORKSPACE` 环境变量配置。这些特定于存储的工作区环境变量是：`REDIS_WORKSPACE`, `MILVUS_WORKSPACE`, `QDRANT_WORKSPACE`, `MONGODB_WORKSPACE`, `POSTGRES_WORKSPACE`, `NEO4J_WORKSPACE`, `OPENSEARCH_WORKSPACE`。 **用法示例：** 有关在单个应用程序中管理多个隔离知识库（例如，将“书籍”内容与“人力资源政策”分开）的实际演示，请参阅 [Workspace Demo](examples/lightrag_gemini_workspace_demo.py)。 ### AGENTS.md -- 指导编码 Agent AGENTS.md 是一种简单的开放格式，用于指导编码 agent (https://agents.md/)。它是一个专用、可预测的地方，用于提供上下文和说明，以帮助 AI 编码 agent 处理 LightRAG 项目。不同的 AI 编码器不应单独维护单独的指导文件。如果任何 AI 编码器无法自动识别 AGENTS.md，可以使用符号链接作为解决方案。建立符号链接后，您可以通过配置本地 `.gitignore_global` 来防止它们被提交到 Git 存储库。 ## 编辑实体和关系 LightRAG 现在支持全面的知识图谱管理功能，允许您在知识图谱中创建、编辑和删除实体和关系。

创建实体和关系

``` # 创建新实体 entity = rag.create_entity("Google", { "description": "Google is a multinational technology company specializing in internet-related services and products.", "entity_type": "company" }) # 创建另一个实体 product = rag.create_entity("Gmail", { "description": "Gmail is an email service developed by Google.", "entity_type": "product" }) # 在实体之间创建关系 relation = rag.create_relation("Google", "Gmail", { "description": "Google develops and operates Gmail.", "keywords": "develops operates service", "weight": 2.0 }) ```

编辑实体和关系

``` # 编辑现有实体 updated_entity = rag.edit_entity("Google", { "description": "Google is a subsidiary of Alphabet Inc., founded in 1998.", "entity_type": "tech_company" }) # 重命名实体（及其所有关系被正确迁移） renamed_entity = rag.edit_entity("Gmail", { "entity_name": "Google Mail", "description": "Google Mail (formerly Gmail) is an email service." }) # 编辑实体之间的关系 updated_relation = rag.edit_relation("Google", "Google Mail", { "description": "Google created and maintains Google Mail service.", "keywords": "creates maintains email service", "weight": 3.0 }) ``` 所有操作都有同步和异步版本。异步版本带有前缀 "a"（例如，`acreate_entity`, `aedit_relation`）。

插入自定义 KG

``` custom_kg = { "chunks": [ { "content": "Alice and Bob are collaborating on quantum computing research.", "source_id": "doc-1", "file_path": "test_file", } ], "entities": [ { "entity_name": "Alice", "entity_type": "person", "description": "Alice is a researcher specializing in quantum physics.", "source_id": "doc-1", "file_path": "test_file" }, { "entity_name": "Bob", "entity_type": "person", "description": "Bob is a mathematician.", "source_id": "doc-1", "file_path": "test_file" }, { "entity_name": "Quantum Computing", "entity_type": "technology", "description": "Quantum computing utilizes quantum mechanical phenomena for computation.", "source_id": "doc-1", "file_path": "test_file" } ], "relationships": [ { "src_id": "Alice", "tgt_id": "Bob", "description": "Alice and Bob are research partners.", "keywords": "collaboration research", "weight": 1.0, "source_id": "doc-1", "file_path": "test_file" }, { "src_id": "Alice", "tgt_id": "Quantum Computing", "description": "Alice conducts research on quantum computing.", "keywords": "research expertise", "weight": 1.0, "source_id": "doc-1", "file_path": "test_file" }, { "src_id": "Bob", "tgt_id": "Quantum Computing", "description": "Bob researches quantum computing.", "keywords": "research application", "weight": 1.0, "source_id": "doc-1", "file_path": "test_file" } ] } rag.insert_custom_kg(custom_kg) ```

其他实体和关系操作

- **create_entity**: 使用指定属性创建新实体 - **edit_entity**: 更新现有实体的属性或重命名它 - **create_relation**: 在现有实体之间创建新关系 - **edit_relation**: 更新现有关系的属性 这些操作在图数据库和向量数据库组件之间保持数据一致性，确保您的知识图谱保持连贯。

## 删除功能 LightRAG 提供全面的删除功能，允许您删除文档、实体和关系。

删除实体

您可以按名称删除实体以及所有关联的关系： ``` # 删除实体及其所有关系（同步版本） rag.delete_by_entity("Google") # 异步版本 await rag.adelete_by_entity("Google") ``` 删除实体时： - 从知识图谱中移除实体节点 - 删除所有关联的关系 - 从向量数据库中移除相关的 Embedding 向量 - 维护知识图谱完整性

删除关系

您可以删除两个特定实体之间的关系： ``` # 删除两个实体之间的关系（同步版本） rag.delete_by_relation("Google", "Gmail") # 异步版本 await rag.adelete_by_relation("Google", "Gmail") ``` 删除关系时： - 移除指定的关系边 - 从向量数据库中删除关系的 Embedding 向量 - 保留两个实体节点及其其他关系

按文档 ID 删除

您可以通过文档 ID 删除整个文档及其所有相关知识： ``` # 按文档 ID 删除（异步版本） await rag.adelete_by_doc_id("doc-12345") ``` 按文档 ID 删除时的优化处理： - **智能清理**: 自动识别并删除仅属于此文档的实体和关系 - **保留共享知识**: 如果实体或关系存在于其他文档中，它们将被保留并重建其描述 - **缓存优化**: 清除相关的 LLM 缓存以减少存储开销 - **增量重建**: 从剩余文档中重建受影响的实体和关系描述 删除过程包括： 1. 删除与文档相关的所有文本块 2. 识别并删除仅属于此文档的实体和关系 3. 重建仍然存在于其他文档中的实体和关系 4. 更新所有相关的向量索引 5. 清理文档状态记录 注意：按文档 ID 删除是一个异步操作，因为它涉及复杂的知识图谱重建过程。

**重要提醒：** 1. **不可逆操作**: 所有删除操作都是不可逆的，请谨慎使用 2. **性能注意事项**: 删除大量数据可能需要一些时间，特别是按文档 ID 删除 3. **数据一致性**: 删除操作自动维护知识图谱和向量数据库之间的一致性 4. **备份建议**: 考虑在执行重要删除操作之前备份数据 **批量删除建议：** - 对于批量删除操作，考虑使用异步方法以获得更好的性能 - 对于大规模删除，考虑分批处理以避免系统负载过高 ## 实体合并

合并实体及其关系

LightRAG 现在支持将多个实体合并为单个实体，自动处理所有关系： ``` # 基本实体合并 rag.merge_entities( source_entities=["Artificial Intelligence", "AI", "Machine Intelligence"], target_entity="AI Technology" ) ``` 使用自定义合并策略： ``` # 为不同字段定义自定义合并策略 rag.merge_entities( source_entities=["John Smith", "Dr. Smith", "J. Smith"], target_entity="John Smith", merge_strategy={ "description": "concatenate", # Combine all descriptions "entity_type": "keep_first", # Keep the entity type from the first entity "source_id": "join_unique" # Combine all unique source IDs } ) ``` 使用自定义目标实体数据： ``` # 为合并后的实体指定确切值 rag.merge_entities( source_entities=["New York", "NYC", "Big Apple"], target_entity="New York City", target_entity_data={ "entity_type": "LOCATION", "description": "New York City is the most populous city in the United States.", } ) ``` 结合两种方法的高级用法： ``` # 结合策略和自定义数据合并公司实体 rag.merge_entities( source_entities=["Microsoft Corp", "Microsoft Corporation", "MSFT"], target_entity="Microsoft", merge_strategy={ "description": "concatenate", # Combine all descriptions "source_id": "join_unique" # Combine source IDs }, target_entity_data={ "entity_type": "ORGANIZATION", } ) ``` 合并实体时： * 来自源实体的所有关系都重定向到目标实体 * 重复的关系被智能合并 * 防止自关系（循环） * 合并后移除源实体 * 保留关系权重和属性

## 多模态文档处理 (RAG-Anything 集成) LightRAG 现在与 [RAG-Anything](https://github.com/HKUDS/RAG-Anything) 无缝集成，这是一个专为 LightRAG 构建的全面**多模态文档处理 RAG 系统**。RAG-Anything 实现了高级解析和检索增强生成 (RAG) 能力，允许您无缝处理多模态文档，并从各种文档格式中提取结构化内容——包括文本、图像、表格和公式——以集成到您的 RAG pipeline 中。 **主要特性：** - **端到端多模态 Pipeline**: 从文档摄取和解析到智能多模态问答的完整工作流 - **通用文档支持**: 无缝处理 PDF、Office 文档 (DOC/DOCX/PPT/PPTX/XLS/XLSX)、图像和各种文件格式 - **专业化内容分析**: 用于图像、表格、数学公式和异构内容类型的专用处理器 - **多模态知识图谱**: 自动实体提取和跨模态关系发现以增强理解 - **混合智能检索**: 跨文本和多模态内容的高级搜索能力，具有上下文理解 **快速开始：** 1. 安装 RAG-Anything: pip install raganything 2. 处理多模态文档：

RAGAnything 使用示例

import asyncio from raganything import RAGAnything from lightrag import LightRAG from lightrag.llm.openai import openai_complete_if_cache, openai_embed from lightrag.utils import EmbeddingFunc import os async def load_existing_lightrag(): # First, create or load an existing LightRAG instance lightrag_working_dir = "./existing_lightrag_storage" # Check if previous LightRAG instance exists if os.path.exists(lightrag_working_dir) and os.listdir(lightrag_working_dir): print("✅ Found existing LightRAG instance, loading...") else: print("❌ No existing LightRAG instance found, will create new one") from functools import partial # Create/Load LightRAG instance with your configurations lightrag_instance = LightRAG( working_dir=lightrag_working_dir, ll_model_func=lambda prompt, system_prompt=None, history_messages=[], **kwargs: openai_complete_if_cache( "gpt-4o-mini", prompt, system_prompt=system_prompt, history_messages=history_messages, api_key="your-api-key", **kwargs, ), embedding_func=EmbeddingFunc( embedding_dim=3072, max_token_size=8192, model="text-embedding-3-large", func=partial( openai_embed.func, # Use .func to access the unwrapped function model="text-embedding-3-large", api_key=api_key, base_url=base_url, ), ) ) # Initialize storage (this will load existing data if available) await lightrag_instance.initialize_storages() # Now initialize RAGAnything with the existing LightRAG instance rag = RAGAnything( lightrag=lightrag_instance, # Pass the existing LightRAG instance # Only need vision model for multimodal processing vision_model_func=lambda prompt, system_prompt=None, history_messages=[], image_data=None, **kwargs: openai_complete_if_cache( "gpt-4o", "", system_prompt=None, history_messages=[], messages=[ {"role": "system", "content": system_prompt} if system_prompt else None, {"role": "user", "content": [ {"type": "text", "text": prompt}, {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}} ]} if image_data else {"role": "user", "content": prompt} ], api_key="your-api-key", **kwargs, ) if image_data else openai_complete_if_cache( "gpt-4o-mini", prompt, system_prompt=system_prompt, history_messages=history_messages, api_key="your-api-key", **kwargs, ) # Note: working_dir, llm_model_func, embedding_func, etc. are inherited from lightrag_instance ) # Query the existing knowledge base result = await rag.query_with_multimodal( "What data has been processed in this LightRAG instance?", mode="hybrid" ) print("Query result:", result) # Add new multimodal documents to the existing LightRAG instance await rag.process_document_complete( file_path="path/to/new/multimodal_document.pdf", output_dir="./output" ) if __name__ == "__main__": asyncio.run(load_existing_lightrag())

有关详细的文档和高级用法，请参阅 [RAG-Anything 仓库](https://github.com/HKUDS/RAG-Anything)。 ## Token 使用追踪

概述和用法

LightRAG 提供了一个 TokenTracker 工具来监控和管理大型语言模型的 Token 消耗。此功能对于控制 API 成本和优化性能特别有用。 ### 用法 ``` from lightrag.utils import TokenTracker # 创建 TokenTracker 实例 token_tracker = TokenTracker() # 方法 1：使用上下文管理器（推荐） # 适用于需要自动 token 使用跟踪的场景 with token_tracker: result1 = await llm_model_func("your question 1") result2 = await llm_model_func("your question 2") # 方法 2：手动添加 token 使用记录 # 适用于需要对 token 统计进行更精细控制的场景 token_tracker.reset() rag.insert() rag.query("your question 1", param=QueryParam(mode="naive")) rag.query("your question 2", param=QueryParam(mode="mix")) # 显示总 token 使用量（包括插入和查询操作） print("Token usage:", token_tracker.get_usage()) ``` ### 使用技巧 - 对长时间会话或批处理操作使用上下文管理器，以自动追踪所有 Token 消耗 - 对于需要分段统计的场景，使用手动模式并在适当时调用 reset() - 定期检查 Token 使用情况有助于及早发现异常消耗 - 在开发和测试期间积极使用此功能，以优化生产成本 ### 实践示例 您可以参考这些示例来实现 Token 追踪： - `examples/lightrag_gemini_track_token_demo.py`: 使用 Google Gemini 模型的 Token 追踪示例 - `examples/lightrag_siliconcloud_track_token_demo.py`: 使用 SiliconCloud 模型的 Token 追踪示例 这些示例演示了如何在不同模型和场景下有效使用 TokenTracker 功能。

## 数据导出功能 ### 概述 LightRAG 允许您以各种格式导出知识图谱数据，用于分析、共享和备份目的。系统支持导出实体、关系和关系数据。 ### 导出功能

基本用法

``` # 基本 CSV 导出（默认格式） rag.export_data("knowledge_graph.csv") # 指定任意格式 rag.export_data("output.xlsx", file_format="excel") ```

支持的不同文件格式

``` #Export data in CSV format rag.export_data("graph_data.csv", file_format="csv") # 将数据导出到 Excel 表格 rag.export_data("graph_data.xlsx", file_format="excel") # 以 markdown 格式导出数据 rag.export_data("graph_data.md", file_format="md") # 以文本格式导出数据 rag.export_data("graph_data.txt", file_format="txt") ```

附加选项

在导出中包含向量 Embedding（可选）： ``` rag.export_data("complete_data.csv", include_vector_data=True) ```

### 导出中包含的数据 所有导出包括： * 实体信息（名称、ID、元数据） * 关系数据（实体之间的连接） * 向量数据库中的关系信息 ## 缓存

清除缓存

您可以使用 `aclear_cache()` 清除已配置的 LLM 响应缓存存储。此 API 清除 `llm_response_cache` 中的所有缓存条目，不支持按模式或缓存类型进行选择性清理。 ``` # 清除所有缓存 await rag.aclear_cache() # 同步版本 rag.clear_cache() ``` 要对查询相关缓存进行选择性清理，请使用 `lightrag.tools.clean_llm_query_cache` 工具，并参阅 [lightrag/tools/README_CLEAN_LLM_QUERY_CACHE.md](./lightrag/tools/README_CLEAN_LLM_QUERY_CACHE.md) 中的指南。它管理 `mix`, `hybrid`, `local`, 和 `global` 模式的查询缓存和关键字缓存。它不会清理提取缓存，例如 `default:extract:*` 和 `default:summary:*`。

## 故障排除 ### 常见初始化错误 如果在使用 LightRAG 时遇到这些错误： 1. **`AttributeError: __aenter__`** - **原因**: 存储后端未初始化 - **解决方法**: 创建 LightRAG 实例后调用 `await rag.initialize_storages()` 2. **`KeyError: 'history_messages'`** - **原因**: Pipeline 状态未初始化 - **解决方法**: 创建 LightRAG 实例后调用 `await rag.initialize_storages()` 3. **连续出现这两个错误** - **原因**: 没有调用任何初始化方法 - **解决方法**: 始终遵循此模式： rag = LightRAG(...) await rag.initialize_storages() ### 模型切换问题 在切换不同的 Embedding 模型时，必须清除数据目录以避免错误。如果您希望保留 LLM 缓存，您可能希望保留的唯一文件是 `kv_store_llm_response_cache.json`。 ## LightRAG API LightRAG Server 旨在提供 Web UI 和 API 支持。**有关 LightRAG Server 的更多信息，请参阅 [LightRAG Server](./lightrag/api/README.md)。** ## 图可视化 LightRAG Server 提供全面的知识图谱可视化功能。它支持各种重力布局、节点查询、子图过滤等。**有关 LightRAG Server 的更多信息，请参阅 [LightRAG Server](./lightrag/api/README.md)。**  ## Langfuse 可观测性集成 Langfuse 提供了 OpenAI 客户端的直接替代品，可自动追踪所有 LLM 交互，使开发人员能够在不更改代码的情况下监控、调试和优化其 RAG 系统。 ### 带 Langfuse 选项的安装 ``` pip install lightrag-hku pip install lightrag-hku[observability] # 或者从源代码安装并启用调试模式 pip install -e . pip install -e ".[observability]" ``` ### 配置 Langfuse 环境变量 修改 .env 文件： ``` ## Langfuse Observability（可选） # LLM 可观测性和追踪平台 # 安装使用：pip install lightrag-hku[observability] # 注册地址：https://cloud.langfuse.com 或自托管 LANGFUSE_SECRET_KEY="" LANGFUSE_PUBLIC_KEY="" LANGFUSE_HOST="https://cloud.langfuse.com" # or your self-hosted instance LANGFUSE_ENABLE_TRACE=true ``` ### Langfuse 用法 安装并配置后，Langfuse 会自动追踪所有 OpenAI LLM 调用。Langfuse 仪表板功能包括： - **追踪**: 查看完整的 LLM 调用链 - **分析**: Token 使用情况、延迟、成本指标 - **调试**: 检查提示和响应 - **评估**: 比较模型输出 - **监控**: 实时告警 ### 重要通知 **注意**: LightRAG 目前仅将兼容 OpenAI 的 API 调用与 Langfuse 集成。诸如 Ollama、Azure 和 AWS Bedrock 之类的 API 尚不支持 Langfuse 可观测性。 ## 基于 RAGAS 的评估 **RAGAS** (Retrieval Augmented Generation Assessment) 是一个使用 LLM 对 RAG 系统进行无参考评估的框架。有一个基于 RAGAS 的评估脚本。有关详细信息，请参阅 [RAGAS-based Evaluation Framework](lightrag/evaluation/README_EVALUASTION_RAGAS.md)。 ## 评估 ### 数据集 LightRAG 中使用的数据集可以从 [TommyChien/UltraDomain](https://huggingface.co/datasets/TommyChien/UltraDomain) 下载。 ### 生成查询 LightRAG 使用以下提示生成高级查询，相应代码在 `examples/generate_query.py` 中。

提示

``` Given the following description of a dataset: {description} Please 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. Output the results in the following structure: - User 1: [user description] - Task 1: [task description] - Question 1: - Question 2: - Question 3: - Question 4: - Question 5: - Task 2: [task description] ... - Task 5: [task description] - User 2: [user description] ... - User 5: [user description] ... ```

### 批量评估 为了评估两个 RAG 系统在高级查询上的性能，LightRAG 使用以下提示，具体代码可在 `reproduce/batch_eval.py` 中找到。

提示

``` ---Role--- You are an expert tasked with evaluating two answers to the same question based on three criteria: **Comprehensiveness**, **Diversity**, and **Empowerment**. ---Goal--- You will evaluate two answers to the same question based on three criteria: **Comprehensiveness**, **Diversity**, and **Empowerment**. - **Comprehensiveness**: How much detail does the answer provide to cover all aspects and details of the question? - **Diversity**: How varied and rich is the answer in providing different perspectives and insights on the question? - **Empowerment**: How well does the answer help the reader understand and make informed judgments about the topic? For 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. Here is the question: {query} Here are the two answers: **Answer 1:** {answer1} **Answer 2:** {answer2} Evaluate both answers using the three criteria listed above and provide detailed explanations for each criterion. Output your evaluation in the following JSON format: {{ "Comprehensiveness": {{ "Winner": "[Answer 1 or Answer 2]", "Explanation": "[Provide explanation here]" }}, "Empowerment": {{ "Winner": "[Answer 1 or Answer 2]", "Explanation": "[Provide explanation here]" }}, "Overall Winner": {{ "Winner": "[Answer 1 or Answer 2]", "Explanation": "[Summarize why this answer is the overall winner based on the three criteria]" }} }} ```

### 整体性能表 ||**Agriculture**||**CS**||**Legal**||**Mix**|| |----------------------|---------------|------------|------|------------|---------|------------|-------|------------| ||NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**|NaiveRAG|**LightRAG**| |**Comprehensiveness**|32.4%|**67.6%**|38.4%|**61.6%**|16.4%|**83.6%**|38.8%|**61.2%**| |**Diversity**|23.6%|**76.4%**|38.0%|**62.0%**|13.6%|**86.4%**|32.4%|**67.6%**| |**Empowerment**|32.4%|**67.6%**|38.8%|**61.2%**|16.4%|**83.6%**|42.8%|**57.2%**| |**Overall**|32.4%|**67.6%**|38.8%|**61.2%**|15.2%|**84.8%**|40.0%|**60.0%**| ||RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**|RQ-RAG|**LightRAG**| |**Comprehensiveness**|31.6%|**68.4%**|38.8%|**61.2%**|15.2%|**84.8%**|39.2%|**60.8%**| |**Diversity**|29.2%|**70.8%**|39.2%|**60.8%**|11.6%|**88.4%**|30.8%|**69.2%**| |**Empowerment**|31.6%|**68.4%**|36.4%|**63.6%**|15.2%|**84.8%**|42.4%|**57.6%**| |**Overall**|32.4%|**67.6%**|38.0%|**62.0%**|14.4%|**85.6%**|40.0%|**60.0%**| ||HyDE|**LightRAG**|HyDE|**LightRAG**|HyDE|**LightRAG**|HyDE|**LightRAG**| |**Comprehensiveness**|26.0%|**74.0%**|41.6%|**58.4%**|26.8%|**73.2%**|40.4%|**59.6%**| |**Diversity**|24.0%|**76.0%**|38.8%|**61.2%**|20.0%|**80.0%**|32.4%|**67.6%**| |**Empowerment**|25.2%|**74.8%**|40.8%|**59.2%**|26.0%|**74.0%**|46.0%|**54.0%**| |**Overall**|24.8%|**75.2%**|41.6%|**58.4%**|26.4%|**73.6%**|42.4%|**57.6%**| ||GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|GraphRAG|**LightRAG**|GraphRAG|**LightRAG**| |**Comprehensiveness**|45.6%|**54.4%**|48.4%|**51.6%**|48.4%|**51.6%**|**50.4%**|49.6%| |**Diversity**|22.8%|**77.2%**|40.8%|**59.2%**|26.4%|73.6%**|36.0%|**64.0%**| |**Empowerment**|41.2%|**58.8%**|45.2%|**54.8%**|43.6%|**56.4%**|**50.8%**|49.2%| |**Overall**|45.2%|**54.8%**|48.0%|**52.0%**|47.2%|**52.8%**|**50.4%**|49.6%| ## 复现 所有代码都可以在 `./reproduce` 目录中找到。 ### 步骤 0 提取唯一上下文 首先，我们需要提取数据集中的唯一上下文。

代码

``` def extract_unique_contexts(input_directory, output_directory): os.makedirs(output_directory, exist_ok=True) jsonl_files = glob.glob(os.path.join(input_directory, '*.jsonl')) print(f"Found {len(jsonl_files)} JSONL files.") for file_path in jsonl_files: filename = os.path.basename(file_path) name, ext = os.path.splitext(filename) output_filename = f"{name}_unique_contexts.json" output_path = os.path.join(output_directory, output_filename) unique_contexts_dict = {} print(f"Processing file: {filename}") try: with open(file_path, 'r', encoding='utf-8') as infile: for line_number, line in enumerate(infile, start=1): line = line.strip() if not line: continue try: json_obj = json.loads(line) context = json_obj.get('context') if context and context not in unique_contexts_dict: unique_contexts_dict[context] = None except json.JSONDecodeError as e: print(f"JSON decoding error in file {filename} at line {line_number}: {e}") except FileNotFoundError: print(f"File not found: {filename}") continue except Exception as e: print(f"An error occurred while processing file {filename}: {e}") continue unique_contexts_list = list(unique_contexts_dict.keys()) print(f"There are {len(unique_contexts_list)} unique `context` entries in the file {filename}.") try: with open(output_path, 'w', encoding='utf-8') as outfile: json.dump(unique_contexts_list, outfile, ensure_ascii=False, indent=4) print(f"Unique `context` entries have been saved to: {output_filename}") except Exception as e: print(f"An error occurred while saving to the file {output_filename}: {e}") print("All files have been processed.") ```

### 步骤 1 插入上下文 对于提取的上下文，我们将它们插入到 LightRAG 系统中。

代码

``` def insert_text(rag, file_path): with open(file_path, mode='r') as f: unique_contexts = json.load(f) retries = 0 max_retries = 3 while retries < max_retries: try: rag.insert(unique_contexts) break except Exception as e: retries += 1 print(f"Insertion failed, retrying ({retries}/{max_retries}), error: {e}") time.sleep(10) if retries == max_retries: print("Insertion failed after exceeding the maximum number of retries") ```

### 步骤 2 生成查询 我们从数据集中每个上下文的前半部分和后半部分提取 Token，然后将它们组合作为数据集描述来生成查询。

代码

``` tokenizer = GPT2Tokenizer.from_pretrained('gpt2') def get_summary(context, tot_tokens=2000): tokens = tokenizer.tokenize(context) half_tokens = tot_tokens // 2 start_tokens = tokens[1000:1000 + half_tokens] end_tokens = tokens[-(1000 + half_tokens):1000] summary_tokens = start_tokens + end_tokens summary = tokenizer.convert_tokens_to_string(summary_tokens) return summary ```

### 步骤 3 查询 对于步骤 2 中生成的查询，我们将提取它们并查询 LightRAG。

代码

``` def extract_queries(file_path): with open(file_path, 'r') as f: data = f.read() data = data.replace('**', '') queries = re.findall(r'- Question \d+: (.+)', data) return queries ```

## 🔗 相关项目 *生态与扩展* ## ⭐ Star 历史 ## 🤝 贡献 ## 📖 引用 ``` @article{guo2024lightrag, title={LightRAG: Simple and Fast Retrieval-Augmented Generation}, author={Zirui Guo and Lianghao Xia and Yanhua Yu and Tu Ao and Chao Huang}, year={2024}, eprint={2410.05779}, archivePrefix={arXiv}, primaryClass={cs.IR} } ```

标签：AI风险缓解, Apex, DLL 劫持, DNS解析, EMNLP2025, GraphRAG, HKUDS, LightRAG, Petitpotam, Python, RAG, 人工智能, 向量数据库, 大语言模型, 开源搜索引擎, 开源项目, 搜索引擎查询, 文本生成, 无后门, 智能问答, 机器学习, 检索增强生成, 测试用例, 深度学习, 用户模式Hook绕过, 语义检索, 请求拦截, 逆向工具