Shao

后端总览

中文 English

这个后端由三个核心文件组成：

整体是一个两层结构：

请求流程

一次前端请求会经过下面这条链路：

  1. 前端向 backend_api.py 的 POST /generate 发送请求。
  2. API 清洗歌词、标准化请求参数、创建 job，并判断是立即派发还是进入队列。
  3. API 通过 POST /generate 把 worker payload 发送给一个或多个 worker。
  4. backend_worker.py 加载或复用 tokenizer 和模型，然后依次执行：
    • prompt 准备
    • backbone 生成
    • super-resolution
    • decoder 波形重建
    • MP3 导出
  5. worker 把输出文件写到 backend/generated_audio/，并返回文件名和元数据。
  6. API 从 worker 拉取生成文件，把结果挂到对应 job 上，并通过 /job/{job_id} 和 /job/{job_id}/track/{track_idx}/mp3|wav 对前端暴露。

文件职责

run_backend.sh

这是本地或容器环境下的启动入口。

它负责：

最重要的启动控制项包括：

backend_api.py

这是面向前端的编排层。

它负责：

它本身不执行 GPU 推理。

backend_worker.py

这是单卡推理运行时。

它负责：

当前的运行策略是：

如何启动

在 backend 目录下执行：

cd backend
bash run_backend.sh

默认行为：

常见高级示例：

bash run_backend.sh --gpus 0
bash run_backend.sh --gpus 0,1
bash run_backend.sh --gpus 0,1 --runtime-mode keep_loaded

停止所有后端进程：

bash run_backend.sh stop

日志

日志输出在：

常用查看方式：

tail -f backend/logs/api.log
tail -f backend/logs/worker_0.log

输出文件

生成结果会写到：

每次请求通常会写出：

常见配置修改

修改使用的 GPU 数量

通过 run_backend.sh 传入 --gpus：

bash run_backend.sh --gpus 0
bash run_backend.sh --gpus 0,1
bash run_backend.sh --gpus 6,7

每个 GPU id 会启动一个 worker，worker 数量会根据你传入的 id 个数自动推导。

修改运行模式

通过 run_backend.sh 传入 --runtime-mode：

bash run_backend.sh --runtime-mode one_shot
bash run_backend.sh --runtime-mode keep_loaded

建议：

修改端口

编辑 run_backend.sh 里的：

修改 checkpoint 或 tokenizer 路径

编辑 backend_worker.py 里的：

通过 /config 对外暴露的模型名目前是通用名称：

健康检查与排错

Worker 健康接口

每个 worker 会暴露：

API 通过 /health 判断 worker 当前是 idle、busy 还是 offline。

如果前端一直卡在 generating

优先看：

  1. backend/logs/api.log
  2. backend/logs/worker_0.log
  3. GET /status
  4. GET /job/{job_id}

如果 worker 启动失败

常见原因：

如果生成文件缺失

优先检查：