Index-TTS2.5最新模型 开机自动运行了 8gb可以运行

• 可用无卡模式运行该项目

bug反馈可以加入科哥专属群交流➕ 广告勿进！

---

运行界面截图

IndexTTS WebUI 用户使用手册

本文档面向最终用户，介绍如何启动 IndexTTS WebUI、完成第一次语音合成、使用主要功能，以及常见问题的处理方法。 安装依赖、下载模型等搭建步骤不在本文档范围内，请参考项目 README.md。

---

1. 项目简介

IndexTTS 是一个**零样本文本转语音（TTS）**系统：只需要一段几秒钟的参考音频，就能克隆该音频的音色，让任意文本用这个音色"说出话来"。

• 支持语言（IndexTTS-2.5）：中文（ZH）、英文（EN）、日文（JA）、阿拉伯语（AR）、西班牙语（ES）。
• 主要能力：
  • 音色克隆（一段参考音频即可）；
  • 多语言合成、跨语言合成；
  • 细粒度情感控制（情感参考音频 / 情感向量 / 情感描述文本）；
  • 语速控制（0.5x–2.0x）；
  • 发音控制（中文拼音 / 英文 CMU 音素 / 日语假名）。
• 两种模型版本：WebUI 默认使用 IndexTTS-2.5，也可以切换到 IndexTTS-2（--version 2）。
• 两种使用方式：浏览器 WebUI（推荐新手）和 命令行 CLI（适合批量/自动化）。

相关目录：

目录	用途
models/	IndexTTS-2.5 模型文件
models_2/	IndexTTS-2 模型文件
examples/	内置示例音频（首次启动自动下载）
outputs/	生成结果、预设文件
checkpoints/	拼音词表等辅助资源

⚠️ 版权与合规提醒：克隆他人音色前请务必获得本人授权，请勿用于非法用途。详见根目录 LICENSE 与 DISCLAIMER。

---

2. 启动应用

2.1 启动前检查（可选）

如果安装后不确定 GPU 是否可用，可以先运行 GPU 检测脚本：

uv run tools/gpu_check.py

• 检测到 NVIDIA CUDA / AMD ROCm / Intel XPU / Apple MPS 会显示设备列表。
• 若显示 No hardware acceleration detected，则程序会以 CPU 模式运行，速度较慢。

2.2 启动 WebUI

在项目根目录运行：

# IndexTTS-2.5（默认版本，推荐）
uv run webui.py

# 使用 IndexTTS-2
uv run webui.py --version 2 --model_dir ./models_2

若首次启动时模型目录不完整，程序会自动联网补齐缺失文件，请耐心等待下载完成。

2.3 确认启动成功

启动成功后会看到类似输出，并显示访问地址：

Running on local URL:  http://127.0.0.1:7860

打开浏览器访问 http://127.0.0.1:7860 即可看到界面。

浏览器地址栏填 127.0.0.1 或 localhost 均可。服务器部署时，可通过局域网 IP 访问（默认监听 0.0.0.0）。

2.4 常用启动参数

运行 uv run webui.py -h 可查看全部参数，常用如下：

参数	默认值	说明
--version {2,2.5}	2.5	模型版本
--model_dir PATH	./models	模型目录
--port PORT	7860	网页服务端口
--host HOST	0.0.0.0	监听地址
--fp16	关闭	IndexTTS-2.5 使用 BF16、IndexTTS-2 使用 FP16 半精度推理（更快、省显存，质量损失极小，推荐开启）
--deepspeed	关闭	启用 DeepSpeed 加速（部分机器可能反而更慢，建议对比测试）
--cuda_kernel	关闭	启用 CUDA 内核加速
--accel	关闭	启用 GPT2 加速引擎（需 flash_attn）
--torch_compile	关闭	用 torch.compile 优化 s2mel（需 triton）
--gui_seg_tokens	120	界面分句最大 Token 数初始值
--verbose	关闭	显示详细日志

示例：

# 开启半精度 + 换端口
uv run webui.py --fp16 --port 7861

# 仅本机访问
uv run webui.py --host 127.0.0.1

---

3. 第一次生成语音（分步操作）

界面顶部是标题栏，下方有两个标签页：「音频生成」 和 「预设管理」。以下均在「音频生成」页完成。

第 1 步：上传音色参考音频

在「音色参考音频」区域，通过以下任一方式选定参考音频：

• 上传：拖入或点击上传一段 WAV/MP3 等格式的人声音频（3–10 秒为佳，音质越清晰克隆效果越好）；
• 录音：点击录音按钮用麦克风现场录一段；
• 从预设加载：如果之前保存过预设，可在右侧下拉框直接选择（详见 4.7 节）。

选好后下方会出现该音频的波形，表示音色已就绪。

💡 参考音频应只包含一个人声、背景干净、无杂音，克隆效果最好。

第 2 步：输入文本

在「文本」输入框中输入要合成的文字，例如：

大家好，欢迎使用 IndexTTS。这是一段零样本语音合成的演示。

输入时下方「预览分句结果」会自动显示模型将把文本切分成几段、每段多少 Token，方便你判断是否需要调整（见 4.6 节）。

第 3 步：选择语言

在「语言」下拉框中选择与文本对应的语言（IndexTTS-2.5 支持 ZH / EN / JA / AR / ES）。

语言选择要与文本内容匹配：文本是英文就选 EN，是中文就选 ZH。跨语言场景（如用中文音色读英文）也请按目标文本的语言选择。

第 4 步：调整语速（可选）

「时长系数」滑杆范围为 0.5 – 2.0：

• 默认 1.0：正常语速；
• 小于 1.0（如 0.8）：语速加快；
• 大于 1.0（如 1.2）：语速放慢（时长变长）。

第 5 步：点击「生成语音」

点击「生成语音」按钮。首次生成需要加载模型，会等待较久；之后生成通常只需几秒到几十秒（取决于文本长度与显卡）。

• 生成过程中按钮下方会显示进度；
• 生成完成后，「生成结果」区域会出现音频播放器，可直接播放或下载。

第 6 步：查看结果

• 每次生成结果会同时保存到项目根目录的 outputs/ 文件夹下，文件名形如 outputs_20260812010101.wav；
• 建议先播放试听，若效果不理想，可调整参考音频、情感设置或高级参数后重新生成。

---

4. 主要功能介绍

4.1 示例（快速体验）

「示例」表格内置了 14 个官方演示用例，覆盖不同语言和情感模式：

• 点击任意一条示例，会自动填充：音色参考音频、目标文本、情感控制方式、情感参数、语言；
• 此时直接点击「生成语音」即可复现该示例的效果；
• 勾选「显示实验功能」后，示例列表会额外显示「情感描述文本控制」的用例。

4.2 情感控制

在「功能设置」区域选择「情感控制方式」，共 4 种模式（默认只显示前 3 种，勾选 「显示实验功能」 后显示第 4 种）：

模式一：与音色参考音频相同（推荐入门）

不使用额外情感输入，生成语音的情感跟随参考音频本身。效果最稳定。

模式二：使用情感参考音频

选择后出现「上传情感参考音频」区域，上传一段带情感的人声（如哭泣、愤怒），并用「情感权重」滑杆调节影响强度（0–1，默认 0.65）。

例：音色参考用 voice_07（普通说话），情感参考用 emo_sad.wav（悲伤），
即可让 voice_07 的音色带着悲伤情绪朗读文本。

模式三：使用情感向量控制

选择后出现 8 个滑杆，对应 8 种情感的强度，顺序为：

喜 → 怒 → 哀 → 惧 → 厌恶 → 低落 → 惊喜 → 平静

• 每项范围 0.0 – 1.0；
• 勾选「情感随机采样」可在推理时引入随机性（注意：随机采样会降低音色克隆的还原度，默认关闭）。

模式四：使用情感描述文本控制（实验功能）

选择后出现「情感描述文本」输入框，直接写一段描述情绪的话，例如：

委屈巴巴、危险在悄悄逼近

模型会把描述自动转换为情感向量。留空则自动使用目标文本作为情绪描述。

• 该功能为实验版，结果可能不稳定；
• 建议把「情感权重」调低（如 0.6 左右）以获得更自然的听感。

💡 无论哪种模式，「情感权重」滑杆（0–1）都控制情感影响的整体强度。权重为 0 时相当于不施加情感控制。

4.3 语速控制

即「时长系数」滑杆（0.5 – 2.0），详见 3.4 节。>1.0 放慢，<1.0 加快。

4.4 发音控制（多音字 / 音标）

IndexTTS-2.5 支持在文本中直接插入 <字|发音> 标注来指定读音：

• 中文拼音：他在银<行|XING2>里<行|HANG2>走了半天，发现这笔业务办不<行|HANG2>。
• 英文 CMU 音素：He had a <minute|M IH1 . N AH0 T> to examine the <minute|M AY0 . N UW1 T> details.
• 日语假名：彼は料理が<上手|じょうず>だが、囲碁では<上手|うわて>に負けた。

IndexTTS-2 则支持中文拼音混排（直接给出拼音代替汉字）：

之前你做DE5很好，所以这一次也DEI3做DE2很好才XING2。

合法拼音列表见 checkpoints/pinyin.vocab；CMU 音素参照 CMU 发音词典。不是所有声母韵母组合都能控制，仅支持合法拼音。

4.5 高级生成参数设置

「高级生成参数设置」折叠面板中的参数影响生成质量与速度，新手保持默认即可：

参数	默认	说明
do_sample	开	是否采样；关闭后结果更确定但可能单调
temperature	0.8	温度，越高越随机
top_p	0.8	累积概率阈值
top_k	30	候选数量（0 表示不限制）
num_beams	3	波束数
repetition_penalty	10.0	重复惩罚，防结巴
length_penalty	0.0	长度惩罚
max_mel_tokens	1500	最大生成 Token 数，过小会导致音频被截断（上限由模型配置决定）
分句最大Token数	120	长文本分句粒度，建议 80–200

「分句最大Token数」推荐 80~200：值越大分句越长、段数越少；值过小或过大都可能导致质量下降。

4.6 分句设置与预览

• 输入文本后，「预览分句结果」表格实时显示：序号、分句内容、Token 数；
• 拖动「分句最大Token数」可实时看到文本重新切分的结果；
• 长文本会被自动分句逐个生成，最终拼接成完整音频。

4.7 预设管理（保存 / 加载音色与参数）

预设可以把「音色 + 情感 + 高级参数」整套配置保存下来，下次一键复用。

保存当前配置：

1. 在「音频生成」页配置好参考音频和各项参数；
2. 点击「保存为预设」按钮，在弹出的窗口确认参数预览，填写预设名称后点「确认」。

从预设加载：

• 在「音频生成」页右侧「从预设加载」下拉框选择预设，一键还原音频与全部参数。

管理预设：

• 切换到「预设管理」标签页，可以查看预设详情、应用、删除、刷新列表，也可以「从当前状态创建」新预设。

预设文件保存在 outputs/presets/<名称>/ 下，音色音频和情感音频会一起复制进去，因此预设可以整体迁移。若参考音频文件缺失，加载时会提示「参考音频文件缺失，已跳过」。

4.8 术语词汇读音（仅 IndexTTS-2）

IndexTTS-2 界面提供「开启术语词汇读音」开关与「自定义术语词汇读音」面板，可自定义个别专业术语的中文/英文读法，例如让 IndexTTS2 读成「Index T-T-S 二」。IndexTTS-2.5 暂无此功能。

4.9 低显存自动分句

IndexTTS-2.5 会自动检测显存，当显卡显存小于 10GB 时进入低显存模式，超过 40 字的文本会被自动按标点切分逐段生成，避免显存溢出。

---

5. 进阶使用：命令行与脚本

WebUI 之外，项目还提供命令行（CLI）与 Python API，适合批量生成或二次开发。

5.1 命令行 indextts2（IndexTTS-2）

注意：indextts2 命令行面向 IndexTTS-2 模型（与 WebUI 默认的 2.5 不同）。

常用子命令：

indextts2 init                                     # 初始化配置目录
indextts2 check                                    # 检查模型/环境/设备
indextts2 synth --text "你好" --voice examples/voice_01.wav --output out.wav   # 单条合成
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav   # 批量合成
indextts2 concat --concat-file list.jsonl --output joined.wav   # 拼接已有 WAV

常用参数：--device cuda:0（指定设备）、--fp16、--force（覆盖输出）、--emotion-audio、--emotion-vector、--emotion-text、--emotion-weight。

情感向量顺序固定为 8 维：高兴,愤怒,悲伤,害怕,厌恶,忧郁,惊讶,平静，例如：

indextts2 synth --text "我好难过" --voice examples/voice_01.wav \
  --emotion-vector 0,0,0.8,0,0,0,0,0 --emotion-weight 1.0 --output sad.wav

详细用法见 docs/cli_v2_usage.md。

5.2 Python API 调用（IndexTTS-2.5）

uv run python

from indextts.infer_v2_5 import IndexTTS2

tts = IndexTTS2(cfg_path="models/config.yaml", model_dir="models", use_bf16=True)

# 1) 基础音色克隆（多语言需指定 lang）
tts.infer(
    spk_audio_prompt='examples/voice_01.wav',
    text="大家好，欢迎使用 IndexTTS。",
    lang="ZH",
    output_path="gen.wav",
    verbose=True,
)

# 2) 情感参考音频 + 情感权重
tts.infer(
    spk_audio_prompt='examples/voice_07.wav',
    text="我站在人海中，却感觉比任何时候都要孤独。",
    lang="ZH",
    output_path="gen_emo.wav",
    emo_audio_prompt="examples/emo_sad.wav",
    emo_alpha=0.8,
    verbose=True,
)

# 3) 语速控制：duration_factor>1 变慢，<1 变快
tts.infer(
    spk_audio_prompt='examples/voice_01.wav',
    text="这是一段语速控制的演示。",
    lang="ZH",
    output_path="gen_slow.wav",
    duration_factor=1.2,
    verbose=True,
)

infer() 常用参数：lang（语言）、emo_audio_prompt、emo_alpha、emo_vector、use_emo_text、emo_text、use_random、duration_factor、max_text_tokens_per_segment。 使用 use_emo_text=True 时，构造 IndexTTS2 需加上 use_qwen_emo=True，否则会报 RuntimeError。

---

6. 输出文件说明

• 生成音频：保存到项目根目录 outputs/，命名 outputs_年月日时分秒.wav，网页内也可直接下载。
• 预设文件：保存到 outputs/presets/<预设名>/，包含 preset.json、prompt.wav（音色）、emo_ref.wav（情感）。
• CLI 输出：由 --output / --output-dir / --output-prefix 指定，父目录会自动创建。

若手动清理过 outputs/ 目录，网页中的历史预设可能失效，请通过「预设管理」页的「刷新」按钮重新加载列表。

---

7. 常见问题（FAQ）

Q1：启动时报 Address already in use 或端口被占用？

说明 7860 端口已被占用。更换端口启动即可：

uv run webui.py --port 7861

Q2：没有独立显卡（GPU）能运行吗？

可以。程序会自动回退到 CPU 模式（日志提示 "Be patient, it may take a while to run in CPU mode"）。但 CPU 推理非常慢，长文本耗时很长，建议有 NVIDIA/AMD/Apple 加速卡时运行。

Q3：显存不够 / 显存溢出（CUDA out of memory）怎么办？

• 启动时加 --fp16（2.5 用 BF16）可大幅降低显存占用，质量损失很小；
• 显存低于 10GB 时模型会自动进入低显存分句模式；
• 调低「分句最大Token数」与「max_mel_tokens」；
• 关闭其他占用显存的程序。

Q4：生成的语音效果不理想（音色不像 / 吐字不清）？

• 更换更干净、更清晰的参考音频（3–10 秒单人声为佳）；
• 参考音频不要有背景音乐、混响、多人声；
• 检查「语言」是否与文本匹配；
• 情感控制权重调低（或模式一），减少情感对音色还原的干扰；
• 尝试降低「分句最大Token数」（80 左右），过长分句可能质量下降。

Q5：模型下载失败 / 下载很慢？

• 首次启动会自动补齐缺失模型文件，网络较慢时可配置镜像后重启，例如：

  export HF_ENDPOINT="https://hf-mirror.com"
  

• 也可以手动下载到 models/（2.5）或 models_2/（2），见 README.md；
• 下载中断后重新启动程序会继续补齐，不会清空已有文件。

Q6：生成结果被截断 / 音频提前结束？

通常是因为「max_mel_tokens」设置过小。在「高级生成参数设置」中调大该值（最大不超过模型配置上限 1815），再重新生成。

Q7：情感控制没有效果？

• 确认「情感权重」不为 0；
• 模式二：确认已上传情感参考音频且权重合适（0.6–1.0）；
• 模式三：确认 8 个情感滑杆至少有一项 > 0；
• 模式四：属于实验功能，效果不稳定，可换用模式二/三。

Q8：勾选「显示实验功能」后示例多了什么？

会增加「使用情感描述文本控制」的示例。该模式通过文字描述驱动情感，是实验功能，结果可能不稳定。

Q9：为什么我的界面没有「术语词汇读音」开关？

「术语词汇读音」与「自定义术语词汇读音」目前仅 IndexTTS-2（--version 2）提供，IndexTTS-2.5 不包含此功能，属于正常现象。

Q10：中文多音字 / 英文生词读错了怎么办？

使用发音标注（见 4.4 节）：

他在银<行|XING2>里<行|HANG2>走了半天。

不生效时请核对拼音是否在合法词表 checkpoints/pinyin.vocab 中。

Q11：FP16 / BF16 是什么？开启安全吗？

半精度推理，速度更快、显存占用更低，仅有极小的质量损失，默认推荐开启。DeepSpeed 与 CUDA kernel 等加速选项因机器而异，建议开/关对比测试后再决定。

Q12：能批量生成很多条语音吗？

可以。使用命令行 indextts2 batch（IndexTTS-2），把任务写进 JSON Lines 清单一次运行；WebUI 本身一次只生成一条。也可用 Python API 写循环脚本。

Q13：生成很慢是正常的吗？

首次启动要加载模型（约数 GB），之后每条语音生成时间取决于文本长度、显卡性能与是否开启半精度/加速。开启 --fp16 并参考 2.4 节加速参数可明显提速。

Q14：我可以用别人上传的音频克隆音色吗？

请务必遵守：克隆音色前须获得音色所有者本人的明确授权，并遵守 LICENSE 与 DISCLAIMER 的约束。请勿将生成语音用于诈骗、伪造证据等违法场景，使用者与传播者自负全责。

---

8. 附：快速上手流程图

启动 uv run webui.py
        ↓
浏览器打开 http://127.0.0.1:7860
        ↓
上传/选择音色参考音频  →  输入文本  →  选择语言
        ↓
（可选）调整语速 / 情感 / 高级参数
        ↓
点击「生成语音」 → 播放试听 → 在 outputs/ 获取音频