IndexTTS2 部署教程 全网超详细 Windows/Linux/Mac 搭建指南

一、IndexTTS2 简介

IndexTTS2 是阿里旗下的B站语音团队（对，就是B站自己搞的）在2025年9月开源的一个TTS模型。说实话，它最大的亮点就两个：情绪到位，时长可控。

技术上它不是那种单块大模型硬怼，而是拆成了三个模块串起来干活：先文本转语义，再语义转旋律，最后用声码器出声。这么拆的好处是每一层可以单独优化，出来的声音更稳。

比较有意思的是它的情感和音色解耦。简单说就是，你换个音色说话，情绪不会跟着跑偏；你想让同一句话开心地说、难过地说，它也能分开控制，不串味儿。

训练上它也耍了点小聪明——分阶段训练，先让模型学会基本发音，再慢慢加情绪负荷，这样复杂情绪不会被压成“太平公主”。

最后还有个时间轴机制，这玩意儿在自回归TTS里算是个创新。以前模型经常把一句话读得忽快忽慢，IndexTTS2给每个音素都标了时间坐标，节奏控制就稳多了，听着更像真人说话的自然节奏。

总之，它不是那种“能出声就行”的老派TTS，是冲着有感情的真人配音去的。

二、环境准备

1.系统要求

• 支持 Linux / Windows / macOS
• 推荐 Linux + NVIDIA GPU（推理速度与稳定性最佳）

2.硬件要求

• GPU： NVIDIA 显卡（建议 ≥ 8GB 显存，CUDA ≥ 12.8）
• CPU： ≥ 4 核
• 内存： ≥ 16GB
• 磁盘： ≥ 20GB 可用空间（模型权重较大）

3.软件依赖

• Git、Git LFS
• Python ≥ 3.9
• uv（Astral 的现代 Python 包管理/运行工具；本项目按官方推荐仅支持 uv 安装）

三、GitHub项目包

https://github.com/index-tts/index-tts

GitHub链接打不开，大概率是网络问题。GitHub国内经常被“半墙”，直连很慢或直接超时，如有条件建议自行开代理。

四、安装

1.安装 Git

官方文档：https://git-scm.com/book/zh/v2/%e8%b5%b7%e6%ad%a5-%e5%ae%89%e8%a3%85-Git

2.克隆项目代码

在你的 Windows / Linux / MacOS 系统上根据自己的需求创建项目文件夹

确保在项目文件夹环境内执行以下命令

# 1.在仓库中启用Git-LFS
git lfs install

# 2.下载代码
git clone https://github.com/index-tts/index-tts.git

# 3.进入 index-tts 目录
cd index-tts

# 4.下载大文件
git lfs pull

3.安装 uv（两种方式任选其一）

官方安装器和 pip 安装

推荐pip 安装但是需要先安装 Python

方式 A：官方安装器

根据你的系统执行以下命令

• Linux / macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows PowerShell（Windows 系统）

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

方式 B：pip 安装（需要先装好 Python）

系统里必须已经安装了 Python 才能执行

pip install -U uv

若用 pip 安装后出现 “找不到 uv 命令”，请参考下方七、uv 环境变量（PATH）配置与校验。

4.使用 uv 安装依赖

# 1.安装所有特性（含 WebUI、DeepSpeed 等）
uv sync --all-extras

# 2.国内加速（任选其一）
uv sync --all-extras --default-index "https://mirrors.aliyun.com/pypi/simple"
# 或
uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

Windows 上安装 DeepSpeed 可能报错；如遇到问题，可改为精简安装：

# 1.安装基础依赖 + WebUI所需组件（不含DeepSpeed，避免Windows/macOS报错）
uv sync --extra webui


# 2.国内加速（任选其一）
uv sync --extra webui --default-index "https://mirrors.aliyun.com/pypi/simple"
# 或
uv sync --extra webui --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

5.下载模型权重

Hugging Face / ModelScope 二选一

A. Hugging Face

uv tool install "huggingface-hub[cli,hf_xet]"

hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints

如果网络不畅可用镜像：

# Linux/macOS
export HF_ENDPOINT="https://hf-mirror.com"

# Windows PowerShell 注意该命令使用 CMD（命令提示符）命令是无效的，需要使用Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

B. ModelScope

uv tool install "modelscope"

modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints

五、检查 GPU 是否可用

此命令可以执行自行检查，如果确定自己的 GPU 正常，可忽略。

uv run tools/gpu_check.py

六、uv 环境变量（PATH）配置与校验

适用场景：执行 uv --version 或 uv sync 报“找不到命令/不是内部或外部命令”。

Windows 配置 PATH

1.查找 uv.exe 路径 在 PowerShell 或 CMD 执行：

where uv.exe

常见位置：

• C:\Users\<你的用户名>\AppData\Roaming\Python\Python311\Scripts\
• 或 C:\Python311\Scripts\ 如果上述命令无结果，可进入 pip show uv 中的 Location 目录，继续在其并列的 Scripts 目录查找 uv.exe。

2.添加到 PATH

• 按 Win + R → 输入 sysdm.cpl 回车
• 选择 高级 → 环境变量
• 在 用户变量（或系统变量）中选中 Path → 编辑
• 点击 新建，填入上一步的 Scripts 路径（例如：C:\Users\<你的用户名>\AppData\Roaming\Python\Python311\Scripts\）
• 确定 保存

3.重启终端并验证

关闭并重新打开 PowerShell 或 CMD，执行：

uv --version

能显示版本号即为成功。若仍失败，先使用完整路径临时执行：

C:\Users\<你的用户名>\AppData\Roaming\Python\Python311\Scripts\uv.exe sync --all-extras

Linux / macOS 配置 PATH

1.确认 uv 安装位置（安装器通常已写 PATH；pip 安装常在 ~/.local/bin/）

which uv || echo "not found"
ls ~/.local/bin/uv  # 若存在，说明 uv 在该目录

2.将 **~/.local/bin** 加入 PATH（以 zsh 为例）

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

bash 用户改为写入 ~/.bashrc 或 ~/.bash_profile：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

3.验证

uv --version

若仍找不到，临时用：

python -m uv 需要 uv 作为 Python 模块被 pip 安装过

python -m uv --version

提示：修改 PATH 后必须 新开一个终端 或执行 source 使之生效。

七、运行方式

启动 WebUI

uv run webui.py

访问地址：http://127.0.0.1:7860

常用可选参数：

# 半精度，省显存
uv run webui.py --fp16

# DeepSpeed 加速（视系统而定）
uv run webui.py --deepspeed

# 编译 CUDA kernel 提升性能
uv run webui.py --compile

# 推荐使用 启用 FP16（半精度浮点）模式 来节省显存并提升推理速度。 --cuda_kernel启用或强制使用 CUDA 加速内核。
uv run webui.py --fp16 --cuda_kernel

八、常见问题（FAQ）

Q1：CUDA 报错或 GPU 不识别？

确认已安装 CUDA Toolkit ≥ 12.8 并与驱动匹配（NVIDIA CUDA 下载页面）

执行 uv run tools/gpu_check.py 查看设备可用性

WebUI 启动可尝试 --fp16 降低显存占用

Q2：Windows 下 DeepSpeed 安装失败？

首次安装可跳过，直接执行：uv sync --extra webui

待环境稳定后再按需补装 DeepSpeed

Q3：下载依赖/权重太慢？

uv sync 时使用国内 PyPI 镜像

Hugging Face 设置 HF_ENDPOINT="https://hf-mirror.com"

Q4：只有 CPU 可跑吗？

可以但极慢且体验差，不推荐生产使用

Q5：uv sync 卡在 Installing wheels... 不动，磁盘无读写？

这通常是 uv 在 Windows 下的兼容性问题。解决方案：

按 Ctrl + C 终止，用 --link-mode=copy 重试：

uv sync --extra webui --link-mode=copy

如果仍卡住，删除虚拟环境重试：

rmdir /s /q .venv
uv cache clean
uv sync --extra webui --link-mode=copy

Q6：uv sync 卡在 Installing wheels... 不动，磁盘无读写？

仓库作者的 LFS 配额已用完，不影响核心代码。解决方案：

方案一：跳过 LFS 文件克隆

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/index-tts/index-tts.git

方案二：直接下载 GitHub 页面的 ZIP 包（无需 LFS）

Q7：运行时提示 NoBackendError（音频解码失败）？

Windows 缺少音频解码库，安装 ffmpeg 即可：

1. 下载 https://github.com/BtbN/FFmpeg-Builds/releases 中的 ffmpeg-master-latest-win64-gpl.zip
2. 解压到 D:\ffmpeg，将 D:\ffmpeg\bin 添加到 PATH
3. 或临时设置：set PATH=D:\ffmpeg\bin;%PATH%

Q8：modelscope download 报错 ModuleNotFoundError: pkg_resources？

直接调用了系统 Python，应使用项目虚拟环境的版本：

# 正确方式
uv run modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints

# 或先激活虚拟环境
.venv\Scripts\activate
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints

Q9：uv tool install 安装的工具和 uv sync 安装的包有什么区别？

	uv tool install	uv sync
安装位置	系统用户目录 ~/.local/bin	项目虚拟环境 .venv
用途	全局命令行工具（如 hf、modelscope）	项目运行依赖
删除方式	uv tool uninstall <包名>	uv pip uninstall <包名> 或删除 .venv

Q10：如何完全清理项目重来？

# 1. 删除虚拟环境
rmdir /s /q .venv

# 2. 删除模型文件（可选）
rmdir /s /q checkpoints

# 3. 清理 uv 缓存
uv cache clean

# 4. 重新开始
uv sync --extra webui --link-mode=copy
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
uv run python webui.py