LightRAG是一种轻量级检索增强生成（RAG）框架，通过构建实体-关系知识图谱（KG）和双层检索机制，实现快速、低参数的知识检索。它避免了传统向量RAG对长文档的上下文丢失问题，以及GraphRAG的重建开销，特别适合动态知识库场景。
核心观点在于：LightRAG将文档索引转化为图结构化过程，使用LLM提取实体（如人、地点）和关系（如“观察”），生成键值对（KV）用于检索。这种图增强索引捕捉了跨文档的语义关联，支持local（实体级细粒度）和global（关系级全局）检索，hybrid模式融合两者，提供全面上下文。
证据来自EMNLP 2025论文和GitHub实现：在UltraDomain数据集（农业、CS、法律、混合）上，LightRAG在全面性（Comprehensiveness 67.6% vs NaiveRAG 32.4%）、多样性（Diversity 76.4% vs 23.6%）和赋能（Empowerment 67.6% vs 32.4%）指标全面超越NaiveRAG、RQ-RAG、HyDE和GraphRAG。检索仅需<100 token和1次API调用，而GraphRAG需社区级遍历。增量更新通过union操作，仅处理新实体/关系，避免全重建。
可落地参数与清单：
-
文档分块：chunk_token_size=1200，chunk_overlap_token_size=100（Tiktoken gpt-4o-mini分词器），平衡召回与粒度。
-
LLM/嵌入要求：
- LLM：≥32B参数，上下文≥32K（推荐64K），索引用非推理模型（如gpt-4o-mini），查询用更强模型。
- 嵌入：BAAI/bge-m3（多语言），text-embedding-3-large；固定模型，避免维度变更需重建。
- Reranker：BAAI/bge-reranker-v2-m3，提升混合查询。
-
查询参数（QueryParam）：
| 参数 |
默认 |
说明 |
| mode |
"global" |
local（实体）、global（关系）、hybrid（融合）、naive（纯向量）、mix（KG+向量） |
| top_k |
60 |
实体/关系TopK |
| chunk_top_k |
20 |
文本块TopK |
| max_entity_tokens |
6000 |
实体令牌预算 |
| max_relation_tokens |
8000 |
关系令牌预算 |
| max_total_tokens |
30000 |
总上下文预算 |
| enable_rerank |
True |
重排序 |
-
存储配置（初始化LightRAG时指定）：
- KV：JsonKVStorage（默认）、PGKVStorage、RedisKVStorage、MongoKVStorage。
- Vector：NanoVectorDBStorage（默认，轻量）、PGVectorStorage、Milvus等；cosine_better_than_threshold=0.2。
- Graph：NetworkXStorage（默认）、Neo4JStorage（生产推荐）、PGGraphStorage。
- DocStatus：JsonDocStatusStorage（默认）。
-
初始化与使用清单：
pip install lightrag-hku # 或 uv pip install lightrag-hku[api]（Server）
export OPENAI_API_KEY=sk-...
WORKING_DIR=./rag_storage
rag = LightRAG(working_dir=WORKING_DIR, embedding_func=openai_embed, llm_model_func=gpt_4o_mini_complete)
await rag.initialize_storages() # 必须
rag.insert("文档文本") # 或批量、带ID、多模态（RAG-Anything）
result = rag.query("查询", param=QueryParam(mode="hybrid", top_k=60))
- 异步版：ainsert/aquery/apipeline_enqueue_documents（后台增量）。
- 编辑KG：rag.create_entity("实体", {"type": "person"})；merge_entities(["AI", "人工智能"], "AI")。
- 删除：rag.delete_by_entity("实体")；adelete_by_doc_id("doc_id")（重建共享实体）。
- 缓存：enable_llm_cache=True；aclear_cache(modes=["local"]）。
- 评估：集成RAGAS、Langfuse；TokenTracker监控消耗。
-
部署与监控：
- Server：lightrag-server（WebUI+API，Ollama兼容）。
- Docker：docker compose up。
- 生产：Neo4J（KG高性能）、PostgreSQL（一站式）、embedding_batch_num=32、llm_model_max_async=4。
- 阈值：cosine_threshold=0.2（向量召回）、similarity_threshold=0.95（QA缓存）。
- 回滚：删除doc_id重建；监控RAGAS指标（context_precision等）。
风险：实体提取需强LLM，否则准确率降；大规模文档初始索引LLM调用多（并行max_parallel_insert=2~10）。优化：小LLM如Qwen2.5-30B-A3B提升提取准度。
资料来源：GitHub HKUDS/LightRAG；arXiv:2410.05779。