PlantAI-rag/docs/api/README.md

# Gene Family MAS V2 - API文档

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

---

## 目录

1. [基础API](#基础api)
2. [RAG API](#rag-api)
3. [RAPTOR层次索引API](#raptor层次索引api)
4. [时序知识图谱API](#时序知识图谱api)
5. [高级RAG API](#高级rag-api)
6. [知识图谱API](#知识图谱api)

---

## 基础API

### 健康检查

```http
GET /health
```

**响应**:
```json
{
  "status": "healthy"
}
```

---

## RAG API

### RAG状态

```http
GET /api/v1/rag/status
```

**响应**:
```json
{
  "status": "ready",
  "total_chunks": 1423,
  "total_documents": 56,
  "agent_enabled": true
}
```

### RAG搜索

```http
POST /api/v1/rag/chat
```

**请求体**:
```json
{
  "query": "SPL基因家族功能",
  "mode": "hybrid",
  "top_k": 10,
  "include_sources": true,
  "use_llm": false
}
```

**响应**:
```json
{
  "response": "基于检索到的5条文献...",
  "sources": [...],
  "mode": "hybrid",
  "total_chunks": 1423,
  "knowledge_graph": {
    "nodes": [...],
    "edges": [...]
  }
}
```

### 高级RAG搜索

```http
POST /api/v1/rag/advanced/search
```

**请求体**:
```json
{
  "query": "SPL基因在拟南芥中的功能",
  "use_agentic": true,
  "enable_self_rag": true,
  "enable_multi_hop": true,
  "max_iterations": 3
}
```

---

## RAPTOR层次索引API

### 构建RAPTOR树

```http
POST /api/v1/raptor/build
```

**请求体**:
```json
{
  "doc_id": "doc_001",
  "chunks": [
    {"content": "...", "metadata": {}},
    {"content": "...", "metadata": {}}
  ],
  "max_levels": 3,
  "summarization_ratio": 0.3
}
```

**响应**:
```json
{
  "status": "success",
  "root_id": "root_doc_001_xxx",
  "total_nodes": 15,
  "level_stats": {
    "leaf": {"count": 8},
    "summary_1": {"count": 2},
    "root": {"count": 1}
  }
}
```

### RAPTOR层次检索

```http
POST /api/v1/raptor/search
```

**请求体**:
```json
{
  "query": "SPL基因",
  "doc_id": "doc_001",
  "top_k": 5,
  "strategy": "top_down",
  "min_level": 0,
  "max_level": 2
}
```

**响应**:
```json
{
  "query": "SPL基因",
  "results": [
    {
      "node_id": "summary_1_0",
      "level": "summary_1",
      "score": 0.85,
      "content": "...",
      "summary": "[层级1摘要] ...",
      "is_summary": true
    }
  ],
  "levels_covered": ["leaf", "summary_1"]
}
```

### 多层级检索

```http
POST /api/v1/raptor/search/multi-level
```

**请求体**:
```json
{
  "query": "SPL基因",
  "levels": [0, 1, 2]
}
```

---

## 时序知识图谱API

### 创建时序实体

```http
POST /api/v1/temporal/entity
```

**请求体**:
```json
{
  "entity_id": "spl_arabidopsis",
  "name": "SPL基因家族(拟南芥)",
  "entity_type": "gene_family",
  "start_year": 2020,
  "end_year": 2023,
  "properties": {"member_count": 16}
}
```

### 创建时序关系

```http
POST /api/v1/temporal/relation
```

**请求体**:
```json
{
  "relation_id": "rel1",
  "source_id": "spl3",
  "target_id": "flowering",
  "relation_type": "regulates",
  "year": 2021
}
```

### 时序范围查询

```http
POST /api/v1/temporal/query/range
```

**请求体**:
```json
{
  "start_year": 2020,
  "end_year": 2023,
  "entity_types": ["gene_family", "gene"],
  "relation_types": ["regulates", "interacts_with"]
}
```

**响应**:
```json
{
  "entities": [...],
  "relations": [...],
  "total_entities": 10,
  "total_relations": 5
}
```

### 获取时间线

```http
POST /api/v1/temporal/timeline
```

**请求体**:
```json
{
  "topic": "SPL",
  "start_year": 2020,
  "end_year": 2023
}
```

**响应**:
```json
{
  "events": [
    {
      "timestamp": "2020",
      "entity_id": "spl_arabidopsis",
      "entity_name": "SPL基因家族(拟南芥)",
      "event_type": "research_entity",
      "description": "研究: SPL基因家族(拟南芥)"
    }
  ],
  "total_events": 4
}
```

### 获取时间线可视化数据

```http
GET /api/v1/temporal/timeline/visualization?topic=SPL&start_year=2020&end_year=2023
```

**响应**:
```json
{
  "topic": "SPL",
  "visualization_data": {
    "years": [2020, 2021, 2022, 2023],
    "series": [...]
  }
}
```

---

## 高级RAG API

### 查询扩展

```http
POST /api/v1/advanced/query/expand
```

**请求体**:
```json
{
  "query": "SPL基因家族功能",
  "num_expansions": 5
}
```

### 实体链接

```http
POST /api/v1/advanced/entity/link
```

**请求体**:
```json
{
  "text": "SPL基因家族在拟南芥中的功能研究"
}
```

### 引用溯源

```http
POST /api/v1/advanced/citation/add
```

### 动态知识图谱构建

```http
POST /api/v1/advanced/kg/build
```

### 跨论文融合

```http
POST /api/v1/advanced/fusion/cross-paper
```

---

## 知识图谱API

### 获取知识图谱数据

```http
GET /api/v1/kg/graph
```

**响应**:
```json
{
  "nodes": [...],
  "edges": [...],
  "stats": {...}
}
```

---

## 错误处理

所有API返回统一的错误格式:

```json
{
  "detail": "错误描述信息"
}
```

常见HTTP状态码:
- `200` - 成功
- `400` - 请求参数错误
- `404` - 资源不存在
- `500` - 服务器内部错误

---

## 限流与认证

当前版本暂无限流和认证要求。

---

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