IndexTTS-2.5 本地装完先跑短句，确认参考音频能被正常读取

装完 IndexTTS-2.5 之后，第一件该做的事不是调音色和韵律，而是用一句八到十二个字的文本把整条链路跑通：环境能导入、参考音频能被解码、输出目录里出现一个能播放的 wav。这三步任一步没过，后面换长文本、换参考音频都只是在叠加变量。判断顺序建议固定成先路径、再依赖、最后显存，因为前两类几乎都能靠命令当场验证。

装完 IndexTTS-2.5 后，先用一句八到十二字的中文把链路走通：环境能 import、参考音频能被 ffprobe 读出采样率与时长、输出目录出现可播放的 wav。三步都过再换长文本和自定义音色；任一步失败，先按报错关键字分清是路径、依赖还是显存问题，不要急着重装整个环境。参考音频建议 3-10 秒、单声道、底噪干净，具体采样率要求以项目配置为准。

确认运行环境与依赖版本

先排除依赖缺失导致的导入失败。这类工程通常要求 Python 3.10 或 3.11，具体以仓库里的 pyproject.toml 或 requirements.txt 为准；用 3.8 或较新的 3.12 时，部分依赖可能编译不过。建议单独建虚拟环境，不要和系统 Python 混用。

python -V
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1

python -m pip install -U pip
pip install -r requirements.txt
# 若项目提供 pyproject.toml，可改用
# pip install -e .

装完后先做导入自检，不要直接跳到合成。下面这段是骨架，模块名和类名按你拉下来的仓库实际入口替换：

python - <<'PY'
import sys, torch
print('python', sys.version.split()[0])
print('torch', torch.__version__)
print('cuda_available', torch.cuda.is_available())
if torch.cuda.is_available():
    print('device', torch.cuda.get_device_name(0))

# 替换为仓库中真实的入口模块
import indextts
print('indextts import ok')
PY

预期输出是：Python 与 torch 版本号正常打印，cuda_available 是 True 或 False 都算通过（CPU 也能先跑短句），最后一行 import ok 没有异常。一旦出现 ModuleNotFoundError 或 ImportError，先把依赖问题解决，别去怀疑音频。

准备并自检参考音频

参考音频读取失败，表现出来往往是没声音或直接抛解码异常，比环境问题更常见。先用 ffprobe 看一眼，不要靠文件后缀猜格式：

ffprobe -v error -select_streams a:0 \
  -show_entries stream=sample_rate,channels,codec_name \
  -show_entries format=duration \
  -of default=noprint_wrappers=1 voice_ref.wav

自检清单纯看这几个字段：时长建议 3-10 秒，太短音色不稳，太长解码慢且容易夹带多余内容；采样率常见要求 16k 或 22.05k / 24k，具体以项目 config 为准；声道建议单声道，双声道不一定报错但可能被误处理；底噪方面，明显电流声、背景音乐、混响会被当成音色学进去，尽量用干净人声。不兼容时就地转换：

# 转成 16kHz 单声道 wav
ffmpeg -i voice_ref.mp3 -ac 1 -ar 16000 -c:a pcm_s16le voice_ref_16k.wav

# 检查是否接近静音
ffmpeg -i voice_ref_16k.wav -af volumedetect -f null - 2>&1 | grep mean_volume

如果 mean_volume 接近负九十几 dB，基本就是静音文件或读到了错误的流，这种参考音频换什么模型都出不来声音。

跑一次最短文本合成

先把目录约定定死，之后定位报错会快很多：

project/
├─ indextts/             # 代码
├─ assets/
│  └─ voice_ref_16k.wav  # 参考音频
├─ inputs/
│  └─ text.txt           # 待合成文本
└─ outputs/              # 合成结果

文本先用一句短的，比如今天天气不错，我们开始测试。脚本骨架如下，函数名与参数按仓库实际接口替换：

from pathlib import Path
import indextts

ref = Path('assets/voice_ref_16k.wav')
text = '今天天气不错，我们开始测试。'
out = Path('outputs/first_try.wav')
out.parent.mkdir(exist_ok=True)

tts = indextts.TTS()  # 参数以实际签名为准
tts.infer(ref_audio=str(ref), text=text, out_path=str(out))
print('saved:', out, out.exists())

预期生成 outputs/first_try.wav，大小在几百 KB 量级，能被系统播放器打开。如果你用的是带 WebUI 的启动脚本，同样输入这句短文本点一次合成，重点是拿到一个落盘的音频文件，而不是只看页面有没有转圈。

核对输出文件的采样率与时长

有文件不等于合成成功，还要确认它是一段有话的音频：

ffprobe -v error -select_streams a:0 \
  -show_entries stream=sample_rate,channels \
  -show_entries format=duration \
  -of default=noprint_wrappers=1 outputs/first_try.wav

对照方法：中文按正常语速大致每字 0.2-0.3 秒估算，上面那句十二字左右，输出落在两到五秒之间比较合理。如果时长只有零点几秒，或者和参考音频时长几乎一致，多半是参考音频被当成了输出，或者文本没真正传进推理函数；如果时长离谱地长，检查是不是把参考音频路径和待合成文本写反了。最后再听一遍：能播放、没有明显电流声、读的不是参考音频里的原话。如果播放出来正好是参考音频那句，说明输入字段传错了。

按报错信息定位三类常见问题

不要一见到红字就重装环境，先按关键字分流，再动手。

路径与音频读取类。关键字：FileNotFoundError、No such file or directory、ffmpeg 解码错误、Could not open。判断顺序是先确认命令在哪个工作目录执行，把参考音频换成绝对路径再试；再确认格式与采样率，必要时按上一节转成 16k 单声道 wav。这一层多数不是模型问题。
显存不足类。关键字：CUDA out of memory、RuntimeError: CUDA error、OOM。判断顺序是先用最短文本重试，仍报错就把 batch 调小或临时改用 CPU，先确认链路能通；再用 nvidia-smi 看是不是已有别的进程占着卡。把 batch 调小只是把短句跑通的止血动作，不代表性能变好了。
依赖缺失类。关键字：ModuleNotFoundError、ImportError、undefined symbol、找不到 libGL 或 libsndfile。判断顺序是回到第一节的导入自检，单独 import 出错的那个包，按 requirements 里的版本重装；undefined symbol 通常是 torch 与 torchaudio 版本不匹配，成对重装更省事。

整个过程建议按路径、依赖、显存的顺序排查：路径问题能立刻验证，依赖问题在导入阶段就会暴露，显存问题才和参数、硬件相关。等短句能稳定产出可播放、时长合理的 wav，再换自己的参考音频和长文本，出问题时至少能确定变量只有一个。