AIRI 官方语音提供商(TTS)接入指南:登录即用的语音合成与低延迟流式方案 人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载本文以 AIRI 官方文档 docs/content/en/docs/manual/config/providers/speech/official.md 为骨架结合仓库源码完整讲解 AIRI「官方语音提供商Official Speech Provider」的登录、配置、试听验证与故障排查全流程并深入剖析其底层实现无第三方 API Key 的鉴权方式、Flux 余额计费体系以及基于双向 WebSocket 的官方流式 TTS 提供商的模型合并与自动切换机制。读完本文你将能够独立完成 AIRI 官方 TTS 的接入并理解设置页背后每一处状态与接口的来龙去脉。什么是官方语音提供商AIRI 的官方语音合成TTS直接复用你正在使用的 AIRI 会话不需要配置任何第三方 API Key。官方文档明确指出其适用场景如果你已经在使用 AIRI 官方 provider希望减少第三方凭据的配置负担应优先尝试这一选项。在源码层面这一特性由两个前端 provider 定义承载位于 packages/stage-ui/src/libs/providers/providers/official/index.tsproviderOfficialSpeechOFFICIAL_SPEECH_PROVIDER_ID official-provider-speechHTTP 形态的官方 TTS任务类型text-to-speechproviderOfficialSpeechStreamingOFFICIAL_SPEECH_STREAMING_PROVIDER_ID official-provider-speech-streaming低延迟双向 WebSocket 流式 TTS。两者的共同特征是requiresCredentials: false、configuredBy: authentication——即**「登录即配置」**无需像第三方提供商那样手动填写 API Key配置状态完全由账号会话驱动。标识常量定义在 packages/stage-ui/src/libs/providers/providers/official/constants.ts。第一步登录你的 AIRI 账号使用 AIRI 账号登录确认当前会话可用的官方语音提供商。⚠️ 账号与服务可用性可用模型、配额与区域均由官方服务决定。请勿共享账号会话或浏览器会话数据。从设置页源码可以看到未登录状态下页面会直接渲染登录引导卡片而不是配置表单——见 packages/stage-pages/src/pages/settings/providers/speech/official-provider-speech.vue 中的v-if!isAuthenticated分支页面通过useAuthStore的isAuthenticated状态判断是否已登录未登录时仅展示登录提示与「登录」按钮触发needsLogin true不会向服务端发起任何受保护的目录请求。这一点同样被浏览器测试覆盖does not request the protected catalog before authentication见 apps/stage-web/src/pages/official-provider-speech-streaming.browser.test.ts确保未认证时不发送受保护接口请求。第二步在 AIRI 中配置官方语音提供商打开Settings → Providers → Speech → Official Speech Provider如提示则完成登录确认页面显示你的Flux 余额与有效连接状态。登录成功后设置页official-provider-speech.vue会渲染两个关键区块Flux 余额卡片从authStore读取credits并展示同时带有一个「购买 Flux」Buy Flux按钮点击后跳转到/settings/flux页面连接状态一个绿色脉冲圆点 「Valid」状态文本表示当前账号对官方语音服务的鉴权有效。关于「购买」按钮的显示条件值得展开说明。按钮仅在!fluxPurchaseDisabled时为真而isFluxPurchaseDisabled()的实现位于 packages/stage-shared/src/env-vars.tsexport function isFluxPurchaseDisabled(): boolean { return isEnvTruthy(import.meta.env.VITE_DISABLE_FLUX_PURCHASE) }也就是说构建或部署时若设置了环境变量VITE_DISABLE_FLUX_PURCHASE可取true/1/yes/on等真值购买入口会被隐藏。这正是官方文档中「如果构建或部署不支持购买则不会出现购买选项」的代码级依据。购买流程页面在 packages/stage-pages/src/pages/settings/flux.vueDesktop 版本会在系统浏览器中打开结账页面。第三步验证配置模型 / 音色 / 试听打开Settings → Modules → Speech选择Official Speech Provider并挑选一个可用模型与音色输入一句简短的测试文本点击Test Voice测试语音确认 AIRI 能播放生成的音频。语音模块页面的实现位于 packages/stage-pages/src/pages/settings/modules/speech.vue其核心交互逻辑值得逐层解读音源选择selectableSpeechSources会过滤掉speech-noop与official-provider-speech-streaming把流式提供商隐藏为普通可选源用户界面上只呈现Official Speech Provider一个入口通过displayedSpeechSource计算属性将流式提供商映射回官方提供商 ID 显示。模型列表合并当选中官方语音源时displayedProviderModels会把普通模型与流式模型合并展示流式模型以streaming:前缀标记STREAMING_MODEL_OPTION_PREFIX streaming:并通过streamingModelOptionId/modelIdFromStreamingOptionId两个函数在展示 ID 与真实模型 ID 之间互转。自动切换内部提供商当用户选中一个streaming:前缀的模型时selectSpeechModel会把nextProvider设为OFFICIAL_SPEECH_STREAMING_PROVIDER_ID并把nextModel设为去掉前缀后的真实模型 ID反过来如果当前是流式提供商而用户选回了普通模型则自动切回OFFICIAL_SPEECH_PROVIDER_ID。这印证了官方文档中「AIRI 会自动切换内部语音提供商以匹配所选模型」的描述。试听generateTestSpeech通过generateSpeech来自 xsai调用当前 provider 的.speech(model, config)拿到音频后用URL.createObjectURL生成可播放地址测试文本默认是Hello, my name is AI Assistant同时支持useSSML切换到原始 SSML 输入。额外控制项试听区下方还有Pitch音高调节范围-100100步长 1与Enable SSML开关可对语音输出做进一步微调。另外官方语音提供商在登录后会自动为当前 UI 语言挑选一个推荐音色pickOfficialSpeechVoice同文件 official/index.ts实现了「服务端推荐音色 → 语言前缀匹配 → 英文兜底 → 字母序第一个」的多层回退策略且仅在官方语音提供商HTTP 流式上自动执行第三方提供商仍由用户手动选择音色。可选的流式语音提供商低延迟双向 WebSocket当官方服务报告流式 TTS 可用时AIRI 会在Settings → Providers → Speech下额外显示一张独立的Official Streaming Speech Provider卡片。在Settings → Modules → Speech中保持Official Speech Provider处于选中状态AIRI 会把流式模型并入该提供商的模型列表中。选择某个流式模型与音色后内部语音提供商即自动切换为流式实现。流式模型的命名与可用性判断流式模型 ID 采用backend/resource形式例如volcengine/seed-tts-2.0。这一格式在流式设置页源码 packages/stage-pages/src/pages/settings/providers/speech/official-provider-speech-streaming.vue 的handleGenerateSpeech中有严格校验模型 ID 必须包含/否则直接拒绝Streaming model id missing backend prefix斜杠后的部分作为api_resource_id透传给上游。试听时通过streamingSynthesize发送并附带extraBodyextraBody: { api_resource_id: apiResourceId, audio: { sample_rate: 24000, bit_rate: 64000 }, },其中 24 kHz 采样率、64 kbps 码率是与实际聊天运行时相同的音频参数——设置页试听走的正是运行时管线同一条链路因此试听结果能忠实反映真实对话中的听感源码注释原话the preview faithfully represents what the user hears in actual chat。流式提供商是否可用完全由服务端目录接口决定客户端不做任何硬编码默认值前端listStreamingModelCatalog请求/api/v1/audio/models/streaming读取available、models、default三个字段见 official/index.ts服务端对应实现listStreamingSpeechModelsserver/apps/api/src/routes/openai/v1/operations/speech-catalog/index.ts读取configKV中的UNSPEECH_UPSTREAM.streaming配置available即!!unspeech?.streaming?.baseURLmodels为运维预置的模型列表default为服务端默认模型。因此流式卡片是否出现、默认选哪个模型均由服务端运维通过UNSPEECH_UPSTREAM.streaming控制新增 ICL 等后端无需发版客户端。流式会话的底层工作流流式 TTS 的完整链路是「ws → API 代理 → unspeech 桥接 → 上游当前为 Volcengine v3 双向」。关键实现客户端streamingSynthesizepackages/stage-ui/src/libs/speech/streaming-session.ts拼接带 token 的 WebSocket 地址/api/v1/audio/speech/ws连接成功后发送start帧含model、voice、extraBody随后发送text帧收到session.finished后拼接返回全部音频支持cancel帧与 AbortSignal 中止。服务端路由工厂createAudioSpeechWsHandlersserver/apps/api/src/routes/audio-speech-ws/index.ts为每个连接创建一个独立的会话状态机server/apps/api/src/routes/audio-speech-ws/session.ts核心步骤包括校验首个start帧读取UNSPEECH_UPSTREAM.streaming配置并解密上游 key计费预检以STREAMING_PREFLIGHT_CHARS_ESTIMATE 2000字符的悲观估算调用speechBilling.assertCanAfford余额不足时以关闭码1008insufficient_flux拒绝连接客户端据此弹出「充值」提示在向上游拨号期间缓冲客户端帧上游 OPEN 后按到达顺序冲刷音频二进制帧原样透传cancel帧与客户端断连时向终止上游会话。运行时的管线在聊天场景中长文本流通过streamSpeechpackages/stage-ui/src/libs/speech/streaming-pipeline.ts把 LLM 文本流按句喂给 WebSocket 会话。该管线支持bufferEntireSession选项对 Seed-TTS 2.0 这类「字幕异步到达、无法按sentence.end切分」的模型会把整段音频缓冲到会话结束再一次性输出而 Seed-TTS 1.0 / ICL 1.0 则在每个sentence.end处按句输出。浏览器测试 official-provider-speech-streaming.browser.test.ts 还验证了流式设置页的几个关键行为未认证不请求受保护目录先应用服务端默认模型再加载音色动作顺序configured → voices目录发现失败时保留既有配置状态而不误标为未配置。故障排查官方文档给出了三条排查主线确认已登录provider 的配置状态完全依赖账号会话configuredBy: authentication未登录时设置页只会显示登录卡片不会触发任何目录请求确认网络可达AIRI 能正常访问官方服务。模型 / 音色目录均从服务端接口拉取/api/v1/audio/models、/api/v1/audio/voices?model...、流式对应/api/v1/audio/models/streaming与/api/v1/audio/voices/streaming若接口 502 / 503前端会显示明确的加载错误且不会把「发现失败」误判为「服务不可用」而清掉既有配置确认 Flux 余额充足打开Settings → Flux查看可用套餐。HTTP TTS 与流式 TTS 都会消耗 Flux流式会话在拨号上游前会做余额预检不足时以insufficient_flux拒绝Desktop 版本会在系统浏览器中打开结账页若构建/部署设置了VITE_DISABLE_FLUX_PURCHASE则不显示购买入口。另外服务端音色目录listVoices要求必须携带?model参数空参数返回 400auto别名表示回退到DEFAULT_TTS_MODELUI 侧总是显式传入当前模型 ID 或auto音色推荐映射存放在configKV的DEFAULT_TTS_VOICES中运维可在不部署的情况下调整各语言的默认音色。关键文件索引官方文档docs/content/en/docs/manual/config/providers/speech/official.mdProvider 定义与音色自动选择packages/stage-ui/src/libs/providers/providers/official/index.tsProvider ID 常量packages/stage-ui/src/libs/providers/providers/official/constants.ts官方 TTS 设置页 / 流式设置页official-provider-speech.vue / official-provider-speech-streaming.vue语音模块模型合并 / 试听 / 自动切换packages/stage-pages/src/pages/settings/modules/speech.vue服务端语音目录接口server/apps/api/src/routes/openai/v1/operations/speech-catalog/index.ts流式 TTS WebSocket 网关server/apps/api/src/routes/audio-speech-ws/index.ts 与会话状态机 session.ts客户端流式会话 / 管线streaming-session.ts / streaming-pipeline.ts购买开关环境变量packages/stage-shared/src/env-vars.ts端到端浏览器测试apps/stage-web/src/pages/official-provider-speech-streaming.browser.test.ts赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐Orpheus-TTS实时流式语音生成实现200ms超低延迟的语音合成终极指南Orpheus TTS实时流式语音生成实现200ms超低延迟的语音合成终极指南 Orpheus TTS是一款革命性的开源文本转语音系统基于Llama 3b架语音音频大模型模型推理服务AIRI 语音合成接入指南配置 ElevenLabs TTS 服务商与音色调试AIRI 语音合成接入指南配置 ElevenLabs TTS 服务商与音色调试 本文以 AIRI 自托管 AI 伴侣项目的语音合成模块为背景完整讲解如何接入人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端实时游戏语音革命Spark-TTSUnity低延迟合成方案实时游戏语音革命Spark TTSUnity低延迟合成方案 你还在为游戏角色语音僵硬、延迟高而烦恼吗传统语音合成方案要么音质差要么延迟高难以满足开放世人工智能语音音频大模型模型推理服务上一篇终极dedupe最佳实践避免8个常见陷阱的完整指南下一篇Crafting Interpreters中文版实战案例构建你自己的脚本语言终极指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考