Shao
### Shao: 基于统一声学词元路线的高保真音乐生成系统
[English](/Shao/) | 中文
✨ Shao（韶元）是什么？
更名说明
本项目原名为 Khala，现已正式更名为 Shao（韶元）。模型、代码库与研究方向保持不变；此次更名是为了统一项目在论文、GitHub、Demo 与后续发布中的长期身份。
Shao 是中文名 韶元 的英文名称。“韶”本义与美好的音乐有关，也让人联想到古代雅乐与文化传承；“元”表示起点、基础与第一性原理。
Shao（韶元）是一个面向高保真音乐生成的开源系统，支持基于文本描述与歌词条件生成完整音乐作品。与依赖语义 token、扩散模型或多级音频生成模块的路线不同，Shao 采用统一的声学词元建模路线，在同一套离散音频表示空间中完成从粗粒度音乐结构到细粒度声学细节的生成。
Shao（韶元）的核心特点包括：
- 完整音乐生成：面向作品级别的音乐生成，而不是短音频片段或伴奏循环。
- 文本与歌词控制：支持通过自然语言 prompt 和 lyrics 控制风格、情绪、演唱与内容。
- 统一声学词元表示：基于 64 层 RVQ acoustic token hierarchy，将音频表示为 coarse-to-fine 的离散声学词元。
- 两阶段生成链路：首先由 backbone 生成粗粒度 acoustic tokens，再由 super-resolution 模型补全高层 RVQ tokens，最后通过 decoder 还原为 waveform。
- 完整系统实现：提供前端界面、FastAPI 后端调度层、单卡推理 worker、模型加载与音频生成链路，而不是仅提供离散推理脚本。
📰 News
⚠️ [2026-06-16]当前推理质量对显卡架构、CUDA 栈、容器镜像以及 Megatron/TransformerEngine 版本高度敏感。经过反复测试，我们发现即使使用相同 prompt，并尽量保持 CUDA/container 配置一致，不同显卡类型之间也无法保证生成结果完全一致。目前最稳定、最可复现的结果来自严格遵循项目提供的 NGC-based 镜像与环境配置说明。尤其是在 H800 上，使用参考镜像可以得到与训练/推理环境一致的正常结果；在 RTX 4090 上，如果严格使用项目提供的环境，也可以正常生成。使用其他容器、CUDA/PyTorch/TransformerEngine 组合或 Megatron 版本，可能导致生成质量严重下降，甚至出现类似噪声的音频。我们保留此说明是为了透明地告知当前限制，也欢迎有经验的用户帮助我们继续定位底层数值与运行时差异。
✅ 已更新
[2026-05-16]在线音频 Demo 页面已上线：Shao Demo[2026-05-11]已支持默认单卡安全启动，并兼容通过同一后端脚本覆盖多卡与不同运行模式的部署推理配置。[2026-05-05]arXiv 论文已上线：Shao: Scaling Acoustic Token Language Models Toward High-Fidelity Music Generation[2026-05-01]代码、环境配置文档与 Dockerfile 已整理完成。
⏳ TODOs
[Coming Soon]对音乐人及小白友好的完整部署教程[Coming Soon]Discord 交流群
🖥️ 前端界面
Prompt 模式
Tag 模式
🎧 音频样例
在线 Demo 页面已提供生成音频样例：Shao Demo
✅ 运行要求
当前版本主要面向具备 GPU 服务器使用经验的研究人员与开发者。
- NVIDIA GPU，推荐 24GB 或以上显存用于完整推理链路（如 RTX 4090 或更高规格 GPU）
- Docker 与 NVIDIA Container Toolkit
- CUDA-compatible NVIDIA Driver
- Python / Node.js 环境已包含在预构建镜像中
- 模型权重需下载到仓库根目录的
checkpoints/目录
🚀 快速开始
本节面向已经具备基本 Docker / CUDA 使用经验的研究人员与开发者，提供一条最短启动路径。
如果你想从干净的 NGC 容器一步步手动配置环境，请阅读：
如果你想了解后端结构与运行逻辑，请阅读：
1. 准备运行环境
当前可直接使用的预构建镜像：
docker pull ghcr.io/davidliujiafeng/khala-env:ngc25.02-node24
docker run --gpus all -it --rm \
--name shao \
-p 30869:30869 \
-p 8889:8889 \
ghcr.io/davidliujiafeng/khala-env:ngc25.02-node24
注意：上述命令使用
--rm，容器退出后容器内文件不会保留。若需要长期开发或保留下载好的模型权重，建议使用挂载目录或去掉--rm。
2. 克隆仓库
进入容器后执行：
cd /workspace
git clone https://github.com/Shao-Music-AI/Shao.git
cd Shao
3. 下载模型权重
模型权重主页：
在仓库根目录执行：
mkdir -p checkpoints
hf download liujiafeng/Shao-MusicGeneration-v1.0 --local-dir checkpoints
该命令会将模型仓库内容下载到本地 checkpoints/ 目录。
4. 启动后端
cd /workspace/Shao/backend
bash run_backend.sh
现在默认启动方式就是单卡安全模式。高级用户也可以通过同一个脚本指定 GPU 编号，并切换 one_shot / keep_loaded 运行模式；具体用法见 backend/README_backend_zh.md。
5. 启动前端
在另一个终端中执行：
cd /workspace/Shao/frontend
npm install
npm run dev
6. 打开页面
默认访问地址：
🧠 系统结构
当前系统由三层组成：
- 前端：负责输入 prompt、lyrics 和生成参数，并展示结果。
- API 调度层：负责接收请求、创建任务、排队并分发到空闲 worker。
- Worker 推理层：负责执行 backbone、super-resolution 和 decoder 推理。
请求链路如下：
flowchart LR
A["Frontend UI"] --> B["backend_api.py"]
B --> C["backend_worker.py"]
C --> D["Backbone"]
D --> E["Super-resolution"]
E --> F["Decoder"]
F --> G["Generated Audio"]
G --> B
B --> A
🔗 相关资源
- Demo 页面：Shao Demo
- arXiv 论文：Shao: Scaling Acoustic Token Language Models Toward High-Fidelity Music Generation
- 模型权重：https://huggingface.co/liujiafeng/Shao-MusicGeneration-v1.0
- 环境配置：ENVIRONMENT_SETUP_zh.md
- 后端说明：backend/README_backend_zh.md
🗂 仓库结构
Shao/
├── backend/
├── frontend/
├── core/
├── models/
├── checkpoints/
├── assets/
├── Dockerfile
├── requirements.txt
├── ENVIRONMENT_SETUP.md
└── ENVIRONMENT_SETUP_zh.md
主要目录说明：
frontend/：前端页面与 Vite 工程。backend/：后端 API、worker 和启动脚本。core/：项目自定义核心模块。models/：Megatron、decoder 和 tokenizer 相关代码。checkpoints/：模型权重文件目录。assets/：README 与展示页面使用的图片资源。
📚 引用方式
如果本项目对你的研究或开发有帮助，欢迎引用我们的论文：
正式 BibTeX 信息将在后续补充到论文页面与仓库文档中。
🙏 致谢
本项目当前实现建立在若干优秀开源项目与工具之上，包括但不限于：
- NVIDIA NGC
- Megatron / Megatron Core
- Hugging Face
- FastAPI
- Vite / React
📜 开源协议
当前模型权重计划采用 CC BY-NC 4.0（Creative Commons Attribution-NonCommercial 4.0 International）许可协议发布。
💬 Contact
欢迎扫码加入微信群交流项目进展、使用问题与后续更新：
