未开始Chapter 920 分钟

常见报错与调试方法

Troubleshooting & Debugging

汇总常见问题的诊断和解决方法

未开始

完成后会同步到学习路径和首页统计

导读

你一定会遇到报错 —— 所有人都会。区别只在于：有人卡半天最后放弃，有人 5 分钟定位解决。差距不在天赋，在有没有一套系统的排错方法。这恰恰是工程师真正值钱的能力。

这一章不教某个具体报错的解法（那些在「报错诊断」库里），而是教你一套通用 4 步法：读最后一行 → 判断类型 → 查站内库 → Google 精确报错。90% 的问题在第 3 步就解决了。

还会教你一件很多人不会的事：怎么把问题问清楚，让 AI 助手或社区能真正帮到你。

为什么重要

这是整个课程里"可迁移性"最强的一章 —— 学会的不只是修 LeRobot 的报错，而是修任何技术报错：

会读 traceback → 不再被一长串红字吓到
会判断错误类型 → 直奔正确的解决方向，不乱试
会问问题 → 求助一次就能得到有效回答，而不是"帮帮我"换来"贴下完整报错"
有了这套方法 → 你能独立走完前 8 章，不依赖别人手把手

本章关键术语复合误差 CUDA / AMP LeRobot

学习目标

掌握常见错误的诊断方法
学会查看日志定位问题
积累调试经验

核心原理

1错误信息是最好的调试起点
2系统化排查优于随机尝试
3记录问题和解决方案便于复用

架构图

排错决策树

flowchart TD
    Err["💥 报错"] --> Read["1. 读最后一行"]
    Read --> Type{"2. 判断类型"}
    Type -->|"环境/安装"| KB["3. 查站内诊断库"]
    Type -->|"硬件/串口"| KB
    Type -->|"数据/文件"| KB
    Type -->|"训练/推理"| KB
    KB --> Found{"找到了吗"}
    Found -->|"是"| Fix["✅ 修复"]
    Found -->|"否"| Google["4. Google 精确报错"]
    Google --> Fix
    style Err fill:#dc2626,color:#fff
    style Fix fill:#16a34a,color:#fff

通用 4 步法。每个分支对应一类典型错误，绝大多数到第 3 步（站内库）就解决。

逐步讲解

第 1 步：读最后一行（不是第一行）

Python traceback 往往有几十行。最后一行才是错误类型 + 直接原因的总结 —— 先看它。

第二关键的是离最后一行最近的、写着你自己代码路径的那一行，那是你能直接改的地方。前面大段是库内部调用，初看可忽略。

小提示

别被红字长度吓到，90% 的信息量在最后一行那一句话里。

第 2 步：判断类型，第 3 步：查站内库

把错误归类：环境/安装、硬件/串口、数据/文件、训练、推理。类型决定了往哪个方向查。

然后去本站「报错诊断」搜关键字 —— 已收录的十几条覆盖了 80% 的常见错（Permission denied、CUDA OOM、meta/info.json、NaN loss 等）。

小提示

搜索时用报错里的英文关键字（如 "CUDA out of memory"），比用中文描述命中率高得多。

完整保存错误，方便排查和求助

出错时先把完整输出存下来，免得滚屏看不到。2>&1 把错误流并入正常输出，| tee 同时显示在屏幕并写文件。

求助别人时附上这个 error.log，比截图清楚 10 倍 —— 别人能直接复制关键字去搜。

保存完整错误到文件

bash

python lerobot/scripts/train.py policy=act ... 2>&1 | tee error.log

你应该看到

(输出同时显示在屏幕 + 写入 error.log)

命令代码

查看完整错误栈

bash

python script.py 2>&1 | tee error.log

检查 GPU 状态

bash

nvidia-smi

检查磁盘空间

bash

df -h

常见误区

看到长 traceback 就懵，从第一行开始读。

根本原因

不知道 traceback 的结构。

正确认识

先读最后一行（错误总结），再看离它最近的"你的代码"那一行。前面的库内部调用栈通常不用细看。

去社区/AI 助手问"我训练报错了帮帮我"，没人能答。

根本原因

信息量为零，别人无法复现或定位。

正确认识

好的提问 = 完整错误栈 + 你跑的命令 + 关键配置（info.json/yaml）+ 已经尝试过什么。信息越全，回答越准。

把报错用自己的话描述一遍发出去。

根本原因

复述会丢掉关键的报错关键字。

正确认识

直接贴原始报错文本（别截图、别复述），关键字一字不差才能被搜到/被识别。

检查点

能够独立诊断常见错误
建立个人错误知识库
理解调试的系统方法

动手练习

给三类报错配原因

把下面三个报错和最可能的原因连起来：

报错：A) ImportError B) CUDA out of memory C) FileNotFoundError

原因：① 显存不够，batch 太大 ② 路径错/数据集没录完整 ③ 缺包或环境没激活

写一条合格的求助

假设你训练时报 NaN loss。按本章的"好提问模板"，列出你该附上哪 4 样信息。

自测

本章讨论区

登录后即可参与讨论 —— 点击右上角的登录按钮

加载中…

flowchart TD Err["💥 报错"] --> Read["1. 读最后一行"] Read --> Type{"2. 判断类型"} Type -->|"环境/安装"| KB["3. 查站内诊断库"] Type -->|"硬件/串口"| KB Type -->|"数据/文件"| KB Type -->|"训练/推理"| KB KB --> Found{"找到了吗"} Found -->|"是"| Fix["✅ 修复"] Found -->|"否"| Google["4. Google 精确报错"] Google --> Fix style Err fill:#dc2626,color:#fff style Fix fill:#16a34a,color:#fff

第 1 步：读最后一行（不是第一行）

第 2 步：判断类型，第 3 步：查站内库

完整保存错误，方便排查和求助

给三类报错配原因

写一条合格的求助

本章讨论区

Command Palette

第 1 步：读最后一行（不是第一行）

第 2 步：判断类型，第 3 步：查站内库

完整保存错误，方便排查和求助

给三类报错配原因

写一条合格的求助

本章讨论区