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

| 接口 | 方法 | 描述 | 示例 |
| :--- | :--- | :--- | :--- |
| `/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`: 侧重于宏观关系的图谱总结。

**租户管理**：

```bash
curl -H "X-Tenant-ID: <tenant_id>" http://localhost:9600/xxx
# <tenant_id> 租户ID 默认值: default
```

## 🛠️ 项目结构

```text
/
├── 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 占用较高，请耐心等待。