前言
最近在测试本地端 AI 音乐生成方案，ACE-Step-1.5 是一款支持 text2music 任务的开源音乐模型，核心能力是输入带分段标记的歌词 + 风格描述，一次性生成包含旋律、伴奏与人声演唱的音频。和网页在线音乐模型相比，本地部署可以规避上传素材、生成次数限制等问题，适合做原创音乐原型、短视频音频素材。
本篇是纯技术实测笔记，记录 Windows 环境下本地部署流程，附带环境检测 Python 脚本、启动批处理、模型调用代码，以及音频后处理 FFmpeg 命令，实测最低硬件：NVIDIA 8G 显存显卡，内存 16G。
前置说明：本文仅为技术研究，模型请从官方开源渠道获取，自行遵守对应的开源协议，商用需要单独确认授权。
一、项目目录规划与环境预检脚本
部署第一件事，路径禁止中文、空格、特殊字符，否则会出现权重加载、文件读写异常。 示例目录：D:\dev\ai-music\ace-step-1.5
ace-step-1.5/ ├─ webui.py # 网页服务入口 ├─ check_env.py # 硬件&依赖检测脚本 ├─ model_weights/ # 模型权重存放目录 ├─ outputs/ # 生成音频输出目录 └─ cache/ # 模型临时缓存
新建check_env.py，执行脚本自动校验 CUDA、显存，提前定位硬件问题：
import torch import os import platform print("==== ACE-Step-1.5 环境检测 ====") print(f"OS: {platform.system()} {platform.release()}") print(f"Python Version: {platform.python_version()}") print(f"Torch CUDA Available: {torch.cuda.is_available()}") if torch.cuda.is_available(): dev = torch.device(0) gpu_name = torch.cuda.get_device_name(dev) vram_total = torch.cuda.get_device_properties(dev).total_memory / 1024**3 print(f"GPU Name: {gpu_name}") print(f"Total VRAM: {vram_total:.2f} GB") if vram_total >= 8.0: print("✅ 显存满足最低运行条件") else: print("❌ 显存不足，至少8GB，会频繁OOM") else: print("❌ 没有可用CUDA设备，无法在GPU运行") # 创建输出文件夹 out_dir = "outputs" if not os.path.exists(out_dir): os.makedirs(out_dir) print(f"✅ 输出目录 {out_dir} 已创建") print("================================")
在项目根目录打开 CMD 执行：
python check_env.py
二、WebUI 服务启动脚本（start.bat）
用来启动本地网页服务，8G 显存设备需要增加显存分片环境变量，控制 pytorch 显存分配策略。
@echo off chcp 65001 echo ===== ACE-Step-1.5 WebUI Start ===== echo Loading model weights, wait patiently... :: 显存分片优化，8G显卡核心配置 set PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512 set CUDA_VISIBLE_DEVICES=0 :: 激活虚拟环境（如果你使用venv） call venv\Scripts\activate.bat :: 启动web服务，lowvram开启显存分片加载 python webui.py --lowvram --listen --port 7860 pause
参数解释
PYTORCH_CUDA_ALLOC_CONF：限制单次显存分配块大小，缓解 8G 卡峰值爆内存--lowvram：权重分模块加载，牺牲少量速度换取显存可用性，12G + 显卡可以删除该参数--listen：局域网可访问，不需要就删掉；--port 7860网页端口 启动成功后，浏览器访问http://127.0.0.1:7860，WebUI 界面选择任务类型text2music。
三、底层 Python 调用示例：text2music 歌词生成音频
不打开 WebUI，直接用脚本批量跑生成任务，适合自动化批量测试不同曲风、种子、歌词。
from ace_step import AceStepPipeline # 加载模型，low_vram适配8G显存 pipeline = AceStepPipeline( model_dir="./model_weights", low_vram=True, device="cuda" ) gen_params = { "task_type": "text2music", "prompt": "Chinese pop song, bright female vocals, clean instrumental accompaniment, KTV style", "lyrics": """[Verse1] 我们家在黄河边上，他们家在机场高速 哪儿我们都去过，所以一提北京都想吐 所有学校周围都有拉面馆和饭店 再往前走不到十米就是成人宝铺 [Verse2] 夜里能去楼下和哥儿几个喝一点 夏天游泳，但是没买游泳裤衩儿 除了整天喝酒，啥做不了干不了的 抽烟不抽别的，点儿大中华烟""", "duration": 25, "seed": 6688, "guidance_scale": 7.0 } audio_result = pipeline.generate(**gen_params) audio_result.save("./outputs/ace_test_01.wav") print("✅ 音频生成完成，保存到 outputs/ace_test_01.wav")
参数说明
prompt：音乐描述，控制曲风、人声音色、配器；英文提示词模型识别更稳定lyrics：歌词，[Verse]、[Chorus]分段标记会影响 AI 演唱断句，建议严格按照格式写duration：音频时长，8G 显存建议≤25 秒，过长直接触发 CUDA OOMseed：随机种子，固定种子可以复现完全相同的生成结果，用来反复调优提示词guidance_scale：提示词相关性，取值范围 1~10，数值越高越贴合 prompt，但过高容易造成音频失真、爆音
四、OOM 显存溢出问题修复代码 & 指令
8G 显卡最容易碰到CUDA out of memory，下面是几种工程上的处理手段。
- 显存缓存清理脚本
free_gpu.py
import torch import gc torch.cuda.empty_cache() gc.collect() print("✅ GPU cache cleared")
CMD 运行
python free_gpu.py
- 进阶环境变量追加到 bat，启用可扩展显存分段
set PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
- 工程方案：分段生成音频，再使用 FFmpeg 拼接 不要一次性生成完整长歌曲，拆成多段 20~25s 片段，分别生成，最后合并音频。
五、FFmpeg 音频处理命令（后处理）
模型默认输出 wav 无损音频，体积很大，这里提供批处理脚本做格式转换、音频拼接。
脚本 1：wav 批量转 mp3 wav2mp3.bat
@echo off for %%i in (outputs\*.wav) do ( ffmpeg -i "%%i" -c:a libmp3lame -b:a 192k -y "outputs\%%~ni.mp3" ) echo 批量转换完成 pause
脚本 2：多段音频拼接 concat_audio.bat
@echo off echo file 'outputs/part1.wav' > audio_list.txt echo file 'outputs/part2.wav' >> audio_list.txt echo file 'outputs/part3.wav' >> audio_list.txt ffmpeg -f concat -safe 0 -i audio_list.txt -c copy outputs/full_song.wav del audio_list.txt echo 音频合并成功 pause
六、硬件参数对照表（实测）
表格
| 硬件 | 推荐配置 | 注意事项 |
| 8G NVIDIA 显卡 | low_vram=True，单次 duration≤25s，guidance_scale 6~7.5 | 长音频必须分段生成 |
| 12G+ NVIDIA 显卡 | low_vram=False，单次 duration≤40s，guidance_scale7~9 | 生成速度更快，音频细节更好 |
七、常见问题排查命令
- 找不到模型权重：检查路径是否含中文，查看当前目录
cd
- PyTorch CUDA 版本查看
python -c "import torch;print(torch.version.cuda)"
- 端口占用：修改 start.bat 里
--port 7860，替换为 7861 等空闲端口
八、本地部署完整工作流总结
- 拉取模型权重，放置到纯英文路径，执行
check_env.py检测硬件环境 - 配置虚拟环境，安装 torch、transformers 等依赖包
- 运行
start.bat启动 WebUI，浏览器访问本地服务 - 选择 text2music 任务，填写风格 prompt + 带分段标记歌词，设置生成参数
- 生成音频保存到 outputs 目录，用 FFmpeg 脚本做格式转换或者分段拼接
- 调整 seed、guidance_scale、prompt 反复迭代，优化演唱与编曲效果
九、限制说明（技术笔记重点）
- 8G 显卡只能生成短片段，长歌曲必须分段拼接，拼接处会有衔接断层；
- 中文歌词的咬字、断句偶尔出现错乱，需要反复调整歌词分段标记；
- 模型偶尔会出现爆音、伴奏和人声音量失衡，生成后需要用音频软件二次混音；
- 请遵守模型开源协议，不要用于侵权、商用音乐需要确认授权。
