PlantAI-rag/docs/user-guide

Gene Family MAS V2 - 使用手册

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

---

目录

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

---

快速开始

环境要求

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

安装依赖

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

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

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

启动服务

# 启动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. 环境准备

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

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

2. 配置环境变量

创建 .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部署

# 构建镜像
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部署

docker-compose up -d

---

配置说明

配置文件结构

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

LLM配置 (config/llm.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)

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查询

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

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层次检索

# 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: 时序知识图谱查询

# 填充演示数据
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

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. 向量存储加载失败

问题: 索引文件不存在

解决:

# 重新构建索引
python scripts/build_index.py

2. LLM调用失败

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

解决:

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

3. Neo4j连接失败

问题: 无法连接到Neo4j

解决:

# 检查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 参数
• 使用更小的嵌入模型
• 增加系统内存或交换空间

日志查看

# 查看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的幸运星