OpenTakeoff端侧语音量算:音频一个字都不离开浏览器的Whisper识别完整实现
OpenTakeoff端侧语音量算:音频一个字都不离开浏览器的Whisper识别完整实现
OpenTakeoff 是一款开源的 PDF 量算(takeoff)工具,用于建筑与地坪工程的材料算量。它最特别的一点是:端侧语音量算——按住快捷键说话,Whisper 模型在浏览器的 Web Worker 里完成语音识别,整条音频链路没有任何一个字节发送到云端,也没有任何遥测。本文带你完整看懂这套"零网络语音识别"是如何实现的。
语音量算为什么必须端侧
传统语音助手把音频上传给云端 API 再返回文字,而量算软件里说的是施工现场的真实数据(材料、损耗、备注)。OpenTakeoff 的选择是:识别引擎直接跑在你的机器上。
- 引擎是 whisper-tiny.en(ONNX 量化版,约 44 MB),通过 transformers.js 风格的 WASM 运行时执行,运行在独立的 Web Worker 中(web/src/stt.worker.ts),解码时画布的平移缩放依然流畅。
- 没有云端识别器,也没有"降级到云端"的后路——这是刻意的隐私承诺。
- 语音识别完成后,识别链路上没有任何 AI:文字交给一套确定性的语法解析器直接映射为应用操作。
从麦克风到文字的完整数据流
整个流程可以拆成四步,全部发生在浏览器进程内:
- 按住 M(或 Voice 按钮)开始录音:web/src/lib/voiceCapture.ts 通过
getUserMedia拿到麦克风,开启回声消除、噪声抑制和自动增益,把音频重采样为 16 kHz 单声道 PCM。音频只存在于内存中,从不落盘。 - 零拷贝交给 Worker:主线程客户端 web/src/lib/voiceRecognizerClient.ts 用
postMessage的 transferable buffer 把 PCM 一次性"转移"给 web/src/stt.worker.ts——主线程只发消息和画 UI,重活全在 Worker。 - Whisper 解码:Worker 内的引擎适配层 web/src/lib/stt/recognizer.ts 加载 q8 量化编码器 + uint8 解码器,纯计算输出文字。
- 确定性意图解析:web/src/lib/voiceIntent.ts 把文字解析成一个类型化意图或类型化拒绝——例如 "carpet one, waste seven" 变成"激活 CPT-1、损耗 7%"。它和手打命令框走的是同一个 dispatcher,语音不是旁路,而是同一套动作的另一种输入方式。
几个值得注意的工程细节:
- 同义纠正来自语料证据:比如 "bass→base"(真实语料里听成 "rubber bass one")、数字槽位里的 "to/too→two",都只作用于数字槽位,避免把 "transition" 听成 "transition two" 之外的误伤。
- 永不猜:"carpet one seven" 是拒绝而不是 CPT-1+损耗 7——因为两种读法都合理时,重新说一遍比改错数据便宜。CI 里 400+ 次识别尝试保持了零错误动作的硬性不变量。
- 生命周期每个状态都有明确报错:模型未部署、麦克风被拒、后台标签页中录音中断等,全部提示而不是静默。
为什么选 whisper-tiny.en:真实语料基准测试
docs/VOICE.md 记录了完整的引擎选型基准,测试集是仓库自带的真实说话人语料(28 条安静 + 9 条噪声录音):
| 引擎/配置 | 模型大小 | 意图召回率(安静/噪声) | 结论 |
|---|---|---|---|
| whisper-tiny.en,greedy 解码(q8 编码器 + uint8 解码器) | 43.5 MB | 82.1% / 66.7% | ✅ 采用 |
| whisper-base.en,greedy | 76.9 MB | 60.7% / 44.4% | ❌ 更大还更差 |
| whisper-tiny.en,beam 5 | 43.5 MB | 75.0% / 55.6% | ❌ 更慢且噪声下出现重复病态 |
| whisper.cpp WASM | — | — | ❌ 需要 SharedArrayBuffer,与项目 CSP 冲突 |
浏览器单线程约 1.2 倍实时速度解码,冷启动约 8 秒。想复现这张表,任何时候都可以跑:
node --import tsx scripts/voice-benchmark.mjs
对应脚本:web/scripts/voice-benchmark.mjs,语料与录制规范在 web/test/fixtures/voice/RECORDING.md。
如何启用端侧语音:模型暂存与构建开关
语音功能默认关闭(按钮不在工具栏上),代码全部保留,通过构建时开关开启:
# 1. 把 ~44MB 的 whisper-tiny.en ONNX 模型暂存到 web/public/models/(gitignored,同源分发)
cd web
node scripts/fetch-voice-model.mjs
# 2. 构建时打开命令框/语音开关
VITE_COMMAND_BOX=1 npx vite build
- 模型刻意不放进 git,也不由应用从第三方运行时拉取:web/scripts/fetch-voice-model.mjs 是唯一接触网络的地方,且只运行在构建/开发阶段,产物以同源路径
/models/分发,永不走 CDN。 - 没有暂存模型时,功能会明确提示 "Voice isn't installed on this deployment"——功能缺失,而非损坏。
- 引擎初始化阶段是唯一允许网络 I/O 的窗口(且仅限同源),模型加载完成后
transcribe()是纯计算。
隐私如何被证明,而不是被声明
"音频不离开浏览器"这种话很容易被空喊。OpenTakeoff 用测试把它钉死:
- 隐私测试 web/test/voicePrivacy.test.ts:在引擎加载之前把
fetch/XMLHttpRequest/WebSocket全部替换成记录器,然后跑完整的"初始化 + 模型加载 + 转写"周期,断言记录到零次网络调用——任何一次触碰网络,构建直接失败。 - 手动验证:打开 DevTools 的 Network 面板,完成一次听写,日志保持为空。
- 权限最小化:
Permissions-Policy只把麦克风授予self,摄像头与地理位置完全禁用。
相关源码与文档导航
| 模块 | 说明 |
|---|---|
| web/src/stt.worker.ts | 识别 Worker:init / transcribe / dispose 协议 |
| web/src/lib/stt/recognizer.ts | 引擎接缝与适配器工厂(transformers.js / whisper.cpp) |
| web/src/lib/stt/transformersJs.ts | 默认引擎:whisper-tiny.en ONNX 适配 |
| web/src/lib/voiceCapture.ts | 按住说话式麦克风采集与 16 kHz 重采样 |
| web/src/lib/voiceIntent.ts | 确定性意图语法:永不猜,只拒绝 |
| web/scripts/fetch-voice-model.mjs | 模型同源暂存脚本(唯一接触网络处) |
| web/test/voicePrivacy.test.ts | 零网络调用隐私证明测试 |
| docs/VOICE.md | 完整设计文档:基准表、语料门槛、生命周期状态 |
写在最后
这套实现的精髓在于把"隐私"做成了工程约束而不是营销话术:模型同源分发、Worker 隔离、transferable buffer 零拷贝、语法层永不猜测、隐私测试常驻 CI。对自托管用户来说,构建前多跑一行脚本,就拥有了一台完全不依赖云端的端侧语音量算工具——说完即算,一个字都不出浏览器。
登录后查看全文


