TorchCodec 环境配置指南
本文档记录了在 GR00T N1.5 项目中配置 TorchCodec 视频解码器遇到的问题及解决方案。
问题描述
运行训练脚本时出现以下错误：
ImportError: torchcodec is not available.或者：
RuntimeError: Could not load libtorchcodec. Likely causes:
1. FFmpeg is not properly installed in your environment.
2. The PyTorch version is not compatible with this version of TorchCodec.问题分析
1. TorchCodec 版本与 PyTorch 版本不兼容
TorchCodec 对 PyTorch 版本有严格的兼容性要求。不同版本的 TorchCodec 需要对应版本的 PyTorch：
| TorchCodec 版本 | 兼容的 PyTorch 版本 |
|---|---|
| 0.8.x | 2.9.x |
| 0.9.x | 2.10.x (部分) |
| 0.4.x | 2.5.x - 2.6.x |
2. FFmpeg 库依赖问题
TorchCodec 需要 FFmpeg 库（版本 4、5、6 或 7）。如果系统没有安装或路径不正确，会导致加载失败。
3. 动态库路径问题
TorchCodec 的核心库依赖 PyTorch 的动态库（libtorch.so、libc10.so 等），如果 LD_LIBRARY_PATH 设置不正确，会导致符号未定义错误。
解决方案
步骤 1：激活 conda 环境
bash
conda activate gr00t步骤 2：安装 FFmpeg
使用 conda 安装 FFmpeg（推荐版本 7）：
bash
conda install -y ffmpeg -c conda-forge验证安装：
bash
ffmpeg -version
# 应显示 ffmpeg version 7.x步骤 3：安装兼容的 PyTorch 版本
关键：必须安装与 TorchCodec 兼容的 PyTorch 版本。
对于 TorchCodec 0.8.0，安装 PyTorch 2.9.1：
bash
# 先卸载现有的 PyTorch
pip uninstall torch torchvision torchaudio -y
# 安装兼容版本（CUDA 13.0）
pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu130步骤 4：安装 TorchCodec
bash
pip install torchcodec==0.8.0步骤 5：验证安装
运行以下 Python 代码验证 TorchCodec 是否正常工作：
python
import torch
print('torch version:', torch.__version__)
import torchcodec
print('torchcodec version:', torchcodec.__version__)
# 测试解码视频
from torchcodec.decoders import VideoDecoder
video_path = '/path/to/your/video.mp4'
decoder = VideoDecoder(video_path)
print('Video duration:', decoder.metadata.duration_seconds, 'seconds')
print('Number of frames:', decoder.metadata.num_frames)
print('FPS:', decoder.metadata.average_fps)
# 解码第一帧
frame = decoder[0]
print('First frame shape:', frame.shape)
print('torchcodec 工作正常！')预期输出：
torch version: 2.9.1+cu130
torchcodec version: 0.8.0
Video duration: 20.8 seconds
Number of frames: 416
FPS: 20.0
First frame shape: torch.Size([3, 256, 256])
torchcodec 工作正常！常见问题排查
问题 1：undefined symbol: _ZN3c1013MessageLoggerC1EPKcii
原因： PyTorch 版本与 TorchCodec 不兼容（ABI 不匹配）。
解决： 降级或升级 PyTorch 到兼容版本。
问题 2：libtorch.so => not found
原因： 动态库路径未设置。
解决： 在脚本中添加：
bash
export LD_LIBRARY_PATH=/path/to/conda/envs/gr00t/lib:/path/to/conda/envs/gr00t/lib/python3.10/site-packages/torch/lib:$LD_LIBRARY_PATH问题 3：FFmpeg 版本不支持
原因： 安装的 FFmpeg 版本过高（如 8.x）或过低。
解决： 使用 conda 安装 FFmpeg 7.x：
bash
conda install -y ffmpeg=7.1 -c conda-forge最终验证的环境配置
| 组件 | 版本 |
|---|---|
| Python | 3.10 |
| PyTorch | 2.9.1+cu130 |
| TorchVision | 0.24.1+cu130 |
| TorchAudio | 2.9.1+cu130 |
| TorchCodec | 0.8.0 |
| FFmpeg | 7.1 |
| CUDA | 13.0 |