苏自博 — AI 辅助 SparseDrive 自动驾驶感知模型调试与代码结构梳理

苏自博 — AI 辅助 SparseDrive 自动驾驶感知模型调试与代码结构梳理

背景

SparseDrive 是一个基于 mmdet3d 的端到端自动驾驶感知模型，支持 3D 目标检测、在线地图分割、运动预测和占据栅格预测（Occupancy）等多个子任务。项目代码量大（mmdet3d 框架 + 自定义 plugin），模块耦合度高，对于不熟悉 mmdet3d 注册机制和 config 驱动架构的人来说，入门调试门槛很高。

在接入「词元计划」后，我将 AI 工具全面引入到 SparseDrive 的开发和调试流程中，主要解决了两个痛点：

1. 训练调不通 — 新增 Occupancy 任务分支后训练频繁崩溃，报错层层传递难以定位根因
2. 代码看不懂 — mmdet3d 的 Registry + Hook + Config 三层架构，新人很难快速理清数据流

AI 工具

• OpenCode / Sisyphus（deepseek-v4-pro） — 本期词元计划主力工具，用于代码理解、Bug 诊断、逻辑梳理
• Claude Code — 之前使用的终端 AI 编程助手

使用方式

场景 1：Occupancy 训练崩溃调试

在 SparseDrive 中添加 Occupancy（占据栅格预测）任务分支后，训练一启动就报 KeyError: 'voxel_semantics'，错误栈被 mmdet3d 的 Hook 框架包裹了好几层，很难一眼看出根因。

过去做法：逐行打断点，从 train_step → forward → loss → head 手工追踪数据流，找到缺少哪个字段后，再去查数据处理 Pipeline 是哪个环节没生成这个字段，整个过程耗时 2-3 小时。

使用 AI 后的做法：直接把完整报错栈 + SparseDriveHead.forward() 源码 + 训练 config 贴给 AI：

「训练 Occ 分支时抛了 KeyError: ‘voxel_semantics’，请帮我分析：1）这个字段应该在数据 Pipeline 的哪个阶段生成？2）config 里有没有漏配什么？3）给出修复方案。」

AI 在几秒内给出了清晰的分析链：

1. voxel_semantics 应由数据 Pipeline 中的 LoadOccGTFromFile 生成，并通过 collect 打包进 batch
2. 训练 config 中 task_config.with_occ=True 已开启，但数据 Pipeline 缺少对应的 GT 加载 transform
3. 给出了具体的 config 修改 diff

结果：从报错到定位根因从 2 小时缩短到 5 分钟，修复后训练正常启动。

场景 2：代码结构梳理 — 理解 mmdet3d 多任务 Head 架构

SparseDrive 的核心是 SparseDriveHead，一个同时管理 Detection、Map、Motion、Occupancy 四个子任务的多任务 Head。每个子任务 Head 通过 mmdet3d 的 Registry 机制动态注册和构建，任务间的数据交互（如 Motion 依赖 Detection 的输出 anchor）使得代码逻辑高度耦合。

问题：新人面对这段代码时，很难回答"数据是怎么从 backbone 图片特征流到各个子任务输出的"。

使用 AI 的方式：

「帮我梳理 SparseDriveHead 的完整 forward 流程：从 feature_maps 输入开始，经过各子任务 Head 的调用链，画一个数据流图。重点标出各子任务之间的依赖关系（比如 Motion 怎么拿到 Detection 的 instance_bank）。」

AI 产出了一份完整的结构化分析：

feature_maps (img backbone 输出)
    │
    ├── det_head.forward(feature_maps, metas)
    │   └── 输出: 3D bbox + instance_bank
    │
    ├── map_head.forward(feature_maps, metas)          并行
    │   └── 输出: BEV map segmentation
    │
    └── motion_plan_head(det_output, map_output, ...)  依赖 det + map
        ├── 读取 det_head.anchor_encoder                        
        ├── 读取 det_head.instance_bank.mask                   
        └── 输出: motion forecasts + planning trajectory

结果：原本需要翻看 6-8 个文件才能串起来的数据流，5 分钟内理清。

场景 3：多 GPU 训练 config 参数追踪

训练脚本中 total_batch_size=64, num_gpus=8, batch_size=8 这样的参数嵌套很常见，但多个 stage 的训练脚本（stage1、stage1_occ、stage1_occ_diag 等）之间存在细微差异，修改一个容易忘记同步另一个。

「这几个 stage 训练脚本之间 batch_size / num_epochs / loss 权重有什么区别？帮我 diff 对比一下。」

AI 列出差异表，指出 stage1_occ 版本多了 occ_loss_weight=1.0 和 lovasz_softmax loss，stage1 基础版本则没有。

成果与收获

指标	使用 AI 前	使用 AI 后
训练 Bug 定位	1-3 小时（手工断点追踪）	5-15 分钟（AI 读报错栈 + 源码分析）
新模块代码理解	0.5-1 天（逐个文件阅读）	10-30 分钟（AI 生成数据流图 + 调用链）
跨 config 参数比对	20 分钟（肉眼 diff）	1 分钟（AI 结构化对比输出）
Git 协作（Fork → MR）	15 分钟（手动命令）	2 分钟（AI 自动执行）

心得与建议

1. 贴完整的报错栈：不要只贴最后一行，AI 需要完整的调用链和上下文才能定位根因
2. 先让 AI 教你看代码：面对不熟悉的框架（如 mmdet3d），先让 AI 解释架构设计意图，比直接改 Bug 更高效
3. 结构化提问：把问题拆成"定位根因 → 分析为什么 → 修复方案"三步，AI 的产出更有条理
4. AI 的代码分析能力是静态的：训练时的显存溢出、梯度爆炸等运行时问题，AI 只能给排查方向，最终还需要自己跑实验验证
5. 保存问题对话记录：把调试过程中的关键分析对话保存下来，相当于给自己积累了一份带注解的项目文档

---

本分享由 AI 辅助创作，内容基于真实的 SparseDrive 开发体验。