GSA 基因芯片分析 API

GSA (Genome Sequencing Accelerator) — 全基因组SNP芯片智能分析引擎
版本: v3.3.0 · 2026-07-12

概述

GSA 分析引擎提供 SNP 芯片数据全自动分析，输入 VCF 文件或 SNP 列表，返回： - 质控结果（QC passed/failed） - 疾病风险评估（481 种疾病覆盖） - 高/中/低风险分级 - 中文 PDF 报告（可选）

基础信息

项目	值
端点	`POST /api/v1/array/analyze`
端口	8004
认证	无（开发模式）
报告存储	`bioinfo_db.reports`（PostgreSQL）

API 端点

`POST /api/v1/array/analyze`

请求

Content-Type: multipart/form-data

参数	类型	必填	说明
`sample_id`	string	是	样本唯一标识
`file`	file	是	VCF 文件（.vcf 或 .txt）
`generate_pdf_report`	string	否	`1` 开启 PDF 报告生成（默认 `0`）

VCF 文件格式示例：

##fileformat=VCFv4.2
#CHROM  POS ID  REF ALT QUAL    FILTER  INFO
1   10511   rs12345 G   A   .   PASS    .
1   23790   rs67890 C   T   .   PASS    .

SNP 列表格式（每行一个 rsID）：

rs12345
rs67890
rs2468

响应

{
  "status": "success",
  "sample_id": "SAMPLE_001",
  "total_snps": 41,
  "assessed_items": 28,
  "qc": {
    "sample_id": "SAMPLE_001",
    "total_snps": 41,
    "assessed_items": 28,
    "qc_passed": true,
    "call_rate": 0.95
  },
  "high_risk": [
    {
      "disease_name": "阿尔茨海默病",
      "risk_level": "高风险",
      "gene": "APOE",
      "snp_id": "rs429358",
      "genotype": "CT",
      "odds_ratio": 3.2,
      "population_prevalence": "25%",
      "recommendation": "建议进一步基因检测和专科随访"
    }
  ],
  "medium_risk": [...],
  "low_risk": [...],
  "categories": {
    "神经系统": [...],
    "心血管系统": [...],
    "内分泌系统": [...]
  },
  "summary": {
    "total_assessed": 28,
    "high_risk_count": 2,
    "medium_risk_count": 5,
    "low_risk_count": 21
  },
  "pdf_path": "/home/ubuntu/bioinfo-system/data/array_reports/PDF_FINAL/PDF_FINAL_report.pdf",
  "report_id": 42
}

响应码

状态码	说明
200	分析成功
400	参数缺失或文件格式错误
500	服务器内部错误

`GET /api/v1/array/health`

服务健康检查。

响应：

{
  "status": "ok",
  "engine": "GSAE2E",
  "version": "3.3.0"
}

`GET /api/v1/array/diseases`

获取支持的全部 481 种疾病列表。

响应：

{
  "total": 481,
  "diseases": [
    {"code": "AD_001", "name": "阿尔茨海默病", "category": "神经系统"},
    {"code": "CAD_001", "name": "冠心病", "category": "心血管系统"},
    ...
  ]
}

`GET /api/v1/database/health`

bioinfo_db PostgreSQL 连接健康检查。

使用示例

cURL

# 基础分析（无 PDF）
curl -X POST 'http://124.220.107.42:8004/api/v1/array/analyze' \
  -F 'sample_id=TEST_001' \
  -F 'file=@sample.vcf'

# 生成 PDF 报告
curl -X POST 'http://124.220.107.42:8004/api/v1/array/analyze?generate_pdf_report=1' \
  -F 'sample_id=TEST_001' \
  -F 'file=@sample.vcf'

Python

import requests

url = "http://124.220.107.42:8004/api/v1/array/analyze"
files = {"file": open("sample.vcf", "rb")}
data = {"sample_id": "TEST_001", "generate_pdf_report": "1"}

resp = requests.post(url, files=files, data=data)
result = resp.json()
print(result["high_risk"])

PDF 报告

PDF 生成由 generate_pdf_report=1 触发，生成后： - 返回 pdf_path 字段（服务器端路径） - 自动保存至 bioinfo_db.reports 表（report_path 字段）

PDF 内容： - 页眉：Bayx 基因芯片分析报告 - 第1页：样本摘要 + 高风险项目（红色） - 第2页：中高风险详情列表 - 字体：WQYZenHei（文泉驿正黑）

已知问题

Mars SSH 密码失效（2026-07-12）

Mars 服务器 SSH 密码已变更，当前无法远程连接。本地已有恢复脚本：

# SSH 恢复后执行
scp /tmp/mars_8004_restore.sh ubuntu@124.220.107.42:/tmp/
ssh ubuntu@124.220.107.42 "bash /tmp/mars_8004_restore.sh"

ai_diagnosis 模块导入挂起

services/ai_diagnosis.py 在 main.py 启动时会导致进程挂起，原因待查。当前 main.py 中已禁用该路由。

更新日志

日期	版本	变更
2026-07-12	v3.3.0	首次文档化 GSA API，PDF 生成完成，history 存储开发中