- 新增 WS format 帧:识别原文只并入会话上下文并分片原样回显,不再经过模型二次改写 - 原方案走 chat 会被咨询提示词压缩成 1-3 句,并被 OutputGuard 的 400 字上限截断 - 补充分片回显测试与 README 协议说明
193 lines
11 KiB
Markdown
193 lines
11 KiB
Markdown
# 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 渲染即可。
|
||
|
||
小程序把识别文本以 WS `format` 帧投递(`{ type: "format", content, id, token, ts }`):
|
||
服务端只把原文并入会话上下文,并按分片原样回显给客户端展示,**不再让模型二次改写**。
|
||
识别结果通常有几百到上千字,模型改写会按咨询提示词压缩成 1-3 句,还会被输出护栏的
|
||
400 字上限截断,长报告必然丢行;原文投递既完整,也省一次生成。
|
||
|
||
### 错误码
|
||
|
||
业务码统一走响应体 `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 解码、会话生命周期、供应商请求与失败路径
|
||
```
|
||
|
||
目录约定:
|
||
|
||
- 根目录只放入口与配置(`index.js` / `app.js` / `websocket.js` / `config.js` 等),不提交临时脚本。
|
||
- 自动化测试统一放 `test/*.test.js`,由 `npm test` 执行;临时验证脚本应先转成正式测试,不要留在根目录。
|
||
- 一次性运维 / 调试脚本放 `scripts/`,用完后删除;需长期保留的请在 README 中说明用途和用法。
|
||
- Agent 共享逻辑放 `agent/infra/`,业务路由与处理器分别放 `routes/`、`handler/`。
|
||
|
||
## 客户端约定
|
||
|
||
- 小程序录音使用 `wx.getRecorderManager()`,`format: 'mp3'`、`sampleRate: 16000`、`numberOfChannels: 1`,
|
||
并带 `frameSize`(单位 KB)以触发 `onFrameRecorded`:每帧转 base64 后按 `asr_chunk` 实时上传,
|
||
点麦克风结束(或满 60 秒)时发 `asr_stop`。
|
||
- **两种录音格式都能实时回填**:真机录的是 16k 单声道 MP3(MPEG-2 Layer III),
|
||
开发者工具录的是 WebM(Matroska)/Opus(文件名仍是 `.mp3`)。供应商自带的解码器对这两种容器
|
||
都不可靠(真机 mp3 实测直接报 `DecodePost resample audio from 0 to 16000 failed`),
|
||
因此服务端按首帧魔数识别容器后,统一用流式解码器(WebM/Opus、mp3/mpg123)转成
|
||
16bit 单声道 PCM(48k 抽取到 16k、16k 原样)再推给供应商,两种环境都能逐字出中间结果。
|
||
客户端不再判断容器,分片一律上传;只有服务端明确回 `asr_error`(认不出容器 / 供应商失败)时
|
||
才降级为「结束后整段转写」。首帧认不出容器时服务端先缓存至多 16KB 再判,避免误杀只有 cluster 的平台。
|
||
- 整段识别遇到供应商偶发断流(`asr socket closed` / 建连超时)会自动重试一次(间隔 600ms),
|
||
避免用户白录一遍;解码/参数类错误不重试。
|
||
- 整段音频按 300ms(压缩格式按 64KB)切片推给供应商,并在发送队列排空后才发 `finish-task`:
|
||
一次性把几秒 PCM 塞进 socket 会让供应商来不及消费而直接断流。
|
||
- 实时链路在说话途中失败时客户端不弹错、不中断录音,标记为降级并继续采集;结束时用完整录音文件
|
||
(而不是失败瞬间的半截分片)整段提交 `/health/ai/asr`,只有整段也失败才提示用户。
|
||
- 微信开发者工具的录音实际是 WebM(Matroska)/Opus(文件名仍是 `.mp3`,控制台会提示格式与移动端不同);
|
||
真机才是真正的 16k mp3。服务端按文件头识别容器后都先解码成 16bit 单声道 PCM 再交给供应商,
|
||
整段兜底的 `/health/ai/asr` 走同一个识别入口,因此两条链路都能正常转写。
|
||
- 拍照 / 选图使用 `wx.chooseMedia`,上传前压缩到 1~2MB。图片不走确认面板:选中后立即作为一条用户消息上屏,
|
||
`/health/ai/ocr` 返回的文本直接落成 AI 回复;图片临时路径不落 storage,重启后历史里只保留 `[图片]` 占位。
|
||
- 语音识别结果实时回填输入框;**再次点麦克风结束识别后直接发送**(`asr_final` 定稿或整段兜底成功后
|
||
立即走聊天 WS),录音中可看到逐字结果,结束后不需要再点一次发送键。
|
||
语音图标本身承担开录与结束(录音中变色,再点一次结束),不弹确认浮层、不遮挡输入框;
|
||
若此时还有上一条回复在途,定稿文本会留在输入框,等回复完成后由用户点发送,不丢内容。
|
||
- 语音与图片识别结果可能有错字,涉及数值、单位、药名、日期时由 agent 提示用户确认。
|