智能问诊业务流程与接口总览
本页是宠物智能问诊的唯一权威全景总览,汇总了问诊的完整时序状态机、接口调用清单、字段跨步骤传递关系、轮次控制策略及 SSE 统一协议。每个接口的详细参数与代码示例见侧边栏对应的独立接口页。
业务主流程与时序
智能问诊不是单次请求,而是一个由前端状态机驱动的多阶段多模态交互闭环:
可选:GET /ai-doc/pre-question(获取预设引导问题)
↓
POST /session-records/sessions(创建问诊会话,固定 module_type=1)
↓
┌─ 第 1 轮问答 ────────────────────────────────────────┐
│ 1. POST /ai-doc/keywords │
│ ↓ │
│ 2. POST /ai-doc/reason-info(SSE,等待 done) │
│ ↓ │
│ 3. POST /ai-doc/analysis │
│ ↓ │
│ 4. POST /ai-doc/related-question │
│ ↓ │
│ 5. 展示问题并保存用户回答:POST /session-records/messages │
└──────────────────────────────────────────────────────┘
↓ 直接进入第 2 轮(不判断是否继续)
┌─ 第 2 轮问答 ── 同样五步 ────────────────────────────┐
└──────────────────────────────────────────────────────┘
↓ 直接进入第 3 轮(不判断是否继续)
┌─ 第 3 轮问答 ── 同样五步 ────────────────────────────┐
│ ↓ │
│ POST /ai-doc/if-continue-ask(SSE,等待 done 裁决) │
│ ├─ True 继续追问:进入第 4 轮(同样五步) │
│ └─ False 结束问答:直接进入下方的图片判断步骤 │
└──────────────────────────────────────────────────────┘
↓
POST /ai-doc/if-need-image(判断是否需要补充体征照片)
├─ 需要传图:先调用 /oss/images 上传,再调用 /ai-doc/pic-result(仅供模型参考,前端不向用户展示)
└─ 无需传图:直接继续下一步
↓
POST /ai-doc/summary(SSE,流式生成并打字展示问诊小结,等待 done)
↓
POST /ai-doc/report(提交结构化报告任务,只提交一次)
↓
GET /ai-tasks/{task_id}(轮询异步报告进度,直至 succeeded)
↓
GET /medical-record?session_id=<SESSION_ID>(读取最终结构化病历与诊断报告详情)接口调用目录与步骤清单
| 步骤 | 接口 | 方法 | 返回类型 | 调用时机与业务说明 |
|---|---|---|---|---|
| 1 | /ai-doc/pre-question | GET | JSON | 可选。在进入问诊前拉取引导问题标签。 |
| 2 | /session-records/sessions | POST | JSON | 必选。初始化问诊会话,获取全局 session_id。 |
| 3 | /ai-doc/keywords | POST | JSON | 每一轮首步:提取症状关键词与实体标签。 |
| 4 | /ai-doc/reason-info | POST | SSE | 每一轮第二步:流式输出模型思考推理说明(思考气泡)。 |
| 5 | /ai-doc/analysis | POST | JSON | 每一轮第三步:获取阶段性病情分析小结。 |
| 6 | /ai-doc/related-question | POST | JSON | 每一轮第四步:获取主动关联追问及预设单选选项。 |
| 7 | /session-records/messages | POST | JSON | 每一轮第五步:保存用户点击或输入的回答内容。 |
| 8 | /ai-doc/if-continue-ask | POST | SSE | 问答裁决。第 3 轮后调用,判断信息是否充分。 |
| 9 | /ai-doc/if-need-image | POST | JSON | 多模态裁决。问答结束后判断是否需要补传照片。 |
| 10 | /oss/images | POST | JSON | 前端直传 OSS 获得临时安全访问 URL。 |
| 11 | /ai-doc/pic-result | POST | JSON | 提交问诊补充图供模型提取特征(前端无需向用户展示)。 |
| 12 | /ai-doc/summary | POST | SSE | 流式生成并打印最终问诊文字小结。 |
| 13 | /ai-doc/report | POST | JSON | 提交结构化报告异步生成任务,返回 task_id。 |
| 14 | /ai-tasks/{task_id} | GET | JSON | 轮询报告任务进度(固定 4 秒间隔),直至 succeeded。 |
| 15 | /medical-record | GET | JSON | 任务成功后,拉取完整的结构化病历与诊断报告详情。 |
核心上下文传递链
第 2 步 创建会话
└── session_id ──────────────┬──> 第 3~12 步:所有问诊交互接口的全局 session_id
└──> 第 13 步:提交报告任务的 session_id
第 10 步 上传图片
└── url ─────────────────────────> 第 11 步:pic-result 的 img_url(原值原样透传)
第 13 步 提交报告任务
└── task.task_id ────────────────> 第 14 步:轮询任务 /ai-tasks/{task_id}
(若响应里没有 task.task_id,说明已同步生成完毕,可直接读取 report_id 直达第 15 步)
第 14 步 任务完成
└── 轮询至 succeeded ────────────> 第 15 步:GET /medical-record?session_id=<SESSION_ID>关键对接规则与避坑指南
1. 轮次控制是前端策略
轮次是前端业务策略,非接口硬约束
- 后端不限制轮次上限,但建议前端前 3 轮直接递进问答;
- 第 3 轮结束后调用
if-continue-ask:True进入第 4 轮,第 4 轮回答保存后直接进入传图判断;示例前端把上限固定为3轮必答 +1轮可选(共 4 轮),接入方可自行调整; - 不要同一轮重复调用
if-continue-ask。
2. SSE 统一协议
流式接口(reason-info、if-continue-ask、summary)的 HTTP 响应为 Content-Type: text/event-stream:
- 帧格式:
data: <JSON>,事件类型在 JSON 的type字段; - 事件四态:
metadata:流开始,包含gateway_request_id;content:数据逐字段传输(打字机渐进渲染,不可据此提前推进流程);done:流成功结束,读取完整结构化数据后进入下一步;error:流异常中断,若retryable: true可重试。
3. 报告生成与固定间隔轮询
POST /ai-doc/report每个会话只提交一次,不要按分片重复提交;- 先查一次,之后固定每 4 秒轮询一次(实测报告约 20~30 秒生成完成),最长轮询 5 分钟;
- 任务一旦进入
succeeded、failed、canceled等终态,立即停止轮询; - 成功后使用
GET /medical-record?session_id=<SESSION_ID>获取完整报告;报告深度字段解析与前端各 UI 卡片映射请参阅 问诊报告字段详解与页面映射。
默认轮次排期与每轮回答处理
if-continue-ask 只在需要裁决「是否继续追问」时调用,且整场只调用一次。下面是推荐的默认排期:最少 3 轮;第 3 轮结束后做一次裁决,True 进入第 4 轮,False 结束问答。
| 轮次 | 回答保存后 |
|---|---|
| 第 1 轮 | 直接进入第 2 轮,不判断是否继续。 |
| 第 2 轮 | 直接进入第 3 轮,不判断是否继续。 |
| 第 3 轮 | 调用 if-continue-ask:True 进入第 4 轮;False 进入 if-need-image。 |
| 第 4 轮 | 已到该默认排期的最大轮次,回答保存后直接进入 if-need-image。 |
不要在第 1、2 轮之后调用 if-continue-ask,也不要在同一轮里重复调用它。轮次上限是前端策略:如果接入方采用更宽松的上限(例如 4~5 轮),同样要保证每轮只裁决一次,并在达到自己的上限后流转到 if-need-image。
每轮用户回答的处理顺序固定:related-question 返回问题后客户端展示给用户,用户回答后先调用 POST /session-records/messages 保存该回答,再按当前轮次决定下一步。建议的保存规则:
| 内容 | role | content_type | 说明 |
|---|---|---|---|
| 用户文字回答 | user | 1 | content 保存用户的原始回答。 |
| 问诊补充图片 | user | 2 | image 字段填写上传接口完整成功响应 data 内 url 的原值,不要改写。 |
| 产品展示用的模型结果 | assistant | 1 | 仅在业务需要回放时保存,内容应为可展示文本或可解析 JSON。 |
不要跨用户或跨会话复用 session_id。客户端重试时基于同一业务会话做幂等控制,避免重复保存同一条用户消息。
创建会话与档案上下文
module_type 固定为 1,content 必须非空,pet_profile_id 必须是有效数字。创建响应中的以下字段用于后续调用(路径均在响应 data 内):
| 字段 | 后续用途 |
|---|---|
session_id | 本次问诊所有后续请求的会话标识。 |
medical_record_id | 创建出的医疗记录 ID;如需按 ID 查询报告,将同一个值作为 report_id Query 参数传入。 |
initial_message | 平台根据创建请求 content 保存的首条消息;原始主诉在 initial_message.content。 |
如果先使用预设问题,GET /ai-doc/pre-question 同样要求有效的数字 pet_profile_id;会话创建后,所有后续接口都应沿用同一份档案上下文。
多轮问答分支与 if-continue-ask 结果读取
每一轮按上方目录中的五个步骤顺序执行。第 3 轮之后的 if-continue-ask,收到 type 为 done 的终止帧后再读取该帧中的业务结果;本接口用业务结果里的 content 字符串表示是否继续追问:
data: {"type":"done","data":{"session_id":"<SESSION_ID>","data":{"content":"True"},"raw_content":"True","gateway_request_id":"<REQUEST_ID>"}}content为True:进入第 4 轮,重新从POST /ai-doc/keywords开始。content为False:结束问答,调用POST /ai-doc/if-need-image。
True、False 是接口返回的字符串,不是 JSON 布尔值。只需按 SSE 协议读取完整的 done 终止帧,再读取该帧 JSON 中业务结果对象的 content 字段;不要依赖中间流文本。
图片补充分支
POST /ai-doc/if-need-image 在问答结束后判断是否需要图片。完整成功响应如下;is_pic 不在响应 data 的顶层,而在 data 内的业务结果对象中(相对响应 data 的路径为 data.is_pic):
{
"code": 200,
"message": "success",
"data": {
"session_id": "<SESSION_ID>",
"data": {
"is_pic": "True",
"pic_explain": "请上传患处清晰、光线均匀的照片。"
},
"raw_content": "模型原始输出",
"gateway_request_id": "<REQUEST_ID>"
}
}响应 data 内的路径 | 值 | 下一步 |
|---|---|---|
data.is_pic | "True" | 展示完整的 pic_explain,上传图片并进入图片补充分支。 |
data.is_pic | "False" | 不上传图片,调用 POST /ai-doc/summary。 |
is_pic 是字符串,不是 JSON 布尔值。字段缺失或出现其他值时,停止自动推进并记录完整响应。
若结果表示需要补图:
- 使用
multipart/form-data调用POST /oss/images上传本地图片; - 阅读上传接口的完整成功响应,读取响应
data内的url字段,并持久化这个字符串; - 如需会话回放,使用已保存的
url以图片消息形式保存; - 将同一个已保存的
url原样填入POST /ai-doc/pic-result请求体的img_url字段; - 获得图片补充结果后(识别结果用于服务端丰富病历上下文,前端无需向用户展示),直接进入生成问诊小结步骤。
禁止任意图片 URL
pic-result.img_url 不是通用网络图片字段。服务会校验当前用户归属、ready 状态、图片媒体类型、问诊图片用途和规范 OSS 地址。把 https://example.com/...、自拼 OSS 地址或他人上传的 URL 传入会被拒绝。
图片上传支持 jpg、jpeg、png、webp、gif,单文件最大 10 MiB。
lang 与 locale
宠物档案等展示类接口用查询参数 ?locale=...;智能问诊把 AI 会话语言存在请求体字段 lang。两者可以取相同的 BCP 47 值,但是两个独立参数,不能互相替代。
| 语言 | 档案/展示请求 | 问诊会话请求体 |
|---|---|---|
| 简体中文 | ?locale=zh-CN | "lang": "zh-CN" |
| 繁体中文(香港) | ?locale=zh-Hant-HK | "lang": "zh-Hant-HK" |
| 英语(美国) | ?locale=en-US | "lang": "en-US" |
语言必须是完整的区域化 BCP 47 值;选择前先调 GET /locales 确认该环境已启用。会话一旦创建,语言就固定:
- 后续 AI 请求建议省略
lang,沿用会话语言; - 如必须传入,值必须与创建会话时完全相同;
- 传入不同值返回 HTTP
400(message为「请求语言与会话语言不一致」;内部标识SESSION_LOCALE_MISMATCH),服务不会隐式切换会话语言。
失败后的处理
下表的标识在哪里可见
表中名称是服务端内部原因标识:流式接口失败时它出现在 SSE error 事件的 code 字段(同一事件还给出公开数字码 error_code);普通 HTTP 4xx/5xx 只返回 {code, message, data},既不含内部标识也不含数字错误码,只能按 HTTP 状态与 message 判断;异步任务失败时数字码在任务对象的 data.error_code。
| 触发条件(内部标识 / 公开可见返回) | 是否重试 | 正确处理 |
|---|---|---|
网络超时,或 SSE retryable: true | 可有限重试 | 请求参数保持不变后重试。 |
| 未收到 SSE 终止事件 | 可有限重试 | 视为本次失败并重新发起整个流;不要把零散 content 当结果。 |
MEDIA_URL_NOT_ALLOWED / MEDIA_URL_INVALIDHTTP 400,message「媒体URL不是当前服务登记的OSS地址」 | 不直接重试 | 重新上传图片,并使用返回的 url 原值。 |
MEDIA_ASSET_NOT_FOUND / MEDIA_ASSET_NOT_READYHTTP 400,message「媒体资产不存在或无权限」/「媒体资产尚未就绪」 | 先排查 | 使用当前用户上传的图片,并等资产就绪后再调用。 |
MEDIA_POLICY_REJECTEDHTTP 400,message「媒体资产用途不匹配」 | 不直接重试 | 通过 POST /oss/images 重新上传符合问诊输入要求的图片。 |
SESSION_LOCALE_MISMATCHHTTP 400,message「请求语言与会话语言不一致」 | 不直接重试 | 省略 lang,或使用与创建会话完全一致的语言。 |
报告任务 failed | 先排查 | 记录 task_id、session_id、error_code;错误码标记为可重试时用 POST /ai-tasks/{task_id}/retry 重试。 |