在 Xinference 中部署 CosyVoice-300M-Instruct指令可控多语言语音合成实战指南【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference本篇技术指南围绕 Xinference 内置音频模型CosyVoice-300M-Instruct展开完整介绍该模型的能力定位、启动方式、指令式语音合成的调用方法以及它在 Xinference 中的源码级实现原理与测试验证方式。读完本文你将能够在本地或服务器上快速启动 CosyVoice-300M-Instruct并通过 OpenAI 兼容 API 或 Xinference Python Client 实现“按指令控制音色与语调”的 TTS 服务。CosyVoice-300M-Instruct 是什么根据内置模型文档 cosyvoice-300m-instruct.rstCosyVoice-300M-Instruct 是 Xinference 内置注册的音频Audio类型模型其核心元信息如下字段值Model NameCosyVoice-300M-InstructModel FamilyCosyVoiceAbilities[text2audio, text2audio_zero_shot]MultilingualTrueModel IDFunAudioLLM/CosyVoice-300M-Instruct从能力标签可以看出该模型支持两类音频能力text2audio直接根据文本合成语音TTStext2audio_zero_shot零样本场景下的文本转语音强调无需针对目标说话人做微调即可完成合成。与同家族的其他两个模型相比它的定位非常明确——audio.rst 中的 CosyVoice 使用说明指出CosyVoice 1.0 家族包含三个各司其职的模型CosyVoice-300M-SFT仅做文本到语音的转换提供预设音色[中文女, 中文男, 日语男, 粤语女, 英文女, 英文男, 韩语女]CosyVoice-300M面向音色克隆与跨语言转换调用时必须提供prompt_speech参考音频CosyVoice-300M-Instruct面向对音色与语调的精细控制通过指令文本instruct_text引导生成。也就是说当你需要一个“既支持预设音色、又能在生成时通过自然语言指令调节语气与表现力”的多语言 TTS 模型时CosyVoice-300M-Instruct 就是官方文档推荐的选项。模型注册与下载源在 Xinference 的音频模型目录 model_spec.json 中CosyVoice-300M-Instruct 有完整的注册条目version: 2关键字段包括{ version: 2, model_name: CosyVoice-300M-Instruct, model_family: CosyVoice, model_ability: [text2audio, text2audio_zero_shot], multilingual: true, model_src: { huggingface: { model_id: FunAudioLLM/CosyVoice-300M-Instruct, model_revision: ba5265d9a3169c1fedce145122c9dd4bc24e062c }, modelscope: { model_id: iic/CosyVoice-300M-Instruct, model_revision: master } } }值得注意的注册细节该模型同时注册了Hugging FaceFunAudioLLM/CosyVoice-300M-Instruct与ModelScopeiic/CosyVoice-300M-Instruct两个下载源并各自固定了model_revision以保证可复现注册表中还声明了该模型的virtualenv 依赖包清单包括librosa、tiktoken、lightning2.0.0、hydra-core1.3.2、inflect、conformer、diffusers0.29.0、gdown、pyarrow、HyperPyYAML、onnxruntime1.16.0、pyworld0.3.4、wetext0.0.9、transformers4.51.3以及系统级的numpy与torch。Xinference 会为音频模型创建独立的虚拟环境来安装这些依赖避免与主进程环境相互污染。启动 CosyVoice-300M-Instruct官方内置模型文档给出了最简启动命令xinference launch --model-name CosyVoice-300M-Instruct --model-type audio该命令等价于通过内置模型目录完成一次标准启动流程从model_spec.json中解析出CosyVoice-300M-Instruct的AudioModelFamilyV2规格按CacheManager的缓存逻辑定位或下载模型权重在模型专属虚拟环境中实例化CosyVoiceModel并加载权重。从源码 core.py 的match_audio/create_audio_model_instance逻辑可以看到音频模型会通过download_hub参数在 Hugging Face 与 ModelScope 之间选择下载源显式传入--download-hub modelscope时优先使用 ModelScope否则根据环境配置的download_from_modelscope()结果自动选择。因此在国内网络环境下通常建议显式指定下载源xinference launch --model-name CosyVoice-300M-Instruct --model-type audio \ --download-hub modelscope启动成功后模型实例由 cosyvoice.py 中的CosyVoiceModel承载。在load()阶段它会把仓库内的thirdparty/cosyvoice目录临时加入sys.path因为模型自带的 yaml 配置硬编码了 import 路径然后根据模型名判断加载 CosyVoice 1.x 的CosyVoice类。load_jit/compile参数用于控制是否启用 JIT 编译两者统一为compile语义加载时可通过--compile true传入。指令式语音合成核心用法CosyVoice-300M-Instruct 与 SFT 版本最大的区别在于instruct_text参数。官方文档 audio.rst 给出的典型用法如下from xinference.client import Client client Client(http://XINFERENCE_HOST:XINFERENCE_PORT) model client.get_model(MODEL_UID) response model.speech( 在面对挑战时他展现了非凡的strong勇气/strong与strong智慧/strong。, voice中文男, instruct_textTheo Crimson, is a fiery, passionate rebel leader. Fights with fervor for justice, but struggles with impulsiveness., )这段代码做了三件事input传入待朗读的文本支持使用strong这类标记对局部内容施加强调效果voice中文男从预设音色中选择说话人instruct_text用一段英文自然语言描述目标角色的性格与语气模型会据此调整语调与表现力。通过 OpenAI 兼容 API 调用Xinference 的 Speech 接口与 OpenAI 的create speechAPI 对齐路由注册见 audio.py 中的/v1/audio/speech。你可以直接用 OpenAI Python Client 调用import openai client openai.Client( api_keycannot be empty, base_urlhttp://XINFERENCE_HOST:XINFERENCE_PORT/v1 ) response client.audio.speech.create( modelMODEL_UID, input在面对挑战时他展现了非凡的strong勇气/strong与strong智慧/strong。, voice中文男, ) response.stream_to_file(output.mp3)通过 cURL 调用curl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/audio/speech \ -H accept: application/json \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: The text to generate audio for, voice: 中文男 }其中voice的可用值即 CosyVoice 预设音色列表[中文女, 中文男, 日语男, 粤语女, 英文女, 英文男, 韩语女]该列表同时出现在官方文档与测试用例中。如果调用时不传voice源码中的_speech_handle会自动选择第一个可用说话人并在日志中输出Auto select speaker: ...提示。请求参数与约束条件从 cosyvoice.py 的speech()方法签名与参数校验逻辑可以整理出 CosyVoice-300M-Instruct 的完整参数契约参数说明备注input待合成语音的文本必填支持strong等强调标记voice预设说话人从可用音色中选取缺省时自动选择第一个response_format输出音频格式默认mp3测试覆盖pcm流式场景speed语速参数API 层接收CosyVoice 1.x 路径不参与实际变速stream是否流式返回音频块默认Falseinstruct_text语气/角色/语调的指令描述Instruct 模型专属能力prompt_speech参考音频WAV 字节Instruct 模型不支持传入会触发断言错误prompt_text参考音频对应的转写文本Instruct 模型不支持传入会触发断言错误seed随机种子默认 0用于结果复现参数校验逻辑值得展开说明。speech()方法内部按模型名分支断言模型名包含Instruct时禁止传入prompt_speech与prompt_text即 Instruct 版本不接受参考音频进行克隆它只能基于预设音色 指令文本来控制表现力模型名包含SFT时除上述两项外还禁止instruct_text对于 CosyVoice-300M零样本/跨语言版与 CosyVoice2允许prompt_speech等克隆参数。这也是“Instruct 模型虽然注册了text2audio_zero_shot能力但实际定位是指令控制而非音色克隆”的源码证据。调用后的内部处理当请求进入_speech_handle()后会按如下优先级分发到 CosyVoice 底层方法有prompt_speech且无instruct_text→inference_cross_lingual跨语言300M 模型有prompt_speechprompt_text→inference_zero_shot零样本克隆无prompt_speech且有instruct_text→inference_instruct指令控制本模型核心路径无prompt_speech且无instruct_text→inference_sft普通文本转语音。非流式调用会把输出的tts_speech张量拼接后通过audio_to_bytes编码为指定格式的字节流返回流式调用streamTrue则通过audio_stream_generator逐块产出编码后的音频。测试用例 test_cosyvoice.py 验证了流式pcm输出遍历生成器并写入文件后断言分块数量大于 5且每个分块均为非空字节。结果可复现seed 机制与许多生成式模型一样CosyVoice 的推理带随机性。speech()在调用底层推理前会执行set_all_random_seed(seed)见 utils.py 中的set_all_random_seed辅助函数seed参数默认值为 0。若你的业务需要对同一文本 指令产出稳定一致的音频例如批量评测或缓存场景可以在每次调用中显式传入相同的seed。源码实现与测试证据模型类实现CosyVoice 家族含本模型在 Xinference 中的实现位于 cosyvoice.pyCosyVoiceModel.__init__记录model_uid、model_path、model_spec与设备信息并通过_is_cosyvoice2标志区分 1.x / 2.x 加载路径load()将xinference/thirdparty加入sys.path后从cosyvoice.cli.cosyvoice导入CosyVoice支持compile别名load_jit开关speech()完成参数校验、随机种子设置并调用_speech_handle()_speech_handle()按前述优先级分发到inference_sft/inference_instruct/inference_zero_shot/inference_cross_lingual最终统一产出流式或非流式音频字节。模型实例的分发入口在 core.py 的create_audio_model_instance当model_family CosyVoice时统一实例化CosyVoiceModel。测试用例仓库为 CosyVoice 家族准备了专门的集成测试 test_cosyvoice.py其中test_cosyvoice_instruct以CosyVoice-300M-Instruct与CosyVoice2-0.5B为参数化对象覆盖了 Instruct 模型的两种典型调用不带指令的普通合成model.speech(文本, voice中文男)断言返回非空字节流且可写入 mp3 文件带指令的合成在voice中文男基础上追加instruct_text一段英文角色描述同样断言输出有效。该测试还展示了launch_model中download_hubmodelscope的用法。注意测试文件头部带有pytest.mark.skip(reasonThe diffusers on the GPU CI action is not compatible.)跳过标记——这是 CI 环境依赖兼容性问题不代表功能不可用。在 Web UI 与集群环境中使用除了 CLI 与 Python Client你还可以在 Xinference 的 Web UI 中完成启动进入Launch Model页面模型类型选择audio搜索CosyVoice-300M-Instruct按需填写参数如download_hub、compile后点击启动。启动成功后在Running Models页面选中该模型实例即可在 Speech 面板中直接输入文本、选择音色并试听合成结果。在多机分布式部署场景下该模型与其他音频模型一样通过 Xinference 统一的模型生命周期管理运行其启动、缓存、虚拟环境等行为均遵循 audio.rst 中描述的音频模型通用机制包括多引擎模型的--model-engine选择规则——CosyVoice 家族当前使用默认的 PyTorch/CosyVoice 运行时。小结CosyVoice-300M-Instruct 是 Xinference 内置的指令可控多语言 TTS 模型其核心价值在于通过instruct_text用自然语言描述语气与表现力同时保持预设音色、多语言支持与 OpenAI 兼容 API 的易用性。本文从模型元信息、启动命令、调用示例、参数契约到源码实现与测试证据完整还原了该模型在 Xinference 中的落地方式。如果你的场景需要在“不引入参考音频”的前提下精细控制合成语音的角色感与语调这个模型是文档明确推荐的选择若你需要的是基于参考音频的音色克隆则应选用 CosyVoice-300M 或 CosyVoice2-0.5B。更多 CosyVoice 家族的完整用法零样本克隆、跨语言合成、流式输出可继续阅读 audio.rst 的 CosyVoice Usage 小节。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考