Files
api_health/README.md
T
lik e385167ec0 docs: 补充语音识别实时协议与客户端约定
说明 /chat 上的 asr_start/asr_chunk/asr_stop/asr_cancel 帧格式、中间结果与定稿的下行帧、两种录音格式(真机 mp3 / 工具 WebM 流式转码)均支持实时回填、结束即发送,以及整段兜底的切片与断流重试策略。
2026-10-31 17:03:02 +08:00

179 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# api-health
陪诊小程序的后端服务(Koa + 原生 WebSocket + MongoDB),除订单/档案等业务接口外,
还提供 AI 陪诊助手与**语音转写 / 图像识别**两类多模态输入能力。
```bash
npm install
npm run dev # nodemon index.js,HTTP 9004 / WS 9005
npm test # node --test test/*.test.js
```
## 语音与图像识别
设计参考 xagent 的设备数据通道(`asr.js` / `asr_dashscope.js` / `ocr.js` / `ocr_qwen.js`),
保留了「识别与投递解耦」的会话契约。语音有两条传输方式:
- **实时分片(默认)**:走聊天 WebSocket 的 `asr_start` / `asr_chunk` / `asr_stop`,
中间结果经 `asr_partial` 逐字回显,定稿经 `asr_final` 返回。
- **HTTP base64 整段上传(兜底)**:`/health/ai/asr` 用于分片缺失(如开发者工具)或实时链路失败的场景。
共同约定:
- 识别只产出文本,服务端不投递、不落库;客户端把文本回填输入框,由用户点发送键后再走原聊天链路(WS `chat`)。
- 音频 / 图片只在本轮请求内存中存在,不落盘、日志不记录正文。
- 默认只做**转写**:语音用 `fun-asr-realtime`,图片用 `qwen-vl-ocr`;是否进一步解读由 agent 的提示词决定。
- 接口必须登录(`token` 或 `Authorization: Bearer <token>`),按用户限流 20 次/分钟。
### 实时语音识别(WS /chat)
上行帧(客户端 → 服务端):
| 帧 | 字段 | 说明 |
| --- | --- | --- |
| `asr_start` | `id` / `token` / `format?` / `sampleRate?` / `channels?` | 声明一轮识别,鉴权与限流都在这一步 |
| `asr_chunk` | `id` / `audio`(base64 分片) | 每帧一个录音分片,单帧 ≤ 128KB,整轮 ≤ 8MB |
| `asr_stop` | `id` | 结束推流并取定稿 |
| `asr_cancel` | `id` | 放弃本轮(页面隐藏、录音中断) |
下行帧(服务端 → 客户端,`type` 为下列值,`id` 与上行 `asr_start` 的 `id` 对应):
| 帧 | `content` | 说明 |
| --- | --- | --- |
| `asr_partial` | 当前累计文本 | 中间结果,客户端实时回填输入框 |
| `asr_final` | 定稿文本(可能为空串) | 结束后返回,客户端提示重录或留在输入框 |
| `asr_error` | 可读错误文案 | 客户端改用整段接口兜底 |
同一连接上同时只保留一轮识别;`asr_start` 会中止上一轮,连接关闭时也会 `abort`。
### POST /health/ai/asr
请求体(JSON,上限 20MB,解码后音频 ≤ 10MB):
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `audio` | string | 是 | base64 或 `data:audio/mpeg;base64,...` |
| `format` | string | 否 | `mp3`(默认)/ `aac` / `wav` / `pcm` / `pcm16` |
| `sampleRate` | number | 否 | `8000` / `16000`(默认)/ `24000` / `48000` |
| `channels` | number | 否 | 仅支持 `1` |
```bash
curl -s http://localhost:9004/health/ai/asr \
-H "Content-Type: application/json" -H "token: <token>" \
-d '{"audio":"<base64>","format":"mp3"}'
# => { "code": 0, "msg": "操作成功", "data": { "text": "我明天想带老人去复查" }, "ts": ... }
```
### POST /health/ai/ocr
请求体(JSON,上限 20MB,解码后图片 ≤ 8MB):
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `image` | string | 是 | base64 或 data URL |
| `mime` | string | 否 | `image/jpeg`(默认)/ `image/png` / `image/webp` |
| `width` / `height` | number | 否 | 像素尺寸,仅用于让模型判断清晰度 |
| `kind` | string | 否 | 首版固定 `auto`,服务端按内容自行判断报告类型 |
```bash
curl -s http://localhost:9004/health/ai/ocr \
-H "Content-Type: application/json" -H "token: <token>" \
-d '{"image":"<base64>","mime":"image/jpeg"}'
```
返回的 `data.text` 是可直接投喂给 agent 的可读文本,段落包括【图像识别】【原文转写】
【结构化要点】(full 模式才有解读段)【图像质量】【说明】,末尾带免责说明。
`profile: transcribe`(默认)只传图片、不附加提示词:qwen-vl-ocr 自带逐行转写模板,
附加系统提示或 JSON 契约会把原文压成摘要、表格列还会粘连,因此【原文转写】段必须是
模型原生输出的完整原文;文档类型与标题由服务端按文本关键词兜底判断。
原生转写用制表符 / 多空格 / 全角空格对齐列,直接展示会被 markdown 折叠成一串,
因此服务端会把连续的分列块转成 markdown 表格(列数不足补空列,超出并进最后一列),
其余行独立成段保留换行。小程序与 Taro 端都按 markdown 渲染即可。
### 错误码
业务码统一走响应体 `code`(HTTP 恒 200),同时写入 `X-Biz-Code` 响应头:
| code | 场景 |
| --- | --- |
| 400 | 参数缺失 / base64 非法 / 格式或采样率不支持 / 超出大小上限 / 未识别到内容 |
| 401 | 未登录或 token 失效 |
| 403 | 无权限 |
| 502 | 供应商识别失败(错误详情只进日志) |
| 503 | 识别服务未配置(缺密钥 / 缺少 endpoint) |
## 配置
识别配置位于 `conf.json` 的 `agent.media` 段,密钥支持直接写 `apiKey`,或通过
`apiKeyEnv` 指向环境变量(`.env` 由 dotenv 加载):
```json
"media": {
"audio": { "rate": 16000, "channels": 1 },
"asr": {
"provider": "dashscope",
"endpoint": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
"model": "fun-asr-realtime",
"apiKeyEnv": "ASR_KEY"
},
"image": { "mimes": ["image/jpeg", "image/png", "image/webp"] },
"ocr": {
"provider": "qwen",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen-vl-ocr",
"profile": "transcribe",
"apiKeyEnv": "ASR_KEY",
"requestTimeoutMs": 60000,
"disclaimer": "本内容为图像文字识别结果,不构成诊断意见,请以医生诊断与医院报告为准。"
},
"limits": { "maxAudioBytes": 10485760, "maxImageBytes": 8388608 }
}
```
- 密钥变量名与参考项目 xagent 一致:`ASR_KEY`;取值顺序为 `apiKey` → `apiKeyEnv` →
`ASR_KEY` → `DASHSCOPE_API_KEY`(后两者兜底,便于两个项目共用同一把 key)。
- `provider: "qwen"` 走 OpenAI 兼容 `chat/completions`;配置 `endpoint`(http/https)可换成自建 OCR 服务;
也可在代码里给 `createOcrSession({ recognize })` 注入本地 PaddleOCR 等实现。
- `provider: "dashscope"` 走实时 ASR;不配 `provider` 而给 `endpoint` 为 ws/wss 时同样按实时处理;
传 `transcribe` 或 http endpoint 则走批式。
- `profile: "full"` 才会要求模型输出解读字段;涉及诊断结论的能力不默认开启。
- 密钥为空时两个接口直接回 503「服务暂不可用」,不会发起外部请求。
## 目录
```
agent/infra/media/ 语音 / 图像识别适配器(会话契约、供应商实现、音频容器识别)
handler/ai_media.js 两个识别接口的入参校验、错误分层与响应
routes/index.js 路由注册(/health/ai/*)
test/media.test.js 元信息白名单、base64 解码、会话生命周期、供应商请求与失败路径
```
## 客户端约定
- 小程序录音使用 `wx.getRecorderManager()`,`format: 'mp3'`、`sampleRate: 16000`、`numberOfChannels: 1`,
并带 `frameSize`(单位 KB)以触发 `onFrameRecorded`:每帧转 base64 后按 `asr_chunk` 实时上传,
点麦克风结束(或满 60 秒)时发 `asr_stop`。
- **两种录音格式都能实时回填**:真机录的是 mp3 分片,服务端按首帧魔数确认为 mp3 后直接透传给供应商;
开发者工具录的是 WebM(Matroska)/Opus(文件名仍是 `.mp3`),服务端用流式解码器同步转成
16bit 单声道 PCM(48k 抽取到 16k)后再推给供应商,因此工具里也能逐字出中间结果。
客户端不再判断容器,分片一律上传;只有服务端明确回 `asr_error`(认不出容器 / 供应商失败)时
才降级为「结束后整段转写」。首帧认不出容器时服务端先缓存至多 16KB 再判,避免误杀只有 cluster 的平台。
- 整段识别遇到供应商偶发断流(`asr socket closed` / 建连超时)会自动重试一次(间隔 600ms),
避免用户白录一遍;解码/参数类错误不重试。
- 整段音频按 300ms(压缩格式按 64KB)切片推给供应商,并在发送队列排空后才发 `finish-task`:
一次性把几秒 PCM 塞进 socket 会让供应商来不及消费而直接断流。
- 实时链路在说话途中失败时客户端不弹错、不中断录音,标记为降级并继续采集;结束时用完整录音文件
(而不是失败瞬间的半截分片)整段提交 `/health/ai/asr`,只有整段也失败才提示用户。
- 微信开发者工具的录音实际是 WebM(Matroska)/Opus(文件名仍是 `.mp3`,控制台会提示格式与移动端不同)。
服务端按文件头识别容器,WebM 会先解码成 16bit 单声道 PCM(48k 抽取到 16k)再交给供应商,
因此工具里也能正常转写;真机录制的 mp3 直接透传。
- 拍照 / 选图使用 `wx.chooseMedia`,上传前压缩到 1~2MB。图片不走确认面板:选中后立即作为一条用户消息上屏,
`/health/ai/ocr` 返回的文本直接落成 AI 回复;图片临时路径不落 storage,重启后历史里只保留 `[图片]` 占位。
- 语音识别结果实时回填输入框;**再次点麦克风结束识别后直接发送**(`asr_final` 定稿或整段兜底成功后
立即走聊天 WS),录音中可看到逐字结果,结束后不需要再点一次发送键。
语音图标本身承担开录与结束(录音中变色,再点一次结束),不弹确认浮层、不遮挡输入框;
若此时还有上一条回复在途,定稿文本会留在输入框,等回复完成后由用户点发送,不丢内容。
- 语音与图片识别结果可能有错字,涉及数值、单位、药名、日期时由 agent 提示用户确认。