Shao

环境安装说明

本文档记录当前版本的推荐运行环境，以及如何从一个干净的 NVIDIA NGC 容器配置到可运行状态。

这份说明对应当前仓库代码，不包含模型训练环境，只覆盖前后端推理与本地联调所需依赖。

[!TIP] 当前提供两种环境配置方式：

1. 使用仓库根目录的 Dockerfile 构建环境镜像。
2. 按照本文档中的步骤，在一个干净的 NGC 容器里手动安装依赖。

---

以下内容是手动配置教程。

1. 基础环境

当前推荐从 NVIDIA NGC 的 PyTorch 容器开始：

• 25.02-py3

这个基础镜像已经自带了当前项目依赖的核心 CUDA / PyTorch / Transformer Engine 环境，因此不建议在此基础上自行重新安装 torch 或 transformer_engine。

2. 项目目录

项目代码可以放在任意位置，后续路径均默认相对于仓库根目录。

例如：

git clone https://github.com/Shao-Music-AI/Shao.git

cd Shao

后续文档中的路径均默认相对于仓库根目录，而不是固定写死某个宿主机目录。

3. Python 依赖

当前项目额外依赖已经整理到仓库根目录的 requirements.txt。

在 NGC 容器内安装：

python3 -m pip install --break-system-packages -r requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 系统依赖

4.1 ffmpeg

后端会在生成 WAV 后调用 ffmpeg 导出 MP3，因此需要安装：

apt update
apt install -y ffmpeg

4.2 SSH（可选）

如果你希望像开发环境一样直接 SSH 登录容器，而不是先进入宿主机再 docker exec，可以额外安装并启动 SSH 服务。

例如：

apt update
apt install -y openssh-server
mkdir -p /var/run/sshd

这一步不是项目运行必需项，只是开发和远程调试更方便。

5. Node.js

前端当前使用 Vite 开发服务器运行，因此需要安装 Node.js。

目前验证可用的版本是：

• node-v24.15.0-linux-x64

安装方式如下：

curl -fsSLO https://nodejs.org/dist/v24.15.0/node-v24.15.0-linux-x64.tar.xz
mkdir -p /usr/local/lib/nodejs
tar -xJf node-v24.15.0-linux-x64.tar.xz -C /usr/local/lib/nodejs
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/node /usr/local/bin/node
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/npm /usr/local/bin/npm
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/npx /usr/local/bin/npx
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/corepack /usr/local/bin/corepack

说明：

• 上面的下载地址可能会随着 Node.js 版本更新而变化，实际使用时请以 Node.js 官网最新可用地址为准。

验证：

node -v
npm -v
npx -v

6. 前端依赖

在仓库根目录下执行：

cd frontend
npm install

当前版本前端推荐通过开发模式启动：

npm run dev

7. 模型文件放置方式

当前代码默认按仓库相对路径查找 tokenizer、decoder 配置和 checkpoints。

请确保目录结构如下：

Shao/
├── backend/
├── frontend/
├── core/
├── models/
│   ├── Decoder/
│   ├── Megatron/
│   └── Tokenizer/
└── checkpoints/
    ├── ...
    └── ...

注意：

• checkpoints/ 目录下的模型文件和目录结构需要与当前代码配置保持一致。
• 项目代码可以放在任意目录，只要仓库内部结构保持一致即可。

8. 启动方式

8.1 启动后端

cd backend
bash run_backend.sh

默认会启动：

• 1 个 API 进程
• GPU_IDS 中指定数量的 worker 进程

停止：

bash run_backend.sh stop

8.2 启动前端

cd frontend
npm run dev

默认情况下：

• 前端开发服务器监听 30869
• 后端 API 监听 8889

9. Docker 高级启动示例

如果你希望把宿主机上的项目目录挂载进容器，可以使用类似这样的命令：

docker run -d \
  --name shao_dev \
  --gpus all \
  -p 2222:22 \
  -p 30869:30869 \
  -p 8889:8889 \
  -v /path/to/your/workspace:/workspace \
  <your-image> \
  /usr/sbin/sshd -D

需要根据你自己的环境调整：

• 宿主机挂载路径
• 镜像名称
• 是否启用 SSH