AIRI 接入阿里云百炼(Model Studio)语音合成:CosyVoice 配置、音色调试与排障指南

原创2026-10-14 17:36:352,171 阅读
文章标签:AI 应用大模型AI Agent数字人前端后端桌面应用移动开发音频

AIRI 接入阿里云百炼(Model Studio)语音合成:CosyVoice 配置、音色调试与排障指南

本文是 AIRI 项目「语音合成(TTS)」服务商配置系列之一,讲解如何在 AIRI 中接入阿里云百炼(Alibaba Cloud Model Studio),使用 CosyVoice 系列模型为你的 AI 伴侣/赛博生命提供高质量的语音合成能力。读完本文,你将掌握 API Key 获取、服务商配置、Ping 连通性验证、模型与音色选择、试听调优以及常见问题的完整排查路径,并能从源码层面理解 AIRI 的服务商注册、配置校验与语音目录加载机制。

为什么选择阿里云百炼

阿里云百炼(Bailian)是阿里云推出的模型服务平台,AIRI 通过它接入 CosyVoice 语音合成模型。如果你已经在使用阿里云百炼,并希望在 CosyVoice 的音色与模型之间自由选择,这是最直接的接入方式——无需额外注册其他 TTS 服务,只需在百炼控制台开通模型服务并获取 API Key。

从 AIRI 的源码看,阿里云百炼语音合成服务商在仓库中注册为 alibaba-cloud-model-studio,类型为云端付费服务商(paidCloud,见 attributes.ts),归属「语音合成」任务(tasks: <a href="https://link.gitcode.com/i/802834a315cf5b5de3fa0071215b2bb3" target="_blank">'text-to-speech'])。其官方描述指向百炼控制台域名 bailian.console.aliyun.com,并在设置界面中显示为「阿里百炼」(见 [zh-Hans/settings.yaml)。

第一步:获取百炼 API Key

  1. 打开并登录阿里云百炼控制台,进入控制台后确认你已经开通了模型服务(尤其是 CosyVoice 相关模型)。
  2. 在「API Key 管理」页面创建密钥。
  3. 复制密钥并妥善保存,后续粘贴到 AIRI 中。

⚠️ API Key 安全 不要将百炼 API Key 提交到 Git 仓库、写入配置文件截图或发送给任何其他人。密钥泄露等同于账户额度被他人盗用。

从源码角度补充一点:AIRI 服务商配置表单将 apiKey 字段声明为 type: 'password'(见 unspeech/index.ts),输入时会以密码框形式隐藏显示,降低旁窥泄密风险。

第二步:在 AIRI 中配置服务商

  1. 打开 设置 → 服务商 → 语音合成 → Alibaba Cloud Model Studio。
  2. 将百炼 API Key 粘贴到「基础配置」的 API 密钥字段。
  3. Base URL 使用界面默认值,除非你配置了自己的兼容网关(例如自建的 unspeech 兼容代理)。

Base URL 的源码细节

服务商配置的完整结构定义在 unspeech/index.ts:

const unspeechConfigSchema = z.object({
  apiKey: z.string(),
  baseUrl: z.string().default('https://unspeech.hyp3r.link/v1/'),
})

也就是说,界面默认的 Base URL 为 https://unspeech.hyp3r.link/v1/。AIRI 通过 createUnAlibabaCloud(config.apiKey.trim(), config.baseUrl?.trim() ?? '') 构造实际客户端(见同文件第 191 行),apiKey 与 baseUrl 两侧空白字符会被自动去除。若你自建了兼容网关,只需把 Base URL 改为网关地址即可,其余配置不变。

配置校验规则

AIRI 在填写配置时会实时校验(对应界面上的「Ping API」能力)。校验逻辑 validateUnspeechConfig 位于 unspeech/index.ts,核心规则如下:

  • apiKey 必填,不允许为空(空白字符串视为未填写);
  • baseUrl 必填,且必须是带协议(http:// 或 https://)的绝对地址;
  • Base URL 必须以斜杠 / 结尾,否则校验失败并提示。

这些规则意味着:如果你把 Base URL 填成了不带协议或尾部缺 / 的地址,即使 API Key 正确,Ping 也会报错——这是最常见的配置错误之一。

第三步:验证配置并试听

配置完成后按以下顺序验证:

  1. Ping API:点击此按钮测试网络连通性以及 API Key 是否填写正确。只有 Ping 通过,才能进入模型与音色选择。
  2. 选择模型和音色:测试成功后,选择 CosyVoice 模型与音色,再回到 设置 → 发声 中启用该语音合成服务。
  3. 输入短文本试听:确认音频可正常生成并播放,即可投入使用。

界面背后的自动加载逻辑

AIRI 的百炼设置页位于 alibaba-cloud-model-studio.vue,其中有几个值得注意的实现细节:

  • 音色目录自动加载:页面会以 500ms 防抖监听 apiKey 与 baseUrl 的变化,一旦两者都填好且校验通过,就自动调用 loadVoicesForProvider(providerId) 拉取音色列表(见该文件第 98-103 行),因此你无需手动刷新即可看到最新音色。
  • 试听组件:页面内置 SpeechPlayground 试听区,支持直接输入文本试听当前音色的合成效果;只有配置了 API Key 时才允许试听(api-key-configured 控制)。
  • 音高/语速/响度微调:设置页提供三组滑杆——音高(pitch,-100% ~ 100%)、语速(speed,0.5 ~ 2.0)、响度(volume,-100% ~ 100%),调整后实时写入服务商配置,用于精细控制合成效果。

模型与音色目录的服务端定义

百炼服务商的模型列表与音色目录定义在 unspeech/index.ts:

listModels: async () => [
  { id: 'cosyvoice-v1', name: 'CosyVoice', ... },
  { id: 'cosyvoice-v2', name: 'CosyVoice (New)', ... },
],

AIRI 目前内置了两个可选模型:

模型 ID 显示名称 说明
cosyvoice-v1 CosyVoice 经典版本,兼容性最广
cosyvoice-v2 CosyVoice (New) 新版模型,部分音色支持 SSML

音色列表通过 listVoices 从远端拉取,每条音色包含 id、name、compatibleModels(兼容模型)、previewURL(试听地址)、languages(支持语言)与 gender(性别)等信息,供选择界面展示与试听使用。设置页默认模型为 cosyvoice-v1(见 alibaba-cloud-model-studio.vue)。

SSML 支持差异:v1 与 v2 的区别

AIRI 的语音合成模块会根据服务商与模型决定是否启用 SSML 标记支持。在 speech.ts 中可以看到明确的判断逻辑:

if (activeSpeechProvider.value === 'alibaba-cloud-model-studio' && activeSpeechModel.value === 'cosyvoice-v2') {
  return true
}

也就是说:

  • 百炼 + cosyvoice-v2:支持 SSML,可以精确控制停顿、语气等细节(SSML 标记会通过 generateSSML 处理后发给服务端);
  • 百炼 + cosyvoice-v1:不支持 SSML,将按纯文本合成。

如果你需要用 SSML 精细控制朗读效果(例如指定停顿),请选择 cosyvoice-v2 模型。这也解释了为什么模型选择要先于音色选择完成——模型会直接影响可用的合成能力。另外在 provider-definitions.test.ts 中,alibaba-cloud-model-studio 被列入「已注册服务商」的断言清单,确保该服务商定义在 stage-ui 中始终可用。

排查与常见问题

Ping API 失败

按以下顺序排查:

  1. API Key 是否正确:重新复制百炼控制台的密钥,注意前后不要带多余空格(AIRI 会自动 trim,但复制过程可能引入换行符)。
  2. Base URL 是否合法:必须是以 https:// 开头、以 / 结尾的绝对地址;若你改了默认值,请先改回默认的 https://unspeech.hyp3r.link/v1/ 再测试。
  3. 账户额度是否充足:确认百炼账户未欠费或超出调用限额。
  4. 网络连通性:确认当前设备可以正常访问百炼控制台与对应网关(部分网络环境需要代理)。

模型或音色不可选

确认百炼账户已开通相应的 CosyVoice 模型服务;不同音色可能只兼容特定模型版本(音色数据中的 compatibleModels 字段会标明兼容范围)。若音色列表一直为空,检查设置页是否已填入有效 API Key——音色目录只在配置校验通过后才会自动加载(见上文「自动加载逻辑」)。

试听正常但对话不发声

确认已完成 设置 → 发声 中的启用操作:仅配置服务商并不会自动切换语音输出,需要在发声设置中选择「阿里百炼」及其音色作为当前生效的语音合成来源。

进一步阅读

本文所属的语音合成服务商配置系列文档位于 docs/content/zh-Hans/docs/manual/config/providers/speech 目录,可继续阅读:

如需了解服务商定义、配置校验与音色目录的完整源码实现,可阅读 packages/provider-inference/src/providers/cloud/unspeech/index.ts、packages/stage-ui/src/stores/modules/speech.ts 与 packages/stage-ui/src/libs/providers/providers/provider-definitions.test.ts。

登录后查看全文
airi