肺炎AI辅助诊断

肺炎医疗影像AI辅助诊断模型调用Skill。基于肺炎AI模型接口，支持异步提交胸部CT DICOM压缩包进行分析，查询/轮询获取肺炎检测结果。

> 特别说明：以下模型能力均仅限中国大陆地区科研用途售卖和使用，不得直接用于临床检测与诊疗等目的。

一、触发条件

• 用户需要提交胸部CT DICOM压缩包进行肺炎AI分析
• 用户需要查询已有的肺炎AI分析任务结果
• 用户需要自动轮询等待肺炎AI分析结果
• 用户提及"肺炎检测"、"肺炎AI"、"胸部CT分析"、"DICOM分析"等关键词

二、鉴权方式

2.1 签名算法

采用 HMAC-SHA256 签名算法，计算公式如下：

signature = HMAC-SHA256(token, appId + timestamp)

2.2 请求头参数

2.3 首次使用

用户首次使用时需提供 appId 和 token，如缺失则主动询问：

请提供以下参数以使用肺炎AI诊断接口：
1. appId（合作方ID）
2. token（密钥）

> 安全提示：token 不得出现在前端、日志或客户端代码中，仅在服务端参与签名计算。

三、接口说明

3.1 肺炎 AI 提交接口

• 接口路径：https://pacs.qq.com/openapi/pneumoniaSubmit
• 请求方式：POST
• Content-Type：multipart/form-data
• 数据要求：胸部 CT 序列 DICOM 文件压缩包（ZIP 格式），最大 300MB

请求参数

通过 multipart/form-data 表单提交：

响应字段

调用方式

使用 Bash 工具执行脚本 @scripts/pneumonia_submit.py：

python3 {SKILL_DIR}/scripts/pneumonia_submit.py \
  --app_id "{appId}" \
  --token "{token}" \
  --study_id "{studyId}" \
  --dicom_file "{zip文件绝对路径}" \
  [--study_date "{检查时间戳}"] \
  [--need_report "1"] \
  [--patient_id "{患者ID}"] \
  [--patient_name "{患者姓名}"] \
  [--patient_gender "{1或2}"] \
  [--patient_age "{年龄}"] \
  [--study_name "{检查项目}"]

> {SKILL_DIR} 为本Skill的安装目录，执行时替换为实际路径。

3.2 肺炎 AI 查询接口

• 接口路径：https://pacs.qq.com/openapi/pneumoniaQuery
• 请求方式：POST
• Content-Type：application/json

请求参数（Body，JSON）

响应字段

status 状态值

调用方式

使用 Bash 工具执行脚本 @scripts/pneumonia_query.py：

python3 {SKILL_DIR}/scripts/pneumonia_query.py \
  --app_id "{appId}" \
  --token "{token}" \
  --task_id "{taskId}" \
  [--need_report "1"]

3.3 自动轮询等待结果

提交成功后自动轮询查询接口，直到任务完成或失败。

调用方式

使用 Bash 工具执行脚本 @scripts/pneumonia_poll.py：

python3 {SKILL_DIR}/scripts/pneumonia_poll.py \
  --app_id "{appId}" \
  --token "{token}" \
  --task_id "{taskId}" \
  [--need_report "1"] \
  [--initial_wait 30] \
  [--interval 10] \
  [--max_attempts 300]

参数说明：

3.4 业务状态码（head.code）

四、结果展示

将分析结果结构化展示给用户：

• 肺炎表征概率：pneumoniaSign 值（如 "肺炎表征 : 97.5%"）
• 感染摘要：全肺/左肺/右肺感染占比
• 病灶详情：每处病灶的肺叶位置、层号范围、体积、体积占比、平均CT值
• 报告链接：如 needReport=1，提供 PDF 报告 URL

pneumoniaAnalysis 格式说明：

第一部分：全肺感染比例摘要

占全肺6.2%; 左肺 肺炎占3.1%; 右肺 肺炎占9.3%

若无感染则为：该患者无肺炎感染

第二部分：病灶详情列表

共3处肺炎感染:
（1）右肺上叶【99 / 182】，体积77657mm³，占右肺体积6.6%，平均CT值-603HU
（2）右肺下叶【157 / 210】，体积49177mm³，占右肺体积4.2%，平均CT值-511HU
（3）右肺中叶【181 / 206】，体积4668mm³，占右肺体积0.4%，平均CT值-495HU

各字段含义：

• 占全肺X.X%：全肺感染体积占比
• 左肺 肺炎占X.X%：左肺感染体积占比
• 右肺 肺炎占X.X%：右肺感染体积占比
• （N）：病灶序号
• [位置]：病灶所在肺叶（左肺上叶/左肺下叶/右肺上叶/右肺中叶/右肺下叶）
• 【起始层 / 结束层】：病灶在 CT 序列中的层号范围
• 体积Xmm³：病灶体积
• 占[左/右]肺体积X.X%：病灶占对应侧肺的体积比
• 平均CT值XHU：病灶区域的平均 CT 值

五、注意事项

• 密钥安全：token 不得出现在前端、日志或客户端代码中；仅在服务端参与签名。
• 时间戳对齐：本地时钟需与 NTP 同步，时间戳与服务器偏差过大将导致鉴权失败。
• 文件格式：DICOM 文件需打包为 ZIP 格式上传，ZIP 内不应包含非 DICOM 文件（如 __MACOSX、隐藏文件等）。
• 文件大小：ZIP 包不超过 300 MB（服务端 multipart 限制）。
• 序列要求：ZIP 包中至少需包含一个图像数量 > 10 张的 CT 序列，否则系统将回退到使用全部图像。
• 并发控制：请根据签约并发阈值控制 QPS，避免触发限流。
• 配额监控：请关注 resourceRemaining，及时续费。配额在 AI 分析完成后由后台异步扣减，提交时的 resourceRemaining 值可能略有延迟。
• 处理时间：肺炎 AI 分析需要较长时间（3~10 分钟），请勿在提交后立即查询，建议等待 30 秒后开始轮询。
• 僵尸任务清理：超过 24 小时未完成的任务将被系统自动标记为失败并移除，不计费。
• taskId 格式：提交成功后返回的 taskId 格式为 {studyId}_{毫秒时间戳}，查询时需使用完整 taskId。
• 多 taskId 查询：查询接口支持分号分隔的多个 taskId，聚合规则为：任一未完成则整体返回"处理中"。
• 重复计费：相同文件用不同 studyId 多次提交会生成不同 taskId，按多次计费。

六、试用与正式使用

试用

当前提供的试用凭证：

如需 sample 肺炎CT数据：可查询访问公开数据集，建议CT层厚＜2mm。

正式使用

如需长期使用，请联系 miying@tencent.com 或访问腾讯健康官网。

七、技术支持

遇到问题时请提供以下信息：

• appId、requestId、taskId
• 调用时间（含时区）
• 请求头与请求参数
• 错误响应体完整内容

八、验证

1. 提交任务后检查返回 head.code 是否为 0，且 head.taskId 非空
2. 查询任务后检查 status 字段是否为"处理完成"或"处理失败"
3. 处理完成时验证 pneumoniaSign 和 pneumoniaAnalysis 非空
4. 签名错误时检查系统时间是否与NTP同步

Reference

• 完整API文档：@references/api_pneumonia.md