LightRAG：简单快速的检索增强生成框架快速上手

推荐语

探索高效问答与内容生成的新选择，LightRAG框架让你轻松驾驭RAG技术。

核心内容：
1. LightRAG框架的轻量化设计及优势
2. 快速部署与安装指南
3. 实际应用示例与环境配置

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

LightRAG 是一款轻量级的 检索增强生成（RAG, Retrieval-Augmented Generation）框架，旨在通过优化检索和生成流程，降低传统 RAG 系统的部署成本与资源消耗，同时保持高效的问答和内容生成能力。它适用于需要快速响应、低算力支持的场景，如智能客服、知识问答、轻量化 AI 助手等。

安装

安装 LightRAG 核心模块

• 从源代码安装（推荐）

  cd LightRAG  
  pip install -e .  
  

• 通过 PyPI 安装

  pip install lightrag-hku  
  

安装 LightRAG 服务端

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

• 通过 PyPI 安装

  pip install "lightrag-hku[api]"  
  

• 从源代码安装

  # 按需创建 Python 虚拟环境  
  # 安装 API 支持的可编辑模式  
  pip install -e ".[api]"  
  

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

快速开始

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

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

查询

使用以下 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.kg.shared_storage import initialize_pipeline_status  
from lightrag.utils import setup_logger  

setup_logger("lightrag", level="INFO")  

async def initialize_rag():  
    rag = LightRAG(  
        working_dir="your/path",  
        embedding_func=openai_embed,  
        llm_model_func=gpt_4o_mini_complete  
    )  

    await rag.initialize_storages()  
    await initialize_pipeline_status()  

    return rag  

def main():  
    # 初始化 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）

class QueryParam:  
    mode: Literal["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

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 模型

参考 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=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 模型

概述：需先拉取模型（如文本生成模型和嵌入模型 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=lambda texts: ollama_embed(  
            texts,  
            embed_model="nomic-embed-text"  
        )  
    ),  
)  

增加上下文长度：

• 修改 Modelfile
  （默认上下文 8k，需至少 32k）：

1. 拉取模型：ollama pull qwen2
2. 导出模型文件：ollama show --modelfile qwen2 > Modelfile
3. 添加参数：PARAMETER num_ctx 32768
4. 创建修改后的模型：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  
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.kg.shared_storage import initialize_pipeline_status  
from lightrag.utils import setup_logger  

setup_logger("lightrag", level="INFO")  

async def initialize_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=lambda texts: llama_index_embed(texts, embed_model=embed_model)  
        ),  
    )  

    await rag.initialize_storages()  
    await initialize_pipeline_status()  

    return rag  

def main():  
    rag = asyncio.run(initialize_rag())  
    with open("./book.txt", "r", encoding="utf-8") as f:  
        rag.insert(f.read())  
    # 执行不同模式的查询...  

if __name__ == "__main__":  
    main()  

详细文档和示例：

• LlamaIndex 文档
• 直接 OpenAI 示例
• LiteLLM 代理示例

Token 使用追踪

LightRAG 提供 TokenTracker 工具监控 LLM 的 token 消耗，便于控制 API 成本和优化性能。

from lightrag.utils import TokenTracker  

# 方法 1：上下文管理器（推荐）  
with TokenTracker() as tracker:  
    result1 = await llm_model_func("问题 1")  
    result2 = await llm_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())  

使用技巧：

• 长会话或批量操作使用上下文管理器自动追踪
• 分段统计时手动调用 reset()
• 开发测试阶段定期检查 token 使用情况

对话历史支持

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"])  

流水线插入

# 异步入队和处理文档（适合后台增量处理）  
await rag.apipeline_enqueue_documents(input_data)  
await rag.apipeline_process_enqueue_documents()  

多文件类型支持

import textract  
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"  

async def initialize_rag():  
    rag = LightRAG(  
        working_dir=WORKING_DIR,  
        llm_model_func=gpt_4o_mini_complete,  
        graph_storage="Neo4JStorage",  # 覆盖默认图存储（NetworkX）  
    )  
    await rag.initialize_storages()  
    return rag  

使用 PostgreSQL 存储

支持 PGVector（向量存储）和 Apache AGE（图存储），适合生产环境：

# 示例：使用 PostgreSQL + AGE  
rag = LightRAG(  
    graph_storage="AGEStorage",  
    vector_storage="PGVectorStorage",  
    kv_storage="PGKVStorage",  
    ...  
)  

使用 Faiss 存储

# 安装依赖：pip install faiss-cpu（或 faiss-gpu）  
async def embedding_func(texts: list[str]) -> np.ndarray:  
    from sentence_transformers import SentenceTransformer  
    model = SentenceTransformer('all-MiniLM-L6-v2')  
    return model.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 响应缓存：

# 清除所有缓存  
await rag.aclear_cache()  
# 清除指定模式（如本地搜索）  
await rag.aclear_cache(modes=["local"])  
# 同步版本  
rag.clear_cache(modes=["global"])  

LightRAG 初始化参数

参数	类型	说明	默认值
working_dir	str	缓存存储目录	lightrag_cache+时间戳
kv_storage	str	文档和文本块存储类型（支持 Json/PG/Redis/Mongo）	JsonKVStorage
vector_storage	str	嵌入向量存储类型（支持 Nano/PG/Milvus/Chroma/Faiss 等）	NanoVectorDBStorage
graph_storage	str	图存储类型（支持 NetworkX/Neo4J/PGGraph/AGE）	NetworkXStorage
doc_status_storage	str	文档处理状态存储类型	JsonDocStatusStorage
chunk_token_size	int	文档分块的最大 token 数	1200
embedding_func	EmbeddingFunc	嵌入函数	openai_embed
llm_model_func	callable	LLM 生成函数	gpt_4o_mini_complete
…	…	更多参数详见文档	…

错误处理

API 包含全面的错误处理：

• 文件未找到（404）
• 处理错误（500）
• 支持多编码（UTF-8/GBK）

LightRAG 服务端

LightRAG 服务端提供 Web 界面和 API，支持知识图谱可视化、文档索引管理等功能。详见 LightRAG Server 文档。

评估

数据集

评估数据集可从 TommyChien/UltraDomain 下载。

生成查询

使用 example/generate_query.py 生成高层级查询，基于数据集描述自动创建用户、任务和问题。

批量评估

通过 example/batch_eval.py 对比不同 RAG 系统的表现，基于 全面性、多样性、赋能性 三个维度进行评估。

复现实验

所有复现代码位于 ./reproduce 目录，步骤包括：

1. 提取唯一上下文
2. 插入 LightRAG 系统
3. 生成查询并执行