# 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 `),按用户限流 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: " \ -d '{"audio":"","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: " \ -d '{"image":"","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`。 - **两种录音格式都能实时回填**:真机录的是 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 提示用户确认。