vLLM-Omni 部署 IndexTTS 2.5

谢白羽2026-08-24 15:42

文章目录

1.第一阶段：autoregressive talker（自回归 Talker 模块）

输入文本，不直接生成音频，输出语义编码（semantic codes）。

语义编码是中间抽象表示：包含说话内容、韵律、停顿、音色信息，是离散 token 序列。

2.第二阶段声学‑波形合成流水线（多个子模块串联）

  • EnhancedCodec → S2Mel CFM/DiT → BigVGAN
  • S2Mel CFM/DiT：把语义编码转换成梅尔频谱（声学特征）；
    BigVGAN 声码器：把梅尔频谱，最终输出 22.05kHz 单声道 WAV 音频。

简单理解：文本 →（自回归 GPT 生成语义 token）→（扩散模型生成梅尔谱）→（GAN 声码器输出声音文件）

一、部署结论与固定参数

项目 固定值
操作系统 Ubuntu Linux
Python 3.12
vLLM 0.27.0
vLLM-Omni 与 vLLM 主次版本一致；本次源码构建版本设为 0.27.0
模型 IndexTeam/IndexTTS-2.5
Python 环境 /opt/vllm-omni-indextts25
vLLM-Omni 源码 /opt/vllm-omni-main
模型目录 /data/models/modelscope/IndexTTS-2.5
使用 GPU 物理 GPU 1，即 CUDA_VISIBLE_DEVICES=1
服务端口 8092
部署配置 /opt/vllm-omni-main/vllm_omni/deploy/indextts2_5.yaml

二、检查环境和服务、安装源码和下载模型

1.安装python环境和库

shell 复制代码 
sudo apt-get update          
sudo apt-get install -y \          
  python3.12 python3.12-venv python3.12-dev \          
  unzip ffmpeg libsndfile1 build-essential

创建独立环境

shell 复制代码 
sudo mkdir -p /opt/vllm-omni-indextts25          
sudo chown -R "$USER":"$USER" /opt/vllm-omni-indextts25          

python3.12 -m venv /opt/vllm-omni-indextts25          
source /opt/vllm-omni-indextts25/bin/activate          

python -m pip install -U pip uv setuptools wheel

确认所有命令都来自新环境：

复制代码 
which python          
which pip          
which uv          
python --version

预期 python、pip、uv 路径均位于 /opt/vllm-omni-indextts25/bin/。

下载包含 IndexTTS 2.5 支持的 vLLM-Omni 源码 ZIP。为避免后续源码变化，生产环境应保存所用 ZIP 的日期或 commit 信息，不要每次重新下载 main。

2.安装源码

启动前确认源码确实支持 IndexTTS 2.5

复制代码 
test -f /opt/vllm-omni-main/vllm_omni/deploy/indextts2_5.yaml          
test -f /opt/vllm-omni-main/examples/online_serving/text_to_speech/indextts2/run_server.sh          

grep -n -A8 -B2 "indextts2" /opt/vllm-omni-main/pyproject.toml

如果任一 test 返回非零，说明 ZIP 太旧或不完整，停止安装并重新取得正确源码。

显式安装匹配版本的 vLLM聊天中的一次失败是只安装了 vllm-omni，环境里没有 vllm 本体。这里先明确安装：

shell 复制代码 
source /opt/vllm-omni-indextts25/bin/activate          

uv pip install \          
  --python /opt/vllm-omni-indextts25/bin/python \          
  "vllm==0.27.0" \          
  --torch-backend=auto

从 ZIP 源码安装 vLLM-Omni 和 IndexTTS 依赖ZIP 不带 .git 元数据，setuptools-scm 无法推导版本。必须使用官方构建变量给出合法版本号，否则可能报：

复制代码 
packaging.version.InvalidVersion: Invalid version: 'dev'

正确安装命令：

shell 复制代码 
cd /opt/vllm-omni-main          
source /opt/vllm-omni-indextts25/bin/activate          

VLLM_OMNI_VERSION_OVERRIDE=0.27.0 \          
VLLM_OMNI_TARGET_DEVICE=cuda \          
uv pip install \          
  --python /opt/vllm-omni-indextts25/bin/python \          
  ".[indextts2]"

3.环境验收

离开源码目录再测试，避免 Python 因当前目录而"碰巧"加载源码：

shell 复制代码 
cd /tmp          
source /opt/vllm-omni-indextts25/bin/activate          

python - <<'PY'          
import torch          
import vllm          
import vllm_omni          
import modelscope          

print("Torch:", torch.__version__)          
print("Torch CUDA:", torch.version.cuda)          
print("vLLM:", vllm.__version__)          
print("vLLM path:", vllm.__file__)          
print("vLLM-Omni path:", vllm_omni.__file__)          
print("ModelScope:", modelscope.__version__)          
print("CUDA available:", torch.cuda.is_available())          
assert torch.cuda.is_available(), "PyTorch cannot access CUDA"          
PY          

vllm --version

如果 vLLM 和 vLLM-Omni 的主次版本不一致，先停止，不要继续启动模型。

3.下载模型

IndexTTS 2.5 不是只有 gpt.pth 和 s2mel.pth。本地离线 bundle 还需要 Wav2Vec2-BERT、CAMPPlus 和指定版本的 BigVGAN。缺一项都会在 Stage 0 或 Stage 1 初始化时失败。

1.下载主模型
shell 复制代码 
source /opt/vllm-omni-indextts25/bin/activate          

MODEL_DIR=/data/models/modelscope/IndexTTS-2.5          
mkdir -p "$MODEL_DIR"          

modelscope download \          
  --model IndexTeam/IndexTTS-2.5 \          
  --local_dir "$MODEL_DIR"

不要使用 IndexTeam/IndexTTS-2 代替 2.5。

2 下载 CAMPPlus

服务器可访问 ModelScope 时：

shell 复制代码 
source /opt/vllm-omni-indextts25/bin/activate          

modelscope download \          
  --model iic/speech_campplus_sv_zh-cn_16k-common \          
  --local_dir /data/models/modelscope/campplus          

CAMPPLUS_FILE="$(find /data/models/modelscope/campplus \          
  -type f -name 'campplus_cn_common.bin' -print -quit)"          

test -n "$CAMPPLUS_FILE"          
install -m 0644 "$CAMPPLUS_FILE" \          
  /data/models/modelscope/IndexTTS-2.5/campplus_cn_common.bin

如果 ModelScope 仓库结构变化，也可以在可访问 Hugging Face 的电脑下载 funasr/campplus，只需取得 campplus_cn_common.bin。

3.准备 Wav2Vec2-BERT

先检查主模型是否已包含：

shell 复制代码 
test -f "$MODEL_DIR/w2v-bert-2.0/config.json"          
test -f "$MODEL_DIR/w2v-bert-2.0/model.safetensors"          
test -f "$MODEL_DIR/w2v-bert-2.0/preprocessor_config.json"

若缺失，在可访问 Hugging Face 的电脑下载并上传：

复制代码 
hf download facebook/w2v-bert-2.0 \          
  --local-dir w2v-bert-2.0          

scp -r w2v-bert-2.0 \          
  rtx4090@服务器IP:/data/models/modelscope/IndexTTS-2.5/
4.准备正确的 BigVGAN

必须使用：

复制代码 
nvidia/bigvgan_v2_22khz_80band_256x

不要使用 24 kHz、100-band、fmax8k 或方言微调模型替代；模型配置不匹配可能造成 shape 错误或音质异常。

特别注意：以下命令会返回 404，禁止再用：

复制代码 
# 错误示例：ModelScope 没有这个同名仓库 ID          
modelscope download --model nvidia/bigvgan_v2_22khz_80band_256x

在可访问 Hugging Face 的电脑下载官方模型：

复制代码 
hf download nvidia/bigvgan_v2_22khz_80band_256x \          
  --local-dir bigvgan_v2_22khz_80band_256x

服务器确认至少存在：

复制代码 
test -f "$MODEL_DIR/bigvgan/config.json"          
test -f "$MODEL_DIR/bigvgan/bigvgan_generator.pt"

同时兼容根目录与 hf_cache 搜索路径不同源码快照可能在根目录或 hf_cache 下查找辅助资产。使用软链接同时兼容两种布局：

shell 复制代码 
mkdir -p "$MODEL_DIR/hf_cache"          

ln -sfn ../w2v-bert-2.0 \          
  "$MODEL_DIR/hf_cache/w2v-bert-2.0"          
ln -sfn ../campplus_cn_common.bin \          
  "$MODEL_DIR/hf_cache/campplus_cn_common.bin"          
ln -sfn ../bigvgan \          
  "$MODEL_DIR/hf_cache/bigvgan
5.一次性资产预检

启动前必须让下面脚本输出 PRECHECK PASSED：

shell 复制代码 
MODEL_DIR=/data/models/modelscope/IndexTTS-2.5          

required_files=(          
  config.yaml          
  codec.pth          
  gpt.pth          
  s2mel.pth          
  feat1.pt          
  feat2.pt          
  wav2vec2bert_stats.pt          
  multilingual_zh_ja_yue_char_del.tiktoken          
  campplus_cn_common.bin          
  qwen0.6bemo4-merge/config.json          
  qwen0.6bemo4-merge/tokenizer.json          
  qwen0.6bemo4-merge/model.safetensors          
  w2v-bert-2.0/config.json          
  w2v-bert-2.0/preprocessor_config.json          
  w2v-bert-2.0/model.safetensors          
  bigvgan/config.json          
  bigvgan/bigvgan_generator.pt          
)          

failed=0          
for rel in "${required_files[@]}"; do          
  if [[ ! -s "$MODEL_DIR/$rel" ]]; then          
    echo "MISSING OR EMPTY: $MODEL_DIR/$rel"          
    failed=1          
  fi          
done          

if [[ $failed -ne 0 ]]; then          
  echo "PRECHECK FAILED"          
  exit 1          
fi          

echo "PRECHECK PASSED"          
du -sh "$MODEL_DIR"

三、启动服务并测试

1.前台启动测试

ModelScope 下载的 IndexTTS 2.5 是 native bundle，不是标准 Hugging Face config.json 布局。如果省略部署配置，可能报：

复制代码 
Could not detect config format          
Could not determine model_type

不要自己伪造 config.json。直接显式传入官方两阶段配置。

复制代码 
source /opt/vllm-omni-indextts25/bin/activate          
cd /tmp          

CUDA_VISIBLE_DEVICES=1 \          
FLASHINFER_DISABLE_VERSION_CHECK=1 \          
vllm serve /data/models/modelscope/IndexTTS-2.5 \          
  --omni \          
  --trust-remote-code \          
  --host 0.0.0.0 \          
  --port 8092 \          
  --deploy-config /opt/vllm-omni-main/vllm_omni/deploy/indextts2_5.yaml

--deploy-config /opt/vllm-omni-main/vllm_omni/deploy/indextts2_5.yaml说明：CUDA_VISIBLE_DEVICES=1 后，进程内部只看到一张逻辑 GPU 0；官方 YAML 中两个 Stage 的 devices: "0" 不需要改成 1。

第一次不要增加 --tensor-parallel-size、--max-model-len 或全局 --gpu-memory-utilization。IndexTTS 2.5 是两个 Stage，显存参数由 YAML 分别控制；本次配置中两个 Stage 默认各为 0.4。

可接受的非致命提示包括实验特性、弃用提醒、Stage 1 的 eager/compile 提示。判断成败要看最后是否持续监听端口，以及 /health 和 /v1/models 是否返回成功

2.后台启动

前台验证完成后按 Ctrl+C 停止，再后台运行：

shell 复制代码 
mkdir -p /data/logs/indextts25          

source /opt/vllm-omni-indextts25/bin/activate          
cd /tmp          

CUDA_VISIBLE_DEVICES=1 \          
FLASHINFER_DISABLE_VERSION_CHECK=1 \          
nohup vllm serve /data/models/modelscope/IndexTTS-2.5 \          
  --omni \          
  --trust-remote-code \          
  --host 0.0.0.0 \          
  --port 8092 \          
  --deploy-config /opt/vllm-omni-main/vllm_omni/deploy/indextts2_5.yaml \          
  > /data/logs/indextts25/server.log 2>&1 &          

echo $! > /data/logs/indextts25/server.pid          
tail -f /data/logs/indextts25/server.log

3.健康检查

复制代码 
curl -fsS http://127.0.0.1:8092/health && echo          
curl -fsS http://127.0.0.1:8092/v1/models | python -m json.tool          
ss -lntp | grep ':8092'          
nvidia-smi

如果 /health 尚未成功，查看日志而不是重复启动多个进程：`

复制代码 
tail -n 200 /data/logs/indextts25/server.log          
ps -ef | grep 'vllm serve' | grep -v grep

4.使用模型

推荐准备 /data/test/reference.wav：单人、无背景音乐、无明显噪声、普通说话，时长约 3～10 秒。确认文件可读：

shell 复制代码 
#读取 reference.wav 的媒体信息，只输出音频总时长，单位是秒。
mkdir -p /data/test          
ffprobe -v error \          
  -show_entries format=duration \          
  -of default=noprint_wrappers=1:nokey=1 \          
  /data/test/reference.wav

推荐：使用官方示例客户端直接携带参考音频

shell 复制代码 
source /opt/vllm-omni-indextts25/bin/activate          

python /opt/vllm-omni-main/examples/online_serving/text_to_speech/indextts2/speech_client.py \          
  --api-base http://127.0.0.1:8092 \          
  --model-version 2.5 \          
  --model /data/models/modelscope/IndexTTS-2.5 \          
  --ref-audio /data/test/reference.wav \          
  --lang zh \          
  --speed 1.0 \          
  --text "你好，这是使用 vLLM Omni 部署 Index TTS 二点五的中文语音合成测试。" \          
  --output /data/test/indextts25-test.wav

检查输出：

复制代码 
test -s /data/test/indextts25-test.wav          
file /data/test/indextts25-test.wav          
ffprobe -v error \          
  -show_entries stream=codec_name,sample_rate,channels,duration \          
  -of default=noprint_wrappers=1 \          
  /data/test/indextts25-test.wav

读取 WAV 音频流信息：

codec_name：编码格式，例如 pcm_s16le

sample_rate：采样率，例如 24000

channels：声道数，例如 1

duration：时长，单位秒

中英混合与语速测试zhen 用于中英混合；IndexTTS 2.5 原生语速范围为 0.5～2.0：

shell 复制代码 
python /opt/vllm-omni-main/examples/online_serving/text_to_speech/indextts2/speech_client.py \          
  --api-base http://127.0.0.1:8092 \          
  --model-version 2.5 \          
  --model /data/models/modelscope/IndexTTS-2.5 \          
  --ref-audio /data/test/reference.wav \          
  --lang zhen \          
  --speed 1.2 \          
  --text "你好，今天我们测试 Index TTS 2.5 的 voice cloning 效果。" \          
  --output /data/test/indextts25-zhen-speed12.wav

情绪文本测试

shell 复制代码 
python /opt/vllm-omni-main/examples/online_serving/text_to_speech/indextts2/speech_client.py \          
  --api-base http://127.0.0.1:8092 \          
  --model-version 2.5 \          
  --model /data/models/modelscope/IndexTTS-2.5 \          
  --ref-audio /data/test/reference.wav \          
  --lang zh \          
  --use-emo-text \          
  --emo-text "开心、兴奋而且充满活力" \          
  --emo-alpha 0.8 \          
  --text "太好了，我们终于把这个系统部署成功了！" \          
  --output /data/test/indextts25-happy.wav

可选：上传并复用命名音色如果当前 vLLM-Omni 版本启用了 /v1/audio/voices，可以上传一次后按名称复用：

复制代码 
curl -fsS -X POST http://127.0.0.1:8092/v1/audio/voices \          
  -F "audio_sample=@/data/test/reference.wav" \          
  -F "consent=authorized-test-voice" \          
  -F "name=test_voice" \          
  -F "speaker_description=Authorized Chinese test voice"          

curl -fsS http://127.0.0.1:8092/v1/audio/voices | python -m json.tool

随后测试：

复制代码 
python /opt/vllm-omni-main/examples/online_serving/text_to_speech/indextts2/speech_client.py \          
  --api-base http://127.0.0.1:8092 \          
  --model-version 2.5 \          
  --model /data/models/modelscope/IndexTTS-2.5 \          
  --voice test_voice \          
  --lang zh \          
  --text "这是复用已上传音色的测试。" \          
  --output /data/test/indextts25-uploaded-voice.wav

若音色上传端点与当前模型适配不一致，直接使用之前的 --ref-audio 路径；这是官方 IndexTTS 2.5 示例客户端的直接用法。

四、常见报错总结

报错或现象 根因 正确处理
Invalid version: 'dev' ZIP 包没有 .git，setuptools-scm 无法获取版本 安装时设置：VLLM_OMNI_VERSION_OVERRIDE=0.27.0
No module named 'vllm' 只安装了 vLLM-Omni，没有 vLLM 本体 显式安装：vllm==0.27.0
No module named 'modelscope' vLLM 导入 ModelScope 支持时缺少依赖 安装：modelscope>=1.18.1
Could not detect config format / Could not determine model_type 本地 native bundle 不是标准 Hugging Face config.json 格式 显式指定：--deploy-config .../indextts2_5.yaml
缺少 Wav2Vec2-BERT 主模型下载不完整，或辅助目录缺失 补齐 w2v-bert-2.0 的配置、处理器与权重
缺少 CAMPPlus checkpoint 没有 campplus_cn_common.bin 下载 CAMPPlus，复制到模型根目录，并链接至 hf_cache
IndexTTS BigVGAN assets are missing BigVGAN 目录不正确或资源不完整 使用 NVIDIA 官方 22kHz / 80-band / 256x BigVGAN 模型
ModelScope BigVGAN 返回 404 将 Hugging Face 模型 ID 当作 ModelScope 模型 ID 从 Hugging Face 下载后上传至服务器
CUDA out of memory 目标 GPU 已运行其他服务，或两个 Stage 配置过大 首次启动时独占 GPU；确认可运行后再逐步调整 YAML 中各 Stage 配置
日志出现 deprecation / experimental warning 通常是非致命提醒 以进程状态、端口、/health 和实际 WAV 生成结果为准

五、参考 资料

相关推荐
dong_junshuai2 分钟前
每天一个开源项目#79 Apache Maka：3K星本地Agent工作台
开源·github·agent
阿里云大数据AI技术1 小时前
知衣科技 × 阿里云：以MaxCompute 向量检索打通商品与海外社媒内容，让跨境选品看见真实热度
人工智能·agent
温暖的苹果1 小时前
opencode 配置完全指南:配置文件、目录与字段详解
ai·llm·agent·vibecoding·opencode
后端小肥肠2 小时前
历经两个月，我跑通了 Codex 自动剪辑，涨粉破千
人工智能·aigc·agent
不一样的少年_3 小时前
图解 AI Agent ②：模型到底是怎么读取文件的？
人工智能·agent·ai编程
zzz_23683 小时前
【AI代码测评】OpenCodeReview 架构拆解：确定性工程与 Agent 如何分工
人工智能·架构·agent·agent测评·harnes
阿里云大数据AI技术3 小时前
从数据平台到智能数据助手：Agentic 数据分析与 API 生产实践
人工智能·数据分析·agent
_遥远的救世主_3 小时前
Hermes Agent 内核原理与 Agent 平台开发方向
agent
AI创飞人类3 小时前
《从个人自动化到企业级交付：国内外主流智能体开发平台横向比较》
agent·智能体
qq_232045573 小时前
AI 应用开发/Agent学习路线----阶段零：认知校准（1~2 天）
agent
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费06历年考研数学一、数学二、数学三真题试卷及答案PDF07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法