AIRI 接入阿里云百炼 CosyVoice:语音合成提供商配置完整指南

原创2026-10-15 22:25:041,334 阅读
文章标签:AI 应用大模型AI Agent数字人前端后端桌面应用移动开发音频

AIRI 接入阿里云百炼 CosyVoice:语音合成提供商配置完整指南

AIRI(自托管 Grok 风格 AI 伴侣项目)支持通过 Alibaba Cloud Model Studio(阿里云百炼) 提供商启用 CosyVoice 语音合成(TTS)。本文以 docs/content/ko/docs/manual/config/providers/speech/alibaba-cloud-model-studio.md 为主线,结合仓库内 provider 注册、UnSpeech 网关适配器与语音模块源码,完整讲解 API Key 获取、网关信任边界、提供商店铺配置、Playground 验证以及让 AIRI 正常回复开口说话的全部步骤。

读完本文,你将掌握:百炼 API Key 的安全管理、https://unspeech.hyp3r.link/v1/ 默认网关的来龙去脉与替代方案、cosyvoice-v1/cosyvoice-v2 两个模型及音色选择逻辑、以及常见故障(凭证失效、配额不足、音色不可用)的排查思路。

一、为什么选择阿里云百炼

根据 docs/content/ko/docs/manual/config/providers/speech/alibaba-cloud-model-studio.md 的说明,阿里云百炼是 AIRI 中 CosyVoice 语音合成模型 的提供方。如果你已经使用阿里云 Model Studio(百炼),并且希望在 CosyVoice 的多个音色与模型版本之间自由选择,那么这是最直接的接入方式。

从仓库源码可以进一步确认这一设计定位:

二、获取百炼 API Key

接入的第一步是在阿里云百炼控制台申请 API Key,官方步骤为:

  1. 登录 Alibaba Cloud Bailian Console(百炼控制台),确认模型服务已激活。
  2. 在 API Key 管理页面生成一个新的密钥。
  3. 复制密钥并妥善保管在安全位置。

::: warning API Key 安全 不要把百炼 API Key 提交到代码仓库、截图分享或泄露给任何人。AIRI 的提供商设置页会将 Key 以密码输入框形式保存(见下文「配置字段校验」),但密钥本身仍然只应保存在你自己的配置存储中。 :::

补充一点仓库证据:在 packages/provider-inference/src/providers/cloud/unspeech/index.ts 的配置 schema 中,apiKey 是必填字段,并在 UI 元数据中被标记为 type: 'password',说明 AIRI 会按敏感字段处理它。

三、在 AIRI 中配置提供商

3.1 导航路径

打开 设置(Settings)→ 提供商(Providers)→ 语音合成(Speech)→ Alibaba Cloud Model Studio,进入该提供商的配置页。对应页面组件为 packages/stage-pages/src/pages/settings/providers/speech/alibaba-cloud-model-studio.vue。

3.2 关键配置字段

字段 说明 默认值
Model Studio API Key 上一步从百炼控制台生成的密钥,必填 无
Base URL UnSpeech 网关地址,不是 阿里云直连 API https://unspeech.hyp3r.link/v1/

配置页内部逻辑(alibaba-cloud-model-studio.vue)默认模型为 cosyvoice-v1,并提供了三个通用语音参数滑块:

  • 音高(pitch):范围 -100% ~ +100%,步长 1;
  • 语速(speed):范围 0.5 ~ 2.0,步长 0.01;
  • 响度(volume):范围 -100% ~ +100%,步长 1。

这些参数在设置变更后(watch)会写回提供商的 pitch/speed/volume 配置。

3.3 Base URL 与信任边界(重要)

原文档特别强调:默认 Base URL 是 AIRI/UnSpeech 网关 https://unspeech.hyp3r.link/v1/,不是 阿里云百炼的直连 API。你的密钥、待合成文本、模型/音色选择以及返回的音频都会经过该网关。因此:

  • 只有当你接受这一信任边界时,才应使用默认网关;
  • 否则,请填写一个兼容的自托管网关 URL;
  • 或者直接选择其他直连提供商(例如 Azure Speech、Volcengine 等)。

从源码结构看,这一信任边界是「UnSpeech」网关模式在 AIRI 中的统一体现:alibaba-cloud-model-studio、deepgram-tts、microsoft-speech、volcengine 都复用同一套 unspeechConfigSchema(见 packages/provider-inference/src/providers/cloud/unspeech/index.ts),其 baseUrl 默认值即 https://unspeech.hyp3r.link/v1/。

网关侧的语音目录接口同样值得注意:在服务端适配器 server/apps/api/src/services/adapters/tts/dashscope-cosyvoice.ts 中,音色列表通过 GET /api/voices?provider=alibaba&model=cosyvoice-v2 向 UnSpeech 请求;该实现说明 UnSpeech 的 alibaba 后端把音色目录内嵌在服务端(//go:embed voices.json),因此拉取音色时不需要百炼上游凭证,只跨越一次 TCP 请求。

3.4 配置校验规则

填写配置后,AIRI 会执行校验。在 packages/provider-inference/src/providers/cloud/unspeech/index.ts 的 validateUnspeechConfig 中可以看到具体规则:

  • apiKey 与 baseUrl 均为必填,且会先 trim();
  • Base URL 必须是绝对地址(包含 http:// 或 https:// scheme),且必须以 / 结尾;
  • 不满足以上任一条都会导致配置无效,无法进入下一步 Playground 测试。

四、验证配置:Provider Playground

配置页内置了 Playground(语音测试台),用于验证凭证是否真正可用:

  1. 在 Playground 中从可用音色列表选择一个音色(此页默认使用 AIRI 内置的 CosyVoice 默认模型 cosyvoice-v1);
  2. 在同一页面输入一段短文本,点击合成并确认音频可以正常播放。

页面中的音色列表由语音 Store 提供:在 packages/stage-ui/src/stores/modules/speech.ts 中,loadVoicesForProvider 会先校验提供商配置,再通过 loadVoiceCatalog 拉取该提供商的音色目录;只有配置有效时才会加载。Playground 组件通过 handleGenerateSpeech(alibaba-cloud-model-studio.vue)调用 speechStore.speech 完成一次真实合成请求。

从测试用例可以印证音色与模型的绑定关系:在 packages/stage-ui/src/stores/modules/speech.test.ts 中,服务器模型目录包含 alibaba/cosyvoice-v2,且注释明确提示 —— 不同模型版本的音色目录不同(v2 使用 *_v2 命名,v3 使用 *_v3),切换模型后需要重新确认所选音色在该模型下存在。

五、让 AIRI 回复真正开口说话

Playground 只能测试凭证与合成链路是否可用。要让普通 AIRI 回复带上语音,必须完成模块级配置:

  1. 打开 设置 → 模块 → 语音合成(Speech);
  2. 选择 Alibaba Cloud Model Studio;
  3. 从可用模型(cosyvoice-v1、cosyvoice-v2)与音色中选择。

这一步会写入语音模块的持久化选择。在 packages/stage-ui/src/stores/modules/speech.ts 中可以看到这些选择的存储键:

  • settings/speech/active-provider(激活的语音提供商,默认 speech-noop);
  • settings/speech/active-model(激活的模型);
  • settings/speech/voice(激活的音色 ID)。

5.1 SSML 支持(cosyvoice-v2)

从源码看,CosyVoice 还具备一项额外能力:SSML。在 packages/stage-ui/src/stores/modules/speech.ts 中,supportsSSML 计算属性在 alibaba-cloud-model-studio 且模型为 cosyvoice-v2 时返回 true(注释说明 v2 只有部分音色支持 SSML);在生成实际输出时,createOutput 会在启用 SSML 且模型为 cosyvoice-v2 时,把文本包装成带 prosody(音高/语速/响度)的 <speak> XML 再送合成。

5.2 服务端直连路径(自托管场景)

如果你的部署使用 AIRI 服务端网关(而非浏览器直连 UnSpeech),服务端同样内置了 CosyVoice 适配器:dashscope-cosyvoice(见 server/apps/api/src/services/adapters/tts/dashscope-cosyvoice.ts)。该适配器:

  • 默认模型为 cosyvoice-v2(v1 已从官方 REST 支持列表移除,v2 是最保守的当前默认,与 v3/v3.5 共享请求体结构,可平滑切换);
  • 通过 UnSpeech 以 alibaba/{model} 的模型名发送合成请求;
  • 拉取音色目录时直接调用 UnSpeech 的 /api/voices?provider=alibaba,并且不携带 Authorization 头(测试用例见 server/apps/api/src/services/adapters/tts/index.test.ts)。

服务端 TTS 上游(含 UnSpeech 网关地址)通过 UNSPEECH_UPSTREAM 环境变量配置,其 schema 定义在 server/apps/api/src/services/adapters/config-kv/definitions.ts。

六、问题排查

原文档给出的排查清单如下:

  • Playground 请求无法完成:依次检查
    1. API Key 是否正确、未过期;
    2. Model Studio 的计费与配额状态(付费云服务需要可用配额,见 packages/stage-ui/src/libs/providers/attributes.ts 的 paidCloud 标记);
    3. 请求限流(rate limit)是否被触发;
    4. 网络连接是否可达网关与百炼。
  • 模型或音色不可用:确认百炼账号中对应模型服务已激活;同时注意音色目录与模型版本的绑定关系 —— 切换 cosyvoice-v1 与 cosyvoice-v2 后,可用音色集合是不同的,需要重新选择。

如果配置校验失败,可对照 3.4 节的校验规则复查:API Key 非空、Base URL 为绝对地址且以 / 结尾。

七、小结

在 AIRI 中接入阿里云百炼 CosyVoice 的完整路径为:

  1. 百炼控制台启用模型服务并生成 API Key;
  2. 在「设置 → 提供商 → 语音合成 → Alibaba Cloud Model Studio」填入 Key(并确认/调整 Base URL 网关);
  3. 用 Playground 验证凭证与音频链路;
  4. 在「设置 → 模块 → 语音合成」选择该提供商、模型与音色,使普通回复生效;
  5. 需要时按文档清单排查计费、配额、限流与音色可用性。

关键事实速查:

登录后查看全文
airi