ACE-Step 1.5 基准测试与性能分析指南

Language / 语言: English | 中文

概述

profile_inference.py 是 ACE-Step 1.5 推理的综合性能分析与基准测试工具。它可以测量端到端耗时、LLM 规划耗时、DiT 扩散耗时、VAE 解码耗时等，支持不同设备、后端和配置的组合测试。

支持的模式

模式	说明
`profile`	对单次生成进行详细的计时分析
`benchmark`	运行配置矩阵（时长 × 批量 × 思考 × 步数），输出汇总表
`tier-test`	通过 `MAX_CUDA_VRAM` 模拟不同显存大小，自动测试所有 GPU 等级
`understand`	分析 `understand_music()` API（音频 → 元数据提取）
`create_sample`	分析 `create_sample()` API（灵感/简单模式）
`format_sample`	分析 `format_sample()` API（标题+歌词 → 结构化元数据）

支持的设备与后端

设备	参数	说明
CUDA (NVIDIA)	`--device cuda`	推荐，默认自动检测
MPS (Apple Silicon)	`--device mps`	macOS Apple 芯片
CPU	`--device cpu`	慢，仅用于测试
自动	`--device auto`	自动选择最佳设备（默认）

LLM 后端	参数	说明
vLLM	`--lm-backend vllm`	CUDA 上最快，推荐 NVIDIA 使用
PyTorch	`--lm-backend pt`	通用后端，所有平台可用
MLX	`--lm-backend mlx`	Apple Silicon 优化
自动	`--lm-backend auto`	根据设备自动选择（默认）

快速开始

bash

# 基本分析（text2music，默认设置）
python profile_inference.py

# 启用 LLM 思考模式
python profile_inference.py --thinking

# 运行基准测试矩阵
python profile_inference.py --mode benchmark

# Apple Silicon 上测试
python profile_inference.py --device mps --lm-backend mlx

# 启用 cProfile 函数级分析
python profile_inference.py --detailed

测试模式

1. `profile` — 单次运行分析

运行单次生成，输出详细计时分解。包含可选的预热和 cProfile。

bash

python profile_inference.py --mode profile

测量内容：

总耗时（端到端）
LLM 规划耗时（token 生成、约束解码、CFG 开销）
DiT 扩散耗时（每步和总计）
VAE 解码耗时
音频保存耗时

此模式的选项：

参数	说明
`--no-warmup`	跳过预热（测量将包含编译开销）
`--detailed`	启用 `cProfile` 函数级分析
`--llm-debug`	深度 LLM 调试（token 数量、吞吐量）
`--thinking`	启用 LLM 思维链推理
`--duration <秒>`	覆盖音频时长
`--batch-size <n>`	覆盖批量大小
`--inference-steps <n>`	覆盖扩散步数

2. `benchmark` — 配置矩阵测试

运行配置矩阵并输出汇总表。自动适配 GPU 显存限制。

bash

python profile_inference.py --mode benchmark

默认矩阵：

时长：30s, 60s, 120s, 240s（根据 GPU 显存裁剪）
批量大小：1, 2, 4（根据 GPU 显存裁剪）
思考模式：True, False
推理步数：8, 16

输出示例：

Duration   Batch   Think   Steps   Wall(s)    LM(s)      DiT(s)     VAE(s)     Status
--------------------------------------------------------------------------------------------------------------------------
30         1       False   8       3.21       0.45       1.89       0.52       OK
30         1       True    8       5.67       2.91       1.89       0.52       OK
60         2       False   16      12.34      0.48       9.12       1.85       OK
...

保存结果为 JSON：

bash

python profile_inference.py --mode benchmark --benchmark-output results.json

3. `understand` — 音频理解分析

分析 understand_music() API，从音频 codes 提取元数据（BPM、调性、拍号、描述）。

bash

python profile_inference.py --mode understand
python profile_inference.py --mode understand --audio-codes "your_audio_codes_string"

4. `create_sample` — 灵感模式分析

分析 create_sample() API，从简单文本查询生成完整歌曲蓝图。

bash

python profile_inference.py --mode create_sample
python profile_inference.py --mode create_sample --sample-query "一首柔和的孟加拉情歌"
python profile_inference.py --mode create_sample --instrumental

5. `format_sample` — 元数据格式化分析

分析 format_sample() API，将描述+歌词转换为结构化元数据。

bash

python profile_inference.py --mode format_sample

6. `tier-test` — 自动化 GPU 等级测试

使用 MAX_CUDA_VRAM 自动模拟不同的 GPU 显存大小，并在每个等级运行生成测试。这是修改 acestep/gpu_config.py 后验证所有 GPU 等级是否正常工作的推荐方式。

bash

# 测试所有等级 (4, 6, 8, 12, 16, 20, 24 GB)
python profile_inference.py --mode tier-test

# 测试特定显存大小
python profile_inference.py --mode tier-test --tiers 6 8 16

# 启用 LM 测试（在支持的等级上）
python profile_inference.py --mode tier-test --tier-with-lm

# 快速测试：非量化等级跳过 torch.compile
python profile_inference.py --mode tier-test --tier-skip-compile

每个等级验证的内容：

正确的等级检测和 GPUConfig 构建
模型初始化（DiT、VAE、文本编码器，可选 LM）
短时间生成（30秒时长，batch=1）无 OOM 完成
自适应 VAE 解码回退（GPU → CPU 卸载 → 完全 CPU）
显存使用保持在模拟限制内

输出示例：

TIER TEST RESULTS
====================================================================================================
  VRAM    Tier       LM      Duration   Status    Peak VRAM    Notes
  ──────────────────────────────────────────────────────────────────────────────
  4GB     tier1      —       30s        ✅ OK     3.8GB        VAE 在 CPU 上解码
  6GB     tier2      —       30s        ✅ OK     5.4GB        分片 VAE chunk=256
  8GB     tier4      0.6B    30s        ✅ OK     7.2GB        vllm 后端
  12GB    tier5      1.7B    30s        ✅ OK     10.8GB       vllm 后端
  16GB    tier6a     1.7B    30s        ✅ OK     14.5GB       启用卸载
  20GB    tier6b     1.7B    30s        ✅ OK     17.2GB       无卸载
  24GB    unlimited  4B      30s        ✅ OK     21.3GB       所有模型在 GPU 上

注意: tier-test 模式使用 torch.cuda.set_per_process_memory_fraction() 强制执行显存硬上限，即使在高端 GPU（如 A100 80GB）上也能实现真实的模拟。

边界测试

使用 --tier-boundary 查找可以安全关闭 INT8 量化和 CPU 卸载的最低显存等级。对每个等级最多测试三种配置：

default — 等级的标准设置
no-quant — 关闭量化，卸载不变
no-offload — 不使用量化，也不使用 CPU 卸载

bash

# 在所有等级运行边界测试
python profile_inference.py --mode tier-test --tier-boundary

# 启用 LM 的边界测试
python profile_inference.py --mode tier-test --tier-boundary --tier-with-lm

# 将边界测试结果保存为 JSON
python profile_inference.py --mode tier-test --tier-boundary --benchmark-output boundary_results.json

输出包含一个 边界分析 摘要，显示每种能力的最低等级。

批次大小边界测试

使用 --tier-batch-boundary 查找每个等级的最大安全批次大小。对每个等级，工具会递进测试批次大小 1、2、4、8（在首次 OOM 时停止），同时测试启用 LM 和未启用 LM 的配置：

bash

# 运行批次边界测试
python profile_inference.py --mode tier-test --tier-batch-boundary --tier-with-lm

# 测试特定等级
python profile_inference.py --mode tier-test --tier-batch-boundary --tier-with-lm --tiers 8 12 16 24

输出包含一个 批次边界摘要，显示每个等级在有 LM 和无 LM 配置下的最大成功批次大小。

命令行参数

设备与后端

参数	默认值	说明
`--device`	`auto`	设备：`auto` / `cuda` / `mps` / `cpu`
`--lm-backend`	`auto`	LLM 后端：`auto` / `vllm` / `pt` / `mlx`

模型路径

参数	默认值	说明
`--config-path`	`acestep-v15-turbo`	DiT 模型配置
`--lm-model`	`acestep-5Hz-lm-1.7B`	LLM 模型路径

硬件选项

参数	默认值	说明
`--offload-to-cpu`	关闭	不使用时卸载模型到 CPU
`--offload-dit-to-cpu`	关闭	不使用时卸载 DiT 到 CPU
`--quantization`	无	量化：`int8_weight_only` / `fp8_weight_only` / `w8a8_dynamic`

生成参数

参数	默认值	说明
`--duration`	来自示例	音频时长（秒）
`--batch-size`	来自示例	批量大小
`--inference-steps`	来自示例	扩散推理步数
`--seed`	来自示例	随机种子
`--guidance-scale`	7.0	DiT 的 CFG 引导缩放

LLM / CoT 参数

参数	默认值	说明
`--thinking`	关闭	启用 LLM 思维链推理
`--use-cot-metas`	关闭	LLM 通过 CoT 生成音乐元数据
`--use-cot-caption`	关闭	LLM 通过 CoT 改写/格式化描述
`--use-cot-language`	关闭	LLM 通过 CoT 检测人声语言
`--use-constrained-decoding`	开启	基于 FSM 的约束解码
`--no-constrained-decoding`	—	禁用约束解码
`--lm-temperature`	0.85	LLM 采样温度
`--lm-cfg-scale`	2.0	LLM CFG 缩放

分析选项

参数	默认值	说明
`--mode`	`profile`	模式：`profile` / `benchmark` / `tier-test` / `understand` / `create_sample` / `format_sample`
`--no-warmup`	关闭	跳过预热
`--detailed`	关闭	启用 `cProfile` 函数级分析
`--llm-debug`	关闭	深度 LLM 调试（token 数量、吞吐量）
`--benchmark-output`	无	保存基准测试结果为 JSON 文件

等级测试选项

参数	默认值	说明
`--tiers`	`4 6 8 12 16 20 24`	要模拟的显存大小（GB）
`--tier-with-lm`	关闭	在支持的等级上启用 LM 初始化
`--tier-skip-compile`	关闭	非量化等级跳过 `torch.compile` 以加速迭代
`--tier-boundary`	关闭	对每个等级测试 no-quant 和 no-offload 变体，查找最低能力边界
`--tier-batch-boundary`	关闭	对每个等级测试批次大小 1、2、4、8，查找最大安全批次大小

输入选项

参数	默认值	说明
`--example`	`example_05.json`	`examples/text2music/` 中的示例 JSON
`--task-type`	`text2music`	任务类型：`text2music` / `cover` / `repaint` / `lego` / `extract` / `complete`
`--reference-audio`	无	参考音频路径（用于翻唱/风格迁移）
`--src-audio`	无	源音频路径（用于音频到音频任务）
`--sample-query`	无	`create_sample` 模式的查询文本
`--instrumental`	关闭	生成纯音乐（用于 `create_sample`）
`--audio-codes`	无	音频 codes 字符串（用于 `understand` 模式）

使用示例

对比不同设备

bash

# NVIDIA GPU
python profile_inference.py --device cuda --lm-backend vllm

# Apple Silicon
python profile_inference.py --device mps --lm-backend mlx

# CPU 基线
python profile_inference.py --device cpu --lm-backend pt

对比不同 LLM 模型

bash

# 轻量版 (0.6B)
python profile_inference.py --lm-model acestep-5Hz-lm-0.6B

# 默认版 (1.7B)
python profile_inference.py --lm-model acestep-5Hz-lm-1.7B

# 大型版 (4B)
python profile_inference.py --lm-model acestep-5Hz-lm-4B

思考模式 vs 非思考模式

bash

# 不使用思考（更快）
python profile_inference.py --mode benchmark

# 使用思考（质量更好，更慢）
python profile_inference.py --thinking --use-cot-metas --use-cot-caption

低显存测试

bash

# 卸载 + 量化
python profile_inference.py --offload-to-cpu --quantization int8_weight_only --lm-model acestep-5Hz-lm-0.6B

完整基准测试套件

bash

# 运行完整基准测试矩阵并保存结果
python profile_inference.py --mode benchmark --benchmark-output benchmark_results.json

# 查看 JSON 结果
cat benchmark_results.json | python -m json.tool

函数级分析

bash

# 启用 cProfile 进行详细的函数级分析
python profile_inference.py --detailed --llm-debug

理解输出

耗时分解

分析器会打印详细的耗时分解：

TIME COSTS BREAKDOWN
====================================================================================================
  Component                          Time (s)       % of Total
  ─────────────────────────────────────────────────────────────
  LLM Planning (total)               2.91           45.2%
    ├─ Token generation              2.45           38.1%
    ├─ Constrained decoding          0.31            4.8%
    └─ CFG overhead                  0.15            2.3%
  DiT Diffusion (total)              1.89           29.4%
    ├─ Per-step average              0.24            —
    └─ Steps                         8               —
  VAE Decode                         0.52            8.1%
  Audio Save                         0.12            1.9%
  Other / Overhead                   0.99           15.4%
  ─────────────────────────────────────────────────────────────
  Wall Time (total)                  6.43          100.0%

关键指标

指标	说明
Wall Time	从开始到结束的端到端耗时
LM Total Time	LLM 规划耗时（token 生成 + 解析）
DiT Total Time	扩散耗时（所有步骤合计）
VAE Decode Time	将潜变量解码为音频波形的耗时
Tokens/sec	LLM token 生成吞吐量（需 `--llm-debug`）

技巧与最佳实践

始终包含预热（默认）— 首次运行包含 JIT 编译和内存分配开销。预热确保测量反映稳态性能。
使用 --benchmark-output 将结果保存为 JSON，方便后续分析或跨硬件对比。
对比思考开启 vs 关闭 — 思考模式显著增加 LLM 耗时，但可能提升生成质量。
使用代表性时长测试 — 短时长（30s）以 LLM 耗时为主；长时长（240s+）以 DiT 耗时为主。
GPU 显存自动适配 — benchmark 模式会自动将时长和批量大小裁剪到 GPU 可处理的范围，使用 acestep/gpu_config.py 中的自适应等级系统。
谨慎使用 --detailed — cProfile 会增加开销；仅在需要调查函数级瓶颈时使用。
使用 tier-test 进行回归测试 — 修改 GPU 等级配置后，运行 --mode tier-test 验证所有等级仍然正常工作。这在更改卸载阈值、时长限制或 LM 模型可用性时尤为重要。
真实模拟低显存 — 使用 MAX_CUDA_VRAM 时，系统通过 set_per_process_memory_fraction() 强制执行显存硬上限，因此模拟期间的 OOM 错误反映了消费级 GPU 上的真实行为。

ACE-Step 1.5 基准测试与性能分析指南 ​

目录 ​

概述 ​

支持的模式 ​

支持的设备与后端 ​

快速开始 ​

测试模式 ​

1. profile — 单次运行分析 ​

2. benchmark — 配置矩阵测试 ​

3. understand — 音频理解分析 ​

4. create_sample — 灵感模式分析 ​

5. format_sample — 元数据格式化分析 ​

6. tier-test — 自动化 GPU 等级测试 ​

边界测试 ​

批次大小边界测试 ​

命令行参数 ​

设备与后端 ​

模型路径 ​

硬件选项 ​

生成参数 ​

LLM / CoT 参数 ​

分析选项 ​

等级测试选项 ​

输入选项 ​

使用示例 ​

对比不同设备 ​

对比不同 LLM 模型 ​

思考模式 vs 非思考模式 ​

低显存测试 ​

完整基准测试套件 ​

函数级分析 ​

理解输出 ​

耗时分解 ​

关键指标 ​

技巧与最佳实践 ​

ACE-Step 1.5 基准测试与性能分析指南

目录

概述

支持的模式

支持的设备与后端

快速开始

测试模式

1. `profile` — 单次运行分析

2. `benchmark` — 配置矩阵测试

3. `understand` — 音频理解分析

4. `create_sample` — 灵感模式分析

5. `format_sample` — 元数据格式化分析

6. `tier-test` — 自动化 GPU 等级测试

边界测试

批次大小边界测试

命令行参数

设备与后端

模型路径

硬件选项

生成参数

LLM / CoT 参数

分析选项

等级测试选项

输入选项

使用示例

对比不同设备

对比不同 LLM 模型

思考模式 vs 非思考模式

低显存测试

完整基准测试套件

函数级分析

理解输出

耗时分解

关键指标

技巧与最佳实践