宠物智能问诊
宠物智能问诊是一条以会话为中心的多步骤流程:收集主诉、提取关键词、展示推理说明、分析与追问、按需补充图片、生成总结,并异步生成完整报告。
https://open-api.habitaxx.com/v1/ms-ai-fast接入前提
- 按身份认证使用项目 API Key 换取
ACCESS_TOKEN;业务请求统一携带Authorization: Bearer <ACCESS_TOKEN>。
注意:源码层还要求
x-qj-user。如果通过公开网关调用,应由网关在完成Authorization校验后注入该请求头;外部客户端不要自行伪造。直接调用服务端时,请按接口总览中的说明显式携带它。
- 为每位最终用户维护独立 Token 上下文;不要把不同用户的
session_id、图片 URL 或报告 ID 混用。 - 所有 AI 请求均使用文档列出的
/v1/ms-ai-fast/...网关路径。不要在该前缀后添加任何未列出的路径段;未发布的地址会返回404 Not Found。 module_type: 1的问诊会话必须提供数字pet_profile_id和非空初始主诉content。pet_profile_id通过宠物档案接口取得,是数值 ID(例如44)。
推荐集成路径
下表只说明接口调用顺序和接口之间需要传递的字段。每个接口的完整请求、返回示例和字段说明见接口总览。
| 步骤 | 调用接口 | 本次请求 | 成功后使用的返回字段 | 下一步 |
|---|---|---|---|---|
| — | 轮次说明 | 第 3~7 步构成一轮问答;后端不强制轮次,常见做法是 3~4 轮 | — | 未到约定轮次时直接进入下一轮,不判断继续。 |
| 1 | GET /ai-doc/pre-question(可选) | Query:pet_profile_id、lang | 预设问题列表 | 创建会话,或直接创建会话。 |
| 2 | POST /session-records/sessions | JSON:module_type、pet_profile_id、content、lang | 完整成功响应 data 对象中的 session_id | 后续问诊接口统一使用该会话 ID。 |
| 3 | POST /ai-doc/keywords | JSON:session_id、pet_profile_id、content | 关键词接口返回的结构化结果 | 调用推理说明或病情分析。 |
| 4 | POST /ai-doc/reason-info(SSE) | JSON:session_id、pet_profile_id | type=done 中的最终结果 | 调用病情分析。 |
| 5 | POST /ai-doc/analysis | JSON:session_id、pet_profile_id | 病情分析结果 | 获取关联追问。 |
| 6 | POST /ai-doc/related-question | JSON:session_id、pet_profile_id | 关联问题列表 | 展示问题并收集用户回答。 |
| 7 | POST /session-records/messages | JSON:session_id、role、content | 消息保存结果 | 第 1、2 轮直接进入下一轮;第 3 轮判断是否继续;第 4 轮进入图片判断。 |
| 8 | POST /ai-doc/if-continue-ask(SSE)仅第 3 轮后调用一次 | JSON:session_id、pet_profile_id | 完整 type=done 事件的业务结果对象中的 content:True 或 False | True 进入第 4 轮问答;False 调用图片判断。 |
| 9 | POST /ai-doc/if-need-image | JSON:session_id、pet_profile_id | 完整成功响应业务结果对象中的 is_pic 和 pic_explain | True 上传图片;False 直接生成总结。 |
| 10 | POST /oss/images(需要图片时) | multipart 表单:file | 完整上传成功响应 data 对象中的 url | 将同一个 URL 填入图片补充接口的 img_url。 |
| 11 | POST /ai-doc/pic-result(需要图片时) | JSON:session_id、pet_profile_id、img_url | 图片补充结果 | 生成问诊总结。 |
| 12 | POST /ai-doc/summary(SSE) | JSON:session_id、pet_profile_id | type=done 中的最终总结 | 提交报告任务。 |
| 13 | POST /ai-doc/report | JSON:session_id、report_type | 完整成功响应 data 对象中 task.task_id | 查询异步任务状态。 |
| 14 | GET /ai-tasks/{task_id} | Path:task_id | 完整成功响应 data 对象中的 status | 状态为 succeeded 后读取完整报告。 |
| 15 | GET /medical-record | Query:session_id 或 report_id(二选一) | 完整医疗记录 | 流程结束。 |
接口分组
| 分组 | 接口 | 用途 |
|---|---|---|
| 会话准备 | GET /ai-doc/pre-question、POST /session-records/sessions | 读取预设问题、创建会话。 |
| 问答分析 | POST /ai-doc/keywords、POST /ai-doc/reason-info、POST /ai-doc/analysis、POST /ai-doc/related-question | 从用户输入形成追问与分析。 |
| 流程分支 | POST /session-records/messages、POST /ai-doc/if-continue-ask、POST /ai-doc/if-need-image | 保存回答、决定继续追问或补图。 |
| 图片补充 | POST /oss/images、POST /ai-doc/pic-result | 上传问诊图片并获取图片补充结果。 |
| 总结与报告 | POST /ai-doc/summary、POST /ai-doc/report、GET /ai-tasks/{task_id}、GET /medical-record | 流式总结、异步生成并读取完整报告。 |
各接口的完整网关地址见接口总览。
关键集成规则
content 会生成 initial_message
content 是创建会话的请求字段,问诊会话必填;服务会把它保存为首条用户消息。响应的 initial_message 是这条消息对象,提交的原文在 initial_message.content——它不是第二个请求字段。
SSE 以终止事件为准
reason-info、if-continue-ask、summary 都返回 text/event-stream。流从 metadata 开始,可能包含多个 content,最终只会以 type=done 或 type=error 之一结束:
data: {"type":"content",...}只用于逐步展示,不代表当前业务步骤完成;- 仅在收到
data: {"type":"done",...}后,才能执行下一步骤;最终结果位于该 JSON 的data字段中,具体字段以对应接口的“返回字段”表为准; - 收到
error或连接在没有终止事件时断开,均应按失败处理; error.retryable=true时可有限重试;否则应提示用户调整输入或稍后重试。
详细事件格式和状态分支见完整流程。
问诊图片必须是平台登记资产
POST /ai-doc/pic-result 不接受任意外部 URL。图片补充分支的字段传递关系如下:
| 顺序 | 接口或字段 | 要求 |
|---|---|---|
| 1 | POST /oss/images | 使用 multipart/form-data 上传图片。 |
| 2 | 上传响应的 url | 获取服务端返回的平台图片 URL。 |
| 3 | POST /ai-doc/pic-result 请求体的 img_url | 填写第 2 步返回的同一个 URL,不要改写。 |
该 URL 必须属于当前用户、状态为 ready、为图片类型,且与上传登记的规范 OSS URL 完全一致。不要使用第三方 URL、自己拼接的对象地址、历史用户资产或示例域名 URL。
报告只需提交一次
POST /ai-doc/report 的请求体只包含 session_id 和 report_type。report_type 允许值为 1、2、3、4、7,省略时默认 1。当前报告生成会汇总这些报告分片;对同一会话的正常流程只需提交一次报告任务,随后轮询 task.task_id,成功后通过 GET /medical-record?session_id=<SESSION_ID> 读取完整报告。不要按五个类型连续提交五次。