AIRI 接入阿里云百炼 CosyVoice 语音合成：从 API Key 到全链路配置实战

AIRI 接入阿里云百炼 CosyVoice 语音合成从 API Key 到全链路配置实战【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文是 AIRI 语音合成Text-to-Speech提供者配置指南的一部分完整讲解如何在 AIRI 中接入阿里云百炼Alibaba Cloud Bailian / Model Studio的 CosyVoice 语音合成模型。你将掌握如何获取百炼 API Key、如何在「设置 → 提供者 → 语音合成」中完成提供者配置含 Base URL 信任边界说明、如何用提供者 Playground 验证凭证、如何将语音真正启用为 AIRI 日常回复的声音以及常见的排障思路。文中所有配置项均结合 AIRI 开源仓库的前端设置页、提供者注册表与服务端适配器源码展开可直接对照实操。为什么选择阿里云百炼AIRI 支持多种语音合成提供者如 ElevenLabs、Azure Speech、Deepgram、火山引擎等相关文档见 speech 提供者文档目录而阿里云百炼在 AIRI 中承载的是CosyVoice 语音合成模型。其定位非常明确如果你已经在使用阿里云 Model Studio百炼并且希望在 CosyVoice 的多个语音和模型中直接选择那么阿里云百炼就是接入 AIRI 的直接途径无需再引入第二家语音服务厂商API Key 的申请与费用结算也统一在阿里云控制台内完成。从源码实现看该提供者的 UI 文案即标注为「阿里百炼」描述为bailian.console.aliyun.com见 settings.yaml可见 AIRI 团队将其作为百炼平台的官方入口对待。第一步获取百炼 API Key在开始配置之前需要先在阿里云侧准备好可用的凭证登录阿里云百炼Bailian控制台进入「模型服务」相关页面确认你的账号下模型服务已开通/激活在 API Key 管理页面创建一个新的密钥Key复制生成的 Key并妥善保存在安全的位置例如密码管理器。⚠️API Key 安全切勿将百炼 API Key 提交到代码仓库、不要让它出现在截图里也不要分享给任何人。后续配置时该 Key 会以密文password 类型输入框填写在 AIRI 设置页中。第二步在 AIRI 中配置提供者操作路径打开 AIRI 的设置 → 提供者Providers→ 语音合成Speech→ Alibaba Cloud Model Studio进入该提供者的配置页。该页面由仓库中的 alibaba-cloud-model-studio.vue 实现其中定义了两个关键默认值提供者 IDalibaba-cloud-model-studio默认模型cosyvoice-v1核心配置项API Key 与 Base URL配置页需要填写两项核心配置配置项说明默认值API Key第一步在百炼控制台生成的密钥无Base URL语音服务的接入地址https://unspeech.hyp3r.link/v1/关键点默认 Base URL 并不是阿里云百炼的直接 API 地址而是 AIRI/UnSpeech 网关。你的 API Key、待合成的文本、模型/语音的选择以及最终返回的音频都会经过这个网关转发到后端语音服务。这是一个需要你明确接受的信任边界trust boundary如果你可以接受该网关中转直接使用默认值即可如果不能接受可以填写一个兼容的自托管网关 URL只要实现了相同的 UnSpeech/OpenAI 兼容接口即可或者干脆选择其他直连的语音提供者。从源码看这一信任边界在提供者注册表中有明确的默认值约束。在 unspeech/index.ts 中UnSpeech 系提供者的配置 Schema 定义如下const unspeechConfigSchema z.object({ apiKey: z.string(), baseUrl: z.string().default(https://unspeech.hyp3r.link/v1/), })即API Key 必填、Base URL 可选默认网关地址。同时配置校验逻辑validateUnspeechConfig还会对 Base URL 做严格检查unspeech/index.tsBase URL 必须是一个绝对 URL需要带http://或https://协议头否则报「Base URL is not absolute」Base URL必须以斜杠/结尾否则报「Base URL must end with a trailing slash (/)」。服务端侧同样依赖该网关TTS 适配器在转发请求时会对 Base URL 做去尾斜杠处理并拼接/v1/路径见 server 侧 unspeech 工具因此前端校验与后端行为保持一致。提供者实例的底层构造填写配置后AIRI 会通过createUnAlibabaCloud(config.apiKey.trim(), config.baseUrl?.trim() ?? )构造语音提供者实例并注册两类能力unspeech/index.ts模型列表固定返回两个 CosyVoice 模型——cosyvoice-v1CosyVoicecosyvoice-v2CosyVoice (New)语音列表通过 UnSpeech 的listVoices拉取返回结果会附带compatible_models兼容模型、preview_audio_url试听地址、languages语言、gender性别等信息供设置页的语音选择器使用。第三步验证配置提供者 Playground配置保存后可以在同一个设置页内置的提供者 Playground中验证凭证是否有效在语音列表中选择一个可用语音——该页面默认使用 AIRI 的 CosyVoice 模型在 Playground 的文本框中输入一小段短文本点击生成确认能否正常播放返回的音频。从设置页源码看alibaba-cloud-model-studio.vue页面挂载时会先校验提供者配置validateProviderConfig校验通过后调用loadVoicesForProvider拉取可用语音当配置如 API Key发生变化时也会触发同样的重载流程。若 API Key 未配置Playground 会处于禁用状态apiKeyConfigured为 false不会发起请求。Playground 的作用仅是测试凭证与语音可用性它并不会让 AIRI 的日常回复自动开口说话。第四步让语音用于 AIRI 日常回复要让合成语音真正接入 AIRI 的普通回复流程还需要完成模块级的选择打开设置 → 模块Modules→ 语音合成Speech在语音提供者列表中选择Alibaba Cloud Model Studio选择可用的模型cosyvoice-v1或cosyvoice-v2与语音。这一步通过 speech store 持久化speech.tssettings/speech/active-provider、settings/speech/active-model、settings/speech/voice三个 key 分别记录当前激活的提供者、模型与语音由 Pinia 同步跨窗口状态。configured计算属性会同时要求「模型 语音」都已选定才认为语音模块配置完成speech.ts。值得注意的模型细节设置页 Playground 的默认模型是cosyvoice-v1而服务端 DashScope CosyVoice 适配器的默认模型是cosyvoice-v2见 dashscope-cosyvoice.ts。源码注释解释了原因v1 已从官方 REST 支持模型列表中移除v2 与 v3/v3.5 的请求体结构一致便于运营通过adapterParams.model无损切换同时提醒「若升级到 v2 以上需确认默认语音在该模型下存在」——因为 v2*_v2与 v3*_v3的语音目录并不相同。服务端适配器默认输出mp3格式与下游消费方默认的 OpenAImp3格式保持一致dashscope-cosyvoice.ts。SSML 支持在 speech store 的supportsSSML逻辑中alibaba-cloud-model-studio且模型为cosyvoice-v2时返回truespeech.ts即 v2 的部分语音支持 SSML 输入可通过generateSSML生成带pitch/rate/volume韵律标记的合成指令。进阶调节语音参数Pitch / Speed / Volume该提供者的设置页额外提供了三个通用语音参数滑杆alibaba-cloud-model-studio.vue参数取值范围步长含义Pitch音调-100% ~ 100%1%音调偏移正值升高、负值降低Speed语速0.5 ~ 2.00.01语速倍率1.0 为原始语速Volume音量-100% ~ 100%1%音量偏移这些值会通过 watch 实时写回提供者配置providerConfig.pitch / speed / volume并在合成请求中作为额外选项下发。注意服务端的 DashScope CosyVoice 直连适配器对 Voice Pack 的 pitch/volume 参数会直接拒绝返回BAD_REQUEST见 dashscope-cosyvoice.ts因此在 UI 中调节这些参数主要作用于支持这些参数的合成路径如 SSML具体效果以实际返回音频为准。问题排查若在 Playground 中请求始终无法完成按以下顺序逐一排查对应 原文档 的排障章节并结合源码补充细节API Key 是否正确确认 Key 已完整复制、无多余空格。前端校验要求 API Key 必填且会trim()处理unspeech/index.ts。Base URL 是否合法必须是带协议头http://或https://且以/结尾的绝对地址若你改用了自托管网关请对照此规则检查。Model Studio 的计费与配额状态百炼侧是否欠费、模型服务的配额是否用尽会在网关侧表现为请求失败。请求限流是否触发了阿里云侧的 QPS/RPM 限流。网络连通性你的环境尤其自托管部署是否能访问https://unspeech.hyp3r.link或你自定义的网关地址。模型/语音不可用若某个模型或语音选择不到回到百炼控制台确认该账号下对应模型服务已开通。此外注意 v1/v2 的语音目录存在差异*_v2与*_v3选择的语音必须与所选模型兼容。小结阿里云百炼接入链路可归纳为三步百炼控制台拿到 API Key → 提供者页配置 Key 与 Base URL默认 UnSpeech 网关→ 模块页选定模型与语音。其中最容易踩坑的是 Base URL 的信任边界与尾斜杠/协议头校验其次是 CosyVoice v1/v2 的语音目录差异。配置完成后Playground 验证通过即代表凭证可用而日常回复是否发声取决于「模块 → 语音合成」中的提供者选择——两者是独立步骤缺一不可。相关实现可继续阅读 提供者注册表、设置页实现、服务端 CosyVoice 适配器 与 speech store 测试。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考