AIRI 官方语音识别ASR/STT接入指南免 API Key 的实时语音转写配置【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文面向希望快速为 AIRI 开启实时语音输入的开发者与使用者。AIRI 官方语音识别以你的 AIRI 登录状态作为唯一凭证无需单独申请或填写任何第三方 API Key即可在设置 → 服务商 → 语音识别中选择官方提供方并在设置 → 听觉中启用实时转写。读完本文你将掌握官方 ASR/STT 的完整启用流程、模型选择Auto自动路由、麦克风与 VAD 参数调优以及常见故障的排查方法并了解这一功能在仓库源码中的真实实现链路。一、官方语音识别的核心设计登录态即凭证与需要手动填入apiKey、baseURL的第三方语音识别服务不同AIRI 官方语音识别官方文档位于 docs/content/zh-Hans/docs/manual/config/providers/transcription/official.md遵循以下两条设计原则复用登录态鉴权请求会携带当前 AIRI 账户的登录令牌Authorization: Bearer token由官方网关统一鉴权与计费零配置开箱即用提供方元数据中requiresCredentials: false、configuredBy: authentication表示该提供方完全不需要用户维护任何密钥类配置。从源码上看这一设计体现在 packages/stage-ui/src/libs/providers/providers/official/index.ts 的providerOfficialTranscription定义中提供方 ID 为official-provider-transcription见 constants.ts 中的OFFICIAL_TRANSCRIPTION_PROVIDER_ID任务声明覆盖speech-to-text、automatic-speech-recognition、asr、stt、streaming-transcription归类为 transcription 类别能力声明capabilities.transcription为protocol: http、generateOutput: false、streamOutput: true、streamInput: true表明官方提供方只走流式转写通道同时支持输入流与输出流不支持一次性文件转写createProvider将转写请求的baseURL直接指向${SERVER_URL}/api/v1/audio/transcriptions/stream并通过withCredentials()包装fetch。withCredentials()的具体实现位于 shared.ts它从认证模块getAuthToken()读取令牌写入Authorization头同时附带当前聊天会话 ID 请求头保证转写请求与对话上下文正确关联。这也解释了为什么官方实时识别依赖当前登录态——令牌过期或未登录时鉴权头缺失请求将无法通过网关。二、第一步登录 AIRI 账户使用官方语音识别前请先完成账户登录使用你的 AIRI 账户完成登录官方实时识别依赖当前登录态登录成功后网关才会签发并接受你的鉴权令牌不需要创建、填写或配置任何第三方 API Key——官方提供方页面中api-key-configured恒为true见 official-provider-transcription.vue即视为已配置状态。⚠️ 账户与音频数据安全 实时识别会将你的音频发送到官方服务处理。请不要使用包含敏感信息的测试音频也不要向他人分享你的账户会话信息。三、第二步在 AIRI 中完成配置配置分两个层面先选中官方转写提供方并确定模型再到听觉模块真正启用语音输入。3.1 选择服务商与模型打开设置 → 服务商 → 语音识别 → AIRI 官方语音识别选择模型为Auto或选择服务端提供的其他模型。关于Auto模型源码中有两点值得说明官方提供方通过extraMethods.listModels固定返回一个模型auto其描述为 Realtime transcription routed by AIRI见 index.ts即模型标识auto表示由官方 AI 网关自动路由到合适的识别模型客户端不做硬编码默认值设置页 official-provider-transcription.vue 中defaultModel auto同样印证了这一点即使不手动选择auto也是官方提供方的默认模型。3.2 在听觉模块启用进入设置 → 听觉在提供方选择卡片中选中AIRI 官方语音识别确认当前激活模型为auto或服务端提供的模型开启音频输入设备并开始实时转写。听觉模块Hearing的设置页实现在 hearing.vue其中你还可以调整以下与官方流式转写强相关的参数参数默认值取值范围说明音频输入设备Audio Input Device系统默认系统可用设备转写数据的麦克风来源模型选择Modelautoauto/ 服务端模型官方提供方由网关路由说话检测灵敏度Sensitivity / VAD Threshold0.60.1–0.9步长0.05VAD 模型判定正在说话的概率阈值停顿判定Pause Before Stop800ms200–1500ms步长50静音持续多久视为一句话结束说话检测方式模型 VAD模型 VAD / 音量检测模型 VAD 更准确音量检测为兜底自动发送Auto-send关闭开关是否自动把转写文本送入对话会消耗 token自动发送延迟2000ms0–10000ms转写结束后延迟多久自动发送其中自动发送与自动发送延迟分别对应 hearing storehearing.ts中的settings/hearing/auto-send-enabled与settings/hearing/auto-send-delay两个持久化配置项autoSendDelay默认 2000ms官方推荐 1000–3000ms 之间开启后转写文本会自动发送到聊天适合免提的实时对话场景但若你希望先人工校对再发送则应保持关闭。四、第三步验证配置允许 AIRI 使用麦克风首次进入听觉模块会触发权限申请见 hearing.vue 的askPermission()点击播放器面板的Start按钮开始音频监控随后说一段短语音若转写文本区域能实时显示文字即表示配置成功。官方转写是流式的验证时你能看到文字随说话过程逐步出现而不是等待整段录音结束这正是capabilities.transcription中streamOutput: true、streamInput: true的实际表现。底层链路为麦克风MediaStream→ VAD 语音活动检测AudioWorklet 切分语音段见 vad-streaming-session.ts→ PCM16 音频流经/api/v1/audio/transcriptions/stream送入官方服务 → 转写增量文本逐字回调刷新界面。在 hearing.ts 的STREAM_TRANSCRIPTION_EXECUTORS中official-provider-transcription被映射到streamTranscription执行器最终由 stream-transcription/index.ts 完成流式请求与增量结果解析。五、常见问题排查官方文档给出的排查要点如下结合源码可以进一步定位1. 模型无法使用确认账户已登录登录态是唯一凭证令牌缺失时网关会拒绝请求确认网络正常浏览器控制台 Network 面板中若出现Failed to fetch/Load failed多为 CORS、超时或 DNS 问题hearing.ts 专门对这些浏览器通用错误给出了提示确认账户有可用额度官方识别走账户计费额度用尽或欠费时服务不可用。2. 没有文字结果检查系统麦克风权限是否已授予 AIRI权限被拒会映射为permission_denied错误码见 hearing.ts检查音频输入设备是否正确选择——未选择任何输入设备时监控按钮会处于禁用状态尝试调整 VAD 灵敏度阈值过高可能把说话误判为静音与停顿判定时长说话时留意Speaking Detected / Silence指示与音量电平表确认音频确实进入了采集链路。3. 转写结果为空但无报错官方提供方不支持verbose_json段级置信度过滤generateOutput: false若你在听觉模块中开启了置信度阈值过滤应确认该提供方下该选项不生效如需该能力可考虑支持文件转写的其他提供方。六、进阶官方转写与第三方方案的差异在 AIRI 的语音识别提供方生态中完整目录见 packages/stage-pages/src/pages/settings/providers/transcription/官方提供方与阿里云 NLS、OpenAI Audio、本地 Whisper 等方案的关键差异可总结为维度AIRI 官方语音识别第三方提供方凭证仅需登录态需各自 API Key模型选择auto自动路由需手动指定模型转写方式流式stream input/output多数为文件/流式混合适用场景快速启用、免密钥实时语音输入定制模型、自有密钥管理如你已在使用 AIRI 官方提供商聊天/语音等且想先快速启用实时语音输入官方语音识别是最优先尝试的选项——无需新增任何密钥登录即用。若需要进一步了解听觉模块的整体架构、VAD 分段的实现细节或希望为官方转写编写自动化验证可继续阅读 hearing.ts、hearing.test.ts 以及流式转写消费方测试 streaming-transcription-consumers.test.ts。【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考