Voice Input Local STT

语音输入（本地 STT）

用说的代替打字：在侧边栏输入框里按 Alt+V 开始录音，边说边出草稿，松手后本地模型补标点、规整数字，不自动发送。

识别完全在本地完成 —— 音频不上传任何服务器，也不需要云端 ASR 服务或额外的 API Key。代价是需要一次性准备两样东西：可选依赖 与 模型包。

← 返回 Wiki 首页 · 相关：代理服务 · 配置说明 · 常见问题

---

一、它长什么样

开启后，输入框工具栏会出现 🎤 按钮；录音期间输入框上方展开一条录音条：

元素	说明
24 根音量柱	实时波形，随音量滚动
计时器	00:12 形式，单次上限默认 5 分钟
状态文案	正在聆听 / 正在转写 / 已达上限 / 识别失败 等
取消按钮	放弃本次录音并回滚草稿（Esc 同效）
完成按钮	结束录音并定稿（再按一次 Alt+V 同效）

两条与「打字」不同的行为需要知道：

• 草稿是临时的：流式模型边说边写；你一旦手动改过输入框，后续草稿只追加「新多出来的尾巴」，不会覆盖你已经改过的文字。若这一版识别结果是改写（不是纯追加），宁可少写一句也不会重写你看到的文本。
• 结果不会自动发出去：定稿只是把文字写进输入框，发不发、什么时候发，仍然由你决定。

---

二、三段式启用（缺一不可）

侧边栏的 🎤 只有在 依赖就绪 + 模型就绪 + 开关启用 三者同时满足时才出现，否则按钮保持隐藏（避免点了才知道不能用）。

1. 安装可选依赖（一次性）

代理端需要 sherpa-onnx-node 及其平台二进制包。三种入口任选其一：

# ① CLI（推荐：先查状态，再装）
aha asr detect
aha asr install

# ② 安装代理时顺带勾选（默认不装）
bash install.sh --with-asr

# ③ 扩展「选项页 → 语音」Tab 一键安装（进度每 2 秒轮询）

内网环境需要放通 npm 镜像里的 sherpa-onnx 平台包，否则安装会停在「缺少平台二进制」。完整包名清单见仓库 docs/Voice-Input-Local-STT.md。

2. 准备模型包

模型放在代理端的固定目录，一个子目录一个模型，目录内必须有 manifest.json：

~/.ai-helper-agent/asr/models/
└── sense-voice-zh-en-ja-ko-yue-2024-07-17/
    ├── manifest.json
    ├── model.int8.onnx
    └── tokens.txt

三类模型各有分工，可以只装其中一部分（只装 offline 也能用，只是没有边说边出的草稿）：

类型	作用	缺了会怎样
online（流式）	边说边出草稿	录音条不再显示草稿，松手后一次性出结果
offline（定稿）	整段高精度识别 + 标点	退化为使用流式草稿的文本，质量下降
vad（断句）	长句自动断句	仍然可用，长句标点略差

获取途径：

# 机器能访问外网或 HF 镜像：一键下载（自动写 manifest、校验哈希）
curl -H "Authorization: Bearer <token>" -X POST \
  http://127.0.0.1:18910/api/asr/models/download \
  -H 'Content-Type: application/json' \
  -d '{"kind":"offline"}'

完全内网时，在外网机下载后整理成上面的目录结构，连同 manifest.json（含 files 与可选 sha256）一起拷入即可；也可以在配置页用「选择模型目录」导入。

3. 打开开关

选项页「语音」Tab 顶部开关。默认是关闭的 —— 装了依赖与模型也不会自动启用，避免「装了就该能用」的误解。

三项就绪后面板会自动刷新门控（🎤 出现），不需要重开侧边栏。

附：麦克风授权（只能在标签页做）

侧边栏 / 弹窗形态里 Chromium 不允许弹麦克风授权框。首次使用请在选项页（标签页形态）点「语音」Tab 里的「去授权」，允许一次即可；之后侧边栏录音不再打扰你。

未授权时录音条里会出现「去授权」按钮，点击直接跳到该位置。

---

三、怎么用

1. 光标落在输入框（或任意位置），按 Alt+V（Option+V）开始录音；
2. 说话，输入框里出现草稿 —— 可以继续手动打字修改；
3. 松手方式（任选）：
   • 再按一次 Alt+V
   • 点录音条的「完成」
   • 直接按 Enter 发送（会自动停录并定稿后再发）
4. 想放弃：按 Esc 或点录音条「取消」，草稿回滚。

快捷键分两类：

• Alt+V（默认，不可改键）：重点是焦点在网页上时也生效（扩展会把按键转发到面板）。
• 右侧 Alt / 右侧 Ctrl（可选，默认全关）：在「选项页 → 语音 → 快捷触发」里分别勾选，两个都勾 = 任一都能触发。
  • 语义是「按下再松开」算一次；按住期间敲了别的键就整次作废 —— 右 Alt 在 AltGr 布局上是组合键， 这样既不会误开录音，也不会截断 AltGr 的字符输入。
  • 配置写在 chrome.storage.local，勾选后立即生效，侧边栏与网页里同时可用，不用重启扩展或重开面板。
  • 只在语音输入就绪（依赖 × 模型 × 开关）时响应。

---

四、配置项

选项页「语音」Tab

项	说明
启用语音输入	总开关；关闭后 🎤 与 Alt+V 一并失效
快捷触发	右侧 Alt / 右侧 Ctrl 单键开关，默认全关；Alt+V 始终可用、不受它影响
语言	auto / 中文 / 英文 / 日语 / 韩语 / 粤语，默认自动
流式模型	从已扫描到的 online 模型中选，默认取第一个可用包
定稿模型	同上，对应 offline
依赖状态 / 一键安装	显示 sherpa-onnx 检测结果与安装进度
模型扫描 / 导入	重新扫描模型目录，或从任意目录导入模型包

代理端配置文件

~/.ai-helper-agent/asr/asr-config.json（由扩展写入，一般不需要手改）：

{
  "enabled": true,
  "language": "auto",
  "streamingModelId": "sense-voice-streaming-zh-en",
  "offlineModelId": "sense-voice-zh-en-ja-ko-yue-2024-07-17",
  "idleUnloadMs": 600000
}

字段	默认	说明
enabled	false	总开关
language	auto	期望语言，auto 交给模型判断
streamingModelId / offlineModelId	null	null = 按能力自动选第一个可用包
idleUnloadMs	600000	空闲多久卸载引擎（毫秒；0 = 不卸载）

环境变量

变量	默认	说明
AI_HELPER_ASR_ROOT	~/.ai-helper-agent/asr	模型与配置根目录
AI_HELPER_ASR_MAX_RECORDING_MS	300000	单次录音时长上限
AI_HELPER_ASR_SESSION_IDLE_MS	30000	会话空闲回收
AI_HELPER_ASR_MAX_SESSIONS	1	并发会话数
AI_HELPER_ASR_RSS_LIMIT	约 1.5 GB	进程内存超过此值时跳过 offline 定稿
AI_HELPER_ASR_OFFLINE_TIMEOUT_MS	180000	单次定稿推理超时

---

五、接口（面向开发者）

WebSocket 流式会话

ws://127.0.0.1:18910/ws/asr/<sessionId>?token=<token>&language=auto

方向	帧	说明
→	{type:'start'}	开启会话
→	二进制帧	16 kHz / 16-bit / 单声道 PCM
→	{type:'stop'}	结束并定稿（异步，final 稍后补发）
→	{type:'cancel'}	放弃，不回 final
←	{type:'ready', draft}	会话就绪；draft:false 表示没有流式模型
←	{type:'partial', text}	草稿（约 150 ms 一次）
←	{type:'final', text, fallback}	定稿；fallback:true 表示退回流式文本
←	{type:'error', code}	busy / model_missing / max_duration / rss_pressure / internal

松手后会话会立刻让出并发名额，定稿在后台 worker 线程完成后补发 final —— 不必等结果就能开始下一次录音。

HTTP 端点

方法	路径	说明
GET	/api/asr/status	依赖 / 模型 / 开关 / 已加载引擎状态
POST	/api/asr/config	修改配置（开关、语言、模型 id、空闲卸载）
GET	/api/asr/models	已扫描的模型包列表（含非法包与原因）
POST	/api/asr/models/scan	重新扫描模型目录
POST	/api/asr/models/pick	从指定目录导入模型包
GET	/api/asr/models/catalog	可下载模型清单
POST	/api/asr/models/download	下载模型（支持断点续传 + 哈希校验）
GET	/api/asr/models/download/status	下载进度
POST	/api/asr/models/download/cancel	取消下载
POST	/api/asr/transcribe	整段音频（WAV）一次性识别
POST	/api/asr/warmup	预热引擎（启动时自动执行一次）
POST	/api/asr/deps/detect	检测 sherpa-onnx 依赖
POST	/api/asr/deps/install	安装依赖（白名单命令）
GET	/api/asr/deps/install/status	安装进度

所有端点与其余 API 一样需要 Bearer token。

---

六、隐私与资源占用

• 音频不出本机：不经过任何云端 ASR，也不写盘（除你自己导出录音的场景）。
• 不自动发送：定稿只是写进输入框。
• 空闲自动卸载：默认 10 分钟不用就释放引擎，把那几百 MB 原生内存还回去。
• 推理不阻塞代理：定稿在独立 worker 线程里跑，长句转写期间 /health、聊天流、工具执行照常响应。
• 内存保护：进程 RSS 接近阈值时跳过 offline 定稿、退回草稿（rss_pressure），避免拖垮整个代理。

模型体积参考：流式（中英，int8）约 100 MB、定稿 SenseVoice（中英日韩粤，int8）约 230 MB、VAD 约 1 MB。

---

七、常见问题

Q：🎤 按钮一直不出现？ 说明三段式里有一项没满足。打开「选项页 → 语音」，看是「依赖未就绪」还是「模型未就绪」，再点对应的一键安装 / 扫描；开关也要确认已打开。

Q：点了 🎤 提示没有麦克风权限？ 侧边栏弹不出授权框。到选项页「语音」Tab 点「去授权」，在标签页里允许一次。

Q：插入了模型目录，但显示「模型包非法」？ 配置页现在会显示具体原因（缺少 manifest.json、字段缺失、文件不存在、sha256_mismatch 等）。少于 1 个字段不对都不会被加载 —— 按提示修 manifest.json 后重新「扫描」。

Q：识别很慢 / 一松手就要等几秒？ 这是离线定稿模型的正常开销（整段重算、质量更高）。想更快可以只装流式模型，代价是标点与数字规整变差。

Q：说太长了被中断？ 单次上限默认 5 分钟；到上限时代理会自动停录并用整段音频定稿，不会丢掉已说的内容，输入框会显示「已达单次录音时长上限，正在转写…」。

Q：AI 正在生成回答时能补一句吗？ 可以。定稿写进输入框后发送按钮会立刻变成「发送」，不会误触「停止生成」。

Q：可以同时录两路吗？ 默认并发 1 路（本机单用户形态）。第二路会收到 busy，界面提示「正在处理上一段语音」。

---

下一步

• 安装与模型包制作细节（含内网放通清单、离线打包） → 仓库文档 docs/Voice-Input-Local-STT.md
• 代理端其他能力 → 代理服务
• 全部配置项 → 配置说明