安装

安装 LightRAG Core

• 从源码安装（推荐）

  1. cd LightRAG
  2. pip install -e .

• 通过 PyPI 安装

  1. pip install lightrag-hku

安装 LightRAG Server

LightRAG Server 旨在提供 Web 界面和 API 支持。Web 界面方便进行文档索引、知识图谱探索和简单的 RAG 查询。它同时提供与 Ollama 兼容的接口，可将 LightRAG 模拟为 Ollama 聊天模型，便于 Open WebUI 等 AI 聊天机器人接入。

• 通过 PyPI 安装

  1. pip install "lightrag-hku[api]"

• 从源码安装

  1. # 按需创建 Python 虚拟环境
  2. # 以可编辑模式安装并包含 API 支持
  3. pip install -e ".[api]"

关于 LightRAG Server 的更多信息，请参考 LightRAG Server。

快速开始

• 本地运行 视频演示 • 所有示例代码可在 examples 目录找到 • 使用 OpenAI 模型时需设置环境变量：export OPENAI_API_KEY="sk-..." • 下载示例文本《圣诞颂歌》：

  1. curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt

查询

使用以下 Python 代码初始化 LightRAG 并执行查询：

  1. import os
  2. import asyncio
  3. from lightrag import LightRAG, QueryParam
  4. from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed
  5. from lightrag.kg.shared_storage import initialize_pipeline_status
  6. from lightrag.utils import setup_logger
  8. setup_logger("lightrag", level="INFO")
  10. async def initialize_rag():
  11.     rag = LightRAG(
  12.         working_dir="your/path",
  13.         embedding_func=openai_embed,
  14.         llm_model_func=gpt_4o_mini_complete
  15.     )
  17.     await rag.initialize_storages()
  18.     await initialize_pipeline_status()
  20.     return rag
  22. def main():
  23.     # 初始化 RAG 实例
  24.     rag = asyncio.run(initialize_rag())
  25.     # 插入文本
  26.     rag.insert("Your text")
  28.     # 基础搜索模式
  29.     mode="naive"
  30.     # 本地搜索模式
  31.     mode="local"
  32.     # 全局搜索模式
  33.     mode="global"
  34.     # 混合搜索模式
  35.     mode="hybrid"
  36.     # 混合模式（结合知识图谱与向量检索）
  37.     mode="mix"
  39.     rag.query(
  40.         "What are the top themes in this story?",
  41.         param=QueryParam(mode=mode)
  42.     )
  44. if __name__ == "__main__":
  45.     main()

查询参数

  1. class QueryParam:
  2.     mode: Literal["local", "global", "hybrid", "naive", "mix"] = "global"
  3.     """检索模式说明：
  4.     - "local": 聚焦上下文相关信息
  5.     - "global": 利用全局知识
  6.     - "hybrid": 结合本地与全局检索
  7.     - "naive": 基础搜索模式
  8.     - "mix": 整合知识图谱与向量检索：
  9.         - 同时使用结构化（KG）与非结构化（向量）信息
  10.         - 通过分析关联关系提供全面回答
  11.         - 支持 HTML img 标签处理图像内容
  12.         - 通过 top_k 参数控制检索深度"""
  13.     only_need_context: bool = False
  14.     """设为 True 时仅返回检索上下文不生成回答"""
  15.     response_type: str = "Multiple Paragraphs"
  16.     """回答格式，可选：'Multiple Paragraphs', 'Single Paragraph', 'Bullet Points'"""
  17.     top_k: int = 60
  18.     """检索条目数量，'local' 模式表示实体数，'global' 模式表示关系数"""
  19.     max_token_for_text_unit: int = 4000
  20.     """单个文本块最大 token 限制"""
  21.     max_token_for_global_context: int = 4000
  22.     """全局关系描述最大 token 数"""
  23.     max_token_for_local_context: int = 4000
  24.     """本地实体描述最大 token 数"""
  25.     ids: list[str] | None = None # 仅 PG 向量数据库支持
  26.     """文档 ID 过滤列表"""
  27.     model_func: Callable[..., object] | None = None
  28.     """本次查询专用的 LLM 模型函数"""
  29.     ...

可通过环境变量 TOP_K 修改 top_k 默认值

模型注入

LightRAG 需通过 LLM 和 Embedding 模型完成文档索引与查询，初始化时需注入模型调用方法：

使用 OpenAI 类 API • 支持 OpenAI 类聊天/嵌入 API： python 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 ) async def embedding_func(texts: list[str]) -> np.ndarray: return await openai_embed( 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=EmbeddingFunc( embedding_dim=4096, max_token_size=8192, func=embedding_func ) ) await rag.initialize_storages() await initialize_pipeline_status() return rag
使用 Hugging Face 模型 • 使用 Hugging Face 模型配置示例： 参考 lightrag_hf_demo.py python rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=hf_model_complete, llm_model_name='meta-llama/Llama-3.1-8B-Instruct', embedding_func=EmbeddingFunc( embedding_dim=384, max_token_size=5000, func=lambda texts: hf_embed( texts, tokenizer=AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2"), embed_model=AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") ) ), )
使用 Ollama 模型 准备工作 1. 拉取所需模型及嵌入模型（如 nomic-embed-text） 2. 基础配置： python rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=ollama_model_complete, llm_model_name='your_model_name', embedding_func=EmbeddingFunc( embedding_dim=768, max_token_size=8192, func=lambda texts: ollama_embed( texts, embed_model="nomic-embed-text" ) ), ) • 扩展上下文 通过以下方式扩展上下文至 32k tokens： 1. 修改 Modelfile： bash ollama show --modelfile qwen2 > Modelfile # 添加 PARAMETER num_ctx 32768 ollama create -f Modelfile qwen2m 2. 通过 API 配置： python llm_model_kwargs={"options": {"num_ctx": 32768}} • 低显存 GPU 优化 选择小模型并调整上下文窗口（如 gemma2:2b 配合 26k 上下文），可在 6GB 显存设备处理 197 实体 19 关系的文档。
LlamaIndex 集成 支持通过 LlamaIndex 接入 OpenAI 等模型： python from lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed rag = LightRAG( working_dir="your/path", llm_model_func=llama_index_complete_if_cache, embedding_func=EmbeddingFunc( embedding_dim=1536, max_token_size=8192, func=lambda texts: llama_index_embed(texts, embed_model=embed_model) ), ) 详细文档参考： • LlamaIndex 文档 • OpenAI 直连示例 • LiteLLM 代理示例

令牌追踪

使用说明 通过 TokenTracker 监控 LLM 令牌消耗： python from lightrag.utils import TokenTracker # 自动追踪（推荐） with TokenTracker() as tracker: result1 = await llm_model_func("问题1") result2 = await llm_model_func("问题2") print("总消耗:", tracker.get_usage()) # 手动模式 tracker.reset() rag.insert() rag.query(...) print("分阶段统计:", tracker.get_usage()) 应用场景： • 开发测试时优化 token 消耗 • 批量处理时成本控制 • 异常消耗检测 参考示例： • examples/lightrag_gemini_track_token_demo.py • examples/lightrag_siliconcloud_track_token_demo.py

对话历史支持

支持多轮对话上下文管理：

使用示例 python conversation_history = [ {"role": "user", "content": "主角对圣诞节的态度如何？"}, {"role": "assistant", "content": "故事开始时，Scrooge 对圣诞节持负面态度..."} ] response = rag.query( "他态度转变的原因是什么？", param=QueryParam( mode="mix", conversation_history=conversation_history, history_turns=3 ) )

自定义提示

支持定制系统提示模板：

使用示例 python custom_prompt = """ 环境科学专家助手，请提供结构化回答示例： ---对话历史--- {history} ---知识库--- {context_data} ---格式要求--- {response_type} """ response = rag.query( "可再生能源的主要优势？", param=QueryParam(mode="hybrid"), system_prompt=custom_prompt )

智能关键词提取

新增 query_with_separate_keyword_extraction 方法优化关键词提取：

使用示例 python rag.query_with_separate_keyword_extraction( query="解释重力定律", prompt="为高中生物理学习提供详细解释", param=QueryParam(mode="hybrid") )

文档插入

基础操作 python # 单文档插入 rag.insert("文本内容") # 批量插入（默认每批10个文档） rag.insert(["文档1", "文档2"...]) # 自定义批次大小 rag = LightRAG(addon_params={"insert_batch_size": 4})
带ID插入 python # 单文档带ID rag.insert("文档内容", ids=["自定义ID"]) # 批量带ID插入 rag.insert(["文档1", "文档2"], ids=["ID1", "ID2"])
流水线处理 python # 异步文档队列处理 await rag.apipeline_enqueue_documents(input) await rag.apipeline_process_enqueue_documents(input)
多格式文件支持 python import textract text_content = textract.process("TEXT.pdf") rag.insert(text_content.decode('utf-8'))
自定义知识图谱 python custom_kg = { "chunks": [...], "entities": [...], "relationships": [...] } rag.insert_custom_kg(custom_kg)
文献溯源 python rag.insert( ["文档内容1", "文档内容2"], file_paths=["path/to/doc1.txt", "path/to/doc2.txt"] )

存储配置

Neo4J 生产级部署 1. 启动 Neo4J 容器： bash docker run -p 7474:7474 -p 7687:7687 neo4j 2. 环境变量配置： bash export NEO4J_URI="neo4j://localhost:7687" export NEO4J_USERNAME="neo4j" export NEO4J_PASSWORD="password" 3. 代码配置： python rag = LightRAG( graph_storage="Neo4JStorage", ... ) 完整示例参考 test_neo4j.py
使用 PostgreSQL 存储 对于生产级场景，推荐采用 PostgreSQL 作为一站式解决方案，其整合了 KV 存储、向量数据库（pgvector）和图数据库（apache AGE）功能： • 轻量化部署：完整二进制分发包（含必要插件）仅 40MB，推荐使用 Windows 发行版 进行跨平台部署 • Docker 快速上手：可使用预配置镜像 shangor/postgres-for-rag 快速搭建环境 • 示例参考：完整实现详见 examples/lightrag_zhipu_postgres_demo.py • 索引优化示例（将 dickens 替换为实际图谱名称）： sql load 'age'; SET search_path = ag_catalog, "$user", public; -- 创建索引系列 CREATE INDEX CONCURRENTLY entity_p_idx ON dickens."Entity" (id); CREATE INDEX CONCURRENTLY vertex_p_idx ON dickens."_ag_label_vertex" (id); CREATE INDEX CONCURRENTLY directed_p_idx ON dickens."DIRECTED" (id); CREATE INDEX CONCURRENTLY directed_eid_idx ON dickens."DIRECTED" (end_id); CREATE INDEX CONCURRENTLY directed_sid_idx ON dickens."DIRECTED" (start_id); CREATE INDEX CONCURRENTLY directed_seid_idx ON dickens."DIRECTED" (start_id,end_id); CREATE INDEX CONCURRENTLY edge_p_idx ON dickens."_ag_label_edge" (id); CREATE INDEX CONCURRENTLY edge_sid_idx ON dickens."_ag_label_edge" (start_id); CREATE INDEX CONCURRENTLY edge_eid_idx ON dickens."_ag_label_edge" (end_id); CREATE INDEX CONCURRENTLY edge_seid_idx ON dickens."_ag_label_edge" (start_id,end_id); create INDEX CONCURRENTLY vertex_idx_node_id ON dickens."_ag_label_vertex" (ag_catalog.agtype_access_operator(properties, '"node_id"'::agtype)); create INDEX CONCURRENTLY entity_idx_node_id ON dickens."Entity" (ag_catalog.agtype_access_operator(properties, '"node_id"'::agtype)); CREATE INDEX CONCURRENTLY entity_node_id_gin_idx ON dickens."Entity" using gin(properties); ALTER TABLE dickens."DIRECTED" CLUSTER ON directed_sid_idx; -- 索引删除示例 drop INDEX entity_p_idx; ... • 已知问题：Apache AGE 官方版本存在节点/边属性缺失问题，可通过源码编译修复（参考 GitHub PR #1721）
使用 Faiss 存储 • 安装依赖： pip install faiss-cpu （GPU 版本请安装 faiss-gpu） • 配置示例（使用 sentence-transformers 模型）： python 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 # 初始化配置 rag = LightRAG( working_dir=WORKING_DIR, llm_model_func=llm_model_func, embedding_func=EmbeddingFunc( embedding_dim=384, max_token_size=8192, func=embedding_func, ), vector_storage="FaissVectorDBStorage", vector_db_storage_cls_kwargs={ "cosine_better_than_threshold": 0.3 # 相似度阈值 } )

数据删除

  1. # 按实体名删除
  2. rag.delete_by_entity("Project Gutenberg")
  4. # 按文档 ID 删除关联数据
  5. rag.delete_by_doc_id("doc_id")

知识图谱编辑

支持实体与关系的全生命周期管理：

创建实体关系 python # 创建实体 entity = rag.create_entity("Google", { "description": "谷歌是全球领先的科技公司", "entity_type": "企业" }) # 创建关联关系 relation = rag.create_relation("Google", "Gmail", { "description": "谷歌开发并运营Gmail", "keywords": "开发 运营 服务", "weight": 2.0 })
编辑实体关系 python # 更新实体属性 updated_entity = rag.edit_entity("Google", { "description": "Alphabet 旗下子公司，成立于1998年", "entity_type": "科技企业" }) # 重命名实体（自动迁移关联关系） renamed_entity = rag.edit_entity("Gmail", { "entity_name": "谷歌邮箱", "description": "谷歌提供的电子邮件服务" }) # 更新关系属性 updated_relation = rag.edit_relation("Google", "谷歌邮箱", { "description": "谷歌创建并维护邮箱服务", "keywords": "创建 维护 服务", "weight": 3.0 }) > 所有操作均支持同步/异步版本（异步方法前缀为 a）

数据导出

功能概览

支持将知识图谱导出为多种格式：

基础用法 python # 默认 CSV 格式导出 rag.export_data("knowledge_graph.csv") # 指定 Excel 格式 rag.export_data("output.xlsx", file_format="excel")
格式支持 python # CSV 格式 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")
高级选项 包含向量数据导出： python rag.export_data("complete_data.csv", include_vector_data=True)

导出内容

包含：

• 实体元数据 • 关系网络 • 向量数据库关联信息

实体合并

智能实体融合 支持多实体合并与关系迁移： python # 基础合并 rag.merge_entities( source_entities=["人工智能", "AI", "机器智能"], target_entity="AI技术" ) # 自定义合并策略 rag.merge_entities( source_entities=["张三", "张博士", "张工"], target_entity="张三", merge_strategy={ "description": "拼接所有描述", "entity_type": "保留首个实体类型", "source_id": "合并唯一来源ID" } ) # 指定目标属性 rag.merge_entities( source_entities=["纽约", "NYC", "大苹果"], target_entity="纽约市", target_entity_data={ "entity_type": "地理位置", "description": "美国人口最多城市", } ) 合并特性： • 自动迁移所有关联关系 • 消除重复关系 • 防止自循环 • 权重与属性保留

缓存管理

缓存清理 多模式缓存清除： python # 全量清理 await rag.aclear_cache() # 按模式清理 await rag.aclear_cache(modes=["local", "global"]) # 同步方法 rag.clear_cache(modes=["default"]) 有效模式： • "default": 基础提取缓存 • "naive": 基础搜索 • "local": 本地搜索 • "global": 全局搜索 • "hybrid": 混合搜索 • "mix": 混合模式

初始化参数

参数说明 | 参数 | 类型 | 说明 | 默认值 | |————-|—————|————-|—————-| | working_dir | str | 缓存目录 | lightrag_cache+时间戳 | | kv_storage | str | 文档存储类型：JsonKVStorage,PGKVStorage 等 | JsonKVStorage | | vector_storage | str | 向量存储类型：NanoVectorDBStorage,PGVectorStorage 等 | NanoVectorDBStorage | | graph_storage | str | 图谱存储类型：NetworkXStorage,Neo4JStorage 等 | NetworkXStorage | | chunk_token_size | int | 文档分块最大 token 数 | 1200 | | embedding_func | EmbeddingFunc | 文本向量生成函数 | openai_embed | | llm_model_func | callable | LLM 生成函数 | gpt_4o_mini_complete | | llm_model_max_token_size | int | LLM 最大上下文长度 | 32768（可通过环境变量 MAX_TOKENS 修改） | | addon_params | dict | 扩展参数（语言/实体类型/批量大小等） | {"language": "English"} | | embedding_cache_config | dict | 问答缓存配置（相似度阈值/LLM 复核） | {"enabled": False} |

错误处理

点击查看错误处理机制 内置完善的错误处理体系： • 文件未找到错误（404） • 处理过程错误（500） • 多编码支持（UTF-8/GBK）

API 服务

LightRAG Server 提供 Web 界面和 API 支持，详情参考 LightRAG Server 文档。

可视化分析

知识图谱可视化示例

支持特性：

• 多重力布局算法 • 节点查询与子图过滤 • 动态关系分析

性能评估

数据集

采用 TommyChien/UltraDomain 数据集。

查询生成

通过 example/generate_query.py 生成高阶语义查询：

生成提示 python 根据数据集描述生成多用户多任务的高阶语义问题，输出结构化结果。

批量评估

使用 example/batch_eval.py 进行多维度评估：

评估提示 python 从全面性、多样性和信息价值三个维度对比两个答案，输出结构化评估报告。

性能对比

农业领域 计算机 法律 混合
基线模型 LightRAG 基线模型 LightRAG 基线模型 LightRAG 基线模型 LightRAG
全面性 32.4% 67.6% 38.4% 61.6% 16.4% 83.6% 38.8% 61.2%
多样性 23.6% 76.4% 38.0% 62.0% 13.6% 86.4% 32.4% 67.6%
信息价值 32.4% 67.6% 38.8% 61.2% 16.4% 83.6% 42.8% 57.2%

复现指南

所有复现代码位于 ./reproduce 目录。

步骤 0：提取唯一上下文

核心代码 python def extract_unique_contexts(input_dir, output_dir): # 实现跨文件唯一上下文提取 ...

复现步骤

步骤 1：插入上下文

将提取的唯一上下文插入 LightRAG 系统：

核心代码 python 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"插入失败，正在重试 ({retries}/{max_retries})，错误：{e}") time.sleep(10) if retries == max_retries: print("达到最大重试次数后仍插入失败")

步骤 2：生成查询

从数据集上下文中提取关键 token 生成高阶语义查询：

核心代码 python 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：执行查询

对生成的查询进行实际检索：

核心代码 python 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