宠物特征识别业务流程与接口总览
本页是宠物特征识别的唯一权威全景总览,汇总了识别的主流程时序、sub_module_type 取值体系与对应报告模型、接口调用清单及数据传递关系。每个接口的详细参数与代码示例见侧边栏对应的独立接口页。
业务主流程与时序
POST /ms-ai-fast/session-records/sessions(创建识别会话,body 传 module_type=5 与 sub_module_type)
↓
POST /oss/images(上传宠物照片,获取临时安全访问 url)
↓
POST /ms-ai-fast/ai-pic/summary/stream(SSE,流式识别图像特征并输出初筛小结)
↓
POST /ms-ai-fast/ai-pic/sessions/report-tasks(提交异步完整分析报告任务)
↓
GET /ai-tasks/{task_id}(轮询异步任务进度,直至 succeeded)
↓
GET /ms-ai-fast/medical-records/{record_id}(读取最终结构化识别报告详情)sub_module_type 识别能力与报告体系映射
创建会话时通过 sub_module_type 指定识别场景(1 至 8)。虽然细分为 8 种场景,但在底层和前端 UI 渲染上归纳为 3 大核心报告体系:
sub_module_type | 识别场景 | 所属体系 | 核心卡片渲染与数据结构特点 |
|---|---|---|---|
1 | 品种识别 | 品种报告体系 | 包含 result.prob[] 品种概率进度条与双段式饲养养护指南。 |
2 | 情绪/表情识别 | 情绪报告体系 | 包含 result.emotion 核心情绪大徽章、局部表情信号分析与互动安抚指南。 |
3 | 口腔检测 | 通用体征体系 | 牙、便、呕、皮、耳、眼(3~8)共用同一套结构:包含整体健康 Banner、正常/异常 Tab、疾病风险条、四维病理卡片与用药生活指南。 |
4 | 排泄物 | 通用体征体系 | 同上(通用体征报告模型) |
5 | 呕吐物 | 通用体征体系 | 同上(通用体征报告模型) |
6 | 皮肤检测 | 通用体征体系 | 同上(通用体征报告模型) |
7 | 耳道检查 | 通用体征体系 | 同上(通用体征报告模型) |
8 | 眼睛检查 | 通用体征体系 | 同上(通用体征报告模型) |
接口调用目录与步骤清单
| 步骤 | 接口 | 方法 | 返回类型 | 调用时机与业务说明 |
|---|---|---|---|---|
| 1 | /session-records/sessions | POST | JSON | 必选。初始化识别会话(module_type 传 5),绑定 sub_module_type 与 pet_profile_id。 |
| 2 | /oss/images | POST | JSON | 上传识别原图,获得合法的 OSS 资源 url。 |
| 3 | /ai-pic/summary/stream | POST | SSE | 流式识别画面并输出初步分析小结。 |
| 4 | /ai-pic/sessions/report-tasks | POST | JSON | 提交完整结构化分析报告任务,获取 task_id。 |
| 5 | /ai-tasks/{task_id} | GET | JSON | 轮询任务进度,直至 succeeded。 |
| 6 | /medical-records/{record_id} | GET | JSON | 任务成功后,读取完整的结构化报告数据。各体系深度字段请参阅 识别报告字段详解与页面映射。 |
核心上下文传递链
第 1 步 创建会话
└── session_id ──────────────┬──> 第 3 步:流式小结的 session_id
└──> 第 4 步:提交报告任务的 session_id
第 2 步 上传图片
└── url ─────────────────────────> 第 3 步与第 4 步的 img_url
第 4 步 提交报告任务
└── task.task_id ────────────────> 第 5 步:轮询任务 /ai-tasks/{task_id}
第 5 步 任务完成
└── 轮询至 succeeded ────────────> 第 6 步:GET /medical-records/{record_id}分步接入要点
第 1 步 创建识别会话
创建会话前先选定一个 sub_module_type,该值会写入会话,之后不能修改;请求只传对应数字,不要传能力名称。
{
"module_type": 5,
"sub_module_type": 7,
"pet_profile_id": 44,
"lang": "zh-CN"
}module_type 固定为 5;pet_profile_id 是通过宠物档案取得的数字 ID。保存响应 data 中的 session_id。
第 2 步 上传图片
使用 multipart/form-data 上传:
| 表单字段 | 值 |
|---|---|
file | 图片文件本体;支持 jpg、jpeg、png、webp、gif,单文件最大 10 MiB。 |
读取完整上传成功响应 data 内的 url 字段并持久化,后续所有 img_url 都必须原样复用它:不要使用图片网页地址、临时签名地址、自拼 OSS 地址或其他用户上传的地址。
第 3 步 流式识别并生成小结
一次调用同时完成识别和小结,事件按以下规则消费:
- 收到唯一的
metadata事件后,记录链路信息; - 对每个
type为content的事件,读取该事件 JSON 的content字段并渐进展示;不要用中间文本判断业务完成; - 收到完整的
type为done的终止事件后,读取其中的data对象作为结构化识别结果,此时才能把识别标记为完成; - 收到
error,或连接关闭前既没有done也没有error,都判定本次失败;只有error.retryable为true或网络类错误才可有限重试。
第 4 步 并行提交报告任务并读取报告
报告任务可以和识别流同时提交,不必等待识别文本全部返回。
{
"session_id": "<SESSION_ID>",
"img_url": "<UPLOAD_RESPONSE_DATA_URL>"
}从完整成功响应 data 内的 task.task_id 取得任务 ID,用 GET /ai-tasks/{task_id} 轮询:固定每 4 秒一次,最长轮询 5 分钟;状态进入 succeeded、failed 或 canceled 后立即停止。
报告任务成功后,用 GET /medical-records/{record_id} 读取报告详情与分片,或用 GET /medical-records?module_type=5 查询历史识别记录。
两条结果要分别处理
识别流和报告任务是两条独立链路:小结流失败不代表报告任务失败,报告任务成功也不代表客户端已经收到完整的 done 事件。客户端必须分别记录两条结果,并且只有收到 SSE done 才把识别标记为完成。
重试失败的报告任务时,用失败任务返回的 task_id 调用 POST /ai-tasks/{task_id}/retry,不要重复为同一会话创建报告任务。
会话不可变约束
系统会把会话绑定到宠物档案、sub_module_type、语言和首次使用的图片资产。
| 情况 | 公开可见的返回 | 正确处理 |
|---|---|---|
流式识别时 sub_module_type 与会话不一致 | SSE error 事件:code 为 AI_PIC_SUB_MODULE_MISMATCH、error_code 为 6103、retryable 为 false、recommended_action 为 restart_session(HTTP 状态仍为 200) | 使用会话固定的类型,或新建对应类型的会话。 |
| 同一会话换图或换档案后再提交报告任务 | HTTP 4xx,message 提示会话或资源冲突(内部标识 TASK_IDEMPOTENCY_CONFLICT,公开数字码 6001 只在任务对象与 SSE 错误事件中出现) | 不要在同一会话内换图,新建会话。 |
这两类错误都不应直接重试。第一行的字段取值来自线上实测的 SSE 错误事件。
lang 与 locale
宠物档案接口用 Query 参数 ?locale=... 控制品种展示名;图片识别用请求体的 lang 固化 AI 会话语言。两者可以取相同的 BCP 47 值,但不能互相替代。
| 客户端界面语言 | 宠物档案读取 | 图片识别创建会话 |
|---|---|---|
| 简体中文 | ?locale=zh-CN | "lang": "zh-CN" |
| 香港繁体中文 | ?locale=zh-Hant-HK | "lang": "zh-Hant-HK" |
| 美国英语 | ?locale=en-US | "lang": "en-US" |
会话建立后:
- 后续 AI 请求建议省略
lang,沿用会话语言; - 如必须传入,值必须与创建会话时完全相同;
- 传入不同语言会返回
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地址」(SSE 场景下也可能以 error 事件返回) | 不直接重试 | 重新上传,并使用上传响应中的 url 原值。 |
AI_PIC_SUB_MODULE_MISMATCHSSE error 事件,error_code 6103 | 不直接重试 | 使用会话固定的类型,或新建会话。 |
TASK_IDEMPOTENCY_CONFLICTHTTP 4xx(仅 message 可见) | 不直接重试 | 不在旧会话换图,新建会话。 |
报告任务 failed | 先看错误码 | 记录 task_id、session_id 和 error_code;错误码可重试时再调用重试接口。 |