Firebase AI Logic（firebase-js-sdk）多说话人语音合成配置指南：MultiSpeakerVoiceConfig 详解

开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载本文基于 firebase-js-sdk 仓库中packages/aiAI Logic模块的 API 参考文档与源码讲解多说话人multi-speaker语音合成配置接口MultiSpeakerVoiceConfig的字段结构、与周边类型MultiSpeakerSpeechConfig、SpeakerVoiceConfig、VoiceConfig的组装关系以及如何将其嵌入generateContent请求实现旁白 角色式的多角色对话语音输出。读完本文你将能独立构造一份完整的多说话人speechConfig配置并理解其在 SDK 请求流水线中是如何被透传与校验的。一、MultiSpeakerVoiceConfig 是什么MultiSpeakerVoiceConfig是 Firebase AI LogicGemini TTS / speech synthesis 能力中用于描述多说话人语音方案的配置接口。它定义在 packages/ai/src/types/requests.ts源码与参考文档一致/** * Configuration for multi-speaker setup. * * beta */ export interface MultiSpeakerVoiceConfig { /** All the enabled speaker voices. */ speakerVoiceConfigs: SpeakerVoiceConfig[]; }官方参考文档docs-devsite/ai.multispeakervoiceconfig.md给出的签名与注释完全对应Signatureexport interface MultiSpeakerVoiceConfig说明Configuration for multi-speaker setup多说话人方案配置该接口是Public Preview公开预览API文档明确提示可能随反馈调整不要在生产环境使用。这一约束同样体现在源码的beta标注上。唯一属性speakerVoiceConfigs属性类型说明speakerVoiceConfigsSpeakerVoiceConfig[]所有启用的说话人声音配置speakerVoiceConfigs是一个数组数组中的每一项对应一个说话人speaker。换句话说多说话人语音合成本质上是为多个角色分别指定声音让模型按角色发声。二、speakerVoiceConfigs 的组成SpeakerVoiceConfig数组元素类型为SpeakerVoiceConfigdocs-devsite/ai.speakervoiceconfig.md源码定义于 packages/ai/src/types/requests.tsexport interface SpeakerVoiceConfig { /** The name of the speaker to use (same as in prompt). */ speaker: string; /** The configuration for the voice to use. */ voiceConfig: VoiceConfig; }两个字段均为必填属性类型说明speakerstring说话人名称必须与提示词prompt中使用的名字一致voiceConfigVoiceConfig该说话人使用的声音配置这里有一个关键语义speaker字段的值是一个角色名/说话人标识符SDK 并不会自动定义它而是要求开发者在 prompt 中以相同名称指代该角色。例如你希望生成一段旁白narrator与角色character对话的语音那么 prompt 里就要让模型明确输出这两个角色的台词同时在speakerVoiceConfigs中用同名speaker分别绑定不同的声音。voiceConfig 的嵌套结构voiceConfig的类型是VoiceConfigdocs-devsite/ai.voiceconfig.md源码见 packages/ai/src/types/requests.tsexport interface VoiceConfig { prebuiltVoiceConfig?: PrebuiltVoiceConfig; }它目前只承载一个可选字段prebuiltVoiceConfig类型为PrebuiltVoiceConfigdocs-devsite/ai.prebuiltvoiceconfig.md定义于 packages/ai/src/types/requests.tsexport interface PrebuiltVoiceConfig { voiceName?: string; }voiceName用于语音合成的预置声音名称字符串类型、可选。官方文档提示完整的声音列表与试听可参考 Chirp 3: HD Voices 声音表源码注释中也保留了这一引用。因此一个说话人的完整配置链为speakerVoiceConfigs[] → SpeakerVoiceConfig ├─ speaker: 角色名与 prompt 一致 └─ voiceConfig: VoiceConfig └─ prebuiltVoiceConfig: PrebuiltVoiceConfig └─ voiceName: 预置声音名三、MultiSpeakerVoiceConfig 在类型体系中的位置MultiSpeakerVoiceConfig不是孤立存在的它被MultiSpeakerSpeechConfig引用而后者又归属于统一的SpeechConfig联合类型。整条类型链在 packages/ai/src/types/requests.ts 中一次定义清楚export type SpeechConfig SingleSpeakerSpeechConfig | MultiSpeakerSpeechConfig; export interface BaseSpeechConfig { /** IETF BCP-47 language code. */ languageCode?: string; } export interface SingleSpeakerSpeechConfig extends BaseSpeechConfig { voiceConfig?: VoiceConfig; /** Multi-speaker configuration must not be set when using a single speaker. */ multiSpeakerVoiceConfig?: never; } export interface MultiSpeakerSpeechConfig extends BaseSpeechConfig { /** Single-speaker voice configuration must not be set when using multiple speakers. */ voiceConfig?: never; /** Configuration for multi-speaker setup. */ multiSpeakerVoiceConfig?: MultiSpeakerVoiceConfig; }从源码结构可以总结出三个要点二选一的互斥约束SingleSpeakerSpeechConfig中multiSpeakerVoiceConfig的类型是neverMultiSpeakerSpeechConfig中voiceConfig的类型是never。这意味着多说话人与单说话人两种配置不能同时出现SDK 通过 TypeScript 类型系统在编译期强制这一约束——若在设置multiSpeakerVoiceConfig的同时又设置了voiceConfig将无法通过类型检查。共享基类两者都继承BaseSpeechConfig因此可以共用可选的languageCodeIETF BCP-47 语言代码如en-US。挂载点SpeechConfig以可选字段speechConfig的形式出现在两类配置入口上GenerationConfig.speechConfigpackages/ai/src/types/requests.ts面向 TTS 模型的文本生成请求LiveGenerationConfig.speechConfigpackages/ai/src/types/requests.ts面向 Live API 模型。对应的 API 参考文档为 docs-devsite/ai.multispeakerspeechconfig.md。四、完整配置示例来自 SDK 测试的真实用法仓库中的单元测试给出了最可信的用法范本。packages/ai/src/requests/request-helpers.test.ts 中的preserves SpeechConfig for multi-speaker setups用例演示了多说话人配置如何嵌入generateContent请求const result formatGenerateContentInput({ contents: [ { role: user, parts: [{ type: text, text: Write a dialogue. }] } ], generationConfig: { speechConfig: { languageCode: en-US, multiSpeakerVoiceConfig: { speakerVoiceConfigs: [ { speaker: narrator, voiceConfig: { prebuiltVoiceConfig: { voiceName: Aoede } } }, { speaker: character, voiceConfig: { prebuiltVoiceConfig: { voiceName: Charon } } } ] } } } });测试断言result.generationConfig?.speechConfig与上述输入深度相等deep.equal即formatGenerateContentInput会原样保留多说话人配置不做任何改写。这验证了多说话人配置可以直接放在generationConfig.speechConfig.multiSpeakerVoiceConfig下speakerVoiceConfigs数组中每个元素独立指定speaker与voiceConfig该配置在请求格式化阶段会被完整透传pass-through不会丢失。此外同文件中的另一个用例preserves SpeechConfig alongside other GenerationConfig parameterspackages/ai/src/requests/request-helpers.test.ts展示了speechConfig可以与其他生成参数如temperature、maxOutputTokens、responseMimeType共存于同一个generationConfig中。单说话人对照示例作为对照单说话人配置同一测试文件 request-helpers.test.ts使用voiceConfig而非multiSpeakerVoiceConfigspeechConfig: { languageCode: en-US, voiceConfig: { prebuiltVoiceConfig: { voiceName: Puck } } }两相对照可以更直观地理解多说话人 multiSpeakerVoiceConfig.speakerVoiceConfigs[]为每个角色各配一个声音单说话人 直接用voiceConfig指定一个声音两者不可混用。五、如何传递到请求底层调用链多说话人配置从业务代码到网络请求的传递路径在源码中有清晰的实现依据业务层构造调用GenerativeModel.generateContent()时传入GenerateContentRequest其中generationConfig.speechConfig即承载多说话人配置相关类型见 packages/ai/src/types/requests.ts。请求格式化formatGenerateContentInput()packages/ai/src/requests/request-helpers.ts负责把字符串、数组或对象统一成GenerateContentRequest结构并对contents、systemInstruction做标准化对generationConfig.speechConfig则原样透传这正是测试用例断言deep.equal的原因。模型层转发GenerativeModel将格式化后的请求交给底层makeRequest发起推理请求。测试 packages/ai/src/models/generative-model.test.ts 验证了speechConfig中的languageCode与voiceName会出现在实际发出的请求体字符串中value.includes(en-US) value.includes(Puck)证明该配置最终会随请求送达后端模型。也就是说MultiSpeakerVoiceConfig不是 SDK 内部消费的私有类型而是面向调用方开放、由后端 TTS 模型解释的公开配置结构。六、使用要点与注意事项综合参考文档与源码使用MultiSpeakerVoiceConfig时有以下几点需要留意Public Preview 限制整个SpeechConfig家族含MultiSpeakerVoiceConfig都是beta/ Public Preview API接口可能随反馈变更官方明确不建议在生产环境使用。角色名必须与 prompt 对齐SpeakerVoiceConfig.speaker的值要与提示词中使用的角色名一致否则模型无法把台词对号入座到指定声音上。单/多说话人互斥MultiSpeakerSpeechConfig的voiceConfig被声明为never不能在多说话人模式下同时设置单说话人声音反之亦然。languageCode可选但建议设置继承自BaseSpeechConfig使用 IETF BCP-47 语言代码例如en-US测试示例中均显式给出。voiceName需来自预置声音表prebuiltVoiceConfig.voiceName应选用后端支持的声音名称源码注释指引到 Chirp 3: HD Voices 声音列表无效名称将导致合成失败。透传行为formatGenerateContentInput对speechConfig不做校验或改写配置的最终解释权在后端模型因此配置错误通常会在请求阶段以 API 错误形式暴露如AIErrorCode相关错误而非本地类型错误。七、小结MultiSpeakerVoiceConfig是 firebase-js-sdkpackages/ai模块中多说话人语音合成配置的核心承载接口它通过speakerVoiceConfigs: SpeakerVoiceConfig[]为每个角色绑定独立的voiceConfig目前落到prebuiltVoiceConfig.voiceName并由MultiSpeakerSpeechConfig挂载到generateContent/ Live API 请求的generationConfig.speechConfig上。其类型定义见 packages/ai/src/types/requests.ts真实调用范式可参考 packages/ai/src/requests/request-helpers.test.ts 的多说话人测试用例。对于需要旁白 角色多音色对话输出的场景这套配置是开箱即用的标准答案。赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐Firebase AI Logicfirebase-js-sdkCountTokensRequest 接口详解Token 计数请求的完整配置指南Firebase AI Logicfirebase js sdkCountTokensRequest 接口详解Token 计数请求的完整配置指南 Coun开发工具后端Firebase AIGemini多扬声器语音合成配置指南MultiSpeakerSpeechConfig 接口详解Firebase AIGemini多扬声器语音合成配置指南MultiSpeakerSpeechConfig 接口详解 本篇技术指南以 firebase j开发工具后端Firebase AIAI LogicModelParams 接口详解getGenerativeModel() 参数配置指南Firebase AIAI LogicModelParams 接口详解getGenerativeModel 参数配置指南 ModelParams 是 Fi开发工具后端上一篇深入解析 CozeLoop 前端多语言包 cozeloop/loop-lng结构、合并机制与 i18n 集成实践下一篇Android Studio中文界面插件3步告别英文困扰提升开发效率200%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考