
Xinference 内置 CosyVoice2-0.5B 语音合成模型部署命令、四种推理模式与 OpenAI 兼容调用指南【免费下载链接】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/inferenceCosyVoice2-0.5B 是 Xinference 以内置模型形式收录的多语言语音合成TTS模型属于 CosyVoice 模型家族支持普通文本合成、零样本音色克隆与跨语种合成三种能力。本文基于 cosyvoice2-0.5b.rst 模型卡片结合 cosyvoice.py 实现、model_spec.json内置模型注册表与POST /v1/audio/speech接口源码完整讲解从启动命令、参数配置到代码调用与流式输出的全流程。读完本文你将掌握如何用一条xinference launch命令拉起该模型并通过 Python 客户端与 OpenAI 兼容 API 完成普通合成、零样本克隆、跨语种与指令控制等四种典型场景。一、模型卡片速览规格与能力Xinference 官方文档中的模型卡片cosyvoice2-0.5b.rst给出了该内置模型的核心元信息属性值Model NameCosyVoice2-0.5BModel FamilyCosyVoiceAbilitiestext2audio、text2audio_zero_shot、text2audio_voice_cloningMultilingualTrueModel IDJunHowie/CosyVoice2-0.5B三种能力的含义如下text2audio普通文本到语音合成SFT 推理模式直接指定音色即可生成语音text2audio_zero_shot零样本音色克隆zero-shot 推理模式给定一段参考音频与参考文本即可模仿该音色text2audio_voice_cloning声音克隆能力配合prompt_speech参考音频使用可进一步做跨语种cross-lingual合成。在仓库的内置音频模型注册表 model_spec.json 中该模型注册为version: 2、model_family: CosyVoice模型权重同时托管于 Hugging Face 与 ModelScope 两个渠道详见第三节。二、一条命令启动模型命令行参数详解模型卡片给出的标准启动命令为xinference launch --model-name CosyVoice2-0.5B --model-type audio其中--model-name-n指定模型名称CosyVoice2-0.5B该名称必须与内置模型注册表一致--model-type-t指定模型类型为audio默认值是LLM语音模型必须显式指定为audio。从 cmdline.py 的model_launch命令定义看围绕音频模型常用的启动参数还包括参数简写默认值说明--model-uid-uNone自定义模型 UID用于后续 API 调用时定位模型实例--model-path-mpNone本地模型目录路径不指定时由 Xinference 自动从远端缓存下载--replica-r1模型副本数--n-worker—1使用的 worker 数--n-gpu—auto模型使用的 GPU 数量n_worker 1时表示每个 worker 使用的 GPU 数--gpu-idx—None指定该模型可运行的 GPU 编号多个用逗号分隔--worker-ip—None分布式场景下指定模型运行的 worker 节点 IP--enable-virtual-env—None为模型创建独立虚拟环境后安装依赖--disable-virtual-env—None关闭虚拟环境--virtual-env-package-vp—追加需要安装到虚拟环境中的 Python 包可多次指定--api-key-akNone启用鉴权时访问 Xinference API 的密钥CosyVoice2-0.5B 依赖 PyTorch 生态建议部署在有 CUDA GPU 的环境上。由于该模型权重较大、依赖较多推荐保留默认的虚拟环境机制详见第三节由 Xinference 自动隔离安装运行依赖。三、模型权重来源与运行依赖3.1 双渠道下载源根据 model_spec.json 中的model_src字段CosyVoice2-0.5B 支持从两个渠道获取权重Hugging FaceJunHowie/CosyVoice2-0.5B固定 revision7ac9e9a026aec35efe48cde1196eaad6a00ad5f2ModelScopeiic/CosyVoice2-0.5Brevision 为master。Xinference 在match_audio见 core.py中会根据环境变量或显式传入的download_hub决定优先从哪个渠道拉取权重。如需强制指定下载源可在启动时附加参数# 从 ModelScope 下载国内网络环境通常更快 xinference launch --model-name CosyVoice2-0.5B --model-type audio --download-hub modelscopedownload_hub的可选值包括huggingface、modelscope、openmind_hub、csghub。3.2 虚拟环境依赖清单CosyVoice 系列模型依赖较多且版本敏感model_spec.json为 CosyVoice2-0.5B 注册了独立的virtualenv.packages依赖集合包括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。这些依赖会被安装到该模型专属的虚拟环境中避免与主进程环境相互污染。四、源码视角CosyVoice2 的加载与调度链路4.1 引擎分发在 core.py 的create_audio_model_instance中模型分发逻辑为model_family CosyVoice时统一实例化 CosyVoiceModel加载权重前会先通过CacheManager完成模型缓存与解压。因此用户无需手工准备模型目录首次启动时 Xinference 会自动完成下载与缓存。4.2 模型加载细节CosyVoiceModel.load() 的实现揭示了几个关键点当模型名称包含CosyVoice2时从cosyvoice.cli.cosyvoice导入CosyVoice2类并置位_is_cosyvoice2 True支持 JIT 编译加速参数load_jit兼容历史命名compile可通过 kwargs 传入以启用即时编译CosyVoice2 特有的spk2info.pt说话人信息文件会被加载到模型 frontend 中为音色克隆与零样本能力提供基础。可见 Xinference 对 CosyVoice2-0.5B 与 CosyVoice-300M 系列做了差异化处理CosyVoice2 是能力最全的一档同时允许prompt_speech、prompt_text与instruct_text的组合使用见下文第五节的推理分支判断。五、调用合成能力四种推理模式与参数说明5.1 speech() 参数总览Xinference 对音频模型统一暴露speech()方法Python 客户端实现见 restful_client.pyCosyVoice2-0.5B 支持以下参数参数类型默认值说明inputstr必填待合成文本最长 4096 字符voicestr空音色名称为空时自动选择第一个可用音色response_formatstrmp3输出音频格式支持 mp3、wav、pcm、flac、ogg、opus 等speedfloat1.0语速倍率streamboolFalse是否流式返回音频prompt_speechbytesNone参考音频字节流零样本/跨语种/指令模式使用prompt_textstrNone参考音频对应的文本零样本模式必需instruct_textstrNone指令文本情感/风格控制seedint0随机种子用于结果复现5.2 四种推理模式的分派规则cosyvoice.py 的_speech_handle按照“是否提供prompt_speech参考音频”与“是否提供instruct_text指令”组合出四种模式SFT 普通合成不提供prompt_speech仅指定voice或自动选择音色。适合常规文本转语音测试用例中出现的音色包括中文女、中文男、日语男、粤语女、英文女、英文男、韩语女。Zero-shot 零样本克隆提供prompt_speech与prompt_text模型学习参考音频的音色并朗读新文本。Cross-lingual 跨语种合成仅提供prompt_speech而不提供prompt_text用参考音色朗读其他语言文本如测试中把中文音色用于英文长句。Instruct 指令控制提供instruct_text控制情感/风格CosyVoice2 在无参考音频时走inference_instruct配合voice同时提供参考音频时走inference_instruct2实现用指定音色 指令风格的精细控制。从speech()中的断言逻辑可以确认CosyVoice2-0.5B 是 CosyVoice 家族中唯一允许prompt_speech与instruct_text同时出现的版本elif self._is_cosyvoice2: pass分支直接放行因此它同时覆盖了 SFT 模型的三种受限能力。5.3 Python 客户端调用示例from xinference.client import Client client Client(http://127.0.0.1:9997) model_uid client.launch_model( model_nameCosyVoice2-0.5B, model_typeaudio, download_hubmodelscope, ) model client.get_model(model_uid) # 1) 普通合成SFT指定音色 audio_bytes model.speech(你好欢迎使用 Xinference 语音合成服务。, voice中文女) # 2) 零样本音色克隆 with open(prompt.wav, rb) as f: prompt_speech f.read() audio_bytes model.speech( 收到好友从远方寄来的生日礼物那份意外的惊喜让我心中充满了甜蜜的快乐。, prompt_text希望你以后能够做的比我还好呦。, prompt_speechprompt_speech, ) # 3) 指令控制情感/风格 audio_bytes model.speech( 在面对挑战时他展现了非凡的勇气与智慧。, voice中文男, instruct_textTheo is a fiery, passionate rebel leader who fights with fervor for justice., ) # 4) 流式输出为 PCM 音频 for chunk in model.speech(流式合成测试。, streamTrue, response_formatpcm): handle_chunk(chunk) # 逐块写入文件或直接播放六、OpenAI 兼容 API/v1/audio/speech6.1 路由与请求体Xinference 的音频服务注册在 audio.py合成端点即 OpenAI 兼容的POST /v1/audio/speech其请求体 SpeechRequest 定义如下字段类型默认值说明modelstr必填模型 UID即启动时的--model-uidinputstr必填待合成文本voicestrNone音色response_formatstrmp3输出格式speedfloat1.0语速streamboolFalse是否流式kwargsstrNone额外参数的 JSON 字符串可携带prompt_text、instruct_text、seed等当需要上传参考音频时prompt_speech、prompt_latent作为 multipart 文件字段上传见 restful_api.py 的create_speech。6.2 直接使用 OpenAI SDK由于接口与 OpenAI 兼容可以直接用官方openaiPython 库调用import openai client openai.Client(api_keynot empty, base_urlhttp://127.0.0.1:9997/v1) response client.audio.speech.create( modelmodel_uid, # 启动模型时返回的 UID input你好我是通义生成式语音大模型。, voice英文女, ) response.stream_to_file(output.mp3)这正是 test_cosyvoice.py 中验证过的调用方式先通过client.launch_model(...)启动模型再分别走 Xinference 原生model.speech(...)与 OpenAI SDK 两种途径生成音频并断言输出非空。6.3 响应格式与媒体类型create_speech会根据response_format设置正确的Content-Type。支持的格式与媒体类型映射见 restful_api.py 的_AUDIO_RESPONSE_MEDIA_TYPES格式Content-Typemp3 / mpegaudio/mpegwav / waveaudio/wavpcmaudio/pcmflacaudio/flacogg / opusaudio/oggaacaudio/aacm4aaudio/mp4webmaudio/webm其中pcm为 16-bit 单声道裸 PCM 流流式场景下 audio_stream_generator 会基于torchaudio的 StreamWriter或新版 TorchCodec 兼容路径实时编码分块输出并自动剥离 WAV 头保证客户端拿到的每一块都是可直接播放的 PCM 数据。七、测试用例佐证能力覆盖与双下载源验证仓库中的集成测试 test_cosyvoice.py 以[CosyVoice-300M-SFT, CosyVoice2-0.5B]、[CosyVoice-300M, CosyVoice2-0.5B]、[CosyVoice-300M-Instruct, CosyVoice2-0.5B]三组参数对 CosyVoice2-0.5B 进行了全覆盖验证test_cosyvoice_sft验证普通合成、OpenAI SDK 调用、流式 PCM 输出断言流式迭代超过 5 个数据块并同时验证了 Hugging Face 与 ModelScope 两个下载源都能成功启动test_cosyvoice使用仓库自带的zero_shot_prompt.wav与cross_lingual_prompt.wav参考音频验证零样本克隆与跨语种合成并把结果写入.mp3文件确认有效test_cosyvoice_instruct对 CosyVoice2 验证参考音频 指令文本组合对 Instruct 系列验证音色 指令文本组合。上述测试同时表明CosyVoice2-0.5B 是本仓库 CosyVoice 家族中能力覆盖最完整的内置模型一条命令即可同时获得 SFT、zero-shot、cross-lingual、instruct 全部四种合成能力并通过统一的 Xinference 音频 API 对外提供服务。八、适用前提与注意事项运行环境CosyVoice2-0.5B 依赖 PyTorch 与 CUDA GPU建议在 GPU 节点部署model_spec.json未为该模型注册 CPU 或 MLX 引擎变体依赖隔离模型使用独立虚拟环境安装diffusers0.29.0、transformers4.51.3等固定版本依赖首次启动需要下载权重并创建环境耗时较长属正常现象音色名称内置音色以voice参数指定如中文女未指定时自动选取第一个可用音色传入不存在的音色会触发断言错误输入长度单次合成文本上限 4096 字符长文本建议分段合成或使用流式接口结果复现通过seed参数默认 0固定随机种子可提高多次合成的可复现性。 /输出文章【免费下载链接】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),仅供参考