解决 Fish Speech 在 PyTorch 2.10.0+cu130 中的 torchaudio.list_audio_backends AttributeError
解决 Fish Speech 在 PyTorch 2.10.0+cu130 中的torchaudio.list_audio_backendsAttributeError
https://github.com/fishaudio/fish-speech?tab=readme-ov-file
https://speech.fish.audio/install/#system-setup
https://docs.pytorch.ac.cn/audio/stable/generated/torchaudio.list_audio_backends.html
https://github.com/pytorch/audio/issues/3902
目录
解决 Fish Speech 在 PyTorch 2.10.0+cu130 中的 torchaudio.list_audio_backends AttributeError
问题背景
权威引用：为什么这个函数消失了？
解决方案一（降级 PyTorch）
解决方案二（无需降级 PyTorch）
1. 定位文件
2. 修改代码（约第 34 行）
3. 验证
技术细节：为什么选择 soundfile作为回退？
预防措施与给开发者的建议
1. 依赖锁定（Prevention）
2. 代码健壮性（Best Practice）
3. 环境诊断脚本
总结思考
问题背景
在 Windows 11 + RTX 3090 + CUDA 13.0 环境下，使用torch==2.10.0+cu130运行 Fish Speech 的 WebUI (python tools/run_webui.py) 时，程序在加载音频后端时崩溃，报错如下：
AttributeError: module 'torchaudio' has no attribute 'list_audio_backends'根本原因：torchaudio.list_audio_backends()函数在PyTorch 2.9.0 及更高版本中已被官方彻底移除。Fish Speech 项目代码（reference_loader.py）直接调用了这个已废弃的 API。
权威引用：为什么这个函数消失了？
根据 PyTorch Audio 官方文档和源码，这是一个有计划的 API 废弃，属于从“Legacy Backend Mode”向“Dispatcher Mode”迁移的一部分。
版本 | 状态 | 官方说明 |
|---|---|---|
PyTorch 2.8.x | Deprecated | 函数存在但发出警告，提示将在 2.9 中移除。 |
PyTorch 2.9.0+ | Removed | 函数已从 |
官方文档证据：
PyTorch 2.9.0 Docs: torchaudio.list_audio_backends页面顶部明确标注"DEPRECATED" 和"Warning: This function has been deprecated. It will be removed from 2.9 release."。
Migration Guide: 官方建议使用新的Dispatcher Mode，即直接调用
torchaudio.load()而不需要手动设置全局后端。
解决方案一（降级 PyTorch）
解决方案二（无需降级 PyTorch）
核心思路：使用try-except捕获AttributeError，在新版本中直接回退到默认且稳定的soundfile后端。
1. 定位文件
打开导致报错的文件：fish_speech/inference_engine/reference_loader.py
2. 修改代码（约第 34 行）
找到__init__方法中定义后端的代码块。
修改前（报错代码）：
# Define the torchaudio backend backends = torchaudio.list_audio_backends() # <-- 这行在 2.10.0 会爆炸 if "ffmpeg" in backends: self.backend = "ffmpeg" else: self.backend = "soundfile"修改后（兼容代码）：
# Define the torchaudio backend # 处理 torchaudio 版本差异 (>=2.9 移除了 list_audio_backends) try: # 尝试旧版 API (torchaudio < 2.9) backends = torchaudio.list_audio_backends() if "ffmpeg" in backends: self.backend = "ffmpeg" else: self.backend = "soundfile" except AttributeError: # 新版 torchaudio (>=2.9) 已移除该函数 # 在 Windows + PyTorch 2.10 环境下，soundfile 是安全且高效的默认值 self.backend = "soundfile"3. 验证
重新运行python tools/run_webui.py。如果日志显示Warming up done, launching the web UI...且无报错，则修复成功。
技术细节：为什么选择soundfile作为回退？
Windows 原生支持：
soundfile后端在 Windows 上对 WAV 格式的支持最稳定，无需额外安装 FFmpeg 系统库。Fish Speech 需求：项目主要处理的是训练和推理用的标准音频文件（WAV），
soundfile完全够用。性能无损：对于 RTX 3090 的推理流水线，I/O 后端对 GPU 计算速度几乎没有影响。
预防措施与给开发者的建议
1. 依赖锁定（Prevention）
在requirements.txt或项目文档中明确指定torchaudio版本，避免用户自动安装最新版导致 API 断裂。
# 如果项目尚未适配 2.9+，应锁定在 2.8.x torchaudio<2.9.02. 代码健壮性（Best Practice）
在调用可能被废弃的第三方库 API 时，永远使用防御性编程：
# 好习惯：检查属性是否存在 if hasattr(torchaudio, 'list_audio_backends'): # 使用旧版逻辑 else: # 使用新版逻辑或默认值3. 环境诊断脚本
创建一个check_env.py来快速诊断兼容性问题：
import torch, torchaudio print(f"PyTorch: {torch.__version__}") print(f"torchaudio: {torchaudio.__version__}") print(f"Has list_audio_backends: {hasattr(torchaudio, 'list_audio_backends')}")总结思考
这是一个典型的深度学习生态快速迭代导致的“下游项目滞后”问题。PyTorch 为了性能（Dispatcher Mode）移除了旧的全局状态管理 API，但像 Fish Speech 这样的优秀开源项目可能因为维护周期原因未能即时跟进。
对于用户而言，不降级 PyTorch（保持 CUDA 13.0 高性能） 而是手动 Patch 项目代码，是在享受新硬件算力与使用社区模型之间最好的平衡点。