Skip to content

智能问诊业务流程与接口总览 ​

本页是宠物智能问诊的唯一权威全景总览,汇总了问诊的完整时序状态机、接口调用清单、字段跨步骤传递关系、轮次控制策略及 SSE 统一协议。每个接口的详细参数与代码示例见侧边栏对应的独立接口页。

业务主流程与时序 ​

智能问诊不是单次请求,而是一个由前端状态机驱动的多阶段多模态交互闭环:

text
可选: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-questionGETJSON可选。在进入问诊前拉取引导问题标签。
2/session-records/sessionsPOSTJSON必选。初始化问诊会话,获取全局 session_id。
3/ai-doc/keywordsPOSTJSON每一轮首步:提取症状关键词与实体标签。
4/ai-doc/reason-infoPOSTSSE每一轮第二步:流式输出模型思考推理说明(思考气泡)。
5/ai-doc/analysisPOSTJSON每一轮第三步:获取阶段性病情分析小结。
6/ai-doc/related-questionPOSTJSON每一轮第四步:获取主动关联追问及预设单选选项。
7/session-records/messagesPOSTJSON每一轮第五步:保存用户点击或输入的回答内容。
8/ai-doc/if-continue-askPOSTSSE问答裁决。第 3 轮后调用,判断信息是否充分。
9/ai-doc/if-need-imagePOSTJSON多模态裁决。问答结束后判断是否需要补传照片。
10/oss/imagesPOSTJSON前端直传 OSS 获得临时安全访问 URL。
11/ai-doc/pic-resultPOSTJSON提交问诊补充图供模型提取特征(前端无需向用户展示)。
12/ai-doc/summaryPOSTSSE流式生成并打印最终问诊文字小结。
13/ai-doc/reportPOSTJSON提交结构化报告异步生成任务,返回 task_id。
14/ai-tasks/{task_id}GETJSON轮询报告任务进度(固定 4 秒间隔),直至 succeeded。
15/medical-recordGETJSON任务成功后,拉取完整的结构化病历与诊断报告详情。

核心上下文传递链 ​

text
第 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 保存该回答,再按当前轮次决定下一步。建议的保存规则:

内容rolecontent_type说明
用户文字回答user1content 保存用户的原始回答。
问诊补充图片user2image 字段填写上传接口完整成功响应 data 内 url 的原值,不要改写。
产品展示用的模型结果assistant1仅在业务需要回放时保存,内容应为可展示文本或可解析 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 字符串表示是否继续追问:

text
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):

json
{
  "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 布尔值。字段缺失或出现其他值时,停止自动推进并记录完整响应。

若结果表示需要补图:

  1. 使用 multipart/form-data 调用 POST /oss/images 上传本地图片;
  2. 阅读上传接口的完整成功响应,读取响应 data 内的 url 字段,并持久化这个字符串;
  3. 如需会话回放,使用已保存的 url 以图片消息形式保存;
  4. 将同一个已保存的 url 原样填入 POST /ai-doc/pic-result 请求体的 img_url 字段;
  5. 获得图片补充结果后(识别结果用于服务端丰富病历上下文,前端无需向用户展示),直接进入生成问诊小结步骤。

禁止任意图片 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_INVALID
HTTP 400,message「媒体URL不是当前服务登记的OSS地址」
不直接重试重新上传图片,并使用返回的 url 原值。
MEDIA_ASSET_NOT_FOUND / MEDIA_ASSET_NOT_READY
HTTP 400,message「媒体资产不存在或无权限」/「媒体资产尚未就绪」
先排查使用当前用户上传的图片,并等资产就绪后再调用。
MEDIA_POLICY_REJECTED
HTTP 400,message「媒体资产用途不匹配」
不直接重试通过 POST /oss/images 重新上传符合问诊输入要求的图片。
SESSION_LOCALE_MISMATCH
HTTP 400,message「请求语言与会话语言不一致」
不直接重试省略 lang,或使用与创建会话完全一致的语言。
报告任务 failed先排查记录 task_id、session_id、error_code;错误码标记为可重试时用 POST /ai-tasks/{task_id}/retry 重试。
最近更新

栖界开放平台 · API Documentation