跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
PythonAI算法

LightRAG 框架介绍与 WebUI 本地部署应用

LightRAG 框架及其 WebUI 本地部署方法。LightRAG 是一种结合知识图谱的检索增强生成（RAG）框架，通过构建实体关系网络提升上下文理解能力。文章涵盖其核心功能、技术栈要求（LLM、Embedding、Reranker）、部署步骤（PyCharm、Bun、服务器配置）、WebUI 界面功能（文档管理、知识图库、检索、API 管理）。同时对比了 LightRAG 与传统 RAG 及 GraphRAG 的差异，强调了其在增量索引、双重层级检索范式上的优势，适合需要高效、低成本 RAG 解决方案的场景。

利刃发布于 2026/4/6更新于 2026/10/20110 浏览
LightRAG 框架介绍与 WebUI 本地部署应用

前言

LightRAG WebUI 本地部署与应用。

一、LightRAG

LightRAG，一个为实现简单快速的检索增强生成（Retrieval-Augmented Generation）而设计的框架。通过从文档中构建知识图谱来增强传统的检索增强生成（RAG），能够更深入、更具上下文感知地理解源材料，超越了简单的基于关键词的检索，实现了一种利用广泛上下文和具体细节的双层检索范式。

1.1 主要功能

LightRAG 配备了一系列功能，旨在提供一个灵活、强大且可观测的 RAG 系统。

1.2 技术栈

  • 大型语言模型 (LLM)
    • 参数：建议使用至少有 320 亿参数的模型。
    • 上下文长度：至少需要 32KB 的上下文长度；建议使用 64KB 以获得最佳性能。
    • 能力：在文档索引阶段，避免使用主要专注于推理的模型。在查询阶段，建议使用比索引阶段更强大的模型以获得更好的结果。
  • [内容块] 加强模型（Embedding model）
    • 一个高性能、多语言的 embedding 模型至关重要。推荐的模型包括 BAAI/bge-m3 和 text-embedding-3-large。
    • 一致性至关重要：文档索引和查询必须使用相同的 embedding 模型。如果更换模型，您必须清除现有的向量数据，以便 LightRAG 使用正确的维度重新生成。
  • 重排序器模型 (Reranker model)
    • 集成一个 reranker 模型可以显著提高检索性能，尤其是在使用'mix'查询模式时。
    • 推荐的模型包括 BAAI/bge-reranker-v2-m3 或来自 Jina 等提供商的商业产品。
    • Reranker 优化检索结果机制：
      • 语义相关性评分：将用户查询与候选文档输入同一模型（如 Cross-Encoder），输出 0-1 的相似度分数，基于上下文深度分析语义匹配度。
      • 结果重排序：按分数对文档降序排列，优先保留最相关片段，过滤冗余信息。

引用 LightRAG README-zh LightRAG 框架介绍

二、部署

工具

  • Python 3.10.5
  • PyCharm
  • LightRAG-1.4.9.10
  • Windows 11

1. PyCharm 配置、安装 Bun

配置 python 环境 3.10.5，PyCharm 打开 LightRAG-1.4.9.10 源代码，PyCharm 终端 PowerShell 安装 bun。

powershell -c "irm bun.sh/install.ps1|iex"

2. 安装 LightRAG 服务器、Core 和运行 lightrag-server

pip install "lightrag-hku[api]"
pip install lightrag-hku # 构建前端代码
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
# 配置 env 文件
 env.example .


lightrag-server
cp
env
# 使用你的 LLM 和 Embedding 模型访问参数更新.env 文件
# 启动 API-WebUI 服务

.env 文件修改 LLM 模型和 Embedding 模型

### 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 模型嵌入向量的维度值不一样
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 端点。当 API 服务器运行时，访问上述地址。

3.1 文档管理

文档矢量化分 4 段：原始文档变成可检索的向量结构，大致会经过：

  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 等
3.2 知识图库

展示构建的知识图谱结构。

3.3 检索 Retrieval

输入查询，检索上传的文件并响应。

3.4 API 管理

提供 API 接口管理与测试。

三、总结

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

LightRAG 是一种基于 GraphRAG 的创新方法，结合了知识图谱的属性与基于嵌入的检索系统，使其既快速又高效，实现了 SOTA（最先进的技术方案）结果。它在多个基准测试中都优于 naive RAG 和 GraphRAG。

四、技术文献

传统 RAG 系统的局限性 Limitations of Traditional RAG Systems lightrag framewok 1000 万份文档的检索策略：标准混合搜索 与 LightRAG 的比较？

传统 RAG

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

Microsoft GraphRAG:

知识图谱是由一组节点组成的数据结构，这些节点保留了不同实体之间存在于不同数据点之间的关系。结构化知识图谱使 GraphRAG（Edge 等人）能够通过连接点或对比信息片段，在多跳推理中表现出色。

GraphRAG 流水线涉及索引和查询：

1. Indexing – GraphRAG 索引

  • 第一阶段：知识图谱（KG）创建：GraphRAG 依赖于精心设计的提示词 prompt 和多部分的采集检定，使用 LLM 从源文档中提取实体和关系，构建增量结构化的 KG。
  • 第二阶段：语义聚类：基于节点连接密度和可扩展性，应用莱顿算法通过将密切相关的节点分组为层级簇来发现模块化群体。群体划分用于将图索引划分为元素组（节点、边、协变量），LLM 可以在索引和查询时并行汇总这些元素，通过关注高度相关的群落而非整个图，高效地减少搜索空间。利用大型语言模型，这些社区通过自下而上的方法进行总结，作为描述符，完全覆盖了图索引。

2. Querying – GraphRAG 查询

  • 查询阶段，当用户提出问题时，查询中的实体和关系会被识别出来用于 QFS（Query-Focused Summarization 查询相关的摘要）。通过比较问题与图索引之间的这些元素，可以识别出最相关的社区。
  • 然后这些社区总结会被随机洗牌，LLM 生成不同社区层级（本地或全球层面）的中间回复，并匹配 0 到 100 的帮助度评分。该分数表明生成答案与用户查询的相关性。最终的全局答案采用多阶段地图缩减法生成，将中间部分反应汇总，依据帮助度评分作为 LLM 的上下文，按顺序递减排序。

3. GraphRAG 的缺点

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

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

LightRAG

一个简单、快速且高效的图 x RAG。LightRAG 通过将文档分割成更小、更易管理的块块 Di 来增强检索过程。这种分块策略使得快速识别相关内容，无需逐一浏览整个文档。

LightRAG 与 NaiveRAG 和 GraphRAG 有何不同？
  • 全面的信息检索，提供多元答案。
  • 高效且低成本的检索。
  • 快速适应数据，并以最小的重新索引方式更新数据。
LightRAG 解决 GraphRAG 的两个主要痛点？
  • 通过比社区穿越更好的方法，减少索引和响应时间。
  • 通过增量更新算法，只更新特定元素实例，轻松适应新数据。
LightRAG 特点
1. 基于图的文本索引

索引阶段，LightRAG 处理原始文本文档以构建一个结构化且可查询的知识图谱。 LightRAG 通过将文档分割成更小、更易管理的部分，增强了检索系统。这种策略允许快速识别并访问相关信息，而无需分析整份文件。接下来，我们利用大型语言模型识别和提取各种实体（例如名称、日期、地点和事件）以及它们之间的关系。通过该过程收集的信息将用于创建一个全面的知识图谱，突出整个文档集合之间的联系和洞见。

基于图的文本索引范式中使用的函数描述如下：

1.1 提取实体和关系 R（） 大型语言模型 (LLM) 分析这些文本块，以识别关键实体（如人物、地点或概念）及其之间的关系（边）。例如，它可以从文本中提取'心脏病专家'和'心脏病'等实体，以及'心脏病专家诊断心脏病'等关系：'心脏病专家评估症状以识别潜在心脏问题。'为了提高效率，原始文本被分割成多个区块。

1.2 用于键值对生成 P（）的 LLM 分析 采用 LLM 赋能的分析函数为每个实体节点和关系边生成文本键值对。每个索引键是一个单词或短语，便于高效检索，而对应的值则是一个文本段落，总结了外部数据中的相关片段，以辅助文本生成。实体使用其名称作为唯一的索引键，而关系则可能拥有多个索引键，这些索引键源自 LLM 增强，包含来自连接实体的全局主题。

1.3 去重以优化图作 D（.） 去重函数，识别并合并原始文本不同段的相同实体和关系。这一过程通过最小化图的大小，有效减少了图作的开销，从而实现更高效的数据处理。

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

为了从特定文档块及其复杂的相互依赖关系中获取最相关的上下文，LightRAG 提出在详细和抽象层面生成查询键。 借助基于图的文本索引，LightRAG 流水线采用双层检索策略。该方法从 KG 内的多跳子图中识别低级和高级键，以回答多样化的查询。

  • 低层检索 Local Query Keywords：主要关注检索特定实体及其相关属性或关系。该层查询注重细节，旨在提取图中特定节点或边的精确信息。针对单个节点和边缘的具体细致信息，以处理本地查询，如'什么是 Mechazilla？'在这个层面，它提供了详细的节点级洞察。
  • 高层检索 Global Query Keywords：此层次涉及更广泛的主题和整体主题。该层查询汇总多个相关实体和关系的信息，提供对更高层概念和摘要的洞察，而非具体细节。汇总来自不同文档的多个实体信息，回答需要更广泛主题或抽象思考的全球性问题，如'埃隆·马斯克的愿景如何促进其项目的可持续发展？'

双层检索查询过程：

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

对于给定的查询，LightRAG 的检索算法会同时提取本地 k（l）和全局查询关键词 k（g）。然后利用向量相似度，将相关实体匹配到带有低层密钥的本地查询和带有高级概念的全局查询关键词。 通过在局部子图中收集一跳邻近节点，LightRAG 集成了额外的上下文层，提高了图索引中边结果的相关性。这种双层检索结构结合了关键词匹配与由构建的 KG 诱导的相关结构信息。

检索的内容是 LLM 剖析阶段的输出，包含名称、实体和关系的描述以及原文的简短摘要。

4. Indexing 索引

索引流程图： 最后，构建的图索引保存为 graph_chunk_entity_relation.graphml，我们稍后将利用它来可视化 Neo4j 中的 KG。

vdb_relationship.json 文件存储通过 ID 连接源实体和目标实体之间的关系，以表示连接。 vdb_entities.json 包含从文本块中提取的具有唯一 ID、实体名称等的实体向量嵌入。 kv_store_llm_response.json 存储由大型语言模型生成的关于实体及其关系的摘要。它采用缓存机制防止对相同 ID 进行冗余索引。 kv_store_text_chunks.json 存储文档文本块及其相关的元数据，如 chunk_size（令牌）、实际内容、块索引、父文档 ID 等。

5. Incremental Indexing 增量索引

索引新文件，自动更新 LLM 响应 kv_store_llm_response.json，包含任何新的实体和关系，且不会与现有数据冲突或重复。 LLM 响应，kv_store_llm_response.json 文件添加增量节点信息：global:keywords:b3f3bc653c7ca6f095224a9e787b1965

{
"global:keywords:323f0a4456f4753a60d7a65e23267c4e": {
"return": "{\"high_level_keywords\": [\"Code reset\", \"Dropdown functionality\"], \"low_level_keywords\": [\"\\u91cd\\u7f6e\\u4e0b\\u62c9\\u4ee3\\u7801\\u547d\\u4ee4\"]}",
"cache_type": "keywords",
"chunk_id": null,
"original_prompt": "重置下拉代码命令",
"queryparam": {"mode": "global", "response_type": "Multiple Paragraphs", "top_k": 40, "chunk_top_k": 20, "max_entity_tokens": 6000, "max_relation_tokens": 8000, "max_total_tokens": 30000, "user_prompt": "", "enable_rerank": true},
"create_time": 1767666062,
"update_time": 1767666062,
"_id": "global:keywords:323f0a4456f4753a60d7a65e23267c4e"
},
"global:keywords:b3f3bc653c7ca6f095224a9e787b1965": {
"return": "{\"high_level_keywords\": [\"Redis startup process\", \"Database initialization\", \"System boot sequence\"], \"low_level_keywords\": [\"Redis\", \"Configuration file\", \"Persistence setup\", \"Port binding\", \"Log initialization\"]}",
"cache_type": "keywords",
"chunk_id": null,
"original_prompt": "redis 启动过程",
"queryparam": {"mode": "global", "response_type": "Multiple Paragraphs", "top_k": 40, "chunk_top_k": 20, "max_entity_tokens": 6000, "max_relation_tokens": 8000, "max_total_tokens": 30000, "user_prompt": "", "enable_rerank": true},
"create_time": 1767752257,
"update_time": 1767752257,
"_id": "global:keywords:b3f3bc653c7ca6f095224a9e787b1965"
}
}
6. Querying 查询

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

  • Naive RAG – 传统 RAG
# mode="naive"
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="naive"))
  • Local Quer – LightRAG 本地查询
# mode="local"
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="local"))
  • Global Query – LightRAG 全局查询
# mode="global"
await rag.aquery("What are the top themes in this story?", param=QueryParam(mode="global"))
  • Hybrid Query – LightRAG 混合查询
# mode="hybrid"
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

目录

  1. 前言
  2. 一、LightRAG
  3. 1.1 主要功能
  4. 1.2 技术栈
  5. 二、部署
  6. 1. PyCharm 配置、安装 Bun
  7. 2. 安装 LightRAG 服务器、Core 和运行 lightrag-server
  8. 配置 env 文件
  9. 使用你的 LLM 和 Embedding 模型访问参数更新.env 文件
  10. 启动 API-WebUI 服务
  11. 184 行：LLM Configuration - aliyuncs【qwen3-max】
  12. OpenAI compatible embedding - aliyuncs【text-embedding-v1]
  13. 不同的 embedding 模型嵌入向量的维度值不一样
  14. 3. WEBUI 界面
  15. 3.1 文档管理
  16. 3.2 知识图库
  17. 3.3 检索 Retrieval
  18. 3.4 API 管理
  19. 三、总结
  20. 四、技术文献
  21. 传统 RAG
  22. Microsoft GraphRAG:
  23. LightRAG
  24. LightRAG 与 NaiveRAG 和 GraphRAG 有何不同？
  25. LightRAG 解决 GraphRAG 的两个主要痛点？
  26. LightRAG 特点
  27. 1. 基于图的文本索引
  28. 2. 双重 - 层级检索范式-Dual-level Retrieval Paradigm
  29. 3. LightRAG 如何利用知识图谱？
  30. 4. Indexing 索引
  31. 5. Incremental Indexing 增量索引
  32. 6. Querying 查询
  33. mode="naive"
  34. mode="local"
  35. mode="global"
  36. mode="hybrid"

更多推荐文章

查看全部
  • TypeScript 核心概念与面试实战指南
  • Spring AI MCP Server 集成与实现
  • Lostlife2.0 任务系统智能化：LLama-Factory 驱动动态任务生成
  • DeepSeek-R1 大模型基于 MS-Swift 框架部署、推理与微调实践
  • N8N 结合 Claude Code 实现 AI 智能体自动化编排
  • 小智 AI 设备绑定与解绑操作指南
  • MCP 教程：将 Figma 设计稿转化为前端代码
  • HarmonyOS 6 相机 C++ API 核心能力与 NDK 开发
  • Hadoop 分布式架构解析
  • Flutter WalletConnect 鸿蒙适配：Web3 钱包连接与 DApp 授权
  • 云开发 Copilot：AI 赋能的低代码开发工具
  • Qwen3-4B-Instruct 模型本地 CPU 部署与 WebUI 配置
  • UniApp 与 ThinkPHP 图库资料系统源码及搭建说明
  • iOS 26 Liquid Glass TabBar 适配实战与实现
  • 基于 PyTorch 容器高效部署与运行 Llama、ChatGLM 大模型实践
  • OpenClaw 开源机器人实现空间智能体记忆
  • Open Duck Mini v2 智能行走机器人构建指南
  • 企业 RAG 的路走到头了？2026 年，图检索正在接替它
  • AI 智能编码工具：重塑开发效率的革命，从 GitHub Copilot 到国产新秀的全面解析
  • AI 变现逻辑拆解：为何掌握工具却难以盈利

相关免费在线工具

  • 加密/解密文本

    使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Gemini 图片去水印

    基于开源反向 Alpha 混合算法去除 Gemini/Nano Banana 图片水印，支持批量处理与下载。 在线工具，Gemini 图片去水印在线工具，online

  • curl 转代码

    解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online