体检报告分析
1. 文档说明 & 版本记录
V1.1
2. 交互流程概述
由于体检报告(PDF)解析与多模态大模型解读属于耗时操作,本服务采用 异步任务(Asynchronous Task) 模式:
- 提交任务:客户端调用提交接口,上传 PDF 链接和问卷信息,获取
taskId。 - 开始解读:客户端使用
taskId调用开始解读接口,启动解读任务。 - 轮询结果:客户端使用
taskId定时调用查询接口,检查任务状态。 - 获取报告:当状态为
finish时,返回完整的解读数据。
3. 接口定义
3.1. 提交解读任务 (Submit Task)
用于提交体检报告 PDF 及用户健康问卷数据,校验体检报告的合法性(耗时 5s~10s)。校验通过返回 taskId
- 接口地址: https://openapi.wisediag.com/api/report/upload
- 请求方式:
POST - Content-Type:
application/json
请求参数 (Request)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 体检报告 PDF 文件的下载链接 (需保证服务侧可公开访问,支持 PDF 最大页数 50 页) |
| questionnaire | string | 否 | 用户填写的健康问卷信息(文本或序列化的 JSON 字符串) |
请求示例:
curl --location 'https://openapi.wisediag.com/api/report/upload' \
--header 'Authorization: Bearer sk-************************************' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com/sample.pdf",
"questionnaire": "用户自述偶尔胸闷,有高血压家族史..."
}'响应参数 (Response)
| 参数名 | 类型 | 说明 |
|---|---|---|
| success | boolean | 请求是否成功 |
| errCode | string/null | 错误码 (无错误为 null) |
| errMessage | string/null | 错误信息 (无错误为 null) |
| data.taskId | string | 任务唯一标识 ID,用于后续查询结果 |
响应示例:
{
"success": true,
"errCode": null,
"errMessage": null,
"data": {
"taskId": "c1ecce57-4c9b-4f87-ba94-b81f8404c503"
}
}校验错误
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 500 | Internal Server Error | 服务端内部错误,请联系技术支持 |
| 400 | Bad Request | 请求参数错误、PDF 文件加密、PDF 不是有效的体检报告 |
| 50301 | PDF 页数超长 | 支持 PDF 最大页数 50 页 |
3.2. 开始解读任务 (Start Task)
根据 taskId 开启解读任务
- 接口地址: https://openapi.wisediag.com/api/report/startInterpret
- 请求方式:
POST - Content-Type:
application/json
请求参数 (Request)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 提交任务时返回的任务 ID |
请求示例:
curl --location 'https://openapi.wisediag.com/api/report/startInterpret' \
--header 'Authorization: Bearer sk-************************************' \
--header 'Content-Type: application/json' \
--data '{
"taskId":"c1ecce57-4c9b-4f87-ba94-b81f8404c503"
}'响应参数 (Response)
| 参数名 | 类型 | 说明 |
|---|---|---|
| success | boolean | 请求是否成功 |
| errCode | string/null | 错误码 (无错误为 null) |
| errMessage | string/null | 错误信息 (无错误为 null) |
| data.taskId | string | 任务唯一标识 ID,用于后续查询结果 |
响应示例:
{
"success": true,
"errCode": null,
"errMessage": null,
"data": {
"taskId": "c1ecce57-4c9b-4f87-ba94-b81f8404c503"
}
}3.3. 查询任务结果 (Query Result)
根据 taskId 查询任务的当前状态及解读结果。建议轮询间隔:2s - 5s。
- 接口地址: https://openapi.wisediag.com/api/report/query
- 请求方式:
POST - Content-Type:
application/json
请求参数 (Request)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 提交任务时返回的任务 ID |
请求示例:
curl --location 'https://openapi.wisediag.com/api/report/query' \
--header 'Authorization: Bearer sk-************************************' \
--header 'Content-Type: application/json' \
--data '{
"taskId":"c1ecce57-4c9b-4f87-ba94-b81f8404c503"
}'响应参数 (Response)
根据任务状态的不同,data 字段内的内容会有所区别。
公共响应字段:
| 参数名 | 类型 | 说明 |
|---|---|---|
| success | boolean | 接口调用是否成功 |
| data.status | string | 任务状态枚举:queued (任务排队中),processing (进行中), finish (完成), failed (失败) |
| data.process | number | 当前进度百分比 (0-100) |
| data.processingCompletionTime | string | 完成时间 ,仅完成时有值 |
场景 A:解读进行中 (Processing)
响应示例:
{
"success": true,
"errCode": null,
"errMessage": null,
"data": {
"taskId": "c1ecce57-4c9b-4f87-ba94-b81f8404c503",
"status": "processing",
"process": 50,
"processingCompletionTime": "",
"result": {}
}
}场景 B:解读完成 (Finished)
当 status 为 finish 时,result 字段将包含完整的结构化解读数据。
核心字段结构说明 (**data.result**):
| 字段名 | 说明 |
|---|---|
summaryOfSelfReportedHealthStatus | 基于问卷生成的健康状况综述(只有 questionnaire 参数不为空才会有结果) |
healthReview | 体检异常项汇总 (概要) |
healthAdvantages | 健康亮点/优势解读 |
healthConsults | 核心模块:针对每个异常项的深度解读、医学解释及建议 |
lifestyleImpact | 生活方式影响 |
personalizedRecommendations | 个性化建议 |
regularReview | 定期复查建议 |
references | 引用的医学文献或指南来源 |
hasAbnormalValues | 标识体检报告中是否发现异常项 (true/false) |
响应示例 (完整数据):
{
"data": {
"taskId": "98c3d512-32d8-4418-9f50-35fb03071f6d",
"status": "finish",
"process": 100,
"result": {
"summaryOfSelfReportedHealthStatus": "(根据输入的问卷生成) **健康状况**:你自我感知身体状况不佳。\n- **生活习惯**:你有少量饮酒和吸烟习惯...",
"healthReview": {
"description": "",
"abnormalItems": [
{
"abnormalIndex": 0,
"name": "心血管系统异常",
"abnormal": "双侧外周动脉僵硬度增高,频发室性早搏呈二联律。"
},
{
"abnormalIndex": 1,
"name": "心血管系统异常",
"abnormal": "双侧外周动脉僵硬度增高,频发室性早搏呈二联律。"
}
]
},
"healthAdvantages": [
"(总分总结构)您的血脂水平非常理想!这表明您在控制饮食方面做得很好"
],
"healthConsults": [
{
"abnormalIndex": 0,
"abnormalName": "前列腺异常",
"abnormalLevel": 1,
"abnormalValue": "彩超(前列腺) - 前列腺检查 前列腺增大伴钙化; 肿瘤6项(男) - fPSA/tPSA 0.33 (参考区间: 0.00-0.24)",
"abnormalLocality": "前列腺彩超检查提示前列腺增大伴钙化,fPSA/tPSA比值升高...",
"abnormalScience": {
"clinicalDefinition": "前列腺异常指的是前列腺的结构、功能或细胞组成出现了偏离正常的情况...",
"clinicalSignificance": "前列腺增生会导致一系列下尿路症状...",
"clinicalCognition": "前列腺问题是许多中老年男性都会面临的健康挑战之一..."
},
"abnormalHighlight": {
"count": 2,
"detailResults": "前列腺增大伴钙化,fPSA/tPSA 0.33 (参考区间: 0.00-0.24)",
"abnormalItemCnt": 2,
"anomalousIndicators": "前列腺增大伴钙化,fPSA/tPSA 0.33 (参考区间: 0.00-0.24)"
},
"abnormalHealthImpacts": "您的前列腺增大伴钙化,fPSA/tPSA比值为0.33...",
"abnormalLifeAndOtherEx": "建议您尽快安排前列腺专科医生的就诊..."
}
],
"lifestyleImpact": [
{
"key": "吸烟习惯",
"val": "您有少量吸烟习惯,这可能对您的健康产生不利影响..."
},
{
"key": "生活习惯",
"val": "您存在熬夜习惯,这可能会影响您的睡眠质量和身体的正常代谢..."
}
],
"personalizedRecommendations": [
{
"key": "消化道感染根除与黏膜修复计划",
"val": "碳14呼气试验DPM值高达285,明确提示当前存在幽门螺杆菌现症感染,这是..."
},
{
"key": "胆囊息肉动态监控与代谢调",
"val": "2mm胆囊息肉虽小,但结合‘胆囊壁毛糙’和幽门螺杆菌感染背景,提示可能存在慢性胆道刺激或..."
}
],
"regularReview": [
{
"key": "短期复查",
"val": "建议在2-4周内落实以下检查:..."
},
{
"key": "中期复查",
"val": "建议在3-6个月后进行以下复查:..."
},
{
"key": "长期复查",
"val": "建议在1年后纳入年度体检必查项目:..."
},
{
"key": "预警信号",
"val": "若出现以下具体症状,应立即就医:..."
}
],
"references": [
{
"link": "https://pic.wisediag.com/zhizhen/knowledge/wanfang/肛门失禁.pdf",
"type": "local",
"index": "35",
"title": "肛门失禁 - 万方疾病库",
"content": "- 患者部分或完全失去控制排气"
}
],
"hasAbnormalValues": true
},
"processingCompletionTime": "2025-12-19 14:49:49"
},
"success": true,
"errCode": null,
"errMessage": null
}字段补充说明
-
**hasAbnormalValues**(Boolean):true: 表示在体检报告中发现了异常项。此时abnormalItems、healthConsults等字段会有详细内容。false: 表示体检报告未发现明显异常。此时相关分析字段(如healthConsults)可能为空列表[ ]或空字符串""。前端可据此展示“身体健康,未见异常”的状态页。
-
**questionnaire**(问卷信息):- 该字段的内容会直接影响报告中
summaryOfSelfReportedHealthStatus(自述健康状况总结)的生成。 - 如果未提供(空字符串),系统将不生成自述健康状况总结(
summaryOfSelfReportedHealthStatus为空字符串),并跳过基于问卷的针对性分析。建议尽量提供详细的问卷信息(如吸烟史、睡眠时间、既往病史)以获得更完整的健康建议。
- 该字段的内容会直接影响报告中
-
PDF URL 要求:
- 必须是公网可直接访问的下载链接(无需鉴权或仅支持 URL 参数鉴权)。
- 强烈建议 URL 以
.pdf结尾,以便于系统快速识别文件类型。非.pdf结尾的链接可能会在预处理阶段被拦截。
4. 错误码说明 (通用)
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 500 | Internal Server Error | 服务端内部错误,请联系技术支持 |
| 400 | Bad Request | 请求参数格式错误,请检查 JSON 格式 |
| 404 | Task Not Found | 任务 ID 不存在,请检查 taskId 是否正确 |
| 50301 | PDF 页数超长 | 支持 PDF 最大页数 50 页 |