10分钟快速上手LightRAG：从零搭建本地知识库+WebUI的完整教程

10分钟快速上手LightRAG从零搭建本地知识库WebUI的完整教程【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAGLightRAG是一个简单、快速的检索增强生成RAG开源框架也是微软 GraphRAG 的高效轻量替代方案。它通过知识图谱 向量检索的双层架构帮你把一堆文档变成可以问个明白的本地知识库并自带功能完整的WebUI 管理界面——上传文档、浏览知识图谱、在线问答一站式搞定。本教程面向新手全程只需几条命令10 分钟即可跑起属于自己的图知识库服务。一、LightRAG 是什么为什么值得上手传统 RAG 把文档切成小块做向量检索容易只见树木不见森林。LightRAG 让 LLM 从每个文本块中抽取实体和关系构建知识图谱查询时结合低层实体 高层主题双层检索因此擅长跨文档推理和复杂问题回答。它的核心优势对新手尤其友好优势说明 深层上下文理解图谱索引捕捉实体间语义依赖复杂问题回答更完整⚡ 检索快、成本低不依赖社区报告和多重推理LLM 调用少、延迟低 增量更新新文档随时加删除文档可自动重建受影响的图谱 开箱即用的 WebUI文档管理、图谱可视化、在线检索一个界面全有 存储零门槛默认使用本地文件持久化的内存存储无需先装数据库 提示LightRAG 被收录于顶会 EMNLP 2025配套论文与完整项目代码见仓库根目录的 README.md更详细的中文说明见 README-zh.md。二、一键安装3 步装好 LightRAG 服务LightRAG 通过 PyPI 官方包lightrag-hku发布推荐用uv安装没有 uv 的话用 pip 也完全可以见下文注释。第 1 步安装 LightRAG Server打开终端执行uv tool install lightrag-hku[api] # 不喜欢 uv用 pip 同样可行 # python -m venv .venv source .venv/bin/activate # pip install lightrag-hku[api]安装完成后会得到一个lightrag-server命令行工具它就是 WebUI REST API 服务的入口前端源码位于 lightrag_webui/ 目录已随包构建好无需手动编译。第 2 步生成并配置 .env 文件LightRAG 必须接入一个LLM负责实体抽取和生成回答和一个Embedding 模型负责向量化这两个都写在.env配置文件中。# 方式 A交互式向导一路回车按提示选 LLM 即可推荐新手 make env-base # 方式 B手动复制模板再编辑 cp env.example .env用任意文本编辑器打开.env重点只需要改这几项# LLM以 OpenAI 兼容接口为例也支持 ollama、gemini、bedrock 等 LLM_BINDINGopenai LLM_BINDING_HOSThttps://api.openai.com/v1 LLM_BINDING_API_KEYyour_api_key # Embedding 向量模型 EMBEDDING_BINDINGopenai EMBEDDING_BINDING_HOSThttps://api.openai.com/v1 EMBEDDING_BINDING_API_KEYyour_api_key # 服务端口与本地安全 HOST127.0.0.1 PORT9621如果想给服务器加一层 API 密钥鉴权对外部署时强烈建议取消 env.example 中LIGHTRAG_API_KEY的注释并填上自己的密钥。完整的可选变量角色化 LLM、Rerank、存储后端、并发调优等都在env.example里有注释说明也可以在 docs/LightRAG-API-Server.md 中查阅。⚠️ 新手避坑Embedding 模型一旦选定就不要更换。换模型需要把所有文本块、实体和关系重新向量化等于整个知识库重做。第 3 步启动服务lightrag-server看到日志中监听端口后先做健康检查curl http://localhost:9621/health返回正常即代表服务已就绪接下来打开浏览器进入 WebUI。三、WebUI 实战上传、建图谱、问答一条龙管理界面地址http://localhost:9621/webui顶部有 Documents / Knowledge Graph / Retrieval / API 四个标签页。1️⃣ 上传文档构建本地知识库进入Documents页点击Scan可扫描默认工作目录中的文件或直接Upload上传文本、DOCX、Markdown、PDF 等文档。上传后 LightRAG 会自动走解析 → 分块 → 实体关系抽取 → 建图流水线列表中的状态变为 Completed 即代表入库完成2️⃣ 可视化探索知识图谱Knowledge Graph页把抽取出的实体渲染成节点、关系渲染成连线支持换布局Circular / Force Directed 等和搜索。点击任意节点右侧会展示它的描述、属性以及相邻实体想换一批文档观察图谱变化README 里的 README.assets/iShot_2025-03-23_12.40.08.png 展示了图谱在真实项目语料上的效果可以对照体会。3️⃣ Retrieval 面板在线提问Retrieval页就是问答入口。右侧 Parameters 可以调节Query Modemix默认最全、hybrid、local精确实体、global宏观主题、naive纯向量检索Top K Results / Max Tokens控制召回量与上下文长度还可手动指定高/低层关键词做调试4️⃣ 像聊天机器人一样用Ollama 兼容接口LightRAG 还模拟了 Ollama 的聊天接口因此可以接到 Open WebUI 等聊天界面上把它当成带知识库的大脑。下面是配合聊天前端提问《西游记》角色关系并让模型输出 mermaid 关系图谱的示例效果四、快速配置速查新手最常改的 5 个选项配置项作用新手建议LLM_BINDING/EMBEDDING_BINDING指定 LLM 与向量模型抽取用快的回答用强的Embedding 定了别换Query Mode检索策略默认mix效果最佳Rerank对召回结果重排序建议开启质量明显提升见env.example中 RERANK_* 配置存储后端默认本地文件存储生产环境可选 PostgreSQL / MongoDB / Neo4j 等MAX_PARALLEL_INSERT并发处理文档数文档量大时适当调高更多生产级配置角色化 LLM、分块策略、并发调优可阅读 env.example 内的完整注释以及官方文档 docs/ 目录例如 docs/RoleSpecificLLMConfiguration.md 和 docs/FileProcessingPipeline.md。五、常见问题FAQQ1启动后浏览器打不开 9621 端口确认.env里PORT9621未被占用且HOST127.0.0.1时只能在启动服务的那台机器上访问远程访问需改为0.0.0.0并务必配置LIGHTRAG_API_KEY鉴权。Q2文档状态一直是 Processing 不动多是大模型请求慢或超时。可以适当调大EXTRACT_LLM_TIMEOUT或换更快的抽取模型详细排查思路见 README 的 Resolving LLM Timeouts 章节。Q3只想在本地完全离线跑LightRAG 支持 Ollama 本地模型LLM_BINDINGollama离线环境的完整依赖预装方法见 docs/OfflineDeployment.md也提供 docker-compose.yml 一键容器化部署。Q4代码层面想深入了解核心检索与抽取逻辑在 lightrag/operate.py主类封装在 lightrag/lightrag.py服务端在 lightrag/api/lightrag_server.py示例脚本可看 examples/ 目录。六、写在最后回顾一下我们只用了三步就搭好了一个带 WebUI 的本地知识库✅uv tool install lightrag-hku[api]安装✅ 配置.envLLM Embedding✅lightrag-server启动浏览器打开http://localhost:9621/webui接下来可以试试把你的读书笔记、工作文档、甚至整本小说喂给它用mix模式跨文档提问看看图谱检索相比普通 RAG 的差距。祝玩得开心【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考