Mac Studio本地部署 IndexTTS-2 教程：从环境安装到 WebUI 启动

很多人第一次看到 IndexTTS-2，都会默认认为它只能在 Linux + NVIDIA CUDA 环境里运行。实际折腾下来，我的结论是：IndexTTS-2 在 Mac Studio M3 Ultra 上并不是不能跑，而是不能照搬 CUDA 那套默认配置。 官方仓库的主推理代码已经包含对 mps 的判断，并且在检测到 Apple 的 MPS 后端可用时，会自动把设备切到 mps，同时关闭 FP16。源码里甚至直接写了注释：在 MPS 上使用 float16 的收益不如 float32。

真正需要手工改的地方，是 indextts/infer_v2.py 里的 QwenEmotion 子模块。当前官方代码在这个类里仍然把 AutoModelForCausalLM.from_pretrained(...) 写成了 torch_dtype="float16" 和 device_map="auto"，这对 Mac 上的 MPS 路线并不友好。

这篇文章会把整套部署流程整理成 WordPress 适合直接发布的版本，包括环境准备、模型下载、关键补丁以及最终如何启动 WebUI。

一、部署环境说明

这次实测使用的是：

• 设备：Mac Studio
• 芯片：Apple M3 Ultra
• 内存：96GB 统一内存
• 项目目录：/Users/imac/openclaw/index-tts

如果你也是 Apple Silicon 机器，例如 M1、M2、M3 系列，这套思路同样值得参考。需要注意的是，IndexTTS 官方项目当前依赖中固定了 modelscope==1.27.0、torch==2.8.*、torchaudio==2.8.* 和 transformers==4.52.1，这意味着后续最好尽量贴近官方依赖版本，不要随意升级关键包。

---

二、先安装系统级依赖

先打开终端，安装本地需要的基础工具：

brew install uv git ffmpeg sox

这里最关键的是 uv。IndexTTS 官方 README 明确写了，他们只支持 uv 这种安装方式，并建议用 uv sync 来创建项目 .venv 并安装正确版本的依赖。官方同时说明，--extra webui 是 WebUI 支持所需的额外依赖。

三、拉取源码到本地目录

在你希望保存项目的位置执行：

cd /Users/imac/openclaw
git clone https://github.com/index-tts/index-tts.git
cd index-tts

官方仓库就是这个地址，仓库根目录里可以看到 indextts/、webui.py、pyproject.toml、checkpoints/ 等关键文件和目录。

四、创建并同步项目环境

在项目目录执行：

uv sync --extra webui

如果你想把所有额外功能一次性装全，官方文档给出的默认命令是：

uv sync --all-extras

但对我们这个目标来说，--extra webui 已经够用了。官方文档说明，这条命令会自动创建项目级 .venv并安装正确依赖。

如果你想进入环境做一些手动操作，可以再执行：

source .venv/bin/activate

五、下载 IndexTTS-2 模型到本地 checkpoints

官方 README 提供了两种下载方式：

一种是通过 Hugging Face CLI 下载：

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

另一种是通过 ModelScope 下载：

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

这两种方式都写在官方 README 里。

如果你的 modelscope CLI 在 Mac 上遇到工具环境问题，最稳的方式是直接在项目虚拟环境里用 Python SDK 下载。先确保环境有 pip，然后安装项目要求版本的 ModelScope：

python -m ensurepip --upgrade
python -m pip install -U pip
python -m pip install "setuptools<81" "modelscope==1.27.0"

接着执行：

python - <<'PY'
from modelscope import snapshot_download
snapshot_download("IndexTeam/IndexTTS-2", local_dir="checkpoints")
print("download finished")
PY

下载完成后，你的 checkpoints 目录里应该能看到类似这些文件：

ls checkpoints

通常会包括：

• gpt.pth
• s2mel.pth
• config.yaml
• qwen0.6bemo4-merge/
• 以及其他辅助文件

这一步的目的，是让后续 WebUI 直接从本地加载模型，而不是在运行时再临时联网拉取。

---

六、为什么 Mac 上还需要手工改代码

官方 infer_v2.py 的主类 IndexTTS2 已经考虑了 cuda、xpu、mps 和 cpu 这几种设备分支。对于 mps，源码里明确写着：

• 设备设为 mps
• use_fp16 = False
• use_cuda_kernel = False

并且旁边有注释说明：在 MPS 上使用 float16 不如 float32。

但是同一个文件里的 QwenEmotion 却仍然使用了：

self.model = AutoModelForCausalLM.from_pretrained(
    self.model_dir,
    torch_dtype="float16",
    device_map="auto"
)

这意味着项目主体已经偏向 Apple Silicon 兼容，但情感子模块还残留着明显的 CUDA/半精度思路。

所以在 Mac 上要想稳定跑起来，最关键的改动就是把 QwenEmotion 改成：

• MPS 下强制 torch.float32
• MPS 下不使用 device_map="auto"
• 改成手动 .to("mps")

---

七、修改 indextts/infer_v2.py

先备份原文件：

cp indextts/infer_v2.py indextts/infer_v2.py.bak

然后打开文件：

nano indextts/infer_v2.py

在文件里找到 class QwenEmotion:，把它的 __init__ 方法改成下面这个版本：

class QwenEmotion:
    def __init__(self, model_dir):
        self.model_dir = model_dir
        self.tokenizer = AutoTokenizer.from_pretrained(self.model_dir)

        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
            self.device = "mps"
            self.torch_dtype = torch.float32
            self.model = AutoModelForCausalLM.from_pretrained(
                self.model_dir,
                torch_dtype=self.torch_dtype,
                device_map=None,
            ).to(self.device)
        elif torch.cuda.is_available():
            self.device = "cuda:0"
            self.torch_dtype = torch.float16
            self.model = AutoModelForCausalLM.from_pretrained(
                self.model_dir,
                torch_dtype=self.torch_dtype,
                device_map="auto",
            )
        else:
            self.device = "cpu"
            self.torch_dtype = torch.float32
            self.model = AutoModelForCausalLM.from_pretrained(
                self.model_dir,
                torch_dtype=self.torch_dtype,
                device_map=None,
            ).to(self.device)

        self.model.eval()
        self.prompt = "文本情感分类"
        self.cn_key_to_en = {
            "高兴": "happy",
            "愤怒": "angry",
            "悲伤": "sad",
            "恐惧": "afraid",
            "反感": "disgusted",
            "低落": "melancholic",
            "惊讶": "surprised",
            "自然": "calm",
        }
        self.desired_vector_order = ["高兴", "愤怒", "悲伤", "恐惧", "反感", "低落", "惊讶", "自然"]
        self.melancholic_words = {
            "低落",
            "melancholy",
            "melancholic",
            "depression",
            "depressed",
            "gloomy",
        }
        self.max_score = 1.2
        self.min_score = 0.0

这段补丁的核心，不是让 Mac“模拟 CUDA”，而是把加载逻辑切换成 Apple Silicon 友好的方式。

---

八、继续修改 QwenEmotion.inference()

同一个类里，再找到这行：

model_inputs = self.tokenizer([text], return_tensors="pt").to(self.model.device)

把它改成下面这样：

model_inputs = self.tokenizer([text], return_tensors="pt")
model_inputs = {k: v.to(self.device) for k, v in model_inputs.items()}

完整上下文大致如下：

def inference(self, text_input):
    start = time.time()
    messages = [
        {"role": "system", "content": f"{self.prompt}"},
        {"role": "user", "content": f"{text_input}"}
    ]
    text = self.tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
        enable_thinking=False,
    )
    model_inputs = self.tokenizer([text], return_tensors="pt")
    model_inputs = {k: v.to(self.device) for k, v in model_inputs.items()}

    generated_ids = self.model.generate(
        **model_inputs,
        max_new_tokens=32768,
        pad_token_id=self.tokenizer.eos_token_id
    )
    output_ids = generated_ids[0][len(model_inputs["input_ids"][0]):].tolist()

这个改法在 MPS 路线上更稳，也更清晰。

---

九、给 webui.py 增加 Mac 兼容环境变量

打开 webui.py：

nano webui.py

在文件最顶部加上：

import os
os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")

这样可以减少某些 MPS 未实现算子导致的直接报错，也能避免 tokenizer 的并行提示干扰。

---

十、启动前的推荐环境变量

正式启动前，终端里建议先执行：

export PYTORCH_ENABLE_MPS_FALLBACK=1
export TOKENIZERS_PARALLELISM=false
export HF_ENDPOINT="https://hf-mirror.com"

官方 README 提到，如果网络访问 Hugging Face 比较慢，建议设置 HF_ENDPOINT="https://hf-mirror.com"。此外，官方 WebUI 入口就是 uv run webui.py，默认本地访问地址为 http://127.0.0.1:7860。

---

十一、启动 WebUI

现在回到项目根目录，执行：

cd /Users/imac/openclaw/index-tts
uv run webui.py --host 127.0.0.1 --port 7860 --model_dir ./checkpoints

然后浏览器访问：http://127.0.0.1:7860

如果一切正常，你就能看到 IndexTTS-2 的本地 WebUI 页面。

官方 README 里默认给出的 Web Demo 启动方式是：

uv run webui.py

并说明浏览器访问 http://127.0.0.1:7860。

---

十二、Mac 上先不要开的选项

官方 README 提到，WebUI 还可以启用一些额外选项，例如 FP16、DeepSpeed、编译后的 CUDA kernel 等。

但在 Mac 上，建议先不要打开这些：

• --fp16
• --deepspeed
• --cuda_kernel

原因很简单：这些优化项本质上更偏 CUDA/Linux 路线，而我们这里的目标是优先把 Apple Silicon + MPS 路线跑稳。

---

十三、部署过程中最容易踩的坑

1. modelscope 工具找不到

如果你是通过 uv tool install "modelscope" 安装的，很可能工具实际已经装好了，只是路径还没进 PATH。官方 README 也特别提醒，如果命令不可用，要仔细看 uv tool 输出，它会提示如何把工具目录加入系统路径。

2. pkg_resources / setuptools 问题

如果你在独立工具环境里碰到 pkg_resources 缺失，优先考虑使用项目 .venv + python SDK 下载，而不是继续折腾单独的 CLI 环境。

3. 模型下载成功但启动时报设备或 dtype 错

这通常不是模型没下好，而是 QwenEmotion 仍在沿用 float16 + device_map="auto" 的默认逻辑。这个坑是本次 Mac 部署里最关键的一环。

---

十四、这套方案适合什么人

这套方案尤其适合下面几类用户：

• 手上只有 Mac，没有 NVIDIA 显卡
• 想在本机测试和体验 IndexTTS-2
• 想部署本地 WebUI，而不是远程服务器推理
• 想把模型、环境和页面都放在自己的机器里长期使用

如果你本身就是 Apple Silicon 用户，这条路线比你去硬凑 CUDA 环境要现实得多。

---

十五、最后总结

这次实测下来，最重要的结论只有一句话：

IndexTTS-2 在 Mac Studio M3 Ultra 上不是不能跑，而是必须把项目从“CUDA 默认思维”改成“Apple Silicon 友好思维”。

真正的重点有三个：

1. 按官方推荐方式用 uv 建环境
2. 把模型提前下载到本地 checkpoints
3. 修改 QwenEmotion，让它在 MPS 上走 float32 而不是 float16 + auto

只要这三个点处理好，IndexTTS-2 在 Mac 本机启动 WebUI 是完全有机会跑起来的。官方仓库当前的代码结构本身也说明，这条路并不是“强行魔改”，而是在顺着项目已经存在的 MPS 分支往前走。