HeartMuLa-Studio

让 AI 创作音乐：HeartMuLa Studio 上手指南

想象这样一个场景：深夜你突然灵感迸发，想要一首「赛博朋克风格、电子节拍、120BPM」的背景音乐来配合你的短视频。没有乐队，没有录音棚，甚至不认识一个懂音乐的人——你会怎么做？

HeartMuLa Studio 给出了一个让人眼前一亮的答案：让 AI 直接帮你写。

这是一个类 Suno 的音乐生成工作室，专为 HeartLib 引擎设计。用户只需设定风格标签（流派、情绪、节拍、配器），或者上传一段参考音频，AI 就能生成最长 4 分钟的完整歌曲——包括人声和歌词。

图1：HeartMuLa Studio 项目图标

背景：为什么需要本地音乐生成？

在 Suno、Udio 等云端 AI 音乐平台风靡的当下，本地部署方案有着不可替代的优势：隐私保护（音频素材不上传云端）、无限创作（不受平台额度限制）、深度定制（可微调模型、训练专属 LoRA 声音）。

HeartMuLa 团队从 2024 年开始推进 heartlib 项目，这是一个基于 PyTorch 的自研音乐生成模型库，专注于高质量的本地推理体验。HeartMuLa Studio 则是其配套的 Web 前端，通过 FastAPI + React 构建了一套完整的本地音乐创作工作流。

核心功能：从灵感到成品的全链路

HeartMuLa Studio 的功能设计覆盖了 AI 音乐创作的完整流程：

歌曲生成：用户可以通过风格标签生成完整歌曲，支持设定流派（电子、流行、古典等）、情绪（欢快、忧郁、紧张等）、节拍范围、配器要求。生成时间根据 GPU 性能不同，约需 30 秒到数分钟不等。支持 Seed 控制，可复现完全一致的生成结果。

参考音频风格迁移（实验性）：这是最具技术亮点的一个功能。用户可以上传任意音频片段（10 秒以上），Studio 会提取其风格特征（音色、编曲风格、混音质感），并在生成时将这些特征迁移到新歌曲中。拖拽式 10 秒区间选择器让风格采样精确可控，风格影响程度支持 1-100% 滑动调节。底部播放器与模态波形图实时同步，体验流畅。

AI 歌词生成：集成 Ollama（本地 LLM）和 OpenRouter（云端 LLM），用户输入一个主题，AI 自动生成符合风格标签的歌词。支持自定义 API 端点（vLLM、LM Studio、LocalAI），兼容 OpenAI 接口规范。

多生成器队列：可以排队多个生成任务，系统按顺序处理，适合批量产出背景音乐素材。

音频导出：生成的音乐可下载为音频文件，配合视频剪辑软件使用。

技术架构：前后端分离的分布式推理

HeartMuLa Studio 采用典型的前后端分离架构：

前端：React 18 + TypeScript + Vite + TailwindCSS。WaveSurfer.js 驱动波形可视化，React Router 管理多页面路由。组件化设计，API 层独立封装（api.ts），便于后续替换后端地址。

后端：FastAPI + Python 3.11 + SQLModel（SQLAlchemy + Pydantic 融合）。SQLite 数据库（jobs.db）持久化生成任务历史和歌曲记录。路由层在 backend/app/ 下模块化组织，通过 Uvicorn ASGI 服务器运行。

核心推理层：backend/heartmula/ 是整个项目的技术核心，包含音乐生成管线和编解码模块。quantize_heartmula.py 提供模型量化脚本。PyTorch 深度学习框架承担模型推理，结合 mmgp（高效内存管理）和 accelerate 做设备分配与量化加载。模型权重通过 HuggingFace Hub 分发，首次运行自动下载约 5GB 文件到 backend/models/。

内存优化：环境变量 HEARTMULA_4BIT=auto 自动选择 4-bit 量化以节省显存；HEARTMULA_SEQUENTIAL_OFFLOAD=auto 在显存不足时自动启用模型卸载；PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True 减少 CUDA 内存碎片。这些设计让 8GB 显存的消费级显卡也能运行。

容器化部署：Docker compose 一键启动

HeartMuLa Studio 提供了完整的容器化方案，Dockerfile 采用多阶段构建：

• Stage 1（frontend-builder）：Node 20 镜像构建 React 前端，产出静态文件到 dist/
• Stage 2（最终镜像）：基于 nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04，安装 Python 3.11、ffmpeg、libsndfile1、gcc/g++，创建非 root 用户 heartmula，复制后端代码和依赖

docker-compose.yml 配置了 GPU 设备直通（deploy.resources.reservations.devices），数据卷持久化模型文件、生成音频、参考音频和数据库。extra_hosts 让容器可访问宿主机上的 Ollama 服务（host.docker.internal）。healthcheck 每 30 秒探测 /health 接口，确保服务就绪。

启动方式非常简单：

# 默认启动（自动检测 GPU）
./start.sh

# 低显存模式（强制 4-bit 量化 + 模型卸载）
./start.sh --force-4bit --force-swap

# Docker compose 方式
docker-compose up -d

启动后访问 http://localhost:8000 即可使用 Web UI。首次启动会自动从 HuggingFace Hub 下载模型（约 5GB），需要稳定的网络连接。

上手门槛：硬件要求是最大门槛

HeartMuLa Studio 的上手门槛主要体现在硬件而非软件：

维度	要求
GPU	NVIDIA，≥8GB 显存，推荐 12GB+
内存	≥16GB RAM
磁盘	≥10GB（模型 + 生成音频）
软件	Docker + NVIDIA Container Toolkit + CUDA 12.1 + cuDNN 8

对于没有 NVIDIA 显卡的用户，目前没有 CPU 降级方案，这是项目的主要限制。软件层面的安装非常顺畅——克隆仓库、启动脚本，5 分钟内可以跑起来。

局限与争议

LoRA 声音训练尚未发布：项目 roadmap 明确列出了 LoRA 声音训练功能，声称早期测试中声音一致性已超越 Suno，但截至目前该功能仍未发布。

无开源许可证：项目仓库未声明明确的开源许可证，heartlib 依赖通过 Git URL 直接安装而非 PyPI release，二次开发和分发存在法律不确定性。

音频质量上限：作为本地推理方案，模型规模和量化精度受限于消费级 GPU 显存，远不及云端大模型的生成质量，与 Suno/Udio 仍有明显差距。

行业意义：本地 AI 音乐的普惠之路

HeartMuLa Studio 的出现代表了 AI 音乐民主化进程的一个重要方向。在云端平台垄断 AI 音乐创作的背景下，提供一个完整的本地解决方案，让创作者在不依赖第三方服务的情况下完成从灵感到成品的全流程，具有实质性的技术价值。

项目采用 Docker compose 的完整容器化方案，显著降低了部署门槛。GPU 资源预留和量化卸载策略的精细设计，也体现团队对不同硬件配置用户的周到考虑。对于需要在本地进行音乐创作、对素材隐私有要求、或者希望在无网络环境下工作的创作者，HeartMuLa Studio 值得关注。

该项目在 GitHub 上已有 602 颗星、101 个 fork、10 个 open issue，说明社区活跃度较高。持续迭代的 changelog 和逐步完善的路线图，显示这是一个认真维护的健康开源项目。