OpenTakeoff端侧语音量算:音频一个字都不离开浏览器的Whisper识别完整实现

原创2026-11-01 15:24:191,925 阅读

OpenTakeoff端侧语音量算:音频一个字都不离开浏览器的Whisper识别完整实现

OpenTakeoff 是一款开源的 PDF 量算(takeoff)工具,用于建筑与地坪工程的材料算量。它最特别的一点是:端侧语音量算——按住快捷键说话,Whisper 模型在浏览器的 Web Worker 里完成语音识别,整条音频链路没有任何一个字节发送到云端,也没有任何遥测。本文带你完整看懂这套"零网络语音识别"是如何实现的。

语音量算为什么必须端侧

传统语音助手把音频上传给云端 API 再返回文字,而量算软件里说的是施工现场的真实数据(材料、损耗、备注)。OpenTakeoff 的选择是:识别引擎直接跑在你的机器上。

OpenTakeoff端侧语音量算画布:顶栏Voice快捷键与量算报告

  • 引擎是 whisper-tiny.en(ONNX 量化版,约 44 MB),通过 transformers.js 风格的 WASM 运行时执行,运行在独立的 Web Worker 中(web/src/stt.worker.ts),解码时画布的平移缩放依然流畅。
  • 没有云端识别器,也没有"降级到云端"的后路——这是刻意的隐私承诺。
  • 语音识别完成后,识别链路上没有任何 AI:文字交给一套确定性的语法解析器直接映射为应用操作。

从麦克风到文字的完整数据流

整个流程可以拆成四步,全部发生在浏览器进程内:

  1. 按住 M(或 Voice 按钮)开始录音:web/src/lib/voiceCapture.ts 通过 getUserMedia 拿到麦克风,开启回声消除、噪声抑制和自动增益,把音频重采样为 16 kHz 单声道 PCM。音频只存在于内存中,从不落盘。
  2. 零拷贝交给 Worker:主线程客户端 web/src/lib/voiceRecognizerClient.ts 用 postMessage 的 transferable buffer 把 PCM 一次性"转移"给 web/src/stt.worker.ts——主线程只发消息和画 UI,重活全在 Worker。
  3. Whisper 解码:Worker 内的引擎适配层 web/src/lib/stt/recognizer.ts 加载 q8 量化编码器 + uint8 解码器,纯计算输出文字。
  4. 确定性意图解析:web/src/lib/voiceIntent.ts 把文字解析成一个类型化意图或类型化拒绝——例如 "carpet one, waste seven" 变成"激活 CPT-1、损耗 7%"。它和手打命令框走的是同一个 dispatcher,语音不是旁路,而是同一套动作的另一种输入方式。

OpenTakeoff语音量算结果:实时面积计数与选中图形

几个值得注意的工程细节:

  • 同义纠正来自语料证据:比如 "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,摄像头与地理位置完全禁用。

OpenTakeoff语音量算生成的取量报告:材料、面积与损耗汇总

相关源码与文档导航

模块 说明
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。对自托管用户来说,构建前多跑一行脚本,就拥有了一台完全不依赖云端的端侧语音量算工具——说完即算,一个字都不出浏览器。

登录后查看全文
opentakeoff