ASR pipeline silently destroys stereo audio in channels-last layout (what soundfile/librosa return): mean(axis=0) averages across time

问题场景

使用 transformers 库的 AutomaticSpeechRecognitionPipeline（例如 Whisper 模型）时，用户主动传入双声道（stereo）音频数据。音频由 soundfile.read() 或 librosa.load(..., mono=False) 加载，得到形状为 (samples, channels) 的 2D NumPy 数组。pipeline 将其误判为 (channels, samples)，在降混音时沿 axis=0（时间轴）求均值，导致 3 秒的音频（48000 个采样点）被压缩成 2 个数值，后续补零成 30 秒静音，最终只识别出 ' you' 这类几乎无意义的文本。

报错原文

soundfile.read shape : (48000, 2)
UserWarning: We expect a single channel audio input for AutomaticSpeechRecognitionPipeline,
             got 2. Taking the mean of the channels for mono conversion.
mono   : ' See you in the next video!'
stereo : ' you'
after pipeline's mean(axis=0): (2,)

原因分析

可能原因：pipeline 源码（pipelines/automatic_speech_recognition.py，约 422 行）在将多声道输入转为单声道时，硬编码 inputs.mean(axis=0)，即假设输入是常见的 channels-first 布局 (channels, samples)。但 soundfile、librosa 等主流音频库返回的是 channels-last 布局 (samples, channels)。对 (48000, 2) 形状执行 mean(axis=0)，实际是对 48000 个时间点求平均，得到 (2,)，音频内容全部丢失。此外，警告信息中使用了 inputs.ndim（维度数）而非实际声道数，导致任何 2D 输入都提示“got 2”，且不会提示真正有用的形状信息。Issue 作者还指出：同一库内其他音频 pipeline（如音频分类）对 2D 输入会直接抛出 ValueError，而 ASR pipeline 却无声损坏数据，行为不一致。

环境排查

• 确认 Transformers 版本（Issue 中为 5.7.0，请对比你当前的版本是否已修复）。
• 确认音频加载方式：soundfile.read、librosa.load(..., mono=False)、scipy.io.wavfile.read 均返回 channels-last 布局。
• 确认输入给 asr() 的数组形状：打印 audio.shape，若第二维小于 10 而第一维为数千以上，则基本可判定为 channels-last 布局。
• 确认 PyTorch、NumPy 版本（Issue 中分别为 2.11.0、1.26.4），避免其他版本差异干扰。

解决步骤

1. 临时规避：在传入 pipeline 前，手动判断数组形状并转为单声道。例如：
   if audio.ndim == 2 and audio.shape[0] > audio.shape[1]:
    audio = audio.mean(axis=1) # 沿着 channels 轴求均值
else:
    audio = audio.mean(axis=0)
2. 或者：显式将数组转换为 (channels, samples) 布局（转置）后再传入 pipeline，使源码中的 mean(axis=0) 按预期工作。
3. 更稳妥的做法：在调用 pipeline 前统一用 soundfile.read(..., always_2d=False) 或 librosa.load(..., mono=True) 加载为单声道，彻底避免 2D 输入。
4. 如果你愿意修改源码，可参考 Issue 作者提议的补丁：将声道轴推断为形状中较小的维度（ch_axis = int(np.argmin(inputs.shape))），并在警告信息中输出实际形状。该补丁未经官方合并，仅供本地测试。
5. 若你的应用对多声道没有硬性需求，建议在调用 ASR pipeline 前主动拒绝 2D 输入并抛出明确错误，以免静默产生错误转录结果。

验证方法

用同一段语音分别生成单声道和双声道数组，分别调用 ASR pipeline，对比转录文本。若两者输出一致（例如均输出 “See you in the next video!”），说明问题已规避。另一验证方式：在传入 pipeline 前打印 audio.shape，确保它是 (channels, samples) 或一维数组，且降混音后采样点数保持不变。

参考来源

huggingface/transformers #47886：ASR pipeline silently destroys stereo audio in channels-last layout (what soundfile/librosa return): mean(axis=0) averages across time

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。