ACE-Step-1.5 本地 AI 音乐模型实战｜text2music 歌词转人声，部署脚本、参数调优与排坑全记录

前言

最近在测试本地端 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 OOM
seed：随机种子，固定种子可以复现完全相同的生成结果，用来反复调优提示词
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 显卡只能生成短片段，长歌曲必须分段拼接，拼接处会有衔接断层；
中文歌词的咬字、断句偶尔出现错乱，需要反复调整歌词分段标记；
模型偶尔会出现爆音、伴奏和人声音量失衡，生成后需要用音频软件二次混音；
请遵守模型开源协议，不要用于侵权、商用音乐需要确认授权。

ACE-Step-1.5 本地 AI 音乐模型实战｜text2music 歌词转人声，部署脚本、参数调优与排坑全记录

前言

一、项目目录规划与环境预检脚本

二、WebUI 服务启动脚本（start.bat）

三、底层 Python 调用示例：text2music 歌词生成音频

四、OOM 显存溢出问题修复代码 & 指令

五、FFmpeg 音频处理命令（后处理）

脚本 1：wav 批量转 mp3 wav2mp3.bat

脚本 2：多段音频拼接 concat_audio.bat

六、硬件参数对照表（实测）

七、常见问题排查命令

八、本地部署完整工作流总结

九、限制说明（技术笔记重点）

脚本 1：wav 批量转 mp3 `wav2mp3.bat`

脚本 2：多段音频拼接 `concat_audio.bat`