113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# 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 (推荐)
|
||
|
||
```bash
|
||
# 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 (极速)
|
||
|
||
```bash
|
||
# 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 运行
|
||
|
||
```bash
|
||
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` 进行租户隔离，每个租户拥有独立的存储空间。
|
||
```bash
|
||
curl -H "X-Tenant-ID: my_tenant" http://localhost:9600/query -d '{"query": "..."}'
|
||
```
|
||
|
||
## 🛠️ 项目结构
|
||
|
||
```text
|
||
/
|
||
├── 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 占用较高，请耐心等待。
|