LightRAG 本地部署与 WebUI 应用实战

修改 .env 文件以适配你的模型（以下为阿里云 DashScope 示例）：

### 184 行：LLM Configuration - aliyuncs【qwen3-max】
LLM_BINDING=openai
LLM_MODEL=qwen3-max
LLM_BINDING_HOST=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_BINDING_API_KEY=sk-XXXXXXXXXXXXXXX

### OpenAI compatible embedding - aliyuncs【text-embedding-v1]
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-v1
EMBEDDING_DIM=1536
EMBEDDING_SEND_DIM=false
EMBEDDING_TOKEN_LIMIT=8192
EMBEDDING_BINDING_HOST=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_BINDING_API_KEY=sk-XXXXXXXXXXXXXXX

3. WebUI 界面操作

启动服务后，可通过以下地址访问：

• WebUI 首页：http://127.0.0.1:9621/webui/#/
• Swagger UI：http://localhost:9621/docs
• ReDoc：http://localhost:9621/redoc

所有服务器（LoLLMs、Ollama、OpenAI 和 Azure OpenAI）都为 RAG 功能提供相同的 REST API 端点。

3.1 文档管理

上传文档后，矢量化分块大致经过以下步骤：

1. 文档预处理 & 分块
2. 文本块的向量化和存储
3. 基于 LLM 从文本块中抽取实体与关系
4. 为实体描述 / 关系描述生成向量，并存入向量库

生成的文件说明：

• 文本块向量：存入 chunks 向量表（如 vdb_chunks.json）
• 实体描述向量：存入 entities 向量表（vdb_entities.json）
• 关系描述向量：存入 relationships 向量表（vdb_relationships.json）
• 知识图谱：保存结构化实体与关系，如 graph_chunk_entity_relation.graphml 等

3.2 知识图库

查看构建好的知识图谱结构，直观展示实体间的关联。

3.3 检索 (Retrieval)

输入查询词（例如'重置下拉代码'），系统会检索上传的文件并给出响应。

3.4 API 管理

提供标准的 API 接口供外部调用，支持多种查询模式。

技术背景与对比

传统 RAG 的局限性

传统 RAG 存在显著局限性，包括依赖扁平的数据表示和上下文意识不足，可能导致答案支离破碎，未能捕捉复杂的相互依赖关系。当数据语料库增长时，会出现可扩展性低效，导致检索质量差。解决办法是在文本索引和检索过程中融入图结构，如 Microsoft GraphRAG。

Microsoft GraphRAG

GraphRAG 依赖于精心设计的提示词和多部分的采集检定，使用 LLM 从源文档中提取实体和关系，构建增量结构化的 KG。其流水线涉及索引和查询：

1. Indexing：第一阶段创建知识图谱，第二阶段进行语义聚类（莱顿算法），将密切相关的节点分组为层级簇。
2. Querying：识别问题中的实体和关系，用于 QFS（查询相关的摘要）。通过比较问题与图索引之间的元素，识别最相关的社区，生成中间回复并汇总。

缺点：

• 运行慢，需要多个 LLM API 调用，可能遇到速率限制。
• 成本高昂。索引简单书籍《狄更斯的圣诞颂歌》可能花费 6-7 美元。
• 新数据纳入需重建整个 KG，效率低。
• 缺乏显式去重步骤，噪声较大。

LightRAG 特点

LightRAG 是一种基于 GraphRAG 的创新方法，结合了知识图谱的属性与基于嵌入的检索系统，使其既快速又高效，实现了 SOTA 结果。

1. 基于图的文本索引

索引阶段，LightRAG 处理原始文本文档以构建结构化且可查询的知识图谱。它将文档分割成更小、更易管理的部分，利用 LLM 识别和提取各种实体及关系。通过去重函数，识别并合并原始文本不同段的相同实体和关系，最小化图的大小。

2. 双重 - 层级检索范式 (Dual-level Retrieval Paradigm)

LightRAG 提出在详细和抽象层面生成查询键，采用双层检索策略：

• 低层检索 (Local Query Keywords)：关注特定实体及其属性或关系，提取图中特定节点或边的精确信息。
• 高层检索 (Global Query Keywords)：涉及更广泛的主题和整体主题，汇总多个相关实体和关系的信息，回答需要更广泛主题的问题。

查询过程：

1. 查询分析：提取高层概念和底层关键词。
2. 全局检索：使用高层概念查询知识图谱，识别关键关系和实体。
3. 局部检索：使用底层关键词对文本块进行向量搜索。
4. 响应生成：综合全局和局部检索的上下文，传递给 LLM 生成答案。

3. 增量索引

索引新文件时，自动更新 LLM 响应 KV Store，包含任何新的实体和关系，且不会与现有数据冲突或重复。这解决了 GraphRAG 需要重建整个 KG 的低效问题。

4. 查询模式

根据查询模式（naive、local、global、hybrid），相关关键词会被提取并与 KV 存储和向量数据库进行比较，以根据余弦相似度检索候选实体和关系。

# Naive RAG – 传统 RAG
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="naive"))

# Local Query – LightRAG 本地查询
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="local"))

# Global Query – LightRAG 全局查询
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="global"))

# Hybrid Query – LightRAG 混合查询
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="hybrid"))

代码参考：LightRAG-1.4.9.10\examples\lightrag_openai_demo.py

总结

LightRAG 在构建 RAG 系统方面提供了相对完整的解决方案。相比传统的纯向量检索，它的核心特点是引入了知识图谱，能把非结构化文本组织成实体 - 关系网络。这种混合检索策略（语义向量 + 图谱关系）确实能让 LLM 获得更丰富的上下文信息。它在多个基准测试中都优于 naive RAG 和 GraphRAG，是落地高效 RAG 系统的优选方案。