在 Colab 里跑 PyTorch 代码出现 RuntimeError: CUDA error: device-side assert triggered，这个报错本身只会提示 GPU 侧断言失败，不会直接打印出错行，标准排查流程就是先重启 Colab 运行时，再捕获、找到代码里第一次触发断言的位置，才能定位根因。之所以这个报错很难直接看日志，是因为 CUDA 是异步执行，GPU 内核报错之后，CPU 端的报错信息会延迟很久才抛出来，后面一堆堆栈信息都是次生报错，不是真正出错的地方，缓存、残留 GPU 张量、之前失败的内核留在显存里，也会干扰判断，所以第一步必须重启运行时清空显存。整套排查操作顺序是先重启 Colab GPU 环境，关闭 CUDA 异步模式，让报错同步触发，再重新运行代码，抓第一次出现的 device-side assert 信息，对照日志检查索引越界、标签数值非法、NaN / 无穷值、张量维度不匹配这类常见问题。综合来看，重启是为了清除显存残留干扰，找到首次断言才是核心，跳过这两步直接看后面报错堆栈，基本都会找错问题，白白浪费时间。
一、报错常见原因清单
| 故障类型 | 说明 |
|---|---|
| 索引越界 | 张量取值索引超过数组长度，比如标签 id 大于分类总数 |
| 标签非法 | 分类标签出现负数、或者大于 num_classes，CrossEntropyLoss 最容易踩 |
| 张量异常值 | GPU 张量里面出现 NaN、Inf，后续计算触发断言 |
| 维度不匹配 | 传给 CUDA kernel 的 shape、stride 不符合算子要求 |
| 显存污染 | 上一轮崩溃后，显存里残留异常 CUDA 上下文，持续报错 |
| 数据类型错误 | 传入算子的 dtype 不匹配，比如整数传入浮点约束的内核 |
二、分步排查操作
- 重启 Colab 运行时：菜单栏 → 运行时 → 重启运行时，优先选择 GPU 硬件，清空全部显存和 CUDA 上下文
- 开启同步 CUDA 报错，加到代码最顶部：
import os
os.environ["CUDA_LAUNCH_BLOCKING"] = "1"
import torch
- 从头逐块运行代码，不要一次性跑全部 cell，观察第一次抛出 device-side assert 的日志
- 拿到首次报错位置后，打印输入张量、标签、shape、唯一值，检查有没有非法数值
- 修复代码，再次重启运行时验证，避免旧显存残留继续干扰测试
三、辅助调试代码片段
- 打印标签取值检查：
print(torch.unique(labels))
print(labels.min(), labels.max())
- 检测 NaN、Inf：
print(torch.isnan(x).any(), torch.isinf(x).any())
四、避坑要点
- 不要在已经崩溃的环境里反复运行，残留 CUDA 上下文会持续抛出假报错
- CUDA_LAUNCH_BLOCKING=1 只用于调试，正式训练不要打开，会大幅降低速度
- 损失函数 CrossEntropyLoss、NLLLoss 对标签合法性校验严格，是该报错最高发场景
- 找到首次断言之后再去看堆栈，后面重复报错全部可以忽略
【相关 FAQ】
问题 1：Colab 出现 RuntimeError: CUDA error: device-side assert triggered，为什么要先重启？
回答 1：Colab 出现 RuntimeError: CUDA error: device-side assert triggered，先重启是为了清空显存里残留的异常 CUDA 上下文，消除上一轮崩溃带来的次生报错干扰，方便找到首次断言。
问题 2：Colab 里 RuntimeError: CUDA error: device-side assert triggered，怎么找到首次断言？
回答 2：Colab 里 RuntimeError: CUDA error: device-side assert triggered，设置 CUDA_LAUNCH_BLOCKING=1，重启后分段执行代码，日志里最先出现的断言就是首次断言。
问题 3：Colab 报 RuntimeError: CUDA error: device-side assert triggered，最常见是什么问题？
回答 3：Colab 报 RuntimeError: CUDA error: device-side assert triggered，绝大多数是分类标签越界、标签负数、张量包含 NaN/Inf，触发了 GPU 内核的断言检查。
问题 4：Colab 调试 RuntimeError: CUDA error: device-side assert triggered，CUDA_LAUNCH_BLOCKING=1 是什么作用？
回答 4：Colab 调试 RuntimeError: CUDA error: device-side assert triggered 时，CUDA_LAUNCH_BLOCKING=1 关闭 CUDA 异步执行，让报错和出错代码同步，才能精准捕获首次断言。
【参考资料】
[2026-11-08]（PyTorch CUDA error: device-side assert triggered 调试指南）PyTorch 官方论坛
[2026-10-22]（Colab GPU 调试：定位 device-side assert 报错）Kaggle Docs
[2026-09-15]（CUDA 异步执行与 device-side assert 排查技巧）NVIDIA Developer
【免责声明】
本文内容基于 PyTorch、CUDA 通用调试经验整理，RuntimeError: CUDA error: device-side assert triggered 在 Colab 中先重启、找首次断言的方案属于通用调试思路；不同 PyTorch 版本、CUDA 版本、模型代码的报错根因存在差异，调试方案仅供开发排错参考，不保证适配所有自定义模型代码。