企业官网建设流程全解析

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-sama's 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）遵循以下两条设计原则：

1. 复用登录态鉴权：请求会携带当前 AIRI 账户的登录令牌（Authorization: Bearer <token>），由官方网关统一鉴权与计费；
2. 零配置开箱即用：提供方元数据中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 账户

使用官方语音识别前，请先完成账户登录：

1. 使用你的 AIRI 账户完成登录；官方实时识别依赖当前登录态，登录成功后网关才会签发并接受你的鉴权令牌；
2. 不需要创建、填写或配置任何第三方 API Key——官方提供方页面中api-key-configured恒为true（见 official-provider-transcription.vue），即视为"已配置"状态。

⚠️ 账户与音频数据安全 实时识别会将你的音频发送到官方服务处理。请不要使用包含敏感信息的测试音频，也不要向他人分享你的账户会话信息。

三、第二步：在 AIRI 中完成配置

配置分两个层面：先选中官方转写提供方并确定模型，再到"听觉"模块真正启用语音输入。

3.1 选择服务商与模型

1. 打开设置 → 服务商 → 语音识别 → AIRI 官方语音识别；
2. 选择模型为Auto，或选择服务端提供的其他模型。

关于Auto模型，源码中有两点值得说明：

• 官方提供方通过extraMethods.listModels固定返回一个模型auto，其描述为 "Realtime transcription routed by AIRI"（见 index.ts），即模型标识auto表示由官方 AI 网关自动路由到合适的识别模型，客户端不做硬编码默认值；
• 设置页 official-provider-transcription.vue 中defaultModel = 'auto'同样印证了这一点：即使不手动选择，auto也是官方提供方的默认模型。

3.2 在"听觉"模块启用

1. 进入设置 → 听觉；
2. 在提供方选择卡片中选中AIRI 官方语音识别；
3. 确认当前激活模型为auto（或服务端提供的模型）；
4. 开启音频输入设备并开始实时转写。

听觉模块（Hearing）的设置页实现在 hearing.vue，其中你还可以调整以下与官方流式转写强相关的参数：

其中"自动发送"与"自动发送延迟"分别对应 hearing store（hearing.ts）中的settings/hearing/auto-send-enabled与settings/hearing/auto-send-delay两个持久化配置项：autoSendDelay默认 2000ms，官方推荐 1000–3000ms 之间；开启后转写文本会自动发送到聊天，适合免提的实时对话场景，但若你希望先人工校对再发送，则应保持关闭。

四、第三步：验证配置

1. 允许 AIRI 使用麦克风（首次进入听觉模块会触发权限申请，见 hearing.vue 的askPermission()）；
2. 点击播放器面板的Start按钮开始音频监控，随后说一段短语音；
3. 若"转写文本"区域能实时显示文字，即表示配置成功。

官方转写是流式的，验证时你能看到文字随说话过程逐步出现而不是等待整段录音结束，这正是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 官方提供商（聊天/语音等），且想先快速启用实时语音输入，官方语音识别是最优先尝试的选项——无需新增任何密钥，登录即用。若需要进一步了解听觉模块的整体架构、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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi