YuE2-3B on RTX 3090 Ti: full songs, and the host RAM it needs

What You'll Build

A finished song — vocals and accompaniment, 48 kHz stereo — produced on a single RTX 3090 Ti from a style prompt and a lyric sheet, alongside the editable ABC score the model planned it from, so a revised melody or harmony can be re-rendered as the same song.

Hardware data: RTX 3090 Ti (24GB VRAM) · no run on this card has been published by anyone · budget derived from the shipped code · See benchmark data

⚠️ The weights are non-commercial. YuE2's code is Apache 2.0, but the checkpoints this recipe downloads are CC BY-NC 4.0. The repository's LICENSE says the weights are "licensed under Creative Commons Attribution-NonCommercial 4.0 International" and scopes that to "the YuE2 checkpoint weights in model.safetensors, or the corresponding" model files. On GitHub the vendor splits the two explicitly: "YuE2's first-party code, agent skill, and documentation are licensed under" Apache 2.0, while "Model weights are separately licensed under" CC BY-NC 4.0. The licence text names the weights and does not address the audio you generate with them — if you intend to release or monetise output, read the full licence rather than this paragraph.

ℹ️ One runtime, and it is a Python wheel. YuE2-3B runs through the vendor's own yue2 package on Linux with CUDA. There is no llama.cpp, Ollama, LM Studio or ComfyUI path — see Troubleshooting for what the GGUF files on the Hub are and are not.

⚠️ This page carries no speed number, because none exists. The vendor benchmarked two GPUs and this is not one of them, and no published measurement of YuE2-3B names an Ampere card. What follows derives the fit from the library's own source; where a number belongs to a different GPU, the sentence says whose it is.

Requirements

Both vendor surfaces state a capacity and neither states an architecture: the model card says "Linux · Python 3.10+ · 24GB NVIDIA GPU with BF16 support." and the GitHub repository says "Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM.". The 24GB is a recommendation rather than a limit the software imposes; the floor the shipped code actually produces is worked out in Troubleshooting.

Installation

1. Install the inference package into a dedicated virtual environment

These three lines are the model card's quick start, unchanged:

python3 -m venv .yue2 && source .yue2/bin/activate
python -m pip install huggingface-hub==0.36.2
hf download m-a-p/YuE2-3B yue2_infer-0.1.5-py3-none-any.whl --local-dir .
python -m pip install ./yue2_infer-0.1.5-py3-none-any.whl

Make a fresh virtual environment first and activate it. Every one of the wheel's eight runtime dependencies is an exact == pin — torch==2.10.0, transformers==4.57.6, huggingface-hub==0.36.2, safetensors==0.7.0, tiktoken==0.12.0, numpy==2.2.6, soundfile==0.13.1, accelerate==1.13.0, taken from the wheel's own METADATA and matching the repository's pyproject.toml — and an exact pin does not step aside for a newer version that is already installed, it replaces it. The first casualty is already on record: a ComfyUI user reported on 2026-09-10 that this wheel rewrote their PyTorch 2.11 install down to 2.10 and their launcher stopped working.

The wheel this recipe installs is 0.1.5, the version the model card's quick start names; the repository tree is 0.1.6, and the source files this recipe cites are byte-identical between the two, so everything below holds for either install path. The pins also match the versions the vendor used for the numbers in Results.

Install PyTorch's CUDA build first if your environment would otherwise resolve a CPU-only wheel.

2. Confirm the card and the dependencies

The package ships a yue2 command whose doctor subcommand prints your card's name, its memory in GiB and its compute capability, alongside the resolved version of every pinned dependency:

yue2 doctor

Read dependencies_ready and the cuda array in the JSON it prints. doctor reports environment readiness only — the vendor's own note in that output is explicit that it is not an acceptance test. It does not report host RAM, and neither does anything else in the package; see the first Troubleshooting entry for why that matters here.

3. Let the loader fetch the weights

The first pipeline call downloads what it needs from m-a-p/YuE2-3B and m-a-p/YuE2-Vae. The loader uses an explicit allow-list (src/yue2/storage.py L33-39) rather than a full clone, so the demo audio and images in those repositories are not downloaded — that is why the Storage row above is 7.79 GB and not the 7.83 GB the two repositories hold in total.

Running

Load the pipeline once, then generate:

from pathlib import Path
from yue2 import YuE2Pipeline

pipe = YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda")

Then run the vendor's own example prompt, which is shipped inside the model repository:

import json
from huggingface_hub import hf_hub_download

repo = "m-a-p/YuE2-3B"
prompt_path = hf_hub_download(repo, "examples/tonight-awake.json")
demo = json.loads(Path(prompt_path).read_text(encoding="utf-8"))
style, lyrics = demo["style"], demo["lyrics"]

song = pipe(style=style, lyrics=lyrics, cot="full", seed=demo["seed"])
song.save("song.flac")
song.save_artifacts("outputs/song")  # ABC, tokens, latents, audio and settings

song.flac is the finished stereo song. outputs/song holds the ABC score, the semantic tokens, the acoustic latents and the exact settings used — edit score.abc and pass it back as abc= to re-render the same song with a revised melody or harmony.

The same three modes are available from the shell, which is the easier path when you want to queue several songs:

yue2 generate --cot full --style "Mandarin funk, nu-disco" --lyrics-file lyrics.txt --output outputs/song

cot="full" plans melody and chords and is the default; cot="melody" plans melody only and is what the vendor recommends for covers; cot="off" generates with no symbolic plan. The default decoder is m-a-p/YuE2-Vae; pass vae="m-a-p/YuE2-Vae-legacy" to from_pretrained to reproduce the published benchmark protocol instead.

Results

Everything numeric in this section belongs either to the checkpoint — in which case it is the same wherever you load it — or to the one consumer card the vendor benchmarked, which is not this one. Nothing here was measured on an RTX 3090 Ti, by us or by anybody else.

• Speed — nothing to report for this card. The vendor's own consumer-GPU row is an Ada board: 139.48 LM tokens/s in cot="full", 214.85 s of audio produced in 71.04 s of wall clock, summarised on the card as "A 3.6-minute song in 71 seconds on an RTX 4090." (model card). Ada is a generation newer than the Ampere silicon in this board, so the uncertainty runs downward from that figure: it is a ceiling this card sits below by an unknown margin, never a floor it clears. Method, verbatim: "HF: PyTorch 2.10, Transformers 4.57.6, no quantization, default YuE2-Vae." and "4090 values average 32 warm requests per mode". The runtime is described as "The HF package uses PyTorch, CUDA graphs, and FlashAttention, with BF16 AR/NAR and FP32 VAE."
• VRAM usage — the vendor's readings, on the vendor's card. 11.18 GiB peak in full mode, 11.02 GiB in melody, 11.09 GiB in off. These are NVML readings — "NVML records the full-run GPU peak." — so they include the CUDA context, not only the allocator. The vendor separately notes that "maximum-context testing peaked at" 14.08 GiB.
• Which figures inside that peak you can rely on, and why the rest will not separate: two of them are exact and fixed properties of the checkpoint — the AR/NAR weights are 6.763 GiB in BF16 and the VAE decoder is 0.494 GiB, byte counts read from the Hugging Face tree API on 2026-09-10 (YuE2-3B, YuE2-Vae). What they are not is two components of one peak. The pipeline parks the language model in host RAM before the decoder is ever put on the card — decode() at src/yue2/pipeline.py L323-324, the cache flush at L326, the VAE's CPU load and device move at L331-333 and its return to the host at L354, which the host-RAM section below covers in full. The remainder of the 11.18 GiB — KV cache, activations, CUDA-graph pools, CUDA context — has no published breakdown, and the model card does not name the stage the NVML reading came from, so this page does not offer one.
• Headroom: with 12.82 GiB of raw capacity left over after an 11.18 GiB peak, the constraint you will actually meet first is the library's own 22 GiB process ceiling, derived in Troubleshooting — not the physical 24GB.
• Throughput: "One song at a time." The pipeline is not a batching server; the batch subcommand queues requests, it does not run them concurrently on this path.
• Quality notes: the vendor reports a 6.7316 SongBench average for YuE2 and 6.9632 for its best-of-8 setting across 192 WildSongBench prompts, using the legacy decoder. Those are the vendor's own automatic metrics under its own candidate-selection protocol, not an independent evaluation, and they describe the model rather than any particular GPU.

No benchmark exists for this pair. If you run it, please send us the numbers — a measured figure replaces the vendor's on /check/yue2-3b/rtx-3090-ti, which is where the live data for this pair lands.

Troubleshooting

The other 24GB — system RAM, and the fact that nothing checks it

The vendor's requirements line asks for "24GB available host RAM" alongside the GPU. Across the model card and the GitHub repository README that number appears exactly once, in that one sentence — every other requirement line either says VRAM or says nothing about memory at all — and no code enforces it: a case-insensitive search of all fourteen modules in the installed wheel for psutil, virtual_memory, MemAvailable, available_ram and host ram returns nothing, while the same search over the same files for low_cpu_mem_usage and torch.cuda.get_device_properties returns five hits — so the files are being read and the absence is real.

It is load-bearing anyway, because this pipeline deliberately shuttles the model between the card and the CPU. Before the audio decoder is loaded, decode() moves the whole AR/NAR model to the host (src/yue2/pipeline.py L323-324), loads the VAE on the CPU first and then moves it onto the device (L331-333), and returns it to the host in the finally (L354). So for the whole of the decode stage the 6.763 GiB BF16 checkpoint is resident in system RAM. The optional --offload-ar flag moves the same weights host-side again during the NAR stage.

That is the largest host-resident object anyone can put a byte count on; the torch and CUDA runtime footprint, pinned staging buffers and the downloader's working set are not quantities any published source bounds, so this recipe does not tell you that 16 GB of system RAM is enough. The practical half is the failure mode: because nothing checks, a shortfall does not raise a YuE2 error. The machine swaps, or the kernel's OOM killer ends the process — neither of which will mention this package.

Does an Ampere board clear the runtime's hardware tests?

Yes, and there are only two of them to clear. The pipeline's constructor calls torch.cuda.is_bf16_supported() and raises The unquantized preset requires CUDA BF16 support if it returns false (src/yue2/pipeline.py L159-160); BF16 is supported on this generation, so it passes. The second test guards the optional FP8 mode below and the default path never reaches it.

Nothing else consults the device's compute capability. The attention backend is chosen from the dtype and a head dimension of 128 (from the model's config.json) and degrades from PyTorch's fused FlashAttention to cuDNN to plain SDPA rather than failing, with no architecture test in that chain — and there is no flash-attn package involved at all, which the runtime states in its own comment: "CUDA normally uses PyTorch's fused SDPA without an external flash package." The pinned torch==2.10.0 also ships kernels for this silicon: the PyPI release's Linux x86_64 dependency set pins nvidia-cuda-runtime-cu12==12.8.90, i.e. the CUDA 12.8 build, whose architecture list in PyTorch's release script is 7.0;7.5;8.0;8.6;9.0;10.0;12.0 — and 8.6 is the compute capability of this board's GA102.

Experimental FP8 AR requires CUDA compute capability >=8.9

One optional mode is closed to this generation. Setting quantization="fp8" reaches the only compute-capability test in the package (src/yue2/quantization.py L71-72), which demands 8.9 or newer.

Nothing measurable is lost. Its own module docstring introduces it as "Opt-in experimental FP8 AR linear layers; NAR always restores exact BF16." and warns that "No quantized quality or speed claim is implied by enabling this module.", and the runtime's status output marks both its quality and its performance validation unvalidated. Every published figure was taken with the default quantization="none", and an unquantized load fits a 24GB board comfortably. Do not change it.

Memory budget must leave room for a 2GiB reserve — and where the 16GB floor comes from

memory_budget_gib defaults to 24 and is then clamped against the hardware: the constructor reads total device memory and takes the smaller of memory_budget_gib − 2 and total − 2 GiB, applying it with set_per_process_memory_fraction (src/yue2/pipeline.py L161-165). Only capacity enters that expression, so the ceiling is reproducible across cards of the same size:

• A 24GB board, this one included: about 22 GiB either way, the two terms coinciding within rounding at this capacity. The 11.18 GiB ordinary peak and the 14.08 GiB maximum-context peak both sit well inside it.
• A 16GB board: 14 GiB, and the whole range fits. Measured here on an RTX 5060 Ti 16GB (2026-09-10, WSL2, driver 591.86): an ordinary song peaked at 10.05 GiB — below the vendor's own 4090 figure — and a deliberately full-context song run with the second CFG branch, the worst case the library can be put in, peaked at 13.48 GiB on the device and 12.64 GiB in-process, leaving 1.29 GiB under the clamp. No OOM in any run. An earlier version of this page said a maximum-context song would not fit 16GB; that was wrong, and wrong in an instructive way — it compared the vendor's 14.08 GiB, which is a device peak, against a ceiling set_per_process_memory_fraction imposes on the process. A device peak includes whatever a monitor is holding; the clamp never sees it.
• A 12GB board: 10 GiB, below the 11.18 GiB the vendor measured for the ordinary case. The documented install does not fit, and it fails as an allocator error rather than as the message above.

Trading context for memory is not on offer: the generation config rejects any context but 24576 (src/yue2/protocol.py L54-55). Set the budget explicitly when the default is wrong for your machine — YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda", memory_budget_gib=16), or --budget 16 from the shell. A budget of 12 or lower additionally halves the VAE core frame count, which changes the decode path and is not purely a memory setting.

One setting moves memory the other way, and the model card recommends trying it. Its tuning table offers cfg_scale=1.2 to "Experiment with stronger text guidance", and any guidance other than 1 makes the sampler build a second, unconditional branch (src/yue2/sampling.py L92) whose KV cache is allocated with the branch count as its leading dimension (src/yue2/cuda_graph.py L90). So raising it costs additional memory. How much is not published, and it cannot be recovered from the vendor's three-mode table: cot="off" already runs two branches — its default guidance is 1.01 (protocol.py L106) and the branch test is cfg_scale == 1 — yet it is measured at 11.09 GiB, below the 11.18 GiB of cot="full" on one branch. The three modes differ in more than their branch count, so the gaps between them cannot be used to price the second branch. At a 22 GiB ceiling there is room to experiment; at 14 GiB there is far less, and nothing published says how much the branch costs.

The GGUF files on the Hub are not a runtime path

A GGUF conversion of this model exists at audio-cpp/Yue2-3B-GGUF, converted from the same upstream revision this recipe pins. It is not a llama.cpp or Ollama artifact — it targets a separate C++ engine, 0xShug0/audio.cpp, and the GGUF repository's own card says that engine's support for this model is still in development and due to land on the engine's dev branch. That changed hours after this page was first published. The port landed on the engine's dev branch on 2026-09-10 at 17:09 UTC — head 3caeba87, 29 paths including src/models/yue2/, include/engine/models/yue2/ and docs/models/yue2.md — and its author reports a peak below 9 GB and a real-time factor of 0.23 to 0.28 through that engine's UI on an RTX 5090 (vendor issue #163). Treat none of it as transferable here: a different engine running a Q8 quantisation, self-reported by the person who wrote the port, and by his own announcement the model sits in a branch for community testing that “won’t be included in the prebuilt binaries before merging” (discussion 3). If you want it, build the dev branch and expect to be an early tester. This page documents the vendor's Python runtime, which is what every number above was measured on.

No community reports yet

YuE2-3B was published on 2026-09-09. Re-checked on 2026-09-10: m-a-p/YuE2-Vae still has no discussion threads and m-a-p/YuE2-3B has one, opened that day — a usage question about getting reliably instrumental output, tried in the hosted Space and naming no GPU. Ten threads sit on the same organisation's YuE v1 model through the identical endpoint, so the near-silence is the model's age rather than a broken query. The only thread that reports a run is the port author's, and it is through his own C++ engine on a Q8 quantisation rather than the vendor's Python runtime this page documents — a thread count decays by the hour, that predicate does not. Enumerating every GitHub issue that mentions YuE2 on 2026-09-10 returns only items from the release's first two days, and they fall into three kinds: vendor pull requests, requests to port the model to third-party engines, and bug reports against a community ComfyUI wrapper. Not one of them describes a run on an Ampere board. The older hardware threads in the vendor's tracker — AMD, macOS and GGUF alike — all predate YuE2 and were filed against YuE v1, a different model on a different runtime, so their answers do not carry over. The package itself contains no ROCm, HIP or Metal code, and the vendor documents no AMD or Apple route.

If you hit something, please report it via the submission form.