PlantAI-rag/docs/api/README.md

Gene Family MAS V2 - API文档

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

---

目录

1. 基础API
2. RAG API
3. RAPTOR层次索引API
4. 时序知识图谱API
5. 高级RAG API
6. 知识图谱API

---

基础API

健康检查

GET /health

响应:

{
  "status": "healthy"
}

---

RAG API

RAG状态

GET /api/v1/rag/status

响应:

{
  "status": "ready",
  "total_chunks": 1423,
  "total_documents": 56,
  "agent_enabled": true
}

RAG搜索

POST /api/v1/rag/chat

请求体:

{
  "query": "SPL基因家族功能",
  "mode": "hybrid",
  "top_k": 10,
  "include_sources": true,
  "use_llm": false
}

响应:

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

高级RAG搜索

POST /api/v1/rag/advanced/search

请求体:

{
  "query": "SPL基因在拟南芥中的功能",
  "use_agentic": true,
  "enable_self_rag": true,
  "enable_multi_hop": true,
  "max_iterations": 3
}

---

RAPTOR层次索引API

构建RAPTOR树

POST /api/v1/raptor/build

请求体:

{
  "doc_id": "doc_001",
  "chunks": [
    {"content": "...", "metadata": {}},
    {"content": "...", "metadata": {}}
  ],
  "max_levels": 3,
  "summarization_ratio": 0.3
}

响应:

{
  "status": "success",
  "root_id": "root_doc_001_xxx",
  "total_nodes": 15,
  "level_stats": {
    "leaf": {"count": 8},
    "summary_1": {"count": 2},
    "root": {"count": 1}
  }
}

RAPTOR层次检索

POST /api/v1/raptor/search

请求体:

{
  "query": "SPL基因",
  "doc_id": "doc_001",
  "top_k": 5,
  "strategy": "top_down",
  "min_level": 0,
  "max_level": 2
}

响应:

{
  "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"]
}

多层级检索

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

请求体:

{
  "query": "SPL基因",
  "levels": [0, 1, 2]
}

---

时序知识图谱API

创建时序实体

POST /api/v1/temporal/entity

请求体:

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

创建时序关系

POST /api/v1/temporal/relation

请求体:

{
  "relation_id": "rel1",
  "source_id": "spl3",
  "target_id": "flowering",
  "relation_type": "regulates",
  "year": 2021
}

时序范围查询

POST /api/v1/temporal/query/range

请求体:

{
  "start_year": 2020,
  "end_year": 2023,
  "entity_types": ["gene_family", "gene"],
  "relation_types": ["regulates", "interacts_with"]
}

响应:

{
  "entities": [...],
  "relations": [...],
  "total_entities": 10,
  "total_relations": 5
}

获取时间线

POST /api/v1/temporal/timeline

请求体:

{
  "topic": "SPL",
  "start_year": 2020,
  "end_year": 2023
}

响应:

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

获取时间线可视化数据

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

响应:

{
  "topic": "SPL",
  "visualization_data": {
    "years": [2020, 2021, 2022, 2023],
    "series": [...]
  }
}

---

高级RAG API

查询扩展

POST /api/v1/advanced/query/expand

请求体:

{
  "query": "SPL基因家族功能",
  "num_expansions": 5
}

实体链接

POST /api/v1/advanced/entity/link

请求体:

{
  "text": "SPL基因家族在拟南芥中的功能研究"
}

引用溯源

POST /api/v1/advanced/citation/add

动态知识图谱构建

POST /api/v1/advanced/kg/build

跨论文融合

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

---

知识图谱API

获取知识图谱数据

GET /api/v1/kg/graph

响应:

{
  "nodes": [...],
  "edges": [...],
  "stats": {...}
}

---

错误处理

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

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

常见HTTP状态码:

• 200 - 成功
• 400 - 请求参数错误
• 404 - 资源不存在
• 500 - 服务器内部错误

---

限流与认证

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

---

文档维护: xialab的幸运星