RuntimeError: Could not load libtorchcodec. Likely causes:

问题场景

用户在使用 vLLM 0.25.0（实际 pyproject.toml 中固定为 0.24.0）启动 vllm serve 时，进程在导入阶段直接崩溃。崩溃发生在 vLLM 的多模态视频处理模块导入 torchcodec 时，原因是 torchcodec 的 CUDA 版本与当前 cu129 环境不匹配。

报错原文

RuntimeError: Could not load libtorchcodec. Likely causes:

原因分析

可能原因：vLLM 在 vllm/multimodal/video.py 中只捕获了 ImportError。当 torchcodec 因 CUDA 不匹配无法加载其原生库时，抛出的实际是 RuntimeError 而非 ImportError，导致异常未被捕获，整个进程在导入阶段崩溃。该问题在 vLLM 主分支上已通过 PR #47888 修复，但该修复合入时间晚于 v0.25.0 分支创建时间，因此 v0.25.0 及更早版本不受保护。

环境排查

• 确认 vLLM 版本：检查是否为 0.25.0 或更早版本。Issue 中用户实际固定的是 0.24.0。
• 确认 PyTorch 是否为 cu129 构建：torch.__version__ 应类似 2.11.0+cu129。
• 确认 torchcodec 是否与 cu129 兼容：当前 torchcodec 并未提供 cu129 对应的 wheel。
• 确认 NVIDIA 驱动版本：Issue 中为 575.57.08。

解决步骤

1. 将 vLLM 升级到 0.25.1 或更高版本。该版本包含 PR #47888 的修复，将异常捕获范围从 ImportError 扩大到 (ImportError, RuntimeError)。
2. 升级后，即使 torchcodec 仍然无法加载，vLLM 也不会在导入阶段崩溃，而是回退到占位实现。
3. 如果确实需要使用 torchcodec 后端处理视频，建议确认 torchcodec 是否已提供与当前 CUDA 版本匹配的 wheel；如果没有，考虑是否可切换 PyTorch 的 CUDA 版本（例如 cu126），或等待 torchcodec 适配 cu129。

验证方法

升级 vLLM 后重新执行 vllm serve 启动命令，确认进程不再因 RuntimeError: Could not load libtorchcodec 崩溃。若启动后仅出现 torchcodec 不可用的提示（而非崩溃），则说明修复已生效。

参考来源

vllm-project/vllm #48592

AI 工具推荐

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

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

了解 GamsGo AI

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