HKUDS/LightRAG：知识图谱增强的轻量级RAG框架

一、官方信息

项目名称	LightRAG
仓库地址	https://github.com/HKUDS/LightRAG
官方网站	https://lightrag.github.io/
最新更新	2026 年持续活跃更新
项目定位	面向个人与开发者的轻量级、低成本知识图谱 RAG 框架
开源协议	MIT

二、项目背景

传统 RAG（Retrieval-Augmented Generation）在面对企业内部文档、技术手册、长网页等场景时，往往只能做"块级"的向量检索：把文档切成若干 chunk，用户提问时拿回最相似的几个片段拼进提示词。这种方式在处理跨文档、跨段落的复杂问题时表现很差——它不知道实体之间的关系，也无法回答"A 与 B 之间有什么联系"这类需要全局上下文的问题。

香港大学数据科学实验室（HKUDS）推出的 LightRAG 正是为了解决这一痛点。它在传统向量检索之外，额外用大模型从文档中抽取出实体（Entity）和关系（Relation），自动构建一张知识图谱，再配合向量索引实现"双层检索"：既可以按关键词 / 向量召回相关片段，也可以沿图谱遍历实体间的关联路径。相比 GraphRAG 这类重量级方案，LightRAG 把依赖、内存占用和构建成本大幅压低，单张消费级显卡或纯 API 调用就能跑通。

LightRAG 同时提供 Python SDK、HTTP Server 和一套开箱即用的 Web UI，支持接入 Ollama、OpenAI、DeepSeek、通义千问等几乎所有兼容 OpenAI 接口的模型，非常适合作为个人知识库、客服机器人、代码助手的底层检索引擎。

三、核心特性

双层检索模式：Low-level 检索抓具体实体细节，High-level 检索抓主题概述，两种模式可混合使用。
自动知识图谱构建：写入文档时自动抽取实体与关系，无需人工标注 Schema。
多存储后端：支持内置 JSON / 磁盘存储，也可切换 Neo4j、PostgreSQL、MongoDB 等持久化后端。
多 LLM / Embedding 兼容：Ollama、OpenAI 兼容接口、vLLM、Xinference 等均可接入。
开箱即用 Web UI：内置可视化界面，支持上传文档、查看图谱、对话检索。
低资源占用：相比 GraphRAG 显著降低 token 消耗与内存占用，适合个人部署。
RESTful API：暴露完整 HTTP 接口，方便被其他业务系统集成。

四、环境要求

操作系统：Ubuntu 20.04 / 22.04、CentOS 7+、macOS 12+、Windows 10+（WSL2 推荐）。
Python 3.9 ~ 3.12（推荐 3.11）。
Docker 20.10+ 与 Docker Compose v2（推荐 Docker 部署方式）。
至少一个可用的 LLM：本地 Ollama 模型，或 OpenAI / DeepSeek / 通义千问等 API Key。
内存：建议 4GB 以上；纯 API 调用时 2GB 即可。

五、详细部署步骤

方式一：pip 本地安装（最快体验）

先创建并激活虚拟环境，避免污染系统 Python：

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install "lightrag-hku[api]"

安装完成后，初始化工作目录并启动服务器：

lightrag-server --host 0.0.0.0 --port 9621

首次启动会在当前目录生成 rag_storage 数据目录和默认配置。浏览器访问 http://服务器IP:9621 即可打开 Web UI。

方式二：Docker Compose 部署（生产推荐）

克隆官方仓库并准备环境变量：

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env

编辑 .env 文件，关键配置逐行说明：

# 服务监听地址与端口
HOST=0.0.0.0
PORT=9621

# 【安全必改】设置 API 访问密钥，不设置则所有接口公开
LIGHTRAG_API_KEY=your_strong_random_password

# 使用 OpenAI 兼容接口（以 DeepSeek 为例）
LLM_BINDING=openai
LLM_MODEL=deepseek-chat
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# Embedding 模型（本地 Ollama 或远程均可）
EMBEDDING_BINDING=ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434

如果你使用本地 Ollama，先拉取模型：

ollama pull qwen2.5:7b
ollama pull nomic-embed-text

启动服务：

docker compose up -d
# 若使用交互式初始化生成的文件，则执行：
docker compose -f docker-compose.final.yml up -d

查看日志确认启动成功：

docker compose logs -f lightrag

方式三：纯 Python SDK 嵌入开发

pip install "lightrag-hku"

from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import openai_complete_if_cache, openai_embed
from lightrag.utils import EmbeddingFunc
import asyncio

WORKING_DIR = "./rag_storage"

rag = LightRAG(
    working_dir=WORKING_DIR,
    llm_model_func=openai_complete_if_cache,
    llm_model_name="deepseek-chat",
    llm_model_kwargs={"base_url": "https://api.deepseek.com/v1", "api_key": "sk-xxx"},
    embedding_func=EmbeddingFunc(
        embedding_dim=1536,
        max_token_size=8192,
        func=lambda texts: openai_embed(texts, embed_model="text-embedding-3-small",
                                        base_url="https://api.deepseek.com/v1", api_key="sk-xxx"),
    ),
)

async def main():
    await rag.ainsert("LightRAG 是一个知识图谱增强的 RAG 框架……")
    result = await rag.aquery("LightRAG 的核心优势是什么？", param=QueryParam(mode="hybrid"))
    print(result)

asyncio.run(main())

验证部署

curl http://localhost:9621/health
# 带密钥访问：
curl -H "X-API-Key: your_strong_random_password" http://localhost:9621/documents

六、使用方法

打开 http://服务器IP:9621，首次进入在右上角输入 LIGHTRAG_API_KEY。
进入 Documents 页面，上传 TXT / MD / DOCX / PDF 文件，系统会自动抽实体建图。
在 Query 页面选择检索模式（naive / local / global / hybrid / mix），输入问题即可对话。
Graph 页面可可视化浏览自动生成的知识图谱。

七、常见问题 FAQ

Q1：启动后访问 9621 端口打不开？
A：检查服务器安全组 / 防火墙是否放行 9621；Docker 部署时确认 docker compose ps 中容器状态为 running。

Q2：写入文档时报 Embedding 维度错误？
A：切换 Embedding 模型后维度会变化，需删除 rag_storage 目录重新初始化，或保持与首次一致的模型。

Q3：如何设置访问密码？
A：在 .env 中设置 LIGHTRAG_API_KEY，不设置则接口完全公开，公网部署务必设置。

Q4：构建知识图谱太慢 / token 消耗大？
A：这是 LLM 抽取实体的固有开销。可改用本地 Ollama 模型降低成本，或调小单次写入的文档块大小。

Q5：数据存在哪里？
A：默认存于工作目录的 rag_storage（含向量索引与图结构 JSON），Docker 部署时已通过 volume 映射到宿主机。

八、跳转链接

GitHub 仓库：https://github.com/HKUDS/LightRAG
官方文档：https://lightrag.github.io/
Docker 部署文档：DockerDeployment.md
PyPI 包：https://pypi.org/project/lightrag-hku/