|
LightRAG 是一款轻量级的 检索增强生成（RAG, Retrieval-Augmented Generation）框架，旨在通过优化检索和生成流程，降低传统 RAG 系统的部署成本与资源消耗，同时保持高效的问答和内容生成能力。它适用于需要快速响应、低算力支持的场景，如智能客服、知识问答、轻量化 AI 助手等。 安装安装 LightRAG 核心模块从源代码安装（推荐） ingFang SC", "Microsoft YaHei", sans-serif;font-size: 14px;margin: 1.2em 0px 24px;line-height: 22px;color: rgb(0, 0, 0);">
pipinstall-e.
通过 PyPI 安装 ingFang SC", "Microsoft YaHei", sans-serif;font-size: 14px;margin: 1.2em 0px 24px;line-height: 22px;color: rgb(0, 0, 0);">
安装 LightRAG 服务端LightRAG 服务端提供 Web 界面和 API 支持，便于文档索引、知识图谱探索和简单的 RAG 查询。同时兼容 Ollama 接口，可模拟为 Ollama 聊天模型，方便 Open WebUI 等 AI 聊天机器人接入。 通过 PyPI 安装 ingFang SC", "Microsoft YaHei", sans-serif;font-size: 14px;margin: 1.2em 0px 24px;line-height: 22px;color: rgb(0, 0, 0);">
从源代码安装 ingFang SC", "Microsoft YaHei", sans-serif;font-size: 14px;margin: 1.2em 0px 24px;line-height: 22px;color: rgb(0, 0, 0);">
# 安装 API 支持的可编辑模式
pipinstall-e".[api]"
更多关于 LightRAG 服务端的信息，请参考LightRAG Server。 快速开始- 本地运行演示视频
- 所有代码示例位于
- 使用 OpenAI 模型时需设置环境变量：
- 下载演示文本《圣诞颂歌》：
curlhttps://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt>./book.txt
查询使用以下 Python 代码初始化 LightRAG 并执行查询： importos
importasyncio
fromlightragimportLightRAG,QueryParam
fromlightrag.llm.openaiimportgpt_4o_mini_complete,gpt_4o_complete,openai_embed
fromlightrag.kg.shared_storageimportinitialize_pipeline_status
fromlightrag.utilsimportsetup_logger
setup_logger("lightrag",level="INFO")
asyncdefinitialize_rag():
rag=LightRAG(
working_dir="your/path",
embedding_func=openai_embed,
llm_model_func=gpt_4o_mini_complete
)
awaitrag.initialize_storages()
awaitinitialize_pipeline_status()
returnrag
defmain():
# 初始化 RAG 实例
rag=asyncio.run(initialize_rag())
# 插入文本
rag.insert("Your text")
# 选择检索模式：朴素搜索、本地搜索、全局搜索、混合搜索、知识图谱与向量混合搜索
mode="mix"
rag.query(
"What are the top themes in this story?",
param=QueryParam(mode=mode)
)
if__name__=="__main__":
main()
查询参数（QueryParam）classQueryParam:
mode iteral["local","global","hybrid","naive","mix"]="global"
"""检索模式：
- "local": 聚焦上下文相关信息
- "global": 利用全局知识
- "hybrid": 结合本地与全局检索
- "naive": 基础搜索（无高级技术）
- "mix": 融合知识图谱与向量检索（支持结构化 KG 和非结构化向量，通过 HTML img 标签处理图像内容，通过 top_k 控制检索深度）
"""
only_need_context:bool=False
"""若为 True，仅返回检索到的上下文，不生成回答"""
response_type:str="Multiple Paragraphs"
"""响应格式（如："多个段落"、"单个段落"、"项目符号"）"""
top_k:int=60
"""检索的 top 数量（本地模式为实体数，全局模式为关系数）"""
max_token_for_text_unit:int=4000
"""每个检索文本块的最大 token 数"""
max_token_for_global_context:int=4000
"""全局检索中关系描述的最大 token 数"""
max_token_for_local_context:int=4000
"""本地检索中实体描述的最大 token 数"""
ids:list[str]|None=None# 仅支持 PG Vector 数据库
"""过滤 RAG 的 ID 列表"""
model_func:Callable[...,object]|None=None
"""可选：覆盖本次查询的 LLM 模型函数（可针对不同模式使用不同模型）"""
...
top_k 的默认值可通过环境变量TOP_K修改。
LLM 与嵌入模型注入LightRAG 需要注入 LLM 和嵌入模型的调用方法以完成文档索引和查询任务。 使用 OpenAI 风格 API asyncdefllm_model_func(
prompt,system_prompt=None,history_messages=[],keyword_extraction=False,**kwargs
)->str:
returnawaitopenai_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
)
asyncdefembedding_func(texts:list[str])->np.ndarray:
returnawaitopenai_embed(
texts,
model="solar-embedding-1-large-query",
api_key=os.getenv("UPSTAGE_API_KEY"),
base_url="https://api.upstage.ai/v1/solar"
)
asyncdefinitialize_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
)
)
awaitrag.initialize_storages()
awaitinitialize_pipeline_status()
returnrag
使用 Hugging Face 模型 参考lightrag_hf_demo.py： # 初始化 LightRAG 并使用 Hugging Face 模型
rag=LightRAG(
working_dir=WORKING_DIR,
llm_model_func=hf_model_complete,# Hugging Face 文本生成模型
llm_model_name='meta-llama/Llama-3.1-8B-Instruct',# Hugging Face 模型名称
# 使用 Hugging Face 嵌入函数
embedding_func=EmbeddingFunc(
embedding_dim=384,
max_token_size=5000,
func=lambdatexts: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 模型 概述：需先拉取模型（如文本生成模型和嵌入模型nomic-embed-text）： # 初始化 LightRAG 并使用 Ollama 模型
rag=LightRAG(
working_dir=WORKING_DIR,
llm_model_func=ollama_model_complete,# Ollama 文本生成模型
llm_model_name='your_model_name',# 模型名称
# 使用 Ollama 嵌入函数
embedding_func=EmbeddingFunc(
embedding_dim=768,
max_token_size=8192,
func=lambdatexts llama_embed(
texts,
embed_model="nomic-embed-text"
)
),
)
增加上下文长度： - 导出模型文件：
ollama show --modelfile qwen2 > Modelfile - 添加参数：
PARAMETER num_ctx 32768 - 创建修改后的模型：
ollama create -f Modelfile qwen2m
- 通过 Ollama API 设置：
rag=LightRAG(
...
llm_model_kwargs={"options":{"num_ctx":32768}},
...
)
低显存 GPU：选择小模型并调整上下文窗口（如gemma2:2b搭配 26k 上下文）。 集成 LlamaIndex LightRAG 支持与 LlamaIndex 集成（详见llm/llama_index_impl.py）：
# 使用 LlamaIndex 直接访问 OpenAI
importasyncio
fromlightragimportLightRAG
fromlightrag.llm.llama_index_implimportllama_index_complete_if_cache,llama_index_embed
fromllama_index.embeddings.openaiimportOpenAIEmbedding
fromllama_index.llms.openaiimportOpenAI
fromlightrag.kg.shared_storageimportinitialize_pipeline_status
fromlightrag.utilsimportsetup_logger
setup_logger("lightrag",level="INFO")
asyncdefinitialize_rag():
rag=LightRAG(
working_dir="your/path",
llm_model_func=llama_index_complete_if_cache,# LlamaIndex 兼容的生成函数
embedding_func=EmbeddingFunc(
embedding_dim=1536,
max_token_size=8192,
func=lambdatexts:llama_index_embed(texts,embed_model=embed_model)
),
)
awaitrag.initialize_storages()
awaitinitialize_pipeline_status()
returnrag
defmain():
rag=asyncio.run(initialize_rag())
withopen("./book.txt","r",encoding="utf-8")asf:
rag.insert(f.read())
# 执行不同模式的查询...
if__name__=="__main__":
main()
详细文档和示例： - LlamaIndex 文档
- 直接 OpenAI 示例
- LiteLLM 代理示例
Token 使用追踪LightRAG 提供TokenTracker工具监控 LLM 的 token 消耗，便于控制 API 成本和优化性能。 fromlightrag.utilsimportTokenTracker
# 方法 1：上下文管理器（推荐）
withTokenTracker()astracker:
result1=awaitllm_model_func("问题 1")
result2=awaitllm_model_func("问题 2")
print("总 token 消耗:",tracker.get_usage())
# 方法 2：手动记录
tracker=TokenTracker()
tracker.reset()
rag.insert()
rag.query("问题 1",param=QueryParam(mode="naive"))
print("插入和查询的 token 消耗:",tracker.get_usage())
使用技巧： 对话历史支持LightRAG 支持多轮对话，通过传入对话历史实现上下文感知： conversation_history=[
{"role":"user","content":"主角对圣诞节的态度如何？"},
{"role":"assistant","content":"故事开头， Ebenezer Scrooge 对圣诞节持消极态度..."},
{"role":"user","content":"他的态度如何转变？"}
]
query_param=QueryParam(
mode="mix",# 支持所有模式
conversation_history=conversation_history,
history_turns=3# 考虑最近 3 轮对话
)
response=rag.query("这种性格转变的原因是什么？",param=query_param)
自定义提示词支持自定义系统提示词，精细控制模型行为： custom_prompt="""
你是环境科学专家，提供详细且结构化的回答，并包含示例。
---对话历史---
{history}
---知识库---
{context_data}
---响应规则---
目标格式和长度：{response_type}
"""
response_custom=rag.query(
"可再生能源的主要优势是什么？",
param=QueryParam(mode="hybrid"),
system_prompt=custom_prompt
)
独立关键词提取新增query_with_separate_keyword_extraction函数，将关键词提取与用户提示分离，专注查询意图： rag.query_with_separate_keyword_extraction(
query="解释万有引力定律",
prompt="为学习物理的高中生提供详细解释",
param=QueryParam(mode="hybrid")
)
数据插入基础插入 # 单文本插入
rag.insert("文本内容")
批量插入 # 批量插入多文本
rag.insert(["文本 1","文本 2",...])
# 自定义批量大小
rag=LightRAG(addon_params={"insert_batch_size":4})
rag.insert(["文本 1","文本 2",...])# 每批处理 4 个文档（默认 10）
带 ID 插入 # 单文本带 ID
rag.insert("文本 1",ids=["ID_FOR_TEXT1"])
# 多文本带 ID 列表（需与文本数量一致）
rag.insert(["文本 1","文本 2"],ids=["ID1","ID2"])
流水线插入 # 异步入队和处理文档（适合后台增量处理）
awaitrag.apipeline_enqueue_documents(input_data)
awaitrag.apipeline_process_enqueue_documents()
多文件类型支持 importtextract
file_path="文档.pdf"
text_content=textract.process(file_path).decode("utf-8")
rag.insert(text_content)
插入自定义知识图谱 custom_kg={
"chunks":[{"content":"文本块","source_id":"doc-1"}],
"entities":[{"entity_name":"实体","description":"描述"}],
"relationships":[{"src_id":"A","tgt_id":"B","description":"关系"}]
}
rag.insert_custom_kg(custom_kg)
引用功能 # 插入带文件路径的文档（支持溯源）
documents=["内容 1","内容 2"]
file_paths=["path1.txt","path2.txt"]
rag.insert(documents,file_paths=file_paths)
存储配置使用 Neo4J 存储 export NEO4J_URI="neo4j://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="password"
asyncdefinitialize_rag():
rag=LightRAG(
working_dir=WORKING_DIR,
llm_model_func=gpt_4o_mini_complete,
graph_storage="Neo4JStorage",# 覆盖默认图存储（NetworkX）
)
awaitrag.initialize_storages()
returnrag
使用 PostgreSQL 存储 支持 PGVector（向量存储）和 Apache AGE（图存储），适合生产环境： # 示例：使用 PostgreSQL + AGE
rag=LightRAG(
graph_storage="AGEStorage",
vector_storage="PGVectorStorage",
kv_storage="PGKVStorage",
...
)
使用 Faiss 存储 # 安装依赖：pip install faiss-cpu（或 faiss-gpu）
asyncdefembedding_func(texts:list[str])->np.ndarray:
fromsentence_transformersimportSentenceTransformer
model=SentenceTransformer('all-MiniLM-L6-v2')
returnmodel.encode(texts,convert_to_numpy=True)
rag=LightRAG(
vector_storage="FaissVectorDBStorage",
vector_db_storage_cls_kwargs={"cosine_better_than_threshold":0.3},
embedding_func=EmbeddingFunc(embedding_dim=384,func=embedding_func),
...
)
数据删除# 按实体名删除
rag.delete_by_entity("实体名称")
# 按文档 ID 删除（级联删除关联的实体和关系）
rag.delete_by_doc_id("doc_id")
知识图谱编辑支持创建、编辑实体和关系，保持图数据库与向量数据库的一致性： 创建实体和关系 # 创建实体
entity=rag.create_entity("Google",{"description":"科技公司","entity_type":"company"})
# 创建关系
relation=rag.create_relation("Google","Gmail",{"description":"开发邮箱服务"})
编辑实体和关系 # 更新实体
updated_entity=rag.edit_entity("Google",{"description":"Alphabet 子公司"})
# 重命名实体（自动迁移关系）
renamed_entity=rag.edit_entity("Gmail",{"entity_name":"Google Mail"})
# 更新关系
updated_relation=rag.edit_relation("Google","Google Mail",{"description":"维护邮箱服务"})
数据导出支持将知识图谱导出为 CSV、Excel、Markdown 等格式： # 导出为 CSV（默认格式）
rag.export_data("knowledge_graph.csv")
# 指定格式（Excel/Markdown/Text）
rag.export_data("output.xlsx",file_format="excel")
# 包含向量数据
rag.export_data("complete_data.csv",include_vector_data=True)
实体合并自动合并多个实体及其关系，处理冲突和重复： # 基础合并
rag.merge_entities(
source_entities=["AI","人工智能","机器学习"],
target_entity="人工智能技术"
)
# 自定义合并策略
rag.merge_entities(
source_entities=["John","John Doe"],
target_entity="John Smith",
merge_strategy={"description":"拼接","entity_type":"保留首个"}
)
缓存管理清除不同模式的 LLM 响应缓存： # 清除所有缓存
awaitrag.aclear_cache()
# 清除指定模式（如本地搜索）
awaitrag.aclear_cache(modes=["local"])
# 同步版本
rag.clear_cache(modes=["global"])
LightRAG 初始化参数| 参数 | 类型 | 说明 | 默认值 |
|---|
| | | lightrag_cache+时间戳 | | | 文档和文本块存储类型（支持 Json/PG/Redis/Mongo） | JsonKVStorage | | | 嵌入向量存储类型（支持 Nano/PG/Milvus/Chroma/Faiss 等） | NanoVectorDBStorage | | | 图存储类型（支持 NetworkX/Neo4J/PGGraph/AGE） | NetworkXStorage | | | | JsonDocStatusStorage | | | | | | | | openai_embed | | | | gpt_4o_mini_complete | | | | |
错误处理API 包含全面的错误处理： LightRAG 服务端LightRAG 服务端提供 Web 界面和 API，支持知识图谱可视化、文档索引管理等功能。详见LightRAG Server 文档。 评估数据集评估数据集可从TommyChien/UltraDomain下载。 生成查询使用example/generate_query.py生成高层级查询，基于数据集描述自动创建用户、任务和问题。 批量评估通过example/batch_eval.py对比不同 RAG 系统的表现，基于全面性、多样性、赋能性三个维度进行评估。 复现实验所有复现代码位于./reproduce目录，步骤包括：
|
