PlantAI-rag/docs/user-guide/README.md

# Gene Family MAS V2 - 使用手册

**版本**: 2.0.0  
**最后更新**: 2026-04-17

---

## 目录

1. [快速开始](#快速开始)
2. [部署指南](#部署指南)
3. [配置说明](#配置说明)
4. [使用示例](#使用示例)
5. [故障排除](#故障排除)

---

## 快速开始

### 环境要求

- Python 3.10+
- Node.js 16+ (前端开发)
- Neo4j 5.x (可选，用于知识图谱存储)

### 安装依赖

```bash
# 克隆仓库
git clone <repository-url>
cd gene-family-mas-v2

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

# 安装RAG特定依赖
pip install -r requirements-rag.txt
```

### 启动服务

```bash
# 启动API服务
python -m api.main

# 或使用uvicorn
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
```

服务启动后，访问:
- API文档: http://localhost:8000/docs
- 前端页面: http://localhost:8000/static/index.html

---

## 部署指南

### 生产环境部署

#### 1. 环境准备

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装生产依赖
pip install -r requirements.txt
```

#### 2. 配置环境变量

创建 `.env` 文件:

```env
# LLM配置
LLM_PROVIDER=dashscope
LLM_API_KEY=your-api-key

# Neo4j配置 (可选)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password

# 其他配置
LOG_LEVEL=INFO
MAX_WORKERS=4
```

#### 3. 使用Docker部署

```bash
# 构建镜像
docker build -t gene-family-mas-v2 .

# 运行容器
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  --env-file .env \
  gene-family-mas-v2
```

#### 4. 使用docker-compose部署

```bash
docker-compose up -d
```

---

## 配置说明

### 配置文件结构

```
config/
├── llm.yaml          # LLM配置
├── rag.yaml          # RAG配置
└── neo4j.yaml        # Neo4j配置
```

### LLM配置 (config/llm.yaml)

```yaml
default:
  provider: dashscope
  model: kimi-k2.5

providers:
  dashscope:
    api_key: ${DASHSCOPE_API_KEY}
    base_url: https://coding.dashscope.aliyuncs.com/v1
  
  ollama:
    base_url: http://localhost:11434
    model: qwen3:0.6b
```

### RAG配置 (config/rag.yaml)

```yaml
vector_store:
  type: in_memory  # 或 qdrant
  
embedding:
  model: bge-large-zh
  device: cpu

retrieval:
  top_k: 10
  threshold: 0.5
  
advanced:
  enable_self_rag: true
  enable_multi_hop: true
  max_iterations: 3
```

---

## 使用示例

### 示例1: 基础RAG查询

```python
import requests

response = requests.post(
    "http://localhost:8000/api/v1/rag/chat",
    json={
        "query": "SPL基因家族在拟南芥中有多少个成员？",
        "mode": "hybrid",
        "top_k": 5
    }
)

print(response.json())
```

### 示例2: Agent编排RAG

```python
response = requests.post(
    "http://localhost:8000/api/v1/rag/advanced/search",
    json={
        "query": "SPL基因如何调控开花？",
        "use_agentic": True,
        "enable_self_rag": True,
        "enable_multi_hop": True
    }
)

result = response.json()
print(f"迭代次数: {result['agent_result']['iteration']}")
print(f"是否使用MultiHop: {result['agent_result']['multi_hop_used']}")
```

### 示例3: RAPTOR层次检索

```python
# 1. 构建树
requests.post(
    "http://localhost:8000/api/v1/raptor/build",
    json={
        "doc_id": "pecan_paper",
        "chunks": [...],
        "max_levels": 3
    }
)

# 2. 层次检索
response = requests.post(
    "http://localhost:8000/api/v1/raptor/search",
    json={
        "query": "SPL基因功能",
        "doc_id": "pecan_paper",
        "strategy": "top_down"
    }
)

results = response.json()
for result in results['results']:
    print(f"[{result['level']}] {result['summary'][:100]}...")
```

### 示例4: 时序知识图谱查询

```python
# 填充演示数据
requests.post("http://localhost:8000/api/v1/temporal/demo/populate")

# 查询时间线
response = requests.post(
    "http://localhost:8000/api/v1/temporal/timeline",
    json={
        "topic": "SPL",
        "start_year": 2020,
        "end_year": 2023
    }
)

timeline = response.json()
for event in timeline['events']:
    print(f"{event['timestamp']}: {event['description']}")
```

### 示例5: 批量处理PDF

```python
import os

pdf_dir = "/path/to/pdfs"
for pdf_file in os.listdir(pdf_dir):
    if pdf_file.endswith('.pdf'):
        with open(os.path.join(pdf_dir, pdf_file), 'rb') as f:
            response = requests.post(
                "http://localhost:8000/api/v1/upload/batch",
                files={"files": f}
            )
        print(f"上传 {pdf_file}: {response.status_code}")
```

---

## 故障排除

### 常见问题

#### 1. 向量存储加载失败

**问题**: `索引文件不存在`

**解决**:
```bash
# 重新构建索引
python scripts/build_index.py
```

#### 2. LLM调用失败

**问题**: `LLM客户端初始化失败`

**解决**:
- 检查API密钥配置
- 检查网络连接
- 查看日志: `tail -f logs/api.log`

#### 3. Neo4j连接失败

**问题**: `无法连接到Neo4j`

**解决**:
```bash
# 检查Neo4j状态
docker ps | grep neo4j

# 或启动本地Neo4j
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:latest
```

#### 4. 内存不足

**问题**: `MemoryError` 或 `Killed`

**解决**:
- 减少 `top_k` 参数
- 使用更小的嵌入模型
- 增加系统内存或交换空间

### 日志查看

```bash
# 查看API日志
tail -f logs/api.log

# 查看RAG日志
tail -f logs/rag.log
```

### 性能优化

1. **启用缓存**: 在配置中设置 `enable_cache: true`
2. **使用Qdrant**: 替换内存存储为Qdrant向量数据库
3. **调整工作线程**: 设置 `MAX_WORKERS=4`

---

## 更新日志

### v2.0.0 (2026-04-17)

- ✅ RAPTOR层次索引
- ✅ 时序知识图谱
- ✅ Agent状态组件
- ✅ 端到端测试
- ✅ 完整API文档

---

**文档维护**: xialab的幸运星