解决 PyTorch 报错：RuntimeError: CUDA error: an illegal instruction was encountered

最近在跑 YOLO 模型进行视频目标检测时，突然遇到了一个棘手的 CUDA 底层报错。程序在正常处理了几百帧后直接崩溃，抛出了 RuntimeError: CUDA error: an illegal instruction was encountered。经过一番排查，终于找到了原因并成功解决。特此记录一下踩坑过程，希望能帮到有同样困扰的小伙伴。

报错现场

程序在循环处理视频帧并调用模型推理时崩溃，具体的报错堆栈如下：

python 复制代码

Traceback (most recent call last):
  File "C:\Users\user\Desktop\GV-CVI\other\detect_pt_0303.py", line 47, in <module>
    results = model(frame, conf=CONF_THRES, verbose=False)
  # ...省略部分堆栈...
  File "C:\Users\user\.conda\envs\torch312\lib\site-packages\ultralytics\utils\ops.py", line 71, in time
    torch.cuda.synchronize(self.device)
  File "C:\Users\user\.conda\envs\torch312\lib\site-packages\torch\cuda__init__.py", line 566, in synchronize
    return torch._C._cuda_synchronize()
RuntimeError: CUDA error: an illegal instruction was encountered
CUDA kernel errors might be asynchronously reported at some other API call,so the stacktrace below might be incorrect.
For debugging consider passing CUDA_LAUNCH_BLOCKING=1.

原因分析

简单来说，这个报错意味着你的 PyTorch 版本（或它依赖的 CUDA 版本）与你电脑显卡的物理算力架构不匹配。

这就好比你给一辆老款汽车加了最新的高标号赛用燃油，引擎（显卡）在执行某些特定指令时"消化不良"，直接卡壳了。这种情况常见于使用较新的 Python (如 3.12) 配合最新版 PyTorch 2.x，去跑一些相对老旧的显卡（如 GTX 10系列、RTX 20系列）时。

️ 解决方案

我尝试了以下几种方法，按推荐程度排序：

方法一：降级 PyTorch 版本（最推荐，根治方案）

Python 3.12 配合最新版的 PyTorch 在某些显卡上存在兼容性波动。强烈建议将 PyTorch 降级到极其稳定的 2.0.1 或 1.13.1 版本。

在你的 Conda 环境中执行以下命令（以降级到 CUDA 11.8 版本为例）：

bash 复制代码

pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118

方法二：添加环境变量（快速验证）

报错提示中建议了 CUDA_LAUNCH_BLOCKING=1。这个环境变量可以让 CUDA 的错误同步抛出，有时候能绕过某些异步冲突导致的误报。

在代码的最开头（import torch 之前）加上：

python 复制代码

import os
os.environ["CUDA_LAUNCH_BLOCKING"] = "1"

方法三：强制使用 CPU 推理（保底方案）

如果急着出结果，且对处理速度要求不高，可以先强制让模型在 CPU 上跑，避开显卡的兼容性问题。

python 复制代码

# 加载模型后，手动指定设备为 CPU
model = YOLO('你的模型路径.pt') 
model.to('cpu')

方法四：检查显卡驱动

在命令行输入 nvidia-smi，查看右上角的 CUDA Version。确保你安装的 PyTorch 对应的 CUDA 版本不高于驱动支持的最高版本。

总结

遇到 an illegal instruction was encountered 这种底层指令报错，不要慌。绝大多数情况下，降级 PyTorch 到 2.0.1 就能完美解决问题