LightRAG 本地部署与 WebUI 实战指南

注意：不同的 embedding 模型嵌入向量的维度值不一样，请根据实际模型调整 EMBEDDING_DIM。

启动服务后，运行以下命令：

lightrag-server

4. 访问界面

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

• 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 端点。

WebUI 功能详解

1. 文档管理

上传文档后，系统会将原始文档矢量化分块，大致经过以下步骤：

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

生成的文件说明：

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

2. 知识图库

系统会自动展示提取出的实体与关系网络，方便直观查看数据结构。

3. 检索 (Retrieval)

在检索框中输入问题，例如'重置下拉代码'，系统将检索上传的文件并响应。这里可以看到系统如何结合图谱和向量进行回答。

4. API 管理

WebUI 提供了完善的 API 接口管理页面，方便开发者直接调用服务进行测试。

技术原理与对比

传统 RAG 的局限

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

GraphRAG 的痛点

尽管 GraphRAG 看起来很有前景，但由于运营成本和计算复杂性，它并不是一个高效的解决方案：

• 速度慢：运行起来通常非常慢，因为它需要多个 LLM API 调用，可能会遇到速率限制。
• 成本高：非常昂贵。基于测试的网络社区显示，使用 GPT4 时，索引简单书籍《狄更斯的圣诞颂歌》可能花费 6-7 美元，且有 3.2 万字。
• 更新难：要将新数据纳入现有图索引，我们也需要重建整个 KG 的旧数据，这是一种低效的方法。
• 噪声大：没有对重复元素进行显式的去重步骤，导致图索引噪声较大。

LightRAG 的核心优势

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

1. 基于图的文本索引

索引阶段，LightRAG 处理原始文本文档以构建一个结构化且可查询的知识图谱。通过将文档分割成更小、更易管理的部分，增强了检索系统。这种策略允许快速识别并访问相关信息，而无需分析整份文件。

• 提取实体和关系：LLM 分析这些文本块，以识别关键实体及其之间的关系。
• 键值对生成：采用 LLM 赋能的分析函数为每个实体节点和关系边生成文本键值对。
• 去重优化：识别并合并原始文本不同段的相同实体和关系，最小化图的大小。

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

为了从特定文档块及其复杂的相互依赖关系中获取最相关的上下文，LightRAG 提出在详细和抽象层面生成查询键。

• 低层检索 (Local Query Keywords)：主要关注检索特定实体及其相关属性或关系。该层查询注重细节，旨在提取图中特定节点或边的精确信息。
• 高层检索 (Global Query Keywords)：此层次涉及更广泛的主题和整体主题。该层查询汇总多个相关实体和关系的信息，提供对更高层概念和摘要的洞察。

双层检索查询过程：

1. 查询分析：分析用户查询，提取高层概念和底层关键词。
2. 全局检索：使用高层概念查询知识图谱，识别提供广泛上下文的关键关系和实体。
3. 局部检索：使用底层关键词对文本块进行向量搜索，检索具体详细的信息。
4. 响应生成：将来自全局检索和局部检索的组合上下文进行综合，并传递给 LLM，以生成一个全面而准确的答案。

3. 增量索引 (Incremental Indexing)

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

4. 查询模式 (Querying)

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

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

# Local Quer – 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。