LightRAG 是一种轻量级检索增强生成（RAG）系统，专为处理大型文档设计，通过双编码器机制实现低延迟检索，避免了传统嵌入式方法的复杂性。其核心在于构建知识图谱，将文档分解为实体和关系，实现基于图的索引和动态修剪，从而在查询时快速定位相关信息。这种设计特别适合资源受限的环境，因为它最小化了外部依赖，仅需基本的 LLM 和嵌入函数即可运行。
在实现 LightRAG 时，首先需要理解其双编码器架构。双编码器指的是实体级（本地）和关系级（全局）的双层检索机制。本地检索聚焦于特定上下文中的实体，如人物或事件，而全局检索则通过关系图捕捉跨文档的关联。这种分离允许系统在查询时动态选择路径：对于简单问题，使用本地编码器快速匹配；对于复杂查询，则激活全局编码器进行图遍历。LightRAG 的创新在于使用 LLM 自动提取实体-关系对，而非依赖预训练嵌入模型，从而减少了计算开销。根据官方文档，这种方法在处理长文档时，能将检索延迟控制在毫秒级，同时保持高召回率。
要落地 LightRAG 的简单快速实现，我们从安装开始。推荐使用 uv 作为包管理器，执行 uv pip install lightrag-hku 即可引入核心库。对于 API 支持，可安装 lightrag-hku[api]。初始化时，需要指定工作目录、嵌入函数和 LLM 函数。例如，使用 OpenAI 兼容的接口：
from lightrag import LightRAG
from lightrag.llm.openai import openai_embed, gpt_4o_mini_complete
rag = LightRAG(
working_dir="./rag_storage",
embedding_func=openai_embed,
llm_model_func=gpt_4o_mini_complete
)
await rag.initialize_storages()
这里，working_dir 用于持久化数据，默认使用 JSON KV 存储和 NanoVectorDB。对于生产环境，可切换到 PostgreSQL 或 Neo4J 以提升性能。关键参数包括 chunk_token_size=1200（每个文本块的最大令牌数）和 chunk_overlap_token_size=100（块间重叠），这些值确保了文档分割的细粒度控制，避免信息丢失。嵌入函数如 bge-m3 模型维度为 1024，需在初始化前固定，因为切换模型会要求重建向量表。
插入文档是 LightRAG 的核心管道。系统将输入文本拆分为块，使用 LLM 提取实体（如“公司”、“人物”）和关系（如“属于”、“合作”），然后构建知识图谱。批量插入支持 max_parallel_insert=4，限制并发以避免 LLM 瓶颈。对于大型文档，建议分批处理，每批不超过 10 个文件。提取过程的循环次数由 entity_extract_max_gleaning=1 控制，减少冗余调用。LightRAG 还支持多模态扩展，通过 RAG-Anything 集成处理 PDF、图像和表格，自动生成跨模态关系。
查询阶段体现了 LightRAG 的高效性。它支持多种模式：local（实体焦点）、global（关系焦点）、hybrid（混合）和 mix（图+向量）。例如，使用 QueryParam 配置：
from lightrag import QueryParam
result = await rag.aquery(
"文档中的主要主题是什么？",
param=QueryParam(mode="hybrid", top_k=60, chunk_top_k=20)
)
top_k=60 限制检索的实体/关系数量，chunk_top_k=20 控制文本块重排序。启用重排序器（如 bge-reranker-v2-m3）可提升相关性，推荐在混合查询中使用。令牌预算参数如 max_entity_tokens=6000 和 max_total_tokens=30000 确保上下文不超过 LLM 限制。动态修剪机制在此发挥作用：系统根据余弦相似度阈值（默认 0.2）过滤低相关节点，减少噪声。对于低延迟需求，可设置 embedding_batch_num=32 以并行计算嵌入。
在实际部署中，需要关注几个可落地清单。首先，LLM 选择：索引阶段使用 32B 参数模型如 GPT-4o-mini，避免推理模型；查询阶段升级到更强模型如 GPT-4o 以提升生成质量。其次，存储优化：本地开发用默认 NetworkX 图存储，生产用 Neo4J（性能优于 PostgreSQL AGE）。阈值设置包括 cosine_better_than_threshold=0.2，低于此值的节点将被修剪。监控要点：使用 TokenTracker 跟踪令牌消耗，启用 LLM 缓存（enable_llm_cache=True）以加速重复查询。风险包括实体提取准确率依赖 LLM 质量，小模型可能遗漏关系；解决方案是设置 addon_params={"language": "Chinese", "entity_types": ["organization", "person"]} 自定义类型。
进一步优化查询管道，LightRAG 支持流式响应（stream=True）和历史对话（conversation_history），适用于聊天应用。删除功能如 adelete_by_entity("实体名") 确保知识图谱清洁，支持文档级删除以重建受影响部分。评估时，可集成 RAGAS 框架，计算全面性、多样性和赋能度指标。官方基准显示，在混合数据集上，LightRAG 的整体胜率达 60%，优于 NaiveRAG 和 GraphRAG。
总之，LightRAG 的简单实现路径是：最小化依赖（uv + OpenAI），固定嵌入模型，配置双级参数，最后通过混合模式查询。这种方法在大型文档上实现了 embedding-free 风格的低延迟检索，动态修剪确保了效率。实际参数如 top_k=60 和阈值 0.2 可根据文档规模调整，回滚策略包括缓存清除和存储备份。
资料来源：GitHub 仓库 https://github.com/HKUDS/LightRAG；arXiv 论文 https://arxiv.org/abs/2410.05779。