企业官网建设流程全解析

AIRI 官方 TTS 配置指南：免第三方密钥的语音合成与可选流式合成

【免费下载链接】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 内置的 Official Speech Provider（官方语音合成）允许已登录 AIRI 账号的用户直接使用官方服务的 TTS 能力，无需配置任何第三方 API Key。本文基于 AIRI 仓库中的韩语官方文档，完整覆盖"登录账号 → 配置提供器 → 选择模型与音色 → 试听验证 → 启用流式 TTS"的实操流程，并结合 官方提供器源码 与 音频 WebSocket 代理 的实现，说明其背后的认证、目录发现与自动音色选择机制。

官方语音合成提供器是什么

"官方语音合成"使用当前激活的 AIRI 会话完成语音合成，因此不需要填写任何第三方凭据。这一点在源码中有直接体现：providerOfficialSpeech 定义 中requiresCredentials为false，configuredBy为'authentication'——即该提供器的"已配置"状态完全由账号登录状态驱动，而不是由用户填写的 Key 驱动。

提供器 ID 统一收敛在 constants.ts 中：

• official-provider-speech：HTTP 形式的官方 TTS 提供器（对应文档中的Official Speech Provider）
• official-provider-speech-streaming：低延迟双向 WebSocket 流式 TTS 提供器（对应文档中的Official Streaming Speech Provider）
• 此外还有official-provider（文本生成）与official-provider-transcription（实时转写），与语音合成共用同一套认证体系

如果当前已经在用官方 AIRI 提供器，并且希望减少第三方凭据的维护成本，官方建议优先尝试这个官方 TTS 选项。需要注意的边界是：可用模型、配额（Flux 余额）与地区可用性由官方服务决定，客户端只是透传服务端返回的目录。

第一步：登录 AIRI 账号

按照文档的操作顺序：

1. 使用 AIRI 账号登录（桌面端或 Web 端均可，登录后获得会话 Token）。
2. 确认当前会话可以使用官方语音合成提供器。

登录状态会直接决定设置页的形态。在 official-provider-speech.vue 中，页面从 auth store 读取isAuthenticated：未登录时只显示一个引导登录的 Callout 卡片和登录按钮；已登录时则展示 Flux 余额与"状态正常"的绿色脉冲指示灯。也就是说，登录成功本身即为该提供器的可用性验证，无需像第三方提供器那样单独做 Key 校验（validationRequiredWhen恒返回false）。

账号与服务的注意事项（原文档 warning）：可用模型、配额与地区由官方服务决定；不要共享账号会话或浏览器会话数据。从源码看，客户端请求携带Authorization: Bearer <token>（见 authHeaders 与 withCredentials），会话 Token 等价于账号凭证，共享它等于共享账号。

第二步：在 AIRI 中配置官方 TTS

进入设置 → 提供器 → 语音合成 → Official Speech Provider。该页面的行为与源码一一对应：

• 登录提示：若未登录，页面显示登录引导（t('settings.dialogs.onboarding.loginPrompt')），点击按钮触发登录流程。
• Flux 余额：登录后页面顶部展示当前 Flux 余额（credits），余额数据来自账号服务；若未禁用购买，还会显示一个"购买 Flux"的按钮，跳转到设置 → Flux页面。
• 连接状态：已登录即显示"状态正常"（settings.pages.providers.provider.common.status.valid），表明当前会话与官方服务连通。

底层调用链是：提供器的listModelCatalog向GET /api/v1/audio/models发起带认证头的请求，服务端返回models数组与default默认模型；客户端把默认模型复制到目录中，保证新用户可以直接选中服务端推荐值。音色目录则通过GET /api/v1/audio/voices?model=<当前模型>拉取——注意这个端点是按模型作用域的：服务端只对当前生效模型返回合法音色，因此客户端刻意丢弃了响应中的compatible_models字段，避免二次过滤在路由 ID 不一致时把列表清空（源码注释中专门说明了这一决策，位于 index.ts 的 listVoices）。

第三步：验证设置并测试语音

1. 打开设置 → 模块 → 语音合成，选择Official Speech Provider，然后从可用的模型与音色列表中做选择。
2. 输入一段简短的测试文本，点击Test Voice，确认 AIRI 能生成并回放音频。

这一页的选择结果会持久化到本地存储（settings/speech/active-provider、settings/speech/active-model、settings/speech/voice），由 speech store 管理；在多窗口/多渲染进程环境下，目录加载与选择提交都路由到"leader"进程统一执行，防止快照互相覆盖。

两个值得了解的自动化细节：

• 默认模型自动补齐：当提供器有目录但当前没有有效模型选择时，ensureActiveSpeechModel会自动选中服务端default（或列表第一个），并清空旧音色重新走自动选色，避免用户停留在无效组合上。
• 音色自动推荐：登录后的首次选择由pickOfficialSpeechVoice完成，其回退顺序为：当前语言精确匹配的服务端推荐音色 → 同语言前缀的推荐音色 → 该模型任意推荐音色 → 说目标语言的第一个音色 → 英语音色（en-US 优先）→ 列表首个音色。这套分层回退保证了自动选色不会把用户丢进毫无关联的音色（例如字母序靠前的南非英语音色）。

可选：启用官方流式 TTS 提供器

当官方服务通知当前账号可用流式 TTS 时，AIRI 会在设置 → 提供器 → 语音合成下额外显示一张Official Streaming Speech Provider卡片。源码中这一"服务端驱动可见性"有明确实现：official-provider-speech-streaming.vue 在认证后请求/api/v1/audio/models/streaming，根据响应中的available字段调用setProviderAvailabilityOverride——不可用时把提供器置为未配置（隐藏卡片），可用时强制标记为已配置。模型目录完全由运维侧通过UNSPEECH_UPSTREAM.streaming配置项控制，客户端没有任何硬编码默认值，新增后端不需要发 UI 版本。

使用时的关键规则（原文档原文要求）：

• 设置 → 模块 → 语音合成中保持选择Official Speech Provider即可；
• 该提供器的模型列表会包含流式模型；当选择了流式模型与对应音色后，AIRI 会自动把内部语音合成提供器切换到所选模型匹配的流式通道。

从实现看，流式提供器通过capabilities: { speech: { transport: 'bidirectional-ws' } }声明自己走双向 WebSocket 协议（而非 REST），会话层据此分发到streamingSynthesize；请求最终经由服务端/api/v1/audio/speech/ws代理桥接到上游。该代理在 audio-speech-ws/index.ts 中实现：路由层先通过?token=查询参数完成认证并解析出userId，客户端先发送start控制帧声明流式模型与音色，会话在校验通过后才拨号上游（当前为 Volcengine v3），每条连接对应一个独立的会话闭包，无全局对端注册表。同时，createProvider仍返回 OpenAI 形状的.speech()实现，保证 WebSocket 通道出错时 REST/v1/audio/speech的旧路径可以继续兜底。

Flux 余额与购买

文档提到"确认账号 Flux 是否充足"，Flux 是官方服务的计量单位：

• 提供器卡片与设置 → Flux页面均可查看可用套餐；服务端对应 flux 路由，并通过 Stripe 完成套餐结算。
• 桌面版会调用系统浏览器打开支付页面；如果当前构建或部署环境不支持购买，购买选项不会显示。该开关在 env-vars.ts 中由VITE_DISABLE_FLUX_PURCHASE控制（isFluxPurchaseDisabled()），设置页据此渲染或隐藏购买按钮，属于部署侧的环境变量约定，默认未设置时购买入口正常显示。

问题排查

按照文档给出的排查顺序：

1. 确认已登录：未登录时官方提供器所有能力都不可用（requiresCredentials: false不代表无需会话，而是"认证即配置"）。
2. 确认 AIRI 能访问官方服务：模型/音色目录请求失败时，客户端会把上游状态码与响应体摘要（截断到 256 字符）抛出，例如audio models upstream <status>；网络受限环境会出现此类错误。
3. 确认 Flux 余额：打开设置 → Flux查看可用套餐；余额不足时合成请求会被服务端拒绝。
4. 购买入口缺失：若部署环境通过VITE_DISABLE_FLUX_PURCHASE禁用了购买，界面上不会出现购买选项，需联系部署方或改用已有余额。

源码索引

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