企业官网建设流程全解析

AIRI 语音输入输出配置实战：TTS 语音合成与 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 的语音能力分为语音合成（TTS，将 AI 回复朗读出来）与语音识别（ASR/STT，将麦克风音频转成文本）两条独立链路，二者可以分别配置、互不影响。本文以官方配置手册 audio.md 为主线，结合仓库中 Settings 页面（speech.vue、hearing.vue）的源码实现，完整讲解从 Provider 填凭据、Playground 试听到 Module 启用声音/听力的全部流程，并给出常见故障的排查路径，读完即可在 Web / 桌面端把 AIRI 的语音对话跑通。

语音配置的两层架构：Provider 与 Module

AIRI 的语音配置遵循"先配 Provider、再启 Module"的两段式设计，这与整个设置体系（见 Common Configuration Instructions）保持一致：

• Provider 层（Settings → Providers → Speech / Transcription）：负责录入服务商的 API Key、Base URL、Region 等凭据，并支持自动校验与 Playground 试听；
• Module 层（Settings → Modules → Speech / Hearing）：负责从已配置的 Provider 中挑选当前生效的模型与音色，真正把能力挂到 AIRI 的回复管线（Speech）或麦克风输入管线（Hearing）上。

这样设计的好处是：一个 Provider 凭据可以被反复测试、随时切换，而不用改动底层配置；同时 TTS 与 ASR/STT 互不耦合，你可以用云端 TTS 配本地 Web Speech API 识别，也可以反过来组合。

配置语音合成（TTS）

按照 audio.md 的流程，启用语音合成分三步：

1. 打开Settings → Providers → Speech，选择一个 Provider 并填入其凭据（API Key 等）；
2. 在 Provider 页面自带的playground（如果可用）中输入一句短测试句，试听合成效果；
3. 打开Settings → Modules → Speech，选择刚配置好的 Provider、模型与音色。

第 2 步的 Playground 试听只验证 Provider 是否连通，并不会自动把该 Provider 用于正常回复——必须在第 3 步的 Module 页显式选中，这与 ElevenLabs 指南中的明确说明一致："The playground test alone does not enable the provider for normal replies"。

Speech Provider 一览

仓库docs/content/en/docs/manual/config/providers/speech/目录下收录了以下 TTS Provider 指南：

注意后两项：browser-local与desktop-local两个 Provider 页面明确标注 Unavailable，官方建议在生产配置中跳过，改用 Kokoro（AIRI 已实现的本地合成）或任意云 TTS。

关键字段：API Key、Base URL、Model、Voice

Provider 表单中最常见的四个字段（详见 common.md 的字段表）：

• API Key：服务商签发的访问令牌，粘贴完整 Key，不要多带引号、空格或换行；
• Base URL：服务商 API 根地址，仅当服务商文档明确要求时才改动，需包含完整的https://或http://前缀；
• Model：用于合成/识别的模型 ID，优先从 AIRI 的模型列表中选择；若列表加载失败且字段支持自定义输入，可精确填入服务商文档中的 ID；
• Voice：合成所用的音色 ID，先选 Model 再选 Voice，因为音色必须由该模型支持。

以 ElevenLabs 为例还有一个特殊点：其默认 Base URL 是 AIRI/UnSpeech 网关https://unspeech.hyp3r.link/v1/，而不是 ElevenLabs 直连地址——你的 Key、合成文本与音频都会经过该网关，仅在你能接受这一信任边界时使用；否则应填入自托管网关地址或改选直连的 Provider。

使用 OpenAI 兼容接口接入 TTS

如果你的语音服务实现了 OpenAI speech API，优先参考 OpenAI Compatible API (TTS)：

1. 打开Settings → Providers → Speech → OpenAI Compatible；
2. 填入 API Key 与要使用的 TTS 模型 ID，按需调整语速；
3. 注意：OpenAI Compatible 没有默认 Base URL，必须完整填写兼容服务文档给出的 API 根地址；官方 OpenAI 则应选择独立的OpenAIProvider。

⚠️ 兼容性判断：/v1结尾的地址或sk-开头的 Key本身不保证OpenAI speech API 兼容，务必以服务商文档为准。

配置完成后，回到Settings → Modules → Speech选中 Provider、模型、音色，输入测试文本点击Test Voice，能听到音频即配置成功。

源码印证：Speech 模块页的实现

Modules 层的 Speech 页面实现位于 packages/stage-pages/src/pages/settings/modules/speech.vue，从源码可以看到几个与手册对应的实际细节：

• 页面内置了试听逻辑，默认测试文本为Hello, my name is AI Assistant（testTextref），并调用generateSpeech（来自@xsai/generate-speech）生成音频后用<audio>播放；
• 除 Provider / Model / Voice 三项选择外，还提供pitch（音高）调节、SSML开关（ssmlEnabled/useSSML）、VoiceCardManySelect音色卡片选择、模型搜索（modelSearchQuery）等字段；
• 页面区分"已配置的语音来源"与全部 Provider 元数据（moduleSpeechProvidersMetadata/allAudioSpeechProvidersMetadata），只有被正确配置的 Provider 才会出现在 Module 可选列表里——这正是"Provider 配好后 Module 才能选到"的底层原因。

配置语音识别（ASR/STT）

语音识别按照 audio.md 分为四步：

1. 打开Settings → Providers → Transcription，选择 Provider 并录入凭据；
2. 打开Settings → Modules → Hearing，选择已配置的 Provider 与模型；
3. 选择正确的麦克风，点击Start Monitoring（开始监听），说一句简短的话；
4. 在识别结果区域确认文本是否正确显示。

Transcription Provider 一览

docs/content/en/docs/manual/config/providers/transcription/目录收录了以下 ASR/STT Provider：

其中 Web Speech API 是快速体验语音输入的最简方案：它调用浏览器内置的语音识别，不需要任何 Key。配置时在Settings → Providers → Transcription → Web Speech API选择Recognition Language（识别语言），并可开启Continuous Recognition（连续识别）与Show Interim Results（显示中间结果）。注意该 Provider仅存在于 Web 版，Electron 桌面版不提供，且识别质量会随浏览器、网络环境与语言不同而变化。

使用 OpenAI 兼容接口接入 ASR/STT

与 TTS 同理，若转录服务实现 OpenAI transcription API，按 OpenAI Compatible API (ASR/STT) 配置：

1. 打开Settings → Providers → Transcription → OpenAI Compatible；
2. 填入 API Key 与 ASR/STT 模型 ID；
3. 该 Provider 同样没有默认 Base URL，需完整填写兼容服务的 API 根地址；官方 OpenAI 请选择独立的OpenAIProvider。

验证时回到Settings → Modules → Hearing，选中 Provider 与模型、选择音频输入设备，点击Start Monitoring后对着麦克风说话或播放一段音频，转录区出现文本即成功；若识别不准，可调整灵敏度后重试。

源码印证：Hearing 模块页的实现

Hearing 页面实现在 packages/stage-pages/src/pages/settings/modules/hearing.vue，其源码细节与手册高度吻合：

• 页面通过useSettingsAudioDevice的askPermission/startStream/stopStream管理麦克风权限与媒体流，并配合useAudioAnalyzer显示实时音量电平（volumeLevel）——"无文本时先查麦克风权限"正是由此而来；
• Start Monitoring 背后是完整的语音活动检测（VAD）管线：页面暴露了useVADThreshold（默认 0.6，范围 0.1–0.9）、useVolumeThreshold（默认 10，范围 1–80）、useVADMinSilenceDurationMs（默认 800ms），并可在 VAD 模型与基于音量检测两种模式间切换；
• 识别结果以segment（片段）形式逐段呈现，每段有recording / transcribing / complete / empty / error等状态，空片段与失败片段分别显示"无语音"与"转录失败"提示，对应 hearing-playground-segment.vue 中的实现；
• 支持流式输入（supportsStreamInput）、置信度阈值（confidenceThreshold，可禁用）、识别文本自动发送（autoSendEnabled/autoSendDelay）等进阶选项。

常见故障排查（FAQ）

TTS 没有声音

1. 确认Settings → Modules → Speech中已选中 Speech Provider、模型和音色（Playground 试听成功不代表 Module 已启用）；
2. 检查系统输出设备与音量；
3. 若 Playground 报错，检查 API Key、账号余额/额度与模型能力（部分模型不支持目标音色或语言）。

ASR 识别不出文本

1. 确认 AIRI 拥有麦克风权限，且 Hearing 页选择了正确的输入设备（源码中对应askPermission与selectedAudioInput）；
2. 实时识别服务场景下，网络中断或浏览器/系统撤销麦克风权限同样会导致结果为空；
3. 若使用 Web Speech API，还需确认浏览器支持该 API 且识别语言设置正确。

语言或音色不正确

• 选择 Provider 对目标语言支持的模型与音色（先选模型、再选音色）；
• 转录的语言、区域（Region）与模型设置，必须与 Provider 账号开通的能力一致——Region 需与云服务商控制台中的项目/资源区域对应，见 common.md。

通用校验逻辑与下一步

Provider 配置是否成功可依以下顺序验证（来自 common.md 的 Verification results 小节）：

• Chat/语音类 Provider 表单会自动校验必填字段，暴露Ping API的 Provider 可发送实时请求（可能消耗少量额度）；
• Speech Provider 用 Playground 试听合成；Transcription 则在 Hearing 页用所选麦克风实测。

验证失败时按顺序排查：确认账号有服务权限与额度 → 重新复制 API Key（避免头尾空格/换行）→ 恢复默认 Base URL 或与服务商文档逐字比对 → 确认网络/代理/防火墙可达 → 改用 Provider 明确支持的模型（不要把显示名当模型 ID）。

进一步深入学习：字段与校验细节见 Common Configuration Instructions；Provider 专属指南在Providers → Speech与Providers → Transcription目录下按需查阅。

【免费下载链接】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