初始提交

2026-07-10 17:59:59 +08:00
commit 5bb98a937a
660 changed files with 871233 additions and 0 deletions
@@ -0,0 +1,396 @@
+# 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的幸运星