执行摘要

• 一句话：移除 liborsa 直接依赖，用 torchaudio 和内部工具替代
• 推荐动作：建议阅读此 PR 以了解如何系统替换一个外部依赖并保证数值等价。值得关注的设计决策：使用 torchaudio 的 melscale_fbanks 替代 librosa.filters.mel，并参考了上游兼容性测试。此外，示例和测试的统一替换模式（通过内部工具统一入口）也值得在类似重构中复用。

功能与动机

PR 作者指出，移除 librosa 的原因是许可问题。参见 PR body: 'Drop dependency on librosa due to license concerns.'

实现拆解

1. 在 vllm/transformers_utils/processors/cohere_asr.py 中，将 librosa.filters.mel 替换为 torchaudio.functional.melscale_fbanks，参数映射并进行转置调整，生成与之前等价的 mel 滤波器组。
2. 在示例 openai_realtime_client.py 中，将 librosa.load 替换为 vllm.multimodal.media.audio.load_audio，该函数已基于 soundfile / PyAV 实现音频加载和重采样；同时更新注释，从 "librosa" 改为 "soundfile/PyAV"。
3. 在测试文件 test_whisper.py、test_phi4mm.py 等中，将 librosa.resample 替换为 vllm.multimodal.audio.AudioResampler，将 librosa.load 替换为 load_audio，并移除对 librosa 的导入。
4. 在 vllm/multimodal/media/audio.py 中，更新注释原文，移除 "librosa's main backend" 字样，改为 "soundfile being the main audio loading backend"。
5. 同步更新文档 docs/contributing/model/transcription.md 中的相关引用，以及多个测试文件的 import 和注释。

关键文件：

• vllm/transformers_utils/processors/cohere_asr.py（模块 处理器；类别 source；类型 dependency-wiring；符号 FilterbankFeatures）: 核心模型处理器，将 librosa.filters.mel 替换为 torchaudio.functional.melscale_fbanks，是本次移除直接依赖的关键变更。
• examples/online_serving/openai_realtime_client.py（模块 示例；类别 source；类型 dependency-wiring；符号 audio_to_pcm16_base64）: 示例脚本，将 librosa.load 替换为内部 load_audio，展示依赖移除对用户代码的影响。
• vllm/multimodal/media/audio.py（模块 多媒体；类别 source；类型 core-logic）: 核心音频处理文件，更新注释以反映依赖已从 librosa 转向 soundfile/PyAV。
• tests/models/multimodal/generation/test_whisper.py（模块 测试；类别 test；类型 test-coverage；符号 resampled_assets）: Whisper 测试，将 librosa.resample 替换为内部 AudioResampler，验证替换正确性。
• tests/models/multimodal/generation/test_phi4mm.py（模块 测试；类别 test；类型 test-coverage；符号 test_vision_speech_models）: Phi-4MM 测试，将 librosa.load 替换为 load_audio，确保模型测试不依赖 librosa。

关键符号：FilterbankFeatures.init, audio_to_pcm16_base64, resampled_assets, test_vision_speech_models

关键源码片段

vllm/transformers_utils/processors/cohere_asr.py

核心模型处理器，将 librosa.filters.mel 替换为 torchaudio.functional.melscale_fbanks，是本次移除直接依赖的关键变更。

# 在 FilterbankFeatures.__init__ 中，使用 torchaudio 的 melscale_fbanks 生成 mel 滤波器组
filterbanks = melscale_fbanks(
    n_freqs=self.n_fft // 2 + 1, # 原始 librosa 通过 n_fft 推断，这里显式减半 +1
    f_min=lowfreq,
    f_max=highfreq,
    n_mels=nfilt,
    sample_rate=sample_rate,
    norm=mel_norm,
    mel_scale="slaney", # 明确指定 slaney 尺度以匹配 librosa 默认行为
).T.unsqueeze(0) # 转置并增加 batch 维度，与原来 (1, n_mels, n_freqs) 形状一致
self.register_buffer("fb", filterbanks)

examples/online_serving/openai_realtime_client.py

示例脚本，将 librosa.load 替换为内部 load_audio，展示依赖移除对用户代码的影响。

# 示例中的音频加载函数，原先使用 librosa.load，现切换为内部统一 load_audio
def audio_to_pcm16_base64(audio_path: str) -> str:
    # 使用 vllm 的 load_audio 加载音频并重采样至 16kHz 单声道
    audio, _ = load_audio(audio_path, sr=16000, mono=True)
    # 转换为 PCM16 并 base64 编码
    pcm16 = (audio * 32767).astype(np.int16)
    return base64.b64encode(pcm16.tobytes()).decode("utf-8")

评论区精华

Isotr0py 在 review 中询问 melscale_fbanks 替换是否完全数值收敛，因为音频处理对微小差异敏感。NickCao 回复指出该替换已被上游 PyTorch Audio 的兼容性测试覆盖（test/torchaudio_unittest/functional/librosa_compatibility_test_impl.py）。无未解决疑虑。

• melscale_fbanks 数值一致性验证 (correctness): NickCao 确认数值等价，PR 继续合并。

风险与影响

• 风险：主要风险为数值不一致：虽然 melscale_fbanks 在上游通过了与 librosa 的兼容性测试，但 Cohere ASR 的特定参数（如 mel_scale='slaney', norm 等）需要与 librosa 默认行为完全对齐。目前实现未额外验证。另外，librosa 可能仍被间接依赖（如 datasets 库），本次 PR 未移除间接依赖，用户环境可能仍会安装 librosa，需要后续升级 huggingface datasets 版本才能真正解除。
• 影响：对用户而言，不再需要显式安装 librosa，降低了环境配置复杂度。对系统而言，避免了可能引起合规风险的许可问题（librosa 使用 ISC 许可，但项目可能因其他原因担忧）。对团队而言，维护负担轻微减少——音频加载和重采样功能统一由内部工具提供。
• 风险标记：数值不一致风险, 间接依赖残留

关联脉络

• PR #37058 Drop librosa dependency from main code: 在主体代码中已移除 librosa 依赖，此 PR 继续清理了示例、测试和文档中的残留引用。