17 — 故障排查
整理开发过程中高频问题与解决方法，可作为排查清单。
安装阶段
llama-cpp-python 装成 CPU 版。
强制安装 CUDA wheel：
venvs\venv_main\Scripts\pip install llama-cpp-python `
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121
GPT-SoVITS 服务因 import 错误启动失败。
确保启动 api_v2.py 前 PYTHONPATH 包含 vendor\GPT-SoVITS 与 vendor\GPT-SoVITS\GPT_SoVITS。start.ps1 已处理；手动启动需复现（857f3fb）。
9880 端口被占用。
启动脚本会跳过新 SoVITS 进程。可结束旧进程或改 tts.api_port。
运行阶段
STT 输出重复短语或模板句。 两层防护：
- 在
config/filters.txt添加字面幻觉短语（890b782）。 - 依赖
vocal10n.stt.filters的邻接去重和短语重复抑制（d6116c5）。
若仍循环，检查 stt.beam_size = 1 且输入音频未削波。
字幕确认太慢或在句中断开。
调 stt.max_segment_age（53e3cbe 从 2 秒提升到 4 秒）。想更快确认就调低，想更完整句边界就调高。
音频设备选择异常/出现重复项。
PortAudio 可能在多个 host API 下重复上报同一设备。UI 已按名称去重（74be837）。若旧设备失效，手动重新选择一次触发重开。
TTS 队列在消耗，但听不到声音。
确认 tts.ref_audio_path 指向存在文件。新版本使用绝对路径（4a19037）；旧版本常因路径错误静默失败。
TTS 首次响应慢。
服务启动后会后台预热（0f22fcc、142f915）。若仍冷启动，检查日志确认预热请求是否成功。
Qwen3-TTS 输出被污染/协议错乱。
stdout 仅用于协议数据，stderr 单独排空（2311042）。不要在 qwen3_server.py 往 stdout print()。
回声环：TTS 被 STT 再次识别。
确认 aec.enabled = true。混响较大可提高 aec.filter_taps（默认 2048，约 128 ms@16kHz）。若用户说话被压制，aec.dt_threshold 可能过低，适当提高（f334773）。
UI
下拉箭头/按钮被裁切或不可见。
相关修复位于 46675dc 到 2e3bcef。若自定义主题复现，参考 stt_tab.py 中控件最小尺寸设置。
切换到 Simple 模式后 Section A 显示异常。
Pro 与 Simple 的 Section A 布局独立（e96bcb9）。切换模式应触发重建；若未生效，重启应用。
Simple 模式 Start All 卡住。
每阶段有独立超时。查看卡住的状态胶囊并结合日志定位；Qwen3-TTS 预热超时预算最长（81cedf4）。超时后会自动回滚。
文件输出
output/ 没有生成文件。
仅当至少一个 output.* 开关为真时才会创建 writer。检查 Output 页，并确认 output.directory 可写。
SRT 时间轴看起来不对。 SRT 时间来自片段时间/延迟追踪，不是墙钟时间。若会话开始与首个输入存在偏移，和墙钟对比可能看似异常，但文件内部相对时间应一致。