Files
zyt/app/research/local-transcription-setup.md
T
2026-10-30 13:41:35 +08:00

13 KiB
Raw Blame History

本地离线语音转写:安装、打包与验证

当前状态(2026-10-30):用户已明确要求恢复腾讯云实时转写、保留简体中文。客户端默认通路已经恢复腾讯云,启动/打包不再自动安装本地 ASR,也不把本地模型加入发布资源。本文后续内容保留为此前本地方案的开发、安装与评估记录,并非当前默认行为。当前通路见 cloud-transcription-restore.md。

运行时使用 faster-whisper 1.2.1,在医生电脑的 CPU 上以 int8 加载本地 Whisper 模型。音频为浏览器桥接传入的单声道、16 kHz、有符号 PCM16 小端字节流;不写临时音频、不发送至 ASR 服务。模型安装和下载只能通过下面的显式命令执行,视频通话不会触发安装、下载或腾讯云语音识别。

开发环境安装

在已安装医生工作站依赖的 app 目录运行:

.venv\Scripts\python.exe scripts/setup_local_transcription.py --install-dependencies --download --model-size small --check

此命令明确允许联网安装 faster-whisper==1.2.1 及其传递依赖,并从官方 Systran/faster-whisper-small 仓库下载模型,然后禁用网络验证 CPU/int8 模型和 Silero VAD 的加载。tiny、base、small、medium、large-v3 均可选择;中文场景不要使用英文专用 .en 模型。开发默认选择 small,实际识别准确率和延迟仍需在目标电脑与实际通话音频上验收。

--install-dependencies 仅安装至执行命令的 Python 环境;--download 才下载模型。不传操作参数只显示帮助。可用 --revision <官方仓库提交哈希> 固定下载版本。

模型查找顺序为 DOCTOR_ASR_MODEL_PATH、开发目录或安装包内的 resources/local-asr/model、最后为 platformdirs.user_data_path("ZhenyangDoctorWorkstation", appauthor="ZhenYangTang") / "local-asr" / "model"。可以指定独立目录:

$env:DOCTOR_ASR_MODEL_PATH = 'D:\DoctorModels\whisper-small'
.venv\Scripts\python.exe scripts/setup_local_transcription.py --download --model-size small --check

--model-path 只覆盖本次安装/检查命令;工作站仍按上述顺序查找。下载后会记录 doctor-asr-install.json,包含仓库、请求的版本、运行库版本和时间,不包含音频。运行时要求目录存在,且 model.bin、config.json、tokenizer.json、vocabulary.txt 或 vocabulary.json 非空。缺失时直接报错。tokenizer.json 必须随模型提供,以阻止上游缺失 tokenizer 时的自动获取回退。

离线电脑可通过离线安装包安装运行库,再复制完整模型目录;不要在通话过程中初始化下载。离线检查:

.venv\Scripts\python.exe scripts/setup_local_transcription.py --check

桌面安装包

为应用配置 local-asr 可选依赖(faster-whisper==1.2.1),并在实际 PyInstaller 构建环境安装该额外依赖。运行库需要 NumPy、CTranslate2、tokenizers、ONNX Runtime、PyAV 等上游依赖。不能仅在开发 .venv 安装后假设 .venv-build 或已冻结的 exe 自动拥有这些依赖。

PyInstaller spec 已加入 faster_whisper 数据文件(包括 Silero VAD)及 ctranslate2、onnxruntime、av、tokenizers 的 collect_all,缺少运行库时构建会明确失败。Windows/macOS 运行环境准备与打包脚本已加入 --extra local-asr,依赖锁文件同步更新。构建前可把完整模型放在 app/resources/local-asr/model,随现有 resources 打入安装包;也可在目标电脑独立安装到应用数据目录或管理员指定目录。模型不纳入 Git。该模块导入依赖是延迟执行的,没有安装本地 ASR 运行库也不会阻止工作站、视频和录音模块启动。

本轮未生成新 exe 或安装包。发布前仍需验证运行库、模型和 VAD 在成品内真实可用,不能把开发环境通过的单元测试作为成品 ASR 可用性的证明。旧系统兼容性取决于这些原生依赖的官方 wheel 和操作系统支持,不自动沿用工作站其他部分的兼容性声明。

验证

.venv\Scripts\python.exe -m pytest tests/test_local_transcription.py
.venv\Scripts\python.exe -m ruff check src/doctor_workstation/video/local_transcription.py tests/test_local_transcription.py scripts/setup_local_transcription.py
.venv\Scripts\python.exe scripts/setup_local_transcription.py --check --smoke-wav D:\ASR-Test\non-sensitive-16k-mono.wav

smoke WAV 必须是单声道 16 kHz PCM16,最长 12 秒。该命令阻止网络连接并输出识别结果;请使用无患者信息的人工测试音频。建议覆盖短回答“有”“不”、否定句、药物名称、0.5/5、剂量单位、静音、背景噪声,以及医生和患者同时说话。录音通道的角色来源于浏览器端音轨身份,模型不做声纹识别。

单元测试使用替代引擎,验证会话隔离、异步回调、队列上限、序号验证、排空停止、错误脱敏、静音和数字/否定词的原样输出。替代引擎测试不证明实际模型准确率。启动和推理只能在后台执行;Qt 接收方通过 signal 转交主线程。close() 立即取消回调,正在执行的原生推理可能在守护线程中完成,不能在 UI 线程等待它。

2026-10-29 已在本仓库 .venv 安装运行库,并在 app/resources/local-asr/model 安装官方 Systran/faster-whisper-small。CPU/int8 模型和 VAD 加载检查通过;使用 FunASR 官方示例提供的公开中文音频完成真实识别,检查及推理期间阻断网络。输出为“欢迎大家来体验打磨院推出的语音识别模型”,出现“达摩院”的同音误识;这验证了本机推理链路,不能代替医疗词汇、噪声、双向通话及目标电脑负载验收。没有发送真实患者资料,尚未测试真实 AI 服务响应。

视频 AI 接入与验收

现有腾讯音视频通信、IM 和云端录制继续使用;语音转写改由本地音轨 PCM 和本机模型完成。完成分段保存成功后才触发 AI,约八秒合并更新一次,无新增原文时不重复请求。使用现有 tcm.diagnosis/aiAssistantStream 的 live_consultation/live_review 任务;服务端按医生、诊单、通话及转写会话读取完整原文,再连同授权病历交给已授权的现有 Dify 服务。AI 不发送消息或自动写入病历。

客户端新增 AI 辅助、对话原文、患者资料标签、可调侧栏宽度和窄屏抽屉。挂断后在 IM 顶部打开“本次通话复盘”;点击复盘按钮请求复盘草稿。每条辅助结果可以查看完整引用原话,转写未完整保存时明确显示状态。模型缺失、AI 服务未更新或没有权限时显示具体状态,视频通话可继续。

生效需要部署本轮服务端代码,并重启使用新构建资源的客户端。开发验证只使用合成通话数据及公开音频,不连接真实患者。上线验收需在医生测试账号和合成患者下确认双方音轨归属、转写时延、挂断排空、服务端 AI JSON 格式、取消与复盘。

模型/存储准备阶段先采集到最多 12 个 PCM 分段的内存缓冲;超限明确标记转写不完整。挂断后等待原生识别线程排空才封存文字,15 秒仅提示等待,不提前关闭文字存储。关闭应用时沿用 190 秒异常收尾上限,强制退出会把未完成转写标记为 partial。同会话的存储启动临时失败可以显式重试,正在执行或已成功的启动请求仍复用。

音轨接入适配当前锁定的 CallEngine 3.5.9 / TRTCCloud 2.10.19:getTRTCCloudInstance() 返回包装对象,音轨 API 来自其 _trtc。resolveTrtcAudioSource 先验证实际能力,并保留方法所属实例;升级 SDK 时需重新运行真实包装对象的隔离验证。前端采集失败优先覆盖旧的 native running 状态,并保留独立错误文字和重试入口。持续声音或非零底噪的 PCM 提交窗口为约 4 秒,之后才排队识别,因此字幕按分段追加,不是逐字流式识别。无需提高音量来触发分段,轻声和短否定词不会因前端音量阈值被丢弃。

该音轨修复后,118 项前端测试和 63 项转写桥接/通话回归通过,生产资源已重建。公开语音在隔离 Qt 中贯通了实际 SDK 包装适配、生产音频采集、真实 WebChannel、本地 faster-whisper、Qt 信号及实际 App 字幕 DOM,双方共 8 段均显示;首段实测 6.494 秒。SDK 实例的媒体获取替换为公开音频双轨,存储使用内存,因此仍不代表真实 RTC 发布/订阅与在线持久化已验收。详细材料为 app/artifacts/im-ai/asr-fixed-end-to-end.md。已打开的通话页面不会自动载入新脚本,结束当前通话后需关闭并重新打开 IM/视频窗口。

本轮回归:384 项 Python 用例、113 项前端用例通过;PHP 新流式链路 440 项合成断言及 13 组既有回归通过。另有两个既有 PHP 套件在未修改的 HEAD 上同样失败,详见 app/artifacts/im-ai/live-ai-server-implementation.md,未将它们计入通过数。Vue 类型检查、前端生产构建、Python Ruff 和 diff 空白检查通过。隔离 QtWebEngine 加载本地合成页面,验证挂断入口、打开不重新生成、完整引用、弹窗 Tab 焦点循环、Escape 返回焦点和 440px 下按钮可见,截图位于 app/artifacts/im-ai/video-ai-final-*.png。未执行 macOS 真机构建或冻结安装包验收。

核对的官方来源(2026-10-29)

简体输出与多方言边界(2026-10-30)

opencc-python-reimplemented==0.1.7 是客户端基础依赖。使用随包配置/词典进行本地 t2s 字形转换,在原生转写 controller 发出字幕/保存事件前统一为简体;实时字幕、存储和新通话 AI 引用使用同一份文字。已有通话记录打开“面诊对话文字”时以简体显示,不批量改写历史数据库。数字、剂量、否定词、标点和方言词语保留,不使用大模型改写原话。字形转换不能修复误听,也不把粤语词汇翻译成普通话。

安装工具已包含该依赖,PyInstaller 收集 opencc 配置和词典;模型启动时预加载转换资源,缺失则明确报错。不要同时安装同样提供 opencc 导入名的原生 opencc 分发。基础依赖与锁文件更新后,源码运行需要结束通话并重启客户端;单独重新打开网页不会重载原生 Python 代码。已冻结的安装包需要重新构建。

当前通用 Whisper small 不等于多方言专项模型。7 类方言/26 种地域口音的 Fun-ASR-Nano 是本地替代候选,具体能力范围、CPU 成本和离线测试方案见 app/artifacts/im-ai/dialect-asr-research.md;未通过目标电脑的双路时延及对应方言准确率验收前,不应声称“所有方言准确识别”。

本机已在隔离环境完成 Nano CPU float32 公开普通话/粤语测试,固定官方权重通过 SHA-256 校验,加载/推理均禁网。Nano 可以保留这条粤语样本词形,但普通话“开放时间”误成“开饭时间”,没有 VAD 的粤语尾段生成额外“对。”。4 秒双路负载预算也缺乏余量;这些结果不支持默认切换。详细输出、耗时和内存见 app/artifacts/im-ai/dialect-asr-benchmark.md。该评估没有修改应用运行环境,没有宣称四川/湖南已验收。

后续同机 VAD + 动态 int8 有界实测完成 24 个案例,15 次正常生成、9 次无语音输入被 VAD 跳过;短样本平均耗时下降,但量化期间峰值工作集约 5.7 GiB,且输出词形改变。未验证四川/湖南、医疗数字/否定语音和持续视频负载,因此保持默认引擎。完整结果为 app/artifacts/im-ai/dialect-asr-quantized-benchmark.md。评估环境、公开样本及权重保存在 app/artifacts/im-ai/nano-*,不会随客户端 resources 打包。