Windows 10 本地部署 IndexTTS2
工具 Git 和 Git LFS拓展支持并拉取仓库到本地
首先确定本地有git工具, 如果没有可以直接下载并安装git-scm, 安装完成后执行命令支持LFS大文件
git lfs install
新建一个目录用于保存IndexTTS2项目, 比如这里新建E:\Python目录作为存储目录.
# 切换到你想存放源码的目录
cd E:\Python
# 拉取代码，并且重命名文件夹为 indextts2
git clone https://github.com/index-tts/index-tts.git indextts2
# 切换到 indextts2 目录
cd indextts2
# 下载仓库里LFS管理的文件
git lfs pull
安装项目依赖包,基于uv包管理工具(官方推荐)
以下操作都在项目目录下进行,即上面提到的E:\Python\indextts2
安装uv包管理器
# 安装 uv 包管理器
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 验证是否安装成功：重新打开一个powershell窗口执行
uv --version
注意修改项目文件indextts2/pyproject.toml的一下内容使用#注释掉
# deepspeed = [
# "deepspeed==0.17.1",
# ]
# no-build-isolation-package = ["deepspeed"]
开始安装环境依赖
uv python install 3.10 # 安装python解释器，指定版本，项目要求>=3.10
uv python pin 3.10 # 项目锁定版本
uv venv # 创建虚拟环境
uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple" # 安装项目依赖，并指定使用清华的镜像
下载开源模型
# 安装可执行的命令行工具 modelscope
uv tool install "modelscope"
# 执行命令前确保目录是在indextts的工程目录下，这样才会把模型下到工程目录里的checkpoints下面，比如我的：(base) PS D:\ruanjian\indextts2>
# 下载IndexTTS2模型，并且指定下载到checkpoints目录
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
项目检查运行
# 检查本机环境的CUDA和GPU是否可用
uv run tools/gpu_check.py
# 运行WebUI
uv run webui.py
打开浏览器访问http://localhost:7860/
问题排除
错误提示1
按照以上步骤,运行uv run webui.py命令后可能会出现问题
OSError: We couldn't connect to 'https://huggingface.co' to load the files, and couldn't find them in the cached files.
Checkout your internet connection or see how to run the library in offline mode at 'https://huggingface.co/docs/transformers/installation#offline-mode'.
原因是本地环境变量缺少导致
右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
在「用户变量」或「系统变量」中，点击「新建」，分别添加：
变量名：HF_ENDPOINT，变量值：https://hf-mirror.com
变量名：HF_HUB_ENABLE_HF_TRANSFER，变量值：1
错误提示2
OSError: Can't load feature extractor for 'facebook/w2v-bert-2.0'. If you were trying to load it from 'https://huggingface.co/models', make sure you don't have a local directory with the same name. Otherwise, make sure 'facebook/w2v-bert-2.0' is the correct path to a directory containing a preprocessor_config.json file
原因是下载的文件超时没有成功导致缓存占据, 这里需要清理环境并手动下载
1. 进入C:\Users\你的用户名\.cache\huggingface\hub，找到并删除名为 models--facebook--w2v-bert-2.0 的文件夹
2. 在浏览器中打开 https://hf-mirror.com/facebook/w2v-bert-2.0
点击 Files and versions 标签页，下载该页面上的所有文件，将它们放入到
.cache/huggingface/hub/
└── models--facebook--w2v-bert-2.0/
└── snapshots/
└── a1b2c3d.../ <-- 这个文件夹名字可以是任意的，比如用一个随机的哈希值或日期
├── config.json
├── preprocessor_config.json
├── pytorch_model.bin
└── ... (其他所有下载的文件)
错误提示3
raise ValueError(
ValueError: Fast download using 'hf_transfer' is enabled (HF_HUB_ENABLE_HF_TRANSFER=1) but 'hf_transfer' package is not available in your environment. Try `pip install hf_transfer`.
原因是缺少hf_transfer包
# 打开终端，进入项目根目录（E:\Python\indextts2），运行以下命令：
# 用 uv 安装 hf_transfer，自动放入 .venv 虚拟环境
uv pip install hf_transfer
排除多个错误后, 就可以正常进入到页面进行体验了.