AIRI 网页版零配置语音识别：浏览器 Web Speech API（ASR/STT）接入实战指南
【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi
AIRI 内置的Web Speech API 转写提供者（browser-web-speech-api）利用浏览器原生语音识别能力，让 Web 版本无需任何 API Key 和外部服务即可完成实时语音转文字（STT/ASR），是快速体验语音输入的最简方案。本文将带你完成从环境校验、图形化配置到实时转写验证的完整流程，并结合仓库源码剖析其底层实现、参数默认值与问题排查路径，读完即可在自己的浏览器环境中跑通基于 Web Speech API 的语音对话链路。
Web Speech API：为什么它是零门槛的选择
Web Speech API 是浏览器内置的语音识别接口，在 AIRI 中它作为一个本地（Local）转写提供者存在。根据 provider 定义 中的说明：
description: 'Browser-native speech recognition. No API keys.'——无需任何密钥；requiresCredentials: false——不需要填写凭据即可启用；- 支持的任务包括
speech-to-text、automatic-speech-recognition、asr、stt、streaming-transcription，并且同时具备**流式输入（streamInput）与流式输出（streamOutput）**能力，可接入 AIRI 的实时听觉流水线。
正如 index.ts 的配置说明所示：如果你只想在网页上快速试验语音输入，且浏览器支持该 API，这就是设置成本最低的选项——不用申请密钥、不用配置服务器地址、不用选择远端模型。
浏览器支持确认：先检查运行环境
在开始配置前，请先确认两点：
- 使用 AIRI 网页版。Web Speech API 提供者仅能在浏览器环境中运行，无法在桌面版（Electron）中使用。
- 确认浏览器支持该 API 并愿意授予麦克风权限。
这一点在源码中有明确的硬性校验。看 provider.ts 的可用性检测逻辑：
const isAvailable = typeof window !== 'undefined' && ('webkitSpeechRecognition' in window || 'SpeechRecognition' in window) if (!isAvailable) { throw new Error('Web Speech API is not available in this environment. It requires a browser context with SpeechRecognition support (Chrome, Edge, Safari).') }即同时满足两个条件才能使用：
- 存在
window对象（浏览器渲染上下文）； - 全局存在
SpeechRecognition或带厂商前缀的webkitSpeechRecognition（Chrome、Edge、Safari 等基于 Chromium 或 WebKit 的现代浏览器通常都支持）。
从源码结构看，运行环境矩阵测试 明确将browser-web-speech-api归入browserOnlyProviderIds（仅浏览器提供者集合），进一步印证了它对浏览器环境的强依赖。
需要注意：识别性能会因浏览器、网络环境和语言不同而有所差异。Web Speech API 在部分浏览器实现中依赖云端语音服务，因此实际识别质量与网络状况相关。
在 AIRI 网页版中配置 Web Speech API
配置入口与操作步骤：
- 打开Web 版本→设置（Settings）→ 提供者（Providers）→ 转录（Transcription）→ Web Speech API。
- 在Recognition Language（识别语言）下拉框中选择识别语言。
- 按需开启Continuous Recognition（连续识别）与Show Interim Results（显示中间结果）。
- 该页面明确提示No API key required，无需任何凭据即可继续。
三个核心配置项说明
根据 浏览器 Web Speech API 设置页 与 配置 schema，三个配置项的默认值如下：
| 配置项 | 默认值 | 说明 |
|---|---|---|
language（识别语言） | en-US | 指定语音识别使用的语言代码（BCP-47 格式） |
continuous（连续识别） | true | 开启后持续监听，而不是每说完一句话就停止 |
interimResults（显示中间结果） | true | 开启后边说话边实时显示部分识别结果 |
Recognition Language 可选语言列表
设置页面内置了常用的语言选项（见 browser-web-speech-api.vue）：
- English (US) —
en-US - English (UK) —
en-GB - Spanish —
es-ES - French —
fr-FR - German —
de-DE - Italian —
it-IT - Portuguese —
pt-BR - Japanese —
ja-JP - Korean —
ko-KR - Chinese (Simplified) —
zh-CN - Chinese (Traditional) —
zh-TW - Russian —
ru-RU
底层实现：这些配置项如何被使用
在 provider.ts 中，配置项被直接映射到SpeechRecognition实例的属性上：
const recognition = new SpeechRecognition() recognition.lang = extraOptions?.language || 'en-US' recognition.continuous = extraOptions?.continuous ?? true recognition.interimResults = extraOptions?.interimResults ?? true recognition.maxAlternatives = extraOptions?.maxAlternatives ?? 1各参数的语义如下：
lang：识别语言代码，最终传给浏览器语音服务；continuous：是否连续监听。注意 AIRI 在持续监听模式下会在onend事件里自动重启识别会话（延迟 100ms，见 provider.ts），从而让对话无限期进行下去；interimResults：是否返回中间（未定稿）结果。AIRI 出于避免刷屏的考虑，默认只把isFinal === true的定稿片段作为增量（delta）对外发出（见 provider.ts），中间结果主要用于调试日志；maxAlternatives：每个结果最多返回的候选数，默认 1。
另外值得注意的一点：Web Speech API只支持实时流式识别，不支持文件转写。在createWebSpeechAPIProvider的fetch实现中，如果请求体携带FormData、Blob或File，会直接抛出异常提示改用流式 API（见 provider.ts）。
流式转写函数与实时管线
仓库还提供了面向实时听觉流水线的流式转写函数streamWebSpeechAPITranscription（见 provider.ts），它接收MediaStream并返回ReadableStream形式的增量文本流（fullStream）、最终文本 Promise（text）以及文本流（textStream），并通过onSentenceEnd/onSpeechEnd回调把识别结果推送给上层。该函数在 听觉模块 store 中被直接调用，与麦克风流、AbortController、空闲定时器、IO 追踪 Span 等机制整合，构成了完整的“麦克风 → Web Speech API → 转写文本 → 语音对话”链路。
验证设置：从页面测试到模块配置
配置完成后，建议按以下步骤验证转写是否真正生效：
1. 在设置页内直接测试
Web Speech API 的提供者设置页内建了Speech-to-Text Test（语音转文字测试）面板（见 browser-web-speech-api.vue）：
- 选择Audio Input Device（音频输入设备）——未选择时页面会给出提示并要求先选择；
- 点击Start Speech-to-Text Test开始测试；
- 对着麦克风说话，页面会实时显示流式识别文本（Current transcription）与最终结果（Final transcription）。
该测试直接调用streamWebSpeechAPITranscription，无论默认听觉提供者是什么，此测试始终固定使用 Web Speech API，因此非常适合用来单独验证当前浏览器与麦克风环境是否正常。测试过程中页面还会显示当前生效的语言、模式（Streaming）、连续识别与中间结果开关状态。
2. 在听觉（Hearing）模块中启用
- 进入设置 → 模块 → 听觉（Hearing），将转写提供者切换为Web Speech API，并确认选择了正确的音频输入设备。
- 允许浏览器的麦克风访问权限。
- 开始一段简短的语音输入测试，观察 AIRI 中是否出现转写结果。
在听觉 store 中，当activeTranscriptionProvider === 'browser-web-speech-api'时：
configured计算属性直接返回true（Web Speech API 只要选中即可用，不强制要求模型，见 hearing.ts）；- 若未手动选择模型，会自动选中默认模型
web-speech-api（见 hearing.ts）； - 语言与选项的优先级为：调用时传入的
providerOptions> 提供者配置language/continuous/interimResults> 内置默认值（见 hearing.ts）。
问题排查指南
如果转写结果没有出现，请按下表逐项排查：
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 页面提示 Web Speech API 不可用 | 浏览器不支持SpeechRecognition；或在 Electron 桌面版中使用 | 改用 Chrome / Edge / Safari 等支持的浏览器，并使用 AIRI 网页版 |
| 转写无输出 | 浏览器麦克风权限被拒绝 | 在浏览器地址栏的站点权限中允许麦克风访问，并刷新页面重试 |
| 转写无输出 | 选错了音频输入设备 | 在听觉模块或测试面板中切换到实际使用的麦克风 |
| 识别文字与所说语言不符 | 识别语言（Recognition Language）设置不正确 | 将language调整为与实际口音匹配的语言代码（如zh-CN、ja-JP） |
报not-allowed错误 | 麦克风权限被拒绝 | 源码会在该错误下明确提示 “Please grant microphone access and try again.”（见 provider.ts） |
报no-speech/audio-capture/network错误 | 未检测到语音、麦克风采集异常或网络不可用 | 这类错误在实现中会被静默记录而非中断会话（见 provider.ts），可检查麦克风与网络后重试 |
如果当前浏览器确实不支持该 API，仓库中已具备可选的替代路线：改用本地转写提供者（local transcription provider）或云端转写提供者（cloud transcription provider），在提供者列表中切换即可，无需改动其他配置。
结语
Web Speech API 提供者让 AIRI 网页版在“零密钥、零部署”的前提下获得了可用的实时语音识别能力：三个核心开关（语言、连续识别、中间结果）即可覆盖多数语音输入场景，设置页内置的 STT 测试面板又能独立验证浏览器与麦克风环境，源码中的可用性检测、连续模式自动重启、错误分类处理等实现细节则保证了其在真实使用中的健壮性。对于希望快速体验 AIRI 语音对话、或暂时不想接入云端转写服务的用户，这是当前仓库中最便捷的入口。
【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
