RT-DETR实战避坑:PyTorch环境配置与COCO数据集准备最容易踩的5个坑

PyTorch与CUDA版本匹配的隐形陷阱

  现象：按照官方建议安装 torch 2.0.1 后，运行时却提示 CUDA runtime error (38) : no CUDA-capable device is detected，明明显卡驱动和 CUDA Toolkit 都已正确安装。

  根本原因：PyTorch 的 GPU 版本需要与 CUDA Toolkit 版本严格匹配。官方文档提到的 cu118 对应 CUDA 11.8，而很多开发者本地安装的是 CUDA 11.7 或 12.x 版本。

  解决方案：

1. 首先确认本地 CUDA 版本：
   nvcc --version
2. 根据实际 CUDA 版本选择对应的 PyTorch 安装命令。
3. 验证安装是否成功：

import torch
print(torch.cuda.is_available())  # 应返回 True
print(torch.version.cuda)       # 应与本地 CUDA 版本一致

  注意：如果使用 conda 虚拟环境，建议先安装 CPU 版本的 PyTorch，再单独安装 GPU 版本的 torch，避免 conda 自动解析依赖时安装错误版本。

requirements.txt 安装后的隐藏依赖

  现象：成功安装 requirements.txt 中的所有包后，运行训练脚本仍报错 ModuleNotFoundError: No module named 'transformers'。

  问题分析：RT-DETR 的某些功能（如部分数据增强）依赖 Hugging Face 的 transformers 库，但该库并未包含在标准 requirements.txt 中。

  完整依赖清单：

  基础 requirements.txt 包含的包：

• numpy
• opencv-python
• pyyaml
• tqdm
• matplotlib

  必须额外安装的关键依赖：

pip install transformers>=4.28.1  # 用于特定数据增强
pip install pycocotools          # COCO 数据集评估
pip install tensorboard          # 训练可视化

  验证环境完整性的方法：

# 在 Python 环境中执行以下检查
import importlib

required = ['torch', 'transformers', 'pycocotools', 'cv2']
for lib in required:
    try:
        importlib.import_module(lib)
        print(f"{lib} 导入成功")
    except ImportError:
        print(f"缺少依赖: {lib}")

YOLO 转 COCO 时的坐标转换陷阱