Atomic Chat 语音输入完整实战指南：用本地 Voxtral 模型实现 100% 离线语音转文字

Atomic Chat 是一款运行在本地电脑的开源 AI 应用，其语音输入功能内置了 Voxtral Mini 3B 语音识别模型：对着麦克风说话，文字就会实时出现在聊天输入框中，全程 100% 离线，你的声音数据永远不会离开电脑。本文带你从零完成语音转文字的设置，并讲解它背后的工作原理。

为什么选本地语音转文字？

用云端的语音转文字服务，意味着你的每一句话都要先上传服务器。对于律师、医生、记者，或者任何在意隐私的用户，这不可接受。

Atomic Chat 的做法截然不同：

• 🎙️原生麦克风采集：通过 Rust 音频插件直接采集 16 kHz 原始音频，不经过浏览器接口
• 🔒完全离线：语音识别在本地 llama.cpp 引擎上运行，断网也能用
• ⚡边说边出字：每说完整一句话，文字立刻插入输入框，不用等你说完全部
• 🆓零额外组件：引擎早已打包在应用内，唯一要下载的只是约 3 GB 的模型文件

工作原理：Voxtral 模型如何被"藏"在聊天引擎里

这是 Atomic Chat 语音输入最精妙的设计：它不需要第二个推理引擎。

打包应用内的上游 llama.cpp 引擎（llamacpp-upstream）自带libmtmd多模态库，其中已包含 Voxtral 音频投影器，且内置的llama-server本身就提供 OpenAI 兼容的/v1/audio/transcriptions接口。因此整个语音链路是：

1. 采集：音频插件以 16 kHz 单声道 PCM 格式采集麦克风声音
2. 断句：能量 VAD（语音活动检测）在自然停顿处把语音流切成短语，每段最长 15 秒，并保留 300 ms 预卷防止吃字，参数定义在 vad.rs
3. 转写：每句完成后，由 Rust 端直接 POST 到本地/v1/audio/transcriptions接口
4. 插入：识别出的文字追加到输入框光标处，你继续说下一句

语音模型 Voxtral-Mini-3B-2507（Q4_K_M 量化） 会与你的聊天模型并行驻留，空闲 5 分钟后自动卸载（见 transcriptionRegistry.ts），内存占用约 3.4 GB。完整的架构决策记录在 2026-08-24-dictate-into-the-composer-with-a-local-voxtral-model.md。

三步设置：从打开通用麦克风到开始说话

首次点击输入框左侧的 🎤 麦克风按钮，会进入三步设置向导（VoiceSetupDialog.tsx）：

第 1 步 · 介绍"Talk instead of typing" —— 说明语音输入的特性：每句话说完即插入、音频不出本机、聊天和 Agent 模式均可用。

第 2 步 · 授予麦克风权限系统弹出麦克风访问请求，点"允许"即可。⚠️ macOS 用户注意：系统只询问一次，如果之前点了拒绝，需要到「系统设置 → 隐私与安全性 → 麦克风」中重新为 Atomic Chat 开启，之后可能还要重启应用。

第 3 步 · 下载语音模型一键下载 Voxtral Mini 3B（约 2.97 GB，需预留 4 GB 磁盘空间），进度条实时显示。下载通过模型 Hub 的常规管线完成，只此一次。

完成后回到聊天界面，随时点击麦克风按钮即可开始听写，再次点击"停止并插入"，或"取消录音"（已插入的文字会保留）。

实战技巧与设置项

日常使用中值得了解的几个细节：

• 语言设置：默认auto（跟随应用界面语言），也可手动指定为英语，逻辑见 language.ts
• 内存紧张？在语音设置面板开启"听写时卸载聊天模型"开关（unloadChatModel选项），听写时先腾出内存，代价是听写结束后需重新加载聊天模型
• 回复流式输出期间语音输入不可用，属正常行为
• 麦克风被占用：如果提示"麦克风被其他应用占用"，先关闭会议软件再试

语音状态机（监听中/转写中/待命）的完整实现见 useVoiceInput.ts，文本合并逻辑见 promptMerge.ts。

常见问题

错误码与提示文案对照见 useVoiceInput.ts 中的errors文案定义（en/common.json）。

总结

Atomic Chat 的语音输入用最经济的方式实现了完全私有的听写体验：复用已打包的 llama.cpp 引擎和 Voxtral 音频投影器，安装包零增量、签名零成本，用户只需下载一次约 3 GB 的模型。从点击麦克风到文字上屏，所有环节都在你的电脑上完成——没有 API 密钥、没有订阅费用、没有数据外泄的可能。

核心模块路径速查

• 音频采集与 VAD：src-tauri/plugins/tauri-plugin-atomic-audio/
• 语音模型注册表：extensions/llamacpp-upstream-extension/src/transcriptionRegistry.ts
• 语音常量（模型 ID、大小、语言）：web-app/src/constants/voice.ts
• 听写 UI 入口：web-app/src/containers/VoiceInputToggle.tsx