346 lines
5.8 KiB
Markdown
Executable File
346 lines
5.8 KiB
Markdown
Executable File
# 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的幸运星 |