IndexTTS2 本地安装与使用指南：uv、模型下载和 WebUI 测试

整理 IndexTTS2 在 Windows 本地安装、依赖同步、模型下载、WebUI 测试和项目集成的通用流程。

适用场景

IndexTTS2 是一个适合本地部署的文本转语音和音色克隆工具。它常用于中文配音、参考音克隆、视频翻译配音、课程解说和批量语音生成。

这篇文章整理的是通用安装流程，不绑定某个具体项目。你可以把 IndexTTS2 安装到任意稳定目录，例如：

<project-root>\index-tts

或者放到专门的本地 AI 工具目录：

<ai-tools-root>\tts\index-tts

只要后续脚本能找到这个目录即可。

1. 进入你的项目目录

打开 Anaconda Prompt、PowerShell 或 Windows Terminal，进入你准备放置 IndexTTS2 的项目目录：

cd /d <project-root>

这里的 <project-root> 是占位符，换成你自己的项目目录即可。

2. 安装 uv 和 Git LFS

IndexTTS2 官方推荐使用 uv 管理依赖环境，同时仓库和模型文件会用到 Git LFS。先安装或确认这两个工具：

pip install -U uv
git lfs install

如果提示 git lfs 不是命令，说明还没有安装 Git LFS，需要先安装后再执行：

git lfs install

Git LFS 官方地址：

https://git-lfs.com/

3. 下载 IndexTTS2 源码

在项目目录下克隆官方仓库：

git clone https://github.com/index-tts/index-tts.git
cd index-tts
git lfs pull

git lfs pull 用来拉取仓库中的大文件。如果网络不稳定，可以稍后重试。

4. 安装 IndexTTS2 依赖

进入 index-tts 目录后，用 uv 同步依赖：

uv sync --all-extras

如果你只想先跑 WebUI，可以使用：

uv sync --extra webui

如果在 Windows 上安装 DeepSpeed 或加速组件遇到问题，可以先减少 extra，优先把基础推理和 WebUI 跑通。

如果下载 Python 包比较慢，可以指定国内镜像，例如：

uv sync --all-extras --default-index "https://mirrors.aliyun.com/pypi/simple"

也可以换成其它可用 PyPI 镜像。

注意：官方文档强调使用 uv 运行项目，不建议手动激活其它 Python 环境后再混装依赖。uv run 会自动使用当前项目自己的 .venv。

5. 下载 IndexTTS2 模型

模型文件默认建议放到 index-tts\checkpoints 目录。

使用 Hugging Face 下载：

uv tool install "huggingface-hub[cli,hf_xet]"
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints

如果 Hugging Face 下载慢，可以尝试 ModelScope：

uv tool install modelscope
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints

下载完成后，目录里通常应该能看到：

index-tts\checkpoints\config.yaml

如果没有这个文件，说明模型目录不完整，后续推理大概率会失败。

6. 测试 WebUI

在 index-tts 目录下执行：

uv run webui.py

启动后打开浏览器访问：

http://127.0.0.1:7860

WebUI 适合做第一次环境验证：上传参考音、输入文本、确认能否成功合成 wav。等 WebUI 跑通后，再接入自己的 Python 脚本或批处理流程会更稳。

7. 在自己的项目里调用

业务项目不一定要启动 WebUI。更常见的方式是用脚本直接调用 IndexTTS2 推理代码。

为了让业务脚本知道 IndexTTS2 在哪里，可以设置环境变量：

set "INDEXTTS_ROOT=<path-to-index-tts>"
set "INDEXTTS_MODEL_DIR=<path-to-index-tts>\checkpoints"
set "INDEXTTS_CFG=<path-to-index-tts>\checkpoints\config.yaml"

如果你写的是批处理脚本，可以在运行 Python 主流程前设置这些变量。这样同一个视频翻译、语音克隆或批量配音项目就能稳定找到模型。

8. 参考音建议

音色克隆效果很依赖参考音。建议参考音满足这些条件：

单人说话，尽量不要多人重叠
背景音乐和噪声越少越好
不要截到大段静音
3 到 10 秒通常比 1 秒以内更稳
多人视频最好按句截取对应人物的参考音

如果是自动化流程，要在调用模型前检查参考音是否为空、是否太短、音量是否过低。无效参考音要跳过或回退到备用参考音。

9. 常见问题

uv tool 安装后找不到命令

如果安装工具后提示命令不在 PATH，先看 uv tool 输出的提示。它通常会告诉你应该把哪个目录加入 PATH。也可以在脚本里直接使用工具的绝对路径。

下载模型很慢

可以换网络，或从 Hugging Face 改用 ModelScope。模型目录只要最终完整落到 checkpoints 即可。

WebUI 能打开但合成失败

优先检查三件事：

checkpoints\config.yaml 是否存在
参考音是否有效
终端里是否有 CUDA、依赖版本或权限错误

批处理里路径失效

不要在公开脚本里写死个人电脑路径。更推荐用环境变量、配置文件或相对路径。需要公开示例时，用 <project-root>、<path-to-index-tts> 这类占位符。

是否每次都要启动 WebUI

不需要。WebUI 只是测试和手动体验入口。自动化批处理通常直接调用推理脚本，不需要先启动 uv run webui.py。

10. 官方参考

IndexTTS 官方仓库：

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

IndexTTS2 Hugging Face 模型：

https://huggingface.co/IndexTeam/IndexTTS-2

IndexTTS2 ModelScope 模型：

https://modelscope.cn/models/IndexTeam/IndexTTS-2

实际安装命令可能会随官方仓库更新而变化，遇到差异时优先以官方 README 为准。