跳转至

API 接口文档

版本: v3.2.1
基础 URL: http://localhost:8000
更新日期: 2026-05-13

⚠️ URL 前缀说明: pipeline_16s_router 挂载于 /api/v1/16s/（有 /v1 前缀），16S pipeline v1 服务于 /api/v1/16s-pipeline-v1，v2.3服务由 sixteen_s_pipeline_v23.py 提供。

1. 认证 (Auth)

获取 Token

POST /auth/token
Content-Type: application/x-www-form-urlencoded

请求参数:

参数 类型 必填 说明
username string 是 用户名
password string 是 密码

响应:

{
  "status": "success",
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 3600
}

验证 Token

POST /auth/verify
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "valid": true,
  "user_id": "user_001"
}

用户注册

POST /auth/register

请求体:

{
  "username": "string",
  "email": "string",
  "password": "string"
}

获取当前用户

GET /auth/me
Authorization: Bearer <token>

修改密码

POST /auth/change-password
Authorization: Bearer <token>

登出

POST /auth/logout
Authorization: Bearer <token>

获取演示 Token

GET /auth/demo-token

2. 系统管理 (System)

系统状态

GET /api/v1/system/status

响应:

{
  "status": "online",
  "version": "v3.2.1-minimax",
  "security": {
    "rate_limiting": true,
    "rate_limit_requests": 100,
    "rate_limit_window": 60,
    "jwt_enabled": true
  }
}

健康检查

GET /health

数据库健康

GET /api/v1/db/health

缓存清理

POST /api/v1/system/cache/cleanup
Authorization: Bearer <token>

系统信息

GET /api/v1/admin/system-info
Authorization: Bearer <token>

3. 患者档案 (Profiles)

列表

GET /api/v1/profiles/list
Authorization: Bearer <token>

获取档案

GET /api/v1/profiles/{patient_id}
Authorization: Bearer <token>

创建档案

POST /api/v1/profiles
Authorization: Bearer <token>

更新档案

PUT /api/v1/profiles/{patient_id}
Authorization: Bearer <token>

4. 分析记录 (Records)

获取记录列表

GET /api/v1/records
Authorization: Bearer <token>

获取单条记录

GET /api/v1/records/{record_id}
Authorization: Bearer <token>

获取统计

GET /api/v1/records/stats
Authorization: Bearer <token>

删除记录

DELETE /api/v1/records/{record_id}
Authorization: Bearer <token>

5. 组学分析 - 16S / 微生物组

上传并分析（⚠️ 无 /v1 前缀）

POST /api/16s/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>
参数 类型 必填 说明
file file 是 FASTQ 文件
sample_id string 否 样本 ID

响应:

{
  "status": "success",
  "sample_id": "SAMPLE_001",
  "health_score": 78,
  "enterotype": "B肠型",
  "alpha_diversity": {
    "shannon": 4.2,
    "simpson": 0.89,
    "chao1": 350
  }
}

获取分析结果

GET /api/16s/result/{sample_id}
Authorization: Bearer <token>

16S Pipeline 健康检查

GET /api/v1/16s-pipeline/health

模拟 PDF 生成

POST /api/v1/16s-pipeline/simulate-pdf
Authorization: Bearer <token>

微生物组上传

POST /api/v1/microbiome/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "interpretation": "肠道菌群分析...",
  "key_findings": [
    "有益菌: 双歧杆菌↑, 乳杆菌↑",
    "有害菌: 艰难梭菌未检出"
  ],
  "enterotype": "B肠型",
  "scfa_prediction": {
    "butyrate": "正常",
    "acetate": "正常",
    "propionate": "略高"
  }
}

微生物组 PDF 导出

POST /api/v1/microbiome/export-pdf
Authorization: Bearer <token>

6. 组学分析 - 基因组 / WGS / RNA-seq

基因组上传

POST /api/v1/genomics/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "interpretation": "基于基因检测结果的详细解读...",
  "key_findings": [
    "叶酸代谢能力正常",
    "乳糖耐受基因阳性"
  ],
  "risk_assessment": "低风险"
}

WGS 样本列表

GET /api/v1/wgs/samples
Authorization: Bearer <token>

WGS 分析

POST /api/v1/wgs/analyze
Authorization: Bearer <token>

RNA-seq 分析

POST /api/v1/rnaseq/analyze
Authorization: Bearer <token>

RNA-seq 任务状态

GET /api/v1/rnaseq/jobs/{job_id}
Authorization: Bearer <token>

表观遗传上传

POST /api/v1/epigenomics/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

芯片分析上传

POST /api/v1/array/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

芯片结果

GET /api/v1/array/results/{id}
Authorization: Bearer <token>

芯片历史

GET /api/v1/array/history
Authorization: Bearer <token>

芯片报告

GET /api/v1/array/report/{id}
Authorization: Bearer <token>

7. 组学分析 - 代谢组 / 蛋白组 / 免疫组

代谢组上传

POST /api/v1/metabolomics/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "interpretation": "代谢状态评估...",
  "key_findings": [
    "氨基酸代谢正常",
    "糖代谢指标略高"
  ]
}

蛋白组上传

POST /api/v1/proteomics/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

免疫组上传

POST /api/v1/immunology/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

转录组上传

POST /api/v1/transcriptomics/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

心血管分析上传

POST /api/v1/cardiovascular/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

8. 多组学整合

上传报告

POST /api/v1/multi-omics/upload-report
Content-Type: multipart/form-data
Authorization: Bearer <token>
参数 类型 必填 说明
file file 是 报告文件
patient_id string 是 患者 ID
report_type string 是 报告类型

报告类型: - 体检报告 / 基因组学 / 微生物组学 - 代谢组学 / 蛋白质组学 / 免疫组学 - 心血管专项 / 表观基因组学 / 转录组学

解读报告

POST /api/v1/multi-omics/interpret-report
Content-Type: multipart/form-data
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "interpretation": "AI解读内容...",
  "key_findings": [
    "发现1: ...",
    "发现2: ..."
  ],
  "summary": "简要摘要"
}

整合分析

POST /api/v1/multi-omics/integrate
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <token>
参数 类型 必填 说明
patient_id string 是 患者 ID
health_profile JSON 是 健康档案
results_json JSON 是 解读结果

响应:

{
  "status": "success",
  "integrated_summary": "综合评估...",
  "risk_scores": {
    "cardiovascular": "中",
    "metabolic": "高",
    "immune": "低",
    "digestive": "低"
  },
  "food_recommendations": ["西兰花", "三文鱼", "核桃"],
  "integrated_recommendations": [
    "调整饮食结构",
    "定期监测血糖"
  ]
}

生成健康方案

POST /api/v1/multi-omics/generate-plan
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <token>
参数 类型 必填 说明
patient_id string 是 患者 ID
health_profile JSON 是 健康档案
integration_result JSON 是 整合结果
target_period string 否 目标周期 (1个月/3个月/6个月/1年)

响应:

{
  "status": "success",
  "health_plan": {
    "executive_summary": "方案概要...",
    "nutrition_plan": {
      "diet_principles": ["低糖", "高蛋白"],
      "recommended_foods": ["西兰花", "三文鱼"],
      "foods_to_avoid": ["奶茶", "炸鸡"]
    },
    "exercise_plan": {
      "weekly_frequency": "5次",
      "intensity": "中等",
      "duration": "30分钟"
    },
    "sleep_plan": {
      "target_hours": "8小时"
    },
    "monitoring_plan": {
      "daily_tracking": ["体重", "步数", "睡眠时长"]
    }
  }
}

导出 PDF 报告

POST /api/v1/multi-omics/export-pdf
Content-Type: multipart/form-data
Authorization: Bearer <token>
参数 类型 必填 说明
patient_id string 是 患者 ID
health_profile JSON 是 健康档案
reports_json JSON 是 报告数据
integration_json JSON 是 整合结果
plan_json JSON 否 健康方案

9. 高级分析

高级整合分析

POST /api/v1/multi-omics/advanced-integrate
Content-Type: application/json
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "advanced_analysis": {
    "cross_omics_correlations": [...],
    "cluster_analysis": {...},
    "pathway_enrichment": [...]
  }
}

DIABLO 多组学分析

POST /api/v1/multi-omics/diablo-analyze
Content-Type: application/json
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "diablo_result": {
    "component_1": {"loading": [...], "variance": "15%"},
    "component_2": {"loading": [...], "variance": "10%"},
    "discriminant_function": {...}
  }
}

MOFA 降维分析

POST /api/v1/multi-omics/mofa-analyze
Content-Type: application/json
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "mofa_result": {
    "factors": [...],
    "variance_explained": {...},
    "samples_coordinates": [...]
  }
}

肠脑轴分析

POST /api/v1/gut-brain-axis/analyze
Content-Type: application/json
Authorization: Bearer <token>

代谢性炎症分析

POST /api/v1/metabolic-inflammation/analyze
Content-Type: application/json
Authorization: Bearer <token>

综合健康评估

POST /api/v1/comprehensive-health/analyze
Content-Type: application/json
Authorization: Bearer <token>

统计整合

POST /api/v1/statistical-integration/analyze
Content-Type: application/json
Authorization: Bearer <token>

热图分析

POST /api/v1/heatmap/generate
Authorization: Bearer <token>

代谢通路分析

POST /api/v1/metabolism/analyze
Authorization: Bearer <token>

肠道菌群功能预测

POST /api/v1/microbiome/function-predict
Authorization: Bearer <token>

10. 健康评估

BioAge 生理年龄预测

POST /api/v1/bioage/predict
Content-Type: application/json
Authorization: Bearer <token>

请求:

{
  "age": 45,
  "gender": "男",
  "indicators": {
    "ALT": 25,
    "AST": 22,
    "ALP": 68
  }
}

响应:

{
  "status": "success",
  "bio_age": 42,
  "biological_age_delta": -3,
  "assessment": "比实际年龄年轻3岁",
  "risk_factors": [...]
}

ctDNA 液态活检

POST /api/v1/ctdna/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "variants": [...],
  "risk_assessment": "低风险",
  "recommendations": [...]
}

免疫组库分析

POST /api/v1/immune-repertoire/{sample_id}/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

响应:

{
  "status": "success",
  "tcr_diversity": 0.85,
  "bcr_diversity": 0.78,
  "clonality": {...}
}

肿瘤早筛

POST /api/v1/cancer-screening/submit
Authorization: Bearer <token>

遗传病筛查

POST /api/v1/genetic-disease/analyze
Authorization: Bearer <token>

药物基因组学

POST /api/v1/pharmacogenomics/analyze
Authorization: Bearer <token>

个体特质分析

POST /api/v1/traits/analyze
Authorization: Bearer <token>

11. AI 服务

AI 辅助诊断

POST /diagnosis/analyze
Authorization: Bearer <token>

RAG 知识问答

POST /rag/query
Authorization: Bearer <token>

RAG 检索

POST /api/v1/rag/query
Authorization: Bearer <token>

AI 健康对话

WS /chat/ws

健康聊天机器人

POST /api/v1/chatbot/send
Authorization: Bearer <token>

Agent - 任务分析

POST /api/v1/agent/task-analysis
Authorization: Bearer <token>

Agent - 方法设计

POST /api/v1/agent/method-design
Authorization: Bearer <token>

Agent - 快速执行

POST /api/v1/agent/quick-execute
Authorization: Bearer <token>

Agent - 代码执行

POST /api/v1/agent/code-execution
Authorization: Bearer <token>

Agent - Pipeline

POST /api/v1/agent/pipeline
Authorization: Bearer <token>

工作流编排

POST /api/v1/workflows/execute
Authorization: Bearer <token>

工作流状态

GET /api/v1/workflows/{workflow_id}
Authorization: Bearer <token>

工作流列表

GET /api/v1/workflows
Authorization: Bearer <token>

批量处理提交

POST /api/v1/batch/submit
Authorization: Bearer <token>

批量处理状态

GET /api/v1/batch/{job_id}
Authorization: Bearer <token>

批量处理历史

GET /api/v1/batch/history
Authorization: Bearer <token>

Nextflow 流程桥接

POST /api/v1/nextflow/run
Authorization: Bearer <token>

Nextflow 状态

GET /api/v1/nextflow/{run_id}
Authorization: Bearer <token>

12. 管理功能

仪表盘统计

GET /api/v1/admin/dashboard/stats
Authorization: Bearer <token>

用户列表

GET /api/v1/admin/users
Authorization: Bearer <token>

患者档案管理

GET /api/v1/admin/profiles
Authorization: Bearer <token>

数据库迁移

GET /api/v1/admin/migrations
Authorization: Bearer <token>

运行迁移

POST /api/v1/admin/migrations/run
Authorization: Bearer <token>

导出服务

POST /api/v1/exports/generate
Authorization: Bearer <token>

分享创建

POST /api/v1/share/create
Authorization: Bearer <token>

分享列表

GET /api/v1/share/list
Authorization: Bearer <token>

分享验证

GET /api/v1/share/verify/{token}

报告生成

POST /api/v1/reports/generate
Authorization: Bearer <token>

通知发送

POST /notifications/send
Authorization: Bearer <token>

13. 报告模板 (奇云诺德)

体检报告

POST /api/v1/medical-report/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

获取体检报告

GET /api/v1/medical-report/patient/{patient_id}
Authorization: Bearer <token>

各类报告上传（通用）

报告类型 端点
基因组报告 POST /api/v1/genomics/upload
微生物组报告 POST /api/v1/microbiome/upload
代谢组报告 POST /api/v1/metabolomics/upload
蛋白组报告 POST /api/v1/proteomics/upload
免疫组报告 POST /api/v1/immunology/upload
心血管报告 POST /api/v1/cardiovascular/upload
表观遗传报告 POST /api/v1/epigenomics/upload
转录组报告 POST /api/v1/transcriptomics/upload

15. 异步报告处理（商业化 P2）

大文件上传（> 5MB）自动异步处理，避免 HTTP 超时。阈值可通过环境变量 LARGE_FILE_ASYNC_THRESHOLD_MB 配置。

异步上传报告

POST /api/v1/async-reports/upload/{report_type}
Content-Type: multipart/form-data
Authorization: Bearer <token>
参数 类型 必填 说明
file file 是 报告文件
patient_id string 是 患者 ID
report_source string 否 来源（默认：用户上传）
report_date string 是 报告日期
async_process bool 否 true=强制异步处理

响应（大文件 > 5MB）:

{
  "status": "processing",
  "task_id": "ASYNC-20260513-xxxxxx",
  "async": true,
  "message": "文件已接收(12.5MB)，正在后台处理",
  "query_url": "/async-reports/ASYNC-20260513-xxxxxx"
}

查询异步任务状态

GET /api/v1/async-reports/{task_id}
Authorization: Bearer <token>

响应:

{
  "task_id": "ASYNC-20260513-xxxxxx",
  "task_type": "medical_report",
  "status": "processing",
  "progress": 60,
  "created_at": "2026-05-13T08:00:00",
  "result": null,
  "error": null
}

状态流转: pending → processing → completed / failed / cancelled

异步任务列表

GET /api/v1/async-reports?patient_id=P001&status=completed&limit=50
Authorization: Bearer <token>

取消异步任务

DELETE /api/v1/async-reports/{task_id}
Authorization: Bearer <token>

异步任务统计

GET /api/v1/async-reports/stats/overview
Authorization: Bearer <token>

16. 错误码

错误码 说明
400 请求参数错误
401 认证失败 / Token 无效
403 权限不足
404 资源不存在
413 文件过大（默认 50MB）
415 不支持的媒体类型
429 请求过于频繁（限流触发）
500 服务器内部错误
502 上游服务错误
503 服务不可用
504 上游超时

17. 请求示例

Python

import requests

# 获取 Token
resp = requests.post("http://localhost:8000/auth/token",
    data={"username": "admin", "password": "admin123"})
token = resp.json()["access_token"]

headers = {"Authorization": f"Bearer {token}"}

# 上传 16S FASTQ 文件
with open("sample_R1.fastq.gz", "rb") as f:
    resp = requests.post(
        "http://localhost:8000/api/16s/upload",
        headers=headers,
        files={"file": ("R1.fastq.gz", f, "application/gzip")},
        data={"sample_id": "TEST_001"}
    )
print(resp.json())

# 多组学整合分析
resp = requests.post(
    "http://localhost:8000/api/v1/multi-omics/integrate",
    headers=headers,
    data={
        "patient_id": "P001",
        "health_profile": json.dumps({"age": 45, "gender": "男"}),
        "results_json": json.dumps({"genomics": {...}, "microbiome": {...}})
    }
)
print(resp.json())

cURL

# 获取 Token
TOKEN=$(curl -s -X POST http://localhost:8000/auth/token \
  -d "username=admin&password=admin123" | jq -r '.access_token')

# 上传体检报告
curl -X POST http://localhost:8000/api/v1/medical-report/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@report.pdf"

# BioAge 预测
curl -X POST http://localhost:8000/api/v1/bioage/predict \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"age": 45, "gender": "男", "indicators": {"ALT": 25, "AST": 22}}'

文档版本: v3.2.1 | 最后更新: 2026-05-13