[PR #10] Add MiniMax Music 3 NVFP4 export contracts #10

New issue

Open

opened 2026-10-26 22:29:00 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:29:00 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-quants/pull/10
Author: @somewheresy
Created: 8/14/2026
Status: 🔄 Open

Base: main ← Head: codex/minimax-music3-nvfp4

📝 Commits (2)

c948395 Add MiniMax Music 3 NVFP4 export contracts
ee42306 Annotate MiniMax Music 3 test helpers

📊 Changes

11 files changed (+676 additions, -0 deletions)

View changed files

➕ configs/minimax_music3_dit_nvfp4.yaml (+33 -0)
➕ configs/minimax_music3_text_encoder_nvfp4.yaml (+34 -0)
📝 docs/quantization/README.md (+2 -0)
➕ docs/quantization/minimax_music3.md (+86 -0)
📝 docs/quantization/nvfp4.md (+14 -0)
📝 src/comfy_quants/comfy/artifact_contracts.py (+18 -0)
➕ src/comfy_quants/model_adapters/minimax_music3.py (+304 -0)
📝 src/comfy_quants/model_adapters/registry.py (+1 -0)
📝 tests/unit/test_comfy_alignment.py (+10 -0)
📝 tests/unit/test_config_and_cli.py (+14 -0)
➕ tests/unit/test_minimax_music3_contract.py (+160 -0)

📄 Description

Problem

ComfyUI now supports MiniMax Music 3 and has a native NVFP4 runtime, but comfy-quants has no producer contract or recipe for either of Music 3's separately loaded model files.

Change

add static contracts/adapters for the 36-block Music 3 DiT and 36-block AR encoder plus 4-block RVQ depth decoder
add pinned NVFP4 export configs for both published Comfy-Org safetensors files
conservatively keep embeddings, logits heads, norms, convolutions, and boundary projections high precision
document the two-file export flow, model-identity guardrail, licensing caveat, and Blackwell validation checklist
register artifact contracts and add focused shape/selection/config tests

The contracts were checked against the safetensors headers at Comfy-Org/MiniMax-Music-3 revision 6444666eb6edfb2c7fcab5f8b81da8b84b4b17b6: 144/144 selected DiT tensors and 160/160 selected AR/RVQ tensors matched by name and shape. Every selected input dimension is block-16 aligned.

Tests

uv run --python 3.13 --with pytest --with torch --with numpy pytest -q
- 258 passed, 20 skipped, 43 subtests passed
uvx ruff check --select E,F,I src/comfy_quants/model_adapters/minimax_music3.py tests/unit/test_minimax_music3_contract.py
git diff --check

Validation status

This validates the producer contract, packing path, names, shapes, and loader metadata. I have not yet run the resulting full-size checkpoints through Music 3 on Blackwell hardware, so audio-quality parity and sustained-generation VRAM behavior remain explicit follow-up gates before publishing model artifacts.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-quants/pull/10 **Author:** [@somewheresy](https://github.com/somewheresy) **Created:** 8/14/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/minimax-music3-nvfp4` --- ### 📝 Commits (2) - [`c948395`](https://github.com/Comfy-Org/comfy-quants/commit/c948395bd23f82f7a7dba1922e02d0a539005cb8) Add MiniMax Music 3 NVFP4 export contracts - [`ee42306`](https://github.com/Comfy-Org/comfy-quants/commit/ee4230657641acfc481b62eb2961a7948f1cb7d6) Annotate MiniMax Music 3 test helpers ### 📊 Changes **11 files changed** (+676 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `configs/minimax_music3_dit_nvfp4.yaml` (+33 -0) ➕ `configs/minimax_music3_text_encoder_nvfp4.yaml` (+34 -0) 📝 `docs/quantization/README.md` (+2 -0) ➕ `docs/quantization/minimax_music3.md` (+86 -0) 📝 `docs/quantization/nvfp4.md` (+14 -0) 📝 `src/comfy_quants/comfy/artifact_contracts.py` (+18 -0) ➕ `src/comfy_quants/model_adapters/minimax_music3.py` (+304 -0) 📝 `src/comfy_quants/model_adapters/registry.py` (+1 -0) 📝 `tests/unit/test_comfy_alignment.py` (+10 -0) 📝 `tests/unit/test_config_and_cli.py` (+14 -0) ➕ `tests/unit/test_minimax_music3_contract.py` (+160 -0) </details> ### 📄 Description ## Problem ComfyUI now supports MiniMax Music 3 and has a native NVFP4 runtime, but comfy-quants has no producer contract or recipe for either of Music 3's separately loaded model files. ## Change - add static contracts/adapters for the 36-block Music 3 DiT and 36-block AR encoder plus 4-block RVQ depth decoder - add pinned NVFP4 export configs for both published Comfy-Org safetensors files - conservatively keep embeddings, logits heads, norms, convolutions, and boundary projections high precision - document the two-file export flow, model-identity guardrail, licensing caveat, and Blackwell validation checklist - register artifact contracts and add focused shape/selection/config tests The contracts were checked against the safetensors headers at Comfy-Org/MiniMax-Music-3 revision `6444666eb6edfb2c7fcab5f8b81da8b84b4b17b6`: 144/144 selected DiT tensors and 160/160 selected AR/RVQ tensors matched by name and shape. Every selected input dimension is block-16 aligned. ## Tests - `uv run --python 3.13 --with pytest --with torch --with numpy pytest -q` - 258 passed, 20 skipped, 43 subtests passed - `uvx ruff check --select E,F,I src/comfy_quants/model_adapters/minimax_music3.py tests/unit/test_minimax_music3_contract.py` - `git diff --check` ## Validation status This validates the producer contract, packing path, names, shapes, and loader metadata. I have not yet run the resulting full-size checkpoints through Music 3 on Blackwell hardware, so audio-quality parity and sustained-generation VRAM behavior remain explicit follow-up gates before publishing model artifacts. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-26 22:29:00 +00:00

No labels

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Comfy-Org/comfy-quants#10

No description provided.

Rows
Columns