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 文档 (核心)

服务接口完全兼容 OpenAI 响应标准，支持流式与非流式输出。

接口	方法	描述	示例
/query	POST	知识检索	{"query": "问题", "mode": "hybrid", "stream": true, "think": true, "only_rag": false}
/ingest/file	POST	上传文件	multipart/form-data, file=@doc.pdf
/ingest/text	POST	摄入纯文本	{"text": "文本内容"}
/ingest/batch_qa	POST	批量摄入 QA	[{"question": "Q1", "answer": "A1"}, ...]
/documents	GET	文档列表	查看已索引文档及状态
/docs/{id}	DELETE	删除文档	根据 ID 删除文档及关联图谱数据

/query 参数说明:

• query: 用户问题。
• mode: 检索模式 (hybrid, naive, local, global)。推荐使用 hybrid。
• stream: 是否流式输出 (OpenAI 兼容 Chunk 格式)。
• think: 是否启用思考模式 (DeepSeek 风格，返回 reasoning_content)。
• only_rag: 严格模式。若为 true，未从知识库检索到内容时将拒绝回答，不使用 LLM 通用知识。

响应字段 (流式):

• delta.content: 正文回答。
• delta.reasoning_content: 思考过程 (DeepSeek 风格)。
• delta.x_rag_status: 检索命中状态 (hit 或 miss)。

租户管理:

通过 Header X-Tenant-ID 进行租户隔离，每个租户拥有独立的存储空间。

curl -H "X-Tenant-ID: my_tenant" http://localhost:9600/query -d '{"query": "..."}'

🛠️ 项目结构

/
├── app/
│   ├── api/            # 接口路由定义 (OpenAI 标准流式实现)
│   ├── core/           # 核心逻辑 (RAG Manager, 多租户管理, PDF图文解析)
│   ├── config.py       # Pydantic-settings 配置管理
│   └── main.py         # FastAPI 入口
├── index_data/         # [重要] 知识库持久化数据根目录
│   └── {tenant_id}/    # 各租户独立文件夹
│       ├── graph_*.graphml    # 知识图谱结构
│       ├── kv_store_*.json    # 键值存储 (文本块, 实体描述等)
│       └── vdb_*.json         # 向量数据库
├── requirements.txt    # 依赖列表 (包含 Pillow, PyPDF 等)
├── Dockerfile          # 容器化构建文件 (中文注释)
├── deploy.sh           # 一键部署脚本 (支持 host-gateway 访问宿主机 Ollama)
└── .env                # 环境变量配置

⚠️ 注意事项

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