企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本文以 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.ts：

• providerOfficialSpeech（OFFICIAL_SPEECH_PROVIDER_ID = 'official-provider-speech'）：HTTP 形态的官方 TTS，任务类型text-to-speech；
• providerOfficialSpeechStreaming（OFFICIAL_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 账号

1. 使用 AIRI 账号登录；
2. 确认当前会话可用的官方语音提供商。

⚠️ 账号与服务可用性：可用模型、配额与区域均由官方服务决定。请勿共享账号会话或浏览器会话数据。

从设置页源码可以看到，未登录状态下页面会直接渲染登录引导卡片，而不是配置表单——见 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 中配置官方语音提供商

1. 打开Settings → Providers → Speech → Official Speech Provider；
2. 如提示则完成登录；
3. 确认页面显示你的Flux 余额与有效连接状态。

登录成功后，设置页（official-provider-speech.vue）会渲染两个关键区块：

• Flux 余额卡片：从authStore读取credits并展示，同时带有一个「购买 Flux」（Buy Flux）按钮，点击后跳转到/settings/flux页面；
• 连接状态：一个绿色脉冲圆点 + 「Valid」状态文本，表示当前账号对官方语音服务的鉴权有效。

关于「购买」按钮的显示条件，值得展开说明。按钮仅在!fluxPurchaseDisabled时为真，而isFluxPurchaseDisabled()的实现位于 packages/stage-shared/src/env-vars.ts：

export 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.vue；Desktop 版本会在系统浏览器中打开结账页面。

第三步：验证配置（模型 / 音色 / 试听）

1. 打开Settings → Modules → Speech，选择Official Speech Provider，并挑选一个可用模型与音色；
2. 输入一句简短的测试文本，点击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音高调节（范围-100～100，步长 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发送，并附带extraBody：

extraBody: { 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）；
• 服务端对应实现listStreamingSpeechModels（server/apps/api/src/routes/openai/v1/operations/speech-catalog/index.ts）读取configKV中的UNSPEECH_UPSTREAM.streaming配置：available即!!unspeech?.streaming?.baseURL，models为运维预置的模型列表，default为服务端默认模型。

因此，流式卡片是否出现、默认选哪个模型，均由服务端运维通过UNSPEECH_UPSTREAM.streaming控制，新增 ICL 等后端无需发版客户端。

流式会话的底层工作流

流式 TTS 的完整链路是「ws → API 代理 → unspeech 桥接 → 上游（当前为 Volcengine v3 双向）」。关键实现：

1. 客户端：streamingSynthesize（packages/stage-ui/src/libs/speech/streaming-session.ts）拼接带 token 的 WebSocket 地址/api/v1/audio/speech/ws，连接成功后发送start帧（含model、voice、extraBody），随后发送text帧，收到session.finished后拼接返回全部音频；支持cancel帧与 AbortSignal 中止。

2. 服务端：路由工厂createAudioSpeechWsHandlers（server/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，余额不足时以关闭码1008（insufficient_flux）拒绝连接，客户端据此弹出「充值」提示；
   • 在向上游拨号期间缓冲客户端帧，上游 OPEN 后按到达顺序冲刷；
   • 音频二进制帧原样透传，cancel帧与客户端断连时向终止上游会话。

3. 运行时的管线：在聊天场景中，长文本流通过streamSpeech（packages/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）；目录发现失败时保留既有配置状态而不误标为未配置。

故障排查

官方文档给出了三条排查主线：

1. 确认已登录：provider 的配置状态完全依赖账号会话（configuredBy: 'authentication'），未登录时设置页只会显示登录卡片，不会触发任何目录请求；
2. 确认网络可达：AIRI 能正常访问官方服务。模型 / 音色目录均从服务端接口拉取（/api/v1/audio/models、/api/v1/audio/voices?model=...、流式对应/api/v1/audio/models/streaming与/api/v1/audio/voices/streaming），若接口 502 / 503，前端会显示明确的加载错误，且不会把「发现失败」误判为「服务不可用」而清掉既有配置；
3. 确认 Flux 余额充足：打开Settings → Flux查看可用套餐。HTTP TTS 与流式 TTS 都会消耗 Flux：流式会话在拨号上游前会做余额预检，不足时以insufficient_flux拒绝；Desktop 版本会在系统浏览器中打开结账页；若构建/部署设置了VITE_DISABLE_FLUX_PURCHASE，则不显示购买入口。

另外，服务端音色目录（listVoices）要求必须携带?model=参数（空参数返回 400，auto别名表示回退到DEFAULT_TTS_MODEL），UI 侧总是显式传入当前模型 ID 或auto；音色推荐映射存放在configKV的DEFAULT_TTS_VOICES中，运维可在不部署的情况下调整各语言的默认音色。

关键文件索引

• 官方文档：docs/content/en/docs/manual/config/providers/speech/official.md
• Provider 定义与音色自动选择：packages/stage-ui/src/libs/providers/providers/official/index.ts
• Provider 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 Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手