目录
更新时间：2026-04-26
适用对象：Apple Silicon Mac 用户，包括 M1 / M2 / M3 / M4。
这份教程采用官方源码 + uv 的方式部署 IndexTTS-2 WebUI。它不是 Docker 方案，也不是第三方一键包方案。
官方项目地址：
- GitHub：https://github.com/index-tts/index-tts
- Hugging Face 模型：https://huggingface.co/IndexTeam/IndexTTS-2
一、适合什么 Mac？
推荐配置：
| 配置 | 建议 |
|---|---|
| 芯片 | Apple Silicon：M1 / M2 / M3 / M4 |
| 内存 | 16GB 起步，24GB / 32GB 以上更稳 |
| 系统 | macOS 13 以上更推荐 |
| 硬盘 | 至少预留 20GB，建议 30GB 以上 |
| 加速方式 | 优先尝试 PyTorch MPS / Metal，不支持 NVIDIA CUDA |
注意：
Mac 不支持 CUDA。IndexTTS-2 当前推理代码会自动检测 cuda、xpu、mps、cpu，Apple Silicon 可用时会尝试选择 mps，否则退回 CPU。
官方代码里还明确处理了 MPS 下不使用 FP16 的情况，因为在 MPS 上 FP16 可能带来额外开销或兼容性问题。
不过，MPS 是否稳定还取决于 macOS、PyTorch 版本、内存大小和具体算子支持。如果 MPS 报错，可以先强制 CPU 排查。
二、安装前准备
打开「终端」，先安装 Apple 命令行工具：
xcode-select --install
如果提示已经安装，可以忽略。
如果还没有安装 Homebrew，先安装 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
已经安装过 Homebrew 的用户可以跳过。
然后安装基础工具：
brew install git git-lfs ffmpeg uv
启用 Git LFS：
git lfs install
官方要求系统中有 Git 和 Git LFS，并且需要执行 git lfs install。
三、下载 IndexTTS-2 官方源码
建议统一放到英文路径，避免中文、空格、特殊符号导致路径兼容问题：
mkdir -p ~/AI
cd ~/AI
如果你以前没有下载过 IndexTTS-2，直接克隆：
git clone https://github.com/index-tts/index-tts.git
cd index-tts
git lfs pull
如果你以前已经下载过旧版仓库，建议不要在旧目录里直接 git pull。官方 README 当前提示仓库历史曾重置，旧副本建议删除后重新克隆：
cd ~/AI
mv index-tts index-tts-old
git clone https://github.com/index-tts/index-tts.git
cd index-tts
git lfs pull
确认当前目录：
pwd
输出应该类似：
/Users/你的用户名/AI/index-tts
四、安装 Python 环境和依赖
官方项目要求 Python 3.10 以上，仓库里的 .python-version 当前指定为 3.10。
让 uv 安装 Python 3.10：
uv python install 3.10
然后安装 WebUI 所需依赖：
uv sync --extra webui
这里是 Mac 推荐命令，不是官方 README 的唯一写法。
官方 README 当前默认写的是：
uv sync --all-extras
但是 --all-extras 会把 DeepSpeed 也安装进来。DeepSpeed 主要面向 Linux + NVIDIA CUDA 环境，Mac 新手部署 WebUI 时不建议安装它，否则更容易遇到编译或依赖问题。
因此，Mac 上只跑 WebUI，推荐使用：
uv sync --extra webui
如果国内下载 Python 包很慢，可以使用镜像：
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"
五、下载 IndexTTS-2 模型权重
源码只是程序，还必须下载模型权重。官方提供 Hugging Face 和 ModelScope 两种下载方式。
方式 A：Hugging Face 下载
安装 Hugging Face CLI：
uv tool install "huggingface-hub[cli,hf_xet]"
如果你在国内，建议先设置 Hugging Face 镜像：
export HF_ENDPOINT="https://hf-mirror.com"
下载模型到 checkpoints 目录：
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints
方式 B：ModelScope 下载，国内更推荐
安装 ModelScope CLI：
uv tool install "modelscope"
下载模型到 checkpoints 目录：
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
如果 Hugging Face 下载很慢，优先尝试 ModelScope。
六、检查模型文件是否下载成功
执行：
ls -lh checkpoints
正常情况下，checkpoints 目录下应该能看到类似文件：
config.yaml
bpe.model
gpt.pth
s2mel.pth
wav2vec2bert_stats.pt
文件名可能会随版本调整，但至少应该有 config.yaml 和模型权重文件。
如果启动时报：
bpe.model is missing
通常说明模型没有完整下载。重新执行：
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints
或者：
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
七、检查 Mac 是否识别到 MPS 加速
执行：
uv run tools/gpu_check.py
如果输出里看到 mps 可用，说明 Apple GPU 加速可用。
如果没有看到 mps，也能跑，但会退回 CPU，速度会明显慢很多。
注意：
即使能识别到 MPS，也不代表所有情况下都一定稳定。首次测试建议先用短音频和短文本。
八、启动 WebUI
在 index-tts 目录下执行：
uv run webui.py
启动成功后，浏览器打开：
http://127.0.0.1:7860
官方 Web Demo 的启动命令就是：
uv run webui.py
不要写成：
python app.py
也不建议写成：
source .venv/bin/activate
python webui.py
官方提醒：所有 uv 命令会自动使用正确的项目虚拟环境，不建议手动激活环境，否则可能引发依赖冲突。
九、最适合小白的一整套复制版命令
下面这套适合从零开始执行：
# 1. 安装基础工具
xcode-select --install
brew install git git-lfs ffmpeg uv
git lfs install
# 2. 下载源码
mkdir -p ~/AI
cd ~/AI
git clone https://github.com/index-tts/index-tts.git
cd index-tts
git lfs pull
# 3. 安装 Python 3.10 和 WebUI 依赖
uv python install 3.10
uv sync --extra webui
# 4. 下载模型权重，国内推荐 ModelScope
uv tool install "modelscope"
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
# 5. 检查 MPS / GPU 状态
uv run tools/gpu_check.py
# 6. 启动 WebUI
uv run webui.py
浏览器打开：
http://127.0.0.1:7860
如果你以前已经有旧版 ~/AI/index-tts，先执行：
cd ~/AI
mv index-tts index-tts-old
再从 git clone 开始执行。
十、WebUI 使用建议
进入 WebUI 后，建议这样测试：
| 项目 | 建议 |
|---|---|
| 参考音频 | 5-10 秒，干净人声，无背景音乐 |
| 文本长度 | 先用 1-2 句话测试 |
| 语言 | 中文、英文更稳 |
| 文件路径 | 音频文件路径尽量不要有中文、空格、特殊符号 |
| 首次启动 | 可能额外下载小模型，第一次慢是正常的 |
IndexTTS-2 首次运行时可能还会自动下载一些小模型，例如 facebook/w2v-bert-2.0、amphion/MaskGCT、funasr/campplus 等。首次生成慢、终端有下载日志，一般属于正常现象。
十一、常见问题处理
1. 安装时报 DeepSpeed 错误
Mac WebUI 部署不建议安装 DeepSpeed。
推荐命令是：
uv sync --extra webui
不建议 Mac 新手使用：
uv sync --all-extras
DeepSpeed 在官方配置里是单独的 optional extra，不是 Mac WebUI 必需项。
2. 启动时报缺少 bpe.model
说明 checkpoints 没下载完整。
重新下载：
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
或者：
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints
3. Hugging Face 下载慢
先设置镜像：
export HF_ENDPOINT="https://hf-mirror.com"
然后再运行：
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints
如果还是慢，改用 ModelScope：
uv tool install "modelscope"
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
4. 生成速度很慢
这是正常现象。Mac 没有 CUDA，虽然可以尝试 MPS，但整体速度通常还是不如 NVIDIA 显卡机器。
优化建议：
1. 参考音频控制在 5-10 秒
2. 文本不要一次输入太长
3. 第一次生成后，同一个参考音频再次生成可能会快一些
4. 16GB Mac 只建议短文本测试
5. 长篇批量配音建议用 NVIDIA 显卡机器
5. MPS 报错或结果异常
可以强制用 CPU 测试。新建一个测试脚本：
nano test_cpu.py
写入：
from indextts.infer_v2 import IndexTTS2
tts = IndexTTS2(
cfg_path="checkpoints/config.yaml",
model_dir="checkpoints",
device="cpu",
use_fp16=False,
use_cuda_kernel=False,
use_deepspeed=False,
)
tts.infer(
spk_audio_prompt="examples/voice_01.wav",
text="你好，这是一次 IndexTTS 二代在 Mac 上的测试。",
output_path="gen.wav",
verbose=True,
)
运行：
PYTHONPATH="$PYTHONPATH:." uv run test_cpu.py
如果 CPU 可以跑，MPS 报错，通常说明问题在 MPS 兼容性或内存压力，而不是模型文件本身。
6. 端口 7860 被占用
如果启动时报 7860 端口已被占用，可以先关掉之前的 WebUI 终端窗口，或者在终端里查找占用进程：
lsof -i :7860
看到对应进程后再决定是否关闭。
7. 旧仓库无法更新或命令对不上
如果你以前部署过旧版 IndexTTS，当前命令、文件名、依赖可能和旧仓库不一致。
建议重新克隆：
cd ~/AI
mv index-tts index-tts-old
git clone https://github.com/index-tts/index-tts.git
cd index-tts
git lfs pull
十二、不推荐 Mac 新手使用 Docker
Docker 不是 Mac 部署 IndexTTS-2 的首选。
原因：
1. Mac Docker 容器通常不能直接使用 Apple MPS / Metal
2. 很多 IndexTTS-2 Docker 镜像面向 Linux + NVIDIA CUDA
3. 在 Mac 上用 Docker 往往更慢，也更难排错
Mac 用户推荐顺序：
第一推荐：官方源码 + uv
第二选择：可信社区一键包
不推荐首选：Docker
十三、可发布版总结
Mac 部署 IndexTTS-2，最稳妥的方式是走官方源码：
git clone
uv sync --extra webui
下载 checkpoints
uv run webui.py
关键避坑：
1. Mac 不支持 CUDA，但可以尝试 MPS，不要写成“只能 CPU”
2. Mac WebUI 推荐 uv sync --extra webui，不建议新手使用 uv sync --all-extras
3. 不要 python app.py，官方启动命令是 uv run webui.py
4. 如果以前 clone 过旧仓库，建议重新 clone，不要混用旧目录
5. 首次运行可能继续下载小模型，第一次慢是正常的
这套流程对 M1 / M2 / M3 / M4 Mac 都适用。16GB 内存可以体验短文本，24GB / 32GB 以上更稳。
About The Author
