开放 API

身份认证

所有 /v1/* 接口使用 Bearer 令牌。密钥形如 dztx_ 加 48 位十六进制串，服务端只保存 SHA-256 哈希，明文仅在创建时返回一次。

Authorization: Bearer dztx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

签发密钥需要管理员令牌（部署时通过环境变量 ADMIN_TOKEN 设置）：

curl -X POST http://<host>/api/keys \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"某三甲医院-试用"}'

完整跑一遍五段推演链路并返回结果。这是唯一需要的核心接口。

请求参数

调用示例

返回示例（真实运行结果，节选）

{
  "run_id": "43b2d3ce-db95-49a7-9653-5dbac499cb16",
  "domain": "medical",
  "summary": "58岁男性，长期吸烟，新发刺激性干咳、痰中带血、体重下降、盗汗，CT示肺部恶性征结节伴纵隔淋巴结肿大",
  "urgency": "urgent",
  "risk_score": 86,
  "entropy_bits": 1.8967,
  "observability": 0.4722,
  "hypotheses": [
    { "id": "h1", "label": "非小细胞肺癌（NSCLC），肺腺癌可能性大", "posterior": 0.3882 },
    { "id": "h2", "label": "肺结核（慢性纤维空洞型或淋巴结结核）",   "posterior": 0.2869 },
    { "id": "h3", "label": "肺真菌病（如隐球菌或曲霉感染）",         "posterior": 0.1772 },
    { "id": "h4", "label": "类癌或神经内分泌肿瘤",                   "posterior": 0.1477 }
  ],
  "recommendations": [
    { "rank": 1, "action": "痰抗酸染色、Xpert MTB/RIF及真菌培养",
      "utility": 0.5244, "info_gain_bits": 0.2621,
      "timeliness": 0.929, "burden": 0.098, "expected_risk": 55.0 },
    { "rank": 2, "action": "支气管镜检查+活检及刷检",
      "utility": 0.5189, "info_gain_bits": 0.6281,
      "timeliness": 0.893, "burden": 0.530, "expected_risk": 72.6 },
    { "rank": 3, "action": "PET-CT全身显像",
      "utility": 0.4842, "info_gain_bits": 0.2409,
      "timeliness": 0.964, "burden": 0.327, "expected_risk": 67.6 }
  ],
  "calibration": {
    "actionsEvaluated": 3, "coherenceViolations": 3, "violationRate": 1,
    "negativeInfoGain": 0, "negativeRate": 0,
    "meanMarginalError": 0.088942, "maxMarginalError": 0.120135,
    "minRawInfoGain": 0.1455,     "minCalibratedInfoGain": 0.2409,
    "maxIpfIterations": 49,       "maxIpfResidual": 8.83e-15,
    "rankOrderCalibrated":   ["a2", "a1", "a3"],
    "rankOrderUncalibrated": ["a1", "a2", "a3"],
    "rankKendallTau": 0.3333, "rankChanged": true, "topActionChanged": true
  },
  "report": { "headline": "优先痰检排查感染性病因，避免过早有创检查",
              "reasoning": "...", "safetyNet": [...], "watchouts": [...] },
  "warnings": [],
  "telemetry": { "totalMs": 93435, "kernelDeterministic": true, "kernelTrainableParams": 0 }
}

取回完整推演记录，包含 /v1/simulate 精简返回中省略的部分： 每个结构化变量的证据出处、每个动作的逐结局分支及其校准前后条件后验、 未校准对照组的完整打分。用于合规审计与第三方独立复算。

curl http://<host>/v1/runs/8f3c1a94-...-2b6e \
  -H "Authorization: Bearer $DZTX_KEY"

行业模板

模板只改变三件事：效用函数的权重、时间预算、以及给底座模型的角色提示。 推演内核完全相同——新增一个行业不需要改内核任何一行代码。

返回字段说明

校准指标怎么读

calibration 是本平台区别于「让大模型直接给建议」的关键，它记录了底座模型这一次的输出质量。

错误码

免密只读接口

直接调用校准内核，不经过任何大模型。用于验证算法本身。

curl -X POST http://<host>/api/kernel/calibrate \
  -H "Content-Type: application/json" \
  -d '{
    "prior":       [0.40, 0.30, 0.20, 0.10],
    "branchProbs": [0.50, 0.30, 0.20],
    "posteriors":  [[0.70,0.15,0.10,0.05],
                    [0.10,0.60,0.20,0.10],
                    [0.05,0.20,0.55,0.20]]
  }'

返回校准前后的边缘分布、边缘偏差、信息增益、 IPF 迭代次数与残差，以及非负性/有界性是否成立。

限制与 SLA