IndexTTS 2.5 安装、DeepSpeed 加速与视频中文配音指南

在 CMD 检查 NVIDIA 驱动

nvidia-smi

方法 A：新手使用浏览器下载 v2.5.0 ZIP

1. 打开浏览器，在搜索引擎输入 IndexTTS GitHub。
2. 点击标题含 index-tts/index-tts 的结果。地址栏必须是 https://github.com/index-tts/index-tts。
3. 在仓库页面右侧找到 Releases，点击进入。
4. 选择 IndexTTS-2.5 / v2.5.0。也可以直接打开 v2.5.0 发布页。
5. 滚动到页面下方，展开 Assets，点击 Source code (zip)。
6. 浏览器通常把它保存到“下载”文件夹。右键 ZIP，选择全部解压缩。
7. 把解压后的目录移动到路径较短的位置，例如 C:\AI\index-tts-2.5.0。尽量避免 OneDrive、中文特殊符号和过深目录。

方法 B：安装 Git 后克隆代码

在你准备存放项目的父目录打开 CMD，然后输入：

git clone --branch v2.5.0 --depth 1 https://github.com/index-tts/index-tts.git index-tts-2.5.0
cd index-tts-2.5.0

如果你希望跟随开发中的最新版，可以在仓库首页点击绿色 Code 按钮，再点 Download ZIP；但 main 会变化，不保证与本文所有版本号完全一致。

最简单的方法：资源管理器地址栏输入 cmd

1. 在资源管理器进入项目目录，确认能看见 webui.py。
2. 点击窗口顶部的地址栏，原路径会变成可编辑文字。
3. 输入 cmd，按 Enter。
4. 黑色窗口打开后，提示符应显示项目路径，例如：

C:\AI\index-tts-2.5.0>

如果 CMD 已经打开：用 cd /d 切换目录

cd /d "C:\AI\index-tts-2.5.0"

/d 允许同时从 C 盘切换到 D 盘；路径含空格时必须加英文双引号。

确认当前位置正确

dir webui.py pyproject.toml uv.lock

4.1 Git（推荐）

1. 打开 Git for Windows 下载页。
2. 下载 64-bit Git for Windows Setup。
3. 运行安装程序；新手保留默认选项即可。完成后关闭并重新打开 CMD。

git --version

4.2 uv（必须）

uv 会替项目下载合适的 Python，并创建隔离的 .venv。不建议再混用 Conda 或手动激活虚拟环境。

py -m pip install -U uv

uv --version

4.3 NVIDIA CUDA Toolkit 12.8（DeepSpeed/编译加速建议安装）

1. 打开 NVIDIA 的 CUDA Toolkit 12.8 下载页。
2. 依次选择 Windows、x86_64、你的 Windows 版本、exe (local)。
3. 运行安装器。选择“自定义”时至少保留 CUDA Toolkit；如果已有更新的显卡驱动，不必强行降级驱动。
4. 安装结束后关闭所有 CMD，打开一个新 CMD。

where nvcc
nvcc --version

4.4 Visual Studio Build Tools（只在需要编译时安装）

1. 打开 Visual Studio Build Tools，点击 Download Build Tools。
2. 在 Visual Studio Installer 勾选使用 C++ 的桌面开发。
3. 确认右侧包含 MSVC v143、Windows 10/11 SDK、C++ CMake tools，然后安装。
4. 验证时从开始菜单打开 x64 Native Tools Command Prompt for VS 2022，输入 cl。

5.1 让 uv 准备 Python 3.11

uv python install 3.11

5.2 安装核心依赖和网页界面

uv sync --extra webui

中国大陆下载 PyPI 较慢时，可以改用下面任意一个镜像；只选一条运行：

uv sync --extra webui --default-index "https://mirrors.aliyun.com/pypi/simple"

uv sync --extra webui --default-index "https://pypi.tuna.tsinghua.edu.cn/simple"

5.3 验证项目 Python 与 PyTorch

.venv\Scripts\python.exe --version
uv run python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')"

方法 A：中国大陆优先使用 ModelScope

uv tool install modelscope
uv tool update-shell

运行第二条后，关闭 CMD，在项目目录重新输入 cmd 打开新窗口。然后下载：

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

方法 B：使用 HuggingFace

uv tool install "huggingface-hub"
uv tool update-shell

重新打开 CMD 后运行：

hf download IndexTeam/IndexTTS-2.5 --local-dir checkpoints

访问 HuggingFace 困难时，可在当前 CMD 会话临时指定镜像，再运行下载：

set HF_ENDPOINT=https://hf-mirror.com
hf download IndexTeam/IndexTTS-2.5 --local-dir checkpoints

检查模型是否完整

dir checkpoints\config.yaml checkpoints\gpt.pth checkpoints\s2mel.pth checkpoints\codec.pth

uv run webui.py --version 2.5 --fp16 --host 127.0.0.1 --port 7860

IndexTTS 2.5 中，项目的 --fp16 参数入口会选择支持的半精度路径；在支持 BF16 的 NVIDIA GPU 上使用 BF16。它能显著减少显存，通常不会造成可察觉的质量下降。

1. 不要关闭 CMD。
2. 打开浏览器，在地址栏输入 http://127.0.0.1:7860。
3. 如果网页没有自动刷新，等待模型加载完成后按一次刷新。

正确停止并释放内存/显存

1. 回到正在运行 WebUI 的 CMD 窗口。
2. 按 Ctrl + C。
3. 等命令提示符重新出现。此时再关闭窗口。

端口占用时找到进程

netstat -ano | findstr :7860

最后一列是 PID。确认它确实属于 IndexTTS 后，才运行：

taskkill /PID 这里替换成实际PID /T /F

8.1 先确保真正生效的是 CUDA 12.8

where nvcc
nvcc --version
uv run python -c "import torch; print(torch.__version__); print(torch.version.cuda)"

如果已经安装 12.8，但 nvcc --version 仍显示 13.3，可先只修正当前 CMD 会话：

set "CUDA_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8"
set "PATH=%CUDA_PATH%\bin;%CUDA_PATH%\lib\x64;%PATH%"
where nvcc
nvcc --version

永久修改请在 Windows 搜索“编辑系统环境变量” → “环境变量”，把 CUDA_PATH 指向 v12.8，并让 v12.8 的 bin 排在 v13.3 前。不要使用 setx PATH ... 整体重写 PATH，它可能截断或破坏现有内容。

8.2 修改官方 v2.5.0 的 DeepSpeed 版本和 wheel 来源

1. 在项目目录找到 pyproject.toml，右键用记事本或代码编辑器打开。
2. 按 Ctrl + F 搜索 deepspeed==0.17.1，改成 deepspeed==0.17.5。
3. 继续找到 [tool.uv.sources]。紧接在它下面、现有 torch = [ 之前，加入下列内容。

deepspeed = [
  { url = "https://github.com/6Morpheus6/deepspeed-windows-wheels/releases/download/v0.17.5/deepspeed-0.17.5%2Be1560d84-2.8torch_cu128-cp311-cp311-win_amd64.whl", marker = "sys_platform == 'win32' and python_version == '3.11'" },
]

保存 pyproject.toml，回到项目 CMD：

uv lock --upgrade-package deepspeed
uv sync --extra webui --extra deepspeed

8.3 验证 DeepSpeed 版本和完整推理内核

uv run python -c "import torch, deepspeed; print(torch.__version__); print(torch.version.cuda); print(deepspeed.__version__)"

uv run python -m deepspeed.env_report

本机保存的稳定启动命令

set INDEXTTS_DIFFUSION_STEPS=24
uv run --no-sync webui.py --version 2.5 --fp16 --deepspeed --host 127.0.0.1 --port 7860

--no-sync 表示直接使用已经安装好的环境，启动时不重新解析依赖。只有在 uv sync 已成功后使用。

创建双击启动的 BAT 文件

1. 在项目目录右键 → 新建 → 文本文档。
2. 改名为 start_indextts_deepspeed_24.bat。确认扩展名不是 .bat.txt。
3. 用记事本打开，粘贴以下内容并保存。

@echo off
setlocal
cd /d "%~dp0"
set "INDEXTTS_DIFFUSION_STEPS=24"
set "PYTHONUTF8=1"
".venv\Scripts\python.exe" webui.py --version 2.5 --fp16 --deepspeed --host 127.0.0.1 --port 7860
pause
endlocal

扩散步数实测记录（仅代表本机当时状态）

1. 启动 WebUI，打开 http://127.0.0.1:7860。
2. 在第一个文字转语音页面上传“音色参考音频”。
3. 语言选择 ZH，在文本框输入中文。
4. 需要稳定高质量时，在预设中选择质量优先。
5. 点击生成，等待网页播放器出现结果。

怎样准备更像的参考音频

• 推荐有效人声约 6–12 秒；本视频流程默认提取 12 秒。
• IndexTTS 读取参考音频时最多使用前 15 秒。超过 15 秒不会继续增加有效参考信息。
• 只包含一个人，背景音乐、混响、风噪和长静音越少越好。
• 语速、情绪、麦克风距离尽量稳定；不要截在单词或爆破音中间。
• 跨语言音色克隆可以“英文参考 → 中文输出”；模型 2.5 原生支持这种跨语言合成。

长文本如何分句

本机定制版优先把每个非空换行当作一条完整话语。下面输入会生成三句话：

这是第一句话。
这是第二句话。
这是第三句话。

• 没有手动换行时，程序按 。、！、？ 等句末标点拆分。
• 普通默认上限为每段 120 Token；“质量优先”预设提高到 160 Token。
• 超过上限时才继续按逗号等较弱边界拆分，以避免 8 GB 显存溢出。
• 不要简单按“40 个字符”机械切割，否则容易出现语气跳变和明显拼接感。

11.1 安装 Shotcut

1. 打开 Shotcut 官方下载页。
2. 选择 Windows installer，运行安装程序。
3. 建议使用默认目录 C:\Program Files\Shotcut。定制流程直接调用其中的 ffmpeg.exe 和 ffprobe.exe，不需要每次操作 Shotcut 图形界面。

若安装到其他目录，启动前在 CMD 设置：

set "SHOTCUT_ROOT=D:\你的软件目录\Shotcut"

11.2 下载 Whisper large-v3 模型

1. 在 C 盘新建 C:\models 文件夹。
2. 浏览器打开 ggml-large-v3.bin 模型页，点击下载按钮。
3. 国内网络可尝试镜像直链：hf-mirror large-v3。
4. 最终完整路径必须为 C:\models\ggml-large-v3.bin，不要保留浏览器附加的 .download 或 .tmp。

dir "C:\models\ggml-large-v3.bin"

11.3 第一步：提取英文字幕和音色参考

1. 启动本机定制 WebUI，切换到视频中文配音标签。
2. 在“本地视频路径”粘贴完整路径，例如 C:\Users\name\Videos\example.mp4。网页输入框不需要额外加引号。
3. 点击提取英文字幕。
4. 如果 MP4 内嵌英文字幕流，程序直接提取；否则调用 Shotcut/Whisper large-v3 识别。
5. 程序还会提取约 12 秒固定音色参考，供后面的中文 TTS 使用。

结果目录位于：

11.4 第二步：翻译并保存完整中文字幕

1. 打开网页显示的 english.srt。
2. 把完整文件交给可信的翻译 AI，要求保留每一个编号和时间码，只翻译字幕正文。
3. 不要翻译 Claude、Claude Design、prototype、wireframe 等你希望保留的英文名词。
4. 保存为 UTF-8 编码，文件名为 translated.zh.srt，放回同一结果目录。
5. 回到网页，确认“翻译后的中文字幕”输入框是完整路径，开头必须含盘符和反斜杠，例如 C:\...。

正确 SRT 块的格式如下：

1
00:00:00,291 --> 00:00:02,457
Claude Design 刚刚由

2
00:00:02,458 --> 00:00:04,208
Claude 的开发团队发布。很多人称它为

定制流程不会把每个编号误当成一句话。它会根据句末标点跨块重组，例如上面第 1、2 块的前半部分会合成：

本次实际文件从 303 个 SRT 块重组为 130 个完整句子；130 句全部以句末标点结束，没有在这份视频中触发 15 秒保护性硬拆分。

视频已有 chi 中文字幕时

不需要重新翻译。把该中文字幕导出为标准 UTF-8 SRT，保存或填写为 translated.zh.srt，然后按英文字幕对照检查错译。当前定制网页能直接读取这个中文 SRT 生成配音，但官方原版和当前“提取英文字幕”按钮不保证自动替你导出所有 chi 流。

11.5 第三步：选择配音参考模式并生成

1. 在“配音参考模式”选择一种模式。
2. 点击生成中文配音。
3. 保持网页和 CMD 打开，不要刷新或切走页面。
4. 完成状态会显示 SRT 块数、重组句数、情感参考数、总耗时、最大顺延和尾部延长。
5. 结果是同目录下的 chinese_dub.wav，网页也会显示播放器。

时间轴规则

• 不使用 FFmpeg atempo 强制变速。
• 不截掉长句结尾，不让相邻句音频重叠。
• 中文比 SRT 时间窗短：保留自然空白。
• 中文比时间窗长：下一句自然顺延，状态中记录最大漂移；视频末尾也可能延长。
• 视频模式内部 interval_silence=0，没有额外 140 ms 停顿，也没有新增句段边缘淡化。

建议备份的内容

• webui.py
• tools\web_video_dubbing.py 以及其他新增工具脚本
• pyproject.toml 和 uv.lock
• start_indextts_deepspeed_24.bat
• outputs\video-dubbing 中的 SRT、参考音频和最终 WAV

更新依赖后的标准动作

uv sync --extra webui --extra deepspeed

如果没有明确升级需求，不要随意删除 uv.lock。锁文件保证下次仍安装已验证的组合。

不用 TTS 时释放 GPU

1. 启动 CMD 中按 Ctrl+C。
2. 运行 netstat -ano | findstr :7860，确认没有 LISTENING。
3. 运行 nvidia-smi，确认没有项目 Python 进程。

需要释放磁盘空间时

确认不再需要后，可以在资源管理器中删除以下目录；这是卸载而不是普通清理：

• .venv：释放约 8.49 GiB，之后必须重新 uv sync。
• checkpoints：释放模型及缓存约 10.22 GiB，之后必须重新下载模型。
• outputs：会删除已经生成的字幕和音频，先备份需要的结果。

• 项目目录能直接看到 webui.py 和 pyproject.toml。
• uv --version 能输出版本。
• .venv\Scripts\python.exe --version 为 Python 3.11。
• PyTorch 输出 2.8.x+cu128、CUDA 12.8、GPU 可用 True。
• checkpoints 中的 config、gpt、s2mel、codec 文件都存在。
• 不带 DeepSpeed 的基础 WebUI 能启动并生成一段音频。
• 如使用 DeepSpeed/编译内核，nvcc --version 为 12.8。
• DeepSpeed 为 0.17.5，Transformer inference 和 inference core ops 为 YES/OKAY。
• 知道必须在 CMD 按 Ctrl+C 才能释放模型和显存。
• 使用视频定制功能时，Shotcut 和 C:\models\ggml-large-v3.bin 均存在。
• 知道 large-v3 负责英文听写，中文翻译文件必须保留 SRT 编号和时间码。
• 参考音色已取得合法授权。

官方与相关来源

• IndexTTS 官方 GitHub 仓库
• IndexTTS v2.5.0 发布页
• IndexTTS 官方中文 README
• IndexTTS-2.5 ModelScope 模型
• IndexTTS-2.5 HuggingFace 模型
• uv 官方安装文档
• Git for Windows
• NVIDIA CUDA Toolkit 12.8
• Visual Studio Build Tools
• Shotcut 官方下载
• whisper.cpp ggml-large-v3.bin
• 第三方 DeepSpeed Windows 0.17.5 wheel

本文中的本机版本、磁盘占用、扩散步数耗时和 DeepSpeed 内核状态来自 2026-08-26 的实际环境检查。软件更新后应重新核对官方 README、依赖锁文件和发行说明，不应把单机耗时当作所有设备的固定性能。

把本文部署到网站

1. 将这个 HTML 文件和同级的 assets 文件夹一起上传到网站的静态资源目录。HTML 可改名为 indextts-windows-guide.html；若它要作为独立站首页，可改名为 index.html。
2. 页面不需要 PHP、Python、Node.js 或数据库。章节勾选和深色模式使用浏览器 localStorage，只保存在访问者自己的设备。
3. 页面通过 HTTPS 引用 IndexTTS 官方标志和 Lucide 图标 CDN。若网站内容安全策略禁止外部资源，正文仍可阅读，按钮会显示内置备用符号；也可以把这些资源下载到自己网站后修改 src。
4. 发布后检查手机和桌面页面，并定期核对官方版本。不要删除第三方 DeepSpeed wheel 的来源提示。