Music3-Mac16

在 Apple Silicon Mac 上本地运行 MiniMax Music 3 的完整实验型工作流。

这个项目解决一个很具体的问题：没有独立显卡、只有 16GB 统一内存的 Mac，能不能真正运行 MiniMax Music3 并生成音乐？

答案是可以。本项目使用 MLX、4-bit 权重、阶段化模型驻留和分块声学生成，把完整模型拆成可控的运行时 working set，并提供：

• CLI 文本生成
• 本地 WebUI
• 中文或英文 Idea → Music 工作流
• 阶段内存与耗时报告
• 不依赖模型权重的自动化测试
• 面向 AI 编程助手的架构说明和实践入口

本项目是社区工程实现，不是 MiniMax 官方实现，也不声称是 GitHub 上的第一个 MiniMax Music3 项目。

先看这里：这个项目已经跑通了什么

当前不是只有设计文档，而是已经在 16GB Apple Silicon 开发机上跑通了真实生成链路：

音乐描述 / 歌词
      │
      ▼
Stage A：Autoregressive
  只物化 language_model + rvq_depth_decoder
  生成 frame hiddens，并确认其已经 mx.eval 物化
      │
      ├── 释放 Stage A 模型引用
      ├── gc.collect()
      ├── mx.synchronize()
      └── mx.clear_cache()
      │
      ▼
Stage B：Acoustic Flow
  重新 lazy load，只物化 condition_encoder、transformer、vocoder
  按 chunk 生成，每个 chunk 单独 mx.eval，避免 lazy graph 无限累积
      │
      ├── 写出 WAV
      └── 释放 Stage B 模型、hidden states、audio 和 waveform 引用
      │
      ▼
44.1 kHz stereo WAV + profile.json

一次真实 5 秒试听的验证结果：

项目	实测结果
输出格式	44.1 kHz、双声道 WAV
输出时长	4.992 秒
AR 阶段峰值	7.347 GB
Acoustic 阶段峰值	5.019 GB
全流程峰值	7.347 GB
Stage A 退出后 active memory	0.008 GB
Stage B 退出后 active memory	0 GB
音频数值	有限，无 NaN/Inf

项目文档中还保留了此前 30 秒连续生成的实测记录。速度会受到芯片型号、统一内存、Flow steps、音乐长度和系统负载影响；这些数字是开发机证据，不是所有设备的保证。

为什么 16GB 可以运行

这里的关键不是把 Music3 变成一个小模型，而是区分：

1. 本地模型总大小：完整权重仍然保存在 SSD 上。
2. 运行时 working set：某一时刻真正物化到 MLX/统一内存中的部分。
3. 阶段峰值：AR 和 Acoustic 不同时驻留，峰值取两个阶段的最大值，而不是相加。

当前推荐使用 4-bit MLX 权重。Stage A 负责文本到中间 frame hiddens，Stage B 负责把中间表示变成波形。两个阶段之间通过已经 mx.eval 的中间结果交接，因此可以释放上一阶段模型，再加载下一阶段模型。

Flow 阶段还使用窗口化 chunk：每个 chunk 生成后立即 mx.eval，避免把所有延迟计算图留到最终 concatenate 才一次性物化。这个设计是 30 秒及更长片段不会随着时长简单线性爆内存的关键。

长序列 AR 表征实验（M9-A）

仓库还提供一个只跑 AR 的实验入口，用来回答“长序列内存到底在哪增长”。它不会调用 Flow、Vocoder 或写 WAV，也不会改变默认生成管线：

uv run python -m generation.long_ar_benchmark \
  --seconds 60 --seed 0 --flush-interval 32 --profile-interval 32 \
  --output-root outputs/benchmarks-m9a

--flush-interval 0 是 baseline；推荐实验值 32 会周期性 mx.eval 已经存在的 last hidden、真实 KV key/value 和 frame hiddens，但不会清理或截断 KV cache。也可以用 --compare 在相同 prompt、歌词、seed 下比较 baseline 与物化模式：

uv run python -m generation.long_ar_benchmark \
  --seconds 30 --seed 0 --flush-interval 32 --compare \
  --output-root outputs/benchmarks-m9a

每次实验保存 config.json、metrics.csv、summary.json 和 benchmark.log。默认安全边界是 MLX peak 11.5 GiB 或新增 swap 0.5 GiB；触发后会保留 partial 结果并返回非零状态。完整的环境、KV 实测字节、斜率、5/15/30 秒一致性和 60/120 秒长测结论见 docs/M9-A-long-ar-characterization.md。这是一项 opt-in characterization，不是对 5 分钟生成能力的承诺。

M4 16GB 长音频真实测试（M9-B）

M9-B 是完整的 AR → Flow → Vocoder → WAV 实际使用测试，不是 AR-only profiling。它只允许 120、180、240 秒，每次命令只跑一个全新 Python 进程，并固定使用 4-bit、seed=0、30 steps 和 flush=32：

uv run python scripts/run_long_form.py --seconds 120

结果写入 outputs/long_form_test/<seconds>s/，包括 output.wav（成功时）、config.json、summary.json 和 benchmark.log。如果某一档出现真正的持续换页、critical pressure、OOM 或系统异常，应停止后续档位。当前真实测试报告见 docs/M9-B-long-form-real-world-test.md。

给 AI 编程助手的项目上下文

如果你要把这个 GitHub 仓库交给 Codex、Claude Code、Cursor 或其他 AI，请让它先阅读本 README，再按下面的入口理解代码。不要先重写成另一个项目，也不要默认把完整模型一次性加载。

关键文件和职责

文件	责任	AI 修改时要注意
cli.py	baseline、generate、idea、webui 命令入口	CLI 参数必须继续经过生成边界校验
generation/pipeline.py	全量驻留 baseline，用于对比和实验	不要把 baseline 当作 16GB 默认路径
generation/phased_pipeline.py	当前默认的两阶段生成主路径	保持 AR → hidden states → Acoustic 的交接顺序
runtime/memory_manager.py	预算判断、阶段进入/退出、cache 清理和报告	释放必须由调用方清掉真实持有引用，再执行 GC/同步/cache 清理
runtime/profiler.py	记录 MLX active/peak、进程内存、事件和耗时	max_stage_peak_gb 是跨阶段峰值，不要用 reset 后的单阶段值冒充全流程
webui/app.py	FastAPI API、后台任务、串行生成锁	一台统一内存设备只允许一个生成管线；排队任务不能提前重置 MLX 峰值
webui/index.html	本地单页 WebUI	保持 MiniMax-Music3 署名、错误显示和历史记录转义
caption/rewriter.py	本地 LLM 把 Idea 整理为 Music3 caption	这是可选前置阶段，不是远程 API
caption/music-caption-rewriter/	静态 skill、流派索引和模板	不要把模型权重或个人歌词放进仓库
scripts/download_weights.sh	从 Hugging Face 下载 MLX 权重	权重留在 models/，不提交 Git
scripts/check_public_tree.py	扫描 Git 实际跟踪内容	发布前必须运行，不只依赖 .gitignore
tests/test_runtime_contracts.py	运行时契约和发布边界测试	新的非平凡行为先加会失败的测试

当前主路径的伪代码

validate_generation_inputs(caption, lyrics, duration, steps, guidance_scale)

# Stage A
model_a = load_model(model_path, lazy=True)
materialize(model_a.language_model, model_a.rvq_depth_decoder)
frame_hiddens = generate_frame_hiddens(...)
mx.eval(frame_hiddens)
release(model_a)  # 调用方引用置空，再 gc/sync/clear_cache

# Stage B
model_b = load_model(model_path, lazy=True)
materialize(model_b.condition_encoder, model_b.transformer, model_b.vocoder)
audio = run_flow_chunked(model_b, frame_hiddens, ...)
mx.eval(audio)
write_wav(audio)
release(model_b, frame_hiddens, audio)

write_profile(ar_peak, flow_peak, max(ar_peak, flow_peak))

AI 接手任务时的推荐顺序

1. 先读 README.md 和 docs/PM-v0.2.md
2. 再读 generation/phased_pipeline.py 的真实数据流
3. 检查 runtime/memory_manager.py 的生命周期和报告口径
4. 先写一个会失败的最小测试
5. 用最小改动让测试通过
6. 跑权重无关测试、编译检查和公开树检查
7. 最后在真实 Apple Silicon 上跑短片段验证

适合继续完善的方向包括：不同内存规格的 profile、生成速度优化、音质对比、WebUI 易用性、取消任务、可持久化的本地曲库，以及对 mlx-audio 上游内部 API 变化的兼容层。每项改动都应该先说明它如何影响阶段驻留和 16GB 预算。

安装

环境要求

• Apple Silicon Mac
• macOS
• Python 3.13
• uv
• 至少约 12GB 可用磁盘空间保存 4-bit Music3 权重
• 使用 Idea → Music 时，还需要额外空间下载本地 caption rewriter

git clone https://github.com/ruijiaang-lab/music3-mac16.git
cd music3-mac16
uv sync

下载模型权重

权重不随 GitHub 仓库发布。使用脚本从 Hugging Face 下载 MLX 转换版本：

bash scripts/download_weights.sh 4bit

可选变体：4bit、mxfp4、mxfp8、8bit、bf16。

16GB Mac 建议从 4bit 开始。其他变体可能需要更多内存，或在 16GB 设备上速度不适合日常使用。

模型权重属于 MiniMax Music3 Community License，使用前请阅读 docs/LICENSING.md 以及下载包内的原始许可证。模型权重目录被 .gitignore 排除，不应提交到本仓库。

生成第一首音乐

建议先用 5 秒、10 个 steps 做试听：

uv run python cli.py generate \
  "warm acoustic folk, gentle guitar, intimate vocal" \
  --seconds 5 \
  --steps 10 \
  --seed 7

生成结果和报告会写入：

outputs/idea/out_5s.wav
outputs/idea/profile.json

正式尝试可以提高时长和 steps：

uv run python cli.py generate \
  "dark melodic techno, 128 BPM, female airy vocal, lonely but not sad" \
  --seconds 30 \
  --steps 30 \
  --seed 7

歌词使用带段落标签的文本；不想要人声时显式使用 [instrumental]：

uv run python cli.py generate \
  "cinematic piano and strings, slow emotional build" \
  --lyrics $'[verse]\nFalling lights across the room\n[chorus]\nWe rise again' \
  --seconds 15

Idea → Music

idea 命令会先用本地语言模型把简短想法整理成结构化 Music3 caption，再调用音乐模型生成 WAV：

uv run python cli.py idea \
  "一首孤独但不悲伤的 128 BPM 深色电子舞曲，有空灵女声" \
  --seconds 15

第一次使用会下载本地 caption rewriter。只想检查重写结果、不生成音乐时：

uv run python cli.py idea \
  "温暖的原声民谣，像一个下雨天的午后" \
  --dry-run

如果 16GB 设备希望降低 caption 重写阶段的压力，可以指定更小的 MLX 模型：

uv run python cli.py idea \
  "a quiet piano ballad" \
  --rewriter-model mlx-community/Qwen3-4B \
  --seconds 15

WebUI

uv run python cli.py webui

浏览器打开 http://127.0.0.1:8642。

WebUI 特点：

• 本地网页控制器，音乐生成仍在本机执行
• 生成任务串行排队，避免 16GB 设备同时加载多个模型
• 支持 5、15、30、60 秒选项
• 支持快速试听和标准音质两档
• 可查看阶段进度、内存占用、试听和下载
• 最近任务只保存在当前进程内，不上传到云端

不要把 WebUI 绑定到公网地址，也不要在未加认证的情况下把它当作公共服务部署。

验证与开发

权重和生成音频不会影响测试。提交代码前运行：

uv run python -m unittest discover -s tests -v
uv run python scripts/check_public_tree.py
uv run python -m compileall -q cli.py generation runtime webui caption scripts tests

check_public_tree.py 检查 Git 实际跟踪内容，而不只是 .gitignore，会拦截：

• models/ 下的本地模型文件
• outputs/ 下的生成结果
• 常见权重格式，如 .safetensors、.bin、.pt、.gguf
• WAV 等生成音频

项目结构

music3-mac16/
├── caption/                    # 本地 Idea → Music caption 工作流
├── generation/                 # baseline 与阶段化生成管线
├── runtime/                    # 内存预算、释放和 profiler
├── webui/                      # FastAPI 后端和单页 WebUI
├── profiles/                   # Apple Silicon 内存配置
├── scripts/                    # 下载、实验和公开树检查
├── tests/                      # 不依赖模型权重的运行时契约测试
└── docs/                       # 许可证、实测记录和项目文档

已知限制

• 目前主要针对 MLX 和 Apple Silicon，不提供 CUDA/Linux 的主路径
• 4-bit 是 16GB Mac 的推荐档位，音质与速度需要按实际设备和音乐类型试听
• 生成速度仍然较慢，不适合未经改造的高并发服务
• 60 秒虽然在输入范围内，但建议先用短片段确认内存和速度
• Music3 的 tempo、段落、人声和风格控制是生成模型能力，不是严格的硬约束
• mlx-audio 的 MiniMax Music3 内部实现仍可能随上游版本变化，升级依赖前请重新跑完整验证

参与完善

欢迎提交：

• 不同 Apple Silicon 内存规格的真实运行报告
• 生成速度和内存峰值对比
• 中英文 caption 示例
• WebUI 易用性改进
• 可复现的错误日志和修复

提交 Issue 或 PR 时，尽量附上芯片型号、统一内存大小、macOS、Python、MLX 和 mlx-audio 版本。不要上传模型权重、生成音频或包含个人内容的歌词。

致谢与许可证

• 音乐模型：MiniMax Music 3
• Apple Silicon 推理基础：MLX
• Music3 MLX 运行支持：mlx-audio
• Caption rewriter skill：来自 MiniMax Music3 项目的公开文本 skill，并在本项目中通过本地模型调用

本项目的运行代码、文档和测试沿用仓库当前的项目许可安排；MiniMax Music3 模型权重不适用本项目代码许可，始终以原始 Community License 为准。发布或商用前请阅读 docs/LICENSING.md。