Hangry Labs YuE2

版本 v1.0.0。参见版本历史。

根据歌词和音乐风格描述，在自己的GPU上生成歌曲。一个Docker容器提供浏览器工作室、 HTTP API、MCP和48 kHz立体声输出。项目基于 yue2.cpp、C++20与GGML。

快速开始

需要支持NVIDIA GPU的Docker及兼容CUDA 12.9.1的驱动。已验证的设备为16 GB显存的RTX 5070 Ti，其他配置尚未验证。首次使用时，将两个模型文件下载到data/models/。然后在包含data/的目录中，执行以下任意一条单行命令。

Bash：

docker run -d --name yue2 --restart unless-stopped --gpus all -p 127.0.0.1:8087:8087 --mount "type=bind,source=$(pwd)/data/models,target=/models,readonly" --mount type=volume,source=yue2-output,target=/output hangrylabs/yue2:v1.0.0@sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34

PowerShell：

docker run -d --name yue2 --restart unless-stopped --gpus all -p 127.0.0.1:8087:8087 --mount "type=bind,source=$($PWD.Path)\data\models,target=/models,readonly" --mount type=volume,source=yue2-output,target=/output hangrylabs/yue2:v1.0.0@sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34

打开http://localhost:8087，输入歌词与音乐风格，点击“生成歌曲”。主机无需安装Python或编译器。上述命令固定稳定版 v1.0.0；latest 继续跟踪开发版本。相同稳定版镜像也可从 ghcr.io/hangry-labs/yue2:v1.0.0@sha256:446bd69099513f8b1d762656d455826872b7221ab232aa05e907f3ada90c9b34 获取。

首次使用：下载模型

创建data/models/，并保持原始文件名。下载总量约4.34 GB。

模型	用途	大小
YuE2-3B-Q8_0.gguf	歌曲生成	3.81 GB
YuE2-Vae-F32.gguf	音频编码与解码	530 MB

模型清单包含SHA-256校验值。已检出源码时，可通过task models 下载并验证文件。权重不包含在镜像中，服务器也不会自动下载。镜像与模型就绪后，可离线生成。模型使用条款与应用许可分开适用。

功能概览

根据风格和歌词生成歌曲，支持完整乐谱、仅旋律或不使用乐谱的模式。
输出48 kHz立体声Opus、MP3、Ogg、FLAC、WAV及AAC/M4A。
浏览器曲库支持搜索、收藏、播放和复用提示。
可编辑ABC乐谱，通过语义编码重放，或从源片段继续生成。
同一作曲可生成1至3个声音版本，默认2个。
支持本地LoRA适配器，以及音频与潜在表示的VAE编码／解码。
异步任务、取消、队列上限及持久卷结果存储。
系统页面显示模型状态、队列、存储用量与NVIDIA GPU图表。
原生HTTP API、OpenAI兼容客户端接口，以及供智能体使用的MCP工具。

乐谱转录和音频分词需要额外模型与服务器参数，不在默认下载范围内。详情见模型指南。

浏览器工作室

在页眉选择英语、挪威语书面语、波兰语、日语、简体中文或西班牙语。浏览器会记住选择，也可直接访问/en、/nb、/pl、/ja、/zh或/es。切换语言会保留歌词、设置与活动任务。界面语言不决定演唱语言，也不会翻译歌词。

“新建歌曲”每次点击都根据当前歌词和风格重新作曲。“使用ABC乐谱”保留指定旋律。重放音频编码会重新渲染已有演出，因此编辑歌词无法改写编码中已包含的演唱。曲风、乐器、情绪和声线写在音乐风格描述中，[Verse]、[Chorus]等结构标签放在歌词中。这些描述属于模型提示，并非严格控制保证。

API与智能体

/v1/audio/music直接返回完整音频。OpenAI客户端可以使用/v1/audio/speech，但它同样生成歌曲，而非普通语音朗读。/v1/models提供模型信息。

curl --fail-with-body http://localhost:8087/v1/audio/music -H 'Content-Type: application/json' --data '{"model":"yue2","lyrics":"[Verse]\nMorning light across the floor","style":"English acoustic pop, warm singing","duration":30,"steps":8,"response_format":"opus"}' --output song.opus

原生/synth返回任务ID。轮询/job?id=JOB_ID直至done，再从 /job?id=JOB_ID&result=1获取包含音频、重放JSON和潜在表示的multipart结果。参见API指南、本地API文档及 OpenAPI模式，本地文档可离线使用。

通过Streamable HTTP将MCP客户端连接到http://localhost:8087/mcp。工具为skill、generate_song、get_song、cancel_song。智能体先阅读技能说明，编写或整理完整歌曲，再生成并获取有效期一小时的HTTP下载链接。工具不允许修改高级运行设置。详情见MCP指南。

默认值与存储

默认使用8步、随机种子、24,576令牌上下文和2个声音变体。音乐／语音兼容接口及MCP每次调用返回1首。时长是上限，歌曲可能提前结束。正常启动会在各阶段之间释放模型权重。目前仅支持CUDA GPU发行配置。

所有生成接口共用1个串行工作线程，最多接收8个任务（包含活动任务）。队列满时返回HTTP 429及Retry-After，请等待后重试。 /health、/status、/system/queue提供运行状态。设置YUE2_API_KEY可保护/v1和/mcp；工作室与原生接口保持本地访问策略。默认命令仅绑定localhost。

模型位于主机。yue2-output卷可在更换容器后保留已完成的结果。原生结果默认保留24小时，智能体链接保留1小时。浏览器IndexedDB曲库独立存储，请下载重要歌曲；模型目录不是浏览器曲库的备份。参见队列与结果存储。

文档与开发

文档目录 · Docker · 音频格式 · 开发 · 构建依赖 · 基准测试。详细技术参考目前为英文；网站会明确提示尚无所选语言的译文。

有源码、Docker、Python和Task时，依次使用task models、task build、task start。 task validate检查工具、UI及原生CPU代码；task test1执行固定GPU基线。 task pages启动网站预览，task pages-stop停止预览。基准分别记录冷启动、预热生成与显存，ASR仅作为不完美的趋势指标，不代表演唱质量结论。

隐私、来源与许可

生成在本机执行。下载会访问镜像仓库和模型托管站点，UI不依赖CDN。请仅处理有权使用的歌词和录音，并负责任地分享结果。外部产品集成为独立范围。

MAP提供模型， yue2.cpp提供原生引擎。 Hangry Labs维护UI、API、打包和验证。项目代码采用MIT许可，模型另受非商业使用条款约束。请阅读模型来源和第三方声明。联系：contact@hangrylabs.app。

版本历史

v1.0.0

首个稳定版本包含本地工作室、原生／OpenAI兼容API、MCP、多语言界面、外部模型和已验证CUDA依赖。已于2026年11月3日发布。参见发行说明。快速入门固定稳定版标签及经过验证的OCI摘要。