AIRI 接入阿里云百炼 CosyVoice:语音合成提供商配置完整指南
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 的多个音色与模型版本之间自由选择,那么这是最直接的接入方式。
从仓库源码可以进一步确认这一设计定位:
- 在 packages/provider-inference/src/providers/cloud/unspeech/index.ts 中,
alibaba-cloud-model-studio被注册为text-to-speech任务的提供商,其描述指向bailian.console.aliyun.com,并内置两个模型:cosyvoice-v1(CosyVoice)与cosyvoice-v2(CosyVoice (New))。 - 在 packages/stage-ui/src/libs/providers/attributes.ts 中,该提供商被标记为
paidCloud(付费云服务)类别,说明它需要真实的百炼账号与计费配额才能工作。 - 国际化文案中,中文界面将其命名为「阿里百炼」,见 packages/i18n/src/locales/zh-Hans/settings.yaml。
二、获取百炼 API Key
接入的第一步是在阿里云百炼控制台申请 API Key,官方步骤为:
- 登录 Alibaba Cloud Bailian Console(百炼控制台),确认模型服务已激活。
- 在 API Key 管理页面生成一个新的密钥。
- 复制密钥并妥善保管在安全位置。
::: 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(语音测试台),用于验证凭证是否真正可用:
- 在 Playground 中从可用音色列表选择一个音色(此页默认使用 AIRI 内置的 CosyVoice 默认模型
cosyvoice-v1); - 在同一页面输入一段短文本,点击合成并确认音频可以正常播放。
页面中的音色列表由语音 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 回复带上语音,必须完成模块级配置:
- 打开 设置 → 模块 → 语音合成(Speech);
- 选择 Alibaba Cloud Model Studio;
- 从可用模型(
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 请求无法完成:依次检查
- API Key 是否正确、未过期;
- Model Studio 的计费与配额状态(付费云服务需要可用配额,见 packages/stage-ui/src/libs/providers/attributes.ts 的
paidCloud标记); - 请求限流(rate limit)是否被触发;
- 网络连接是否可达网关与百炼。
- 模型或音色不可用:确认百炼账号中对应模型服务已激活;同时注意音色目录与模型版本的绑定关系 —— 切换
cosyvoice-v1与cosyvoice-v2后,可用音色集合是不同的,需要重新选择。
如果配置校验失败,可对照 3.4 节的校验规则复查:API Key 非空、Base URL 为绝对地址且以 / 结尾。
七、小结
在 AIRI 中接入阿里云百炼 CosyVoice 的完整路径为:
- 百炼控制台启用模型服务并生成 API Key;
- 在「设置 → 提供商 → 语音合成 → Alibaba Cloud Model Studio」填入 Key(并确认/调整 Base URL 网关);
- 用 Playground 验证凭证与音频链路;
- 在「设置 → 模块 → 语音合成」选择该提供商、模型与音色,使普通回复生效;
- 需要时按文档清单排查计费、配额、限流与音色可用性。
关键事实速查:
- 模型 ID:
cosyvoice-v1(默认,Playground 使用)、cosyvoice-v2(支持部分音色 SSML); - 默认网关:
https://unspeech.hyp3r.link/v1/(接受信任边界或替换为自托管网关); - 配置校验:API Key 必填、Base URL 必须绝对地址且以
/结尾(源码 packages/provider-inference/src/providers/cloud/unspeech/index.ts); - 音色目录:经由 UnSpeech 拉取,无需百炼凭证(源码 server/apps/api/src/services/adapters/tts/dashscope-cosyvoice.ts)。