ai-lightrag/README.md

LightRAG Knowledge Base Service

基于 HKU-DS/LightRAG 构建的知识库微服务，专为中文场景优化，支持“事实+图谱”混合检索。

🚀 快速开始

1. 准备工作

• Ollama: 确保 Ollama 服务已启动，并已拉取以下模型：
  • LLM: deepseek-v3.2:cloud (或自定义)
  • Embedding: bge-m3
• Python: 3.10+ (推荐使用 uv 管理环境)

2. 本地运行

方式 A: 使用标准 pip (推荐)

# 1. 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动服务
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 9600 --reload

方式 B: 使用 uv (极速)

# 1. 初始化项目
uv venv
source .venv/bin/activate

# 2. 安装依赖
uv pip install -r requirements.txt

# 3. 启动服务
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 9600 --reload

服务地址: http://localhost:9600 API 文档: http://localhost:9600/docs

3. Docker 运行

docker build -t lightrag-api .
docker run -p 9600:9600 --env-file .env lightrag-api

📚 API 文档 (核心)

接口	方法	描述	示例
/query	POST	知识检索	{"query": "问题", "mode": "hybrid", "stream": true}
/ingest/file	POST	上传文件	multipart/form-data, file=@doc.pdf
/documents	GET	文档列表	查看已索引文档及状态
/docs/{id}	DELETE	删除文档	根据 ID 删除文档及关联图谱数据

检索模式 (Mode) 说明:

• hybrid (推荐): 混合检索，同时利用向量相似度(事实)和知识图谱(关系)。
• naive: 纯向量检索，速度快但缺乏深度关联。
• local: 侧重于实体细节的图谱检索。
• global: 侧重于宏观关系的图谱总结。

🛠️ 项目结构

/
├── app/
│   ├── api/            # 接口路由定义
│   ├── core/           # 核心逻辑 (RAG实例, Prompt优化)
│   ├── config.py       # 配置管理
│   └── main.py         # 程序入口
├── index_data/         # [重要] 知识库持久化数据
│   ├── graph_chunk_entity_relation.graphml  # 完整的知识图谱结构 (NetworkX格式)
│   ├── kv_store_*.json       # 键值存储 (文档原文, 实体描述, 关系描述等)
│   ├── vdb_*.json            # 向量数据库 (实体向量, 关系向量, 文本块向量)
│   └── lightrag_cache.json   # LLM 响应缓存 (加速重复查询)
├── requirements.txt    # 依赖列表
└── .env                # 环境变量配置

⚠️ 注意事项

1. 中文优化: 已内置针对中文优化的 Prompt，移除了原版对 {language} 变量的强依赖，支持中英混合查询自动识别。
2. 写锁机制: 当前底层使用文件存储 (NanoVectorDB + NetworkX)，不支持多进程并发写入。
3. 编辑逻辑: RAG 的“编辑”操作本质是“删除旧文档 -> 重新摄入新文档”。直接修改文本块会导致图谱关系错乱。
4. 初始化: 首次启动或摄入大量数据时，需要构建图谱索引，CPU 占用较高，请耐心等待。