XB-BOX - 🔊 CosyVoice3 模型加载

Every CosyVoice3 workflow in XB_ToolBox starts here, and honestly it does the part most people dread: getting the model downloaded, installed, and loaded without a Python terminal session.

CosyVoice3 (FunAudioLLM's Fun-CosyVoice3-0.5B, released December 2025) is the open TTS people keep comparing to the paid stuff. Its superpower is zero-shot voice cloning from just a few seconds of audio, and the community shorthand for it is "max speaker similarity" - which is a nice way of saying the clone actually sounds like the person. The annoying part was that older CosyVoice node packs were written for CosyVoice1 and never updated for the v3 format. This loader, part of the Chinese-ecosystem XB-BOX suite (WJLUOXIAO's pack aimed squarely at ComfyUI beginners and AMD GPU users), is one of the first to treat CosyVoice3 as a first-class citizen.

How it works

Pick a model version and the node does the rest. Three are on the menu:

• Fun-CosyVoice3-0.5B - the default and the one you want. 0.5B params, launched with v3.
• CosyVoice2-0.5B - the previous generation, if you have a specific reason to use it.
• CosyVoice-300M - the original 300M model, mostly for nostalgia or CPU-bound projects.

On first run it downloads the weights into ComfyUI/models/cosyvoice/<version>/ and keeps them there, so subsequent runs are instant. download_source flips between HuggingFace and ModelScope, and if your primary source fails it silently tries the other one - handy if you're in a region where one of them is slow or blocked. device defaults to auto, which just means "whatever device ComfyUI is already running on" (so on a ROCm or DirectML setup it lands on the right one without you thinking about it).

The pack ships its own vendored copy of the CosyVoice code, so it won't fight a pip-installed version of CosyVoice over library versions. That matters more than it sounds: dependency hell is the default failure mode of TTS in ComfyUI, and this sidesteps the worst of it.

The inputs that matter

Three required, two optional, and you'll touch maybe two of them:

• model_version - the dropdown described above. Default is already the right answer.
• download_source - HuggingFace or ModelScope. Change it only if the default is slow for you.
• device - auto is correct for almost everyone.
• force_redownload - re-fetch weights even though they exist. Only for when a download got corrupted.
• force_reload - skip the in-memory cache and rebuild the model object. Useful after switching between two versions in one session.

It outputs a single model (COSYVOICE_MODEL) - that's the handle every synthesis node in the suite (ZeroShot, SpeakerClone, VoiceConversion, etc.) plugs into. You load one model per graph and feed it to all of them.

Install and gotchas

The pack itself installs via ComfyUI Manager (search XB_ToolBox) or:

cd ComfyUI/custom_nodes && git clone https://github.com/wjluoxiao/XB_ToolBox.git

then restart ComfyUI. The README claims no extra pip dependencies, but that's aspirational - the CosyVoice nodes need modelscope, huggingface_hub, transformers, librosa, soundfile, onnxruntime, and openai-whisper. If you get an ImportError, run:

pip install -r ComfyUI/custom_nodes/XB_ToolBox/requirements.txt

Two real-world gotchas. First, the first load downloads a few gigabytes - don't panic when the console sits on "Downloading" for a while. Second, CosyVoice needs ffmpeg for audio decoding; the node finds the imageio-ffmpeg fallback if you don't have one on PATH, so usually it just works.

One more thing worth knowing: v3 expects reference text prefixed with You are a helpful assistant.<|endofprompt|>, and the suite handles that formatting for you internally. You'll never type it, but it explains why the console output looks the way it does.