上个月接了一个自动驾驶相关的项目预研，任务很明确：在给定的边缘设备上跑通实时车道线检测。我一开始按老思路来，把SCNN、LaneNet这类分割方案挨个试了一圈，结果要么精度一般，要么帧率根本压不下来。后来翻到 Ultra-Fast-Lane-Detection 这个项目，读过论文和代码之后就明白了——它没有走“逐像素分割”那条拥挤的路，而是把车道线检测拆成了一个“逐行分类”问题，速度和精度都能兼顾。于是花了大概三天时间在服务器上复现、调参、跑通，顺便在Tusimple数据集上完成了完整训练和评测。
这篇文章就把这次复现的完整过程记录下来，包括模型原理、环境准备、数据集处理、训练测试、踩坑排查，再说说怎么在这个项目基础上做二次开发。如果你正准备跑这个模型，或者对按行分类的车道线检测思路感兴趣，这篇应该能帮你省下不少时间。
1. 为什么选它：速度与精度之外，还要看工程价值
1.1 传统车道线检测方案的瓶颈
车道线检测在自动驾驶里属于一个“看起来简单、做好很难”的任务。早期的主流方案基本都依赖分割思想：把输入图像每个像素分出来是不是车道线，再对这些分割结果做聚类、拟合、后处理。代表性工作有基于UNet风格的分割网络，也有引入空间卷积的SCNN（Spatial CNN）。
SCNN这类方案在精度上确实不错，但代价是计算开销非常大。空间卷积会一行一行地传递消息，串行过程让推理延迟很难压下来。在边缘设备上，这种模型跑不到理想帧率。LaneNet也类似，光是一个实例分割头加上聚类后处理，就已经让CPU动弹不得，GPU上也谈不上轻量。实际做项目的人都清楚，模型再准，如果帧率达不到实时要求，在车上就是没法用的。
1.2 Ultra-Fast-Lane-Detection 的核心卖点
Ultra-Fast-Lane-Detection（下文简称UFLD）的思路非常直接：它不分割像素，而是把“车道线出现在这一行的哪个位置”当成一个分类问题来处理。每一根车道线，在图像每一行附近的位置去分类，从而确定这条线的水平坐标。这样整个车道线检测就被转化为一个相对轻量的分类任务，推理时只需要做一次前向，不需要额外的后处理和聚类。
官方论文给出的速度很夸张，在Tesla V100上可以达到322 FPS左右（根据模型配置不同会有差异）。即使在移动端设备上，用轻量backbone也能跑到实时。对项目预研来说，这种量级的性能空间非常宝贵，因为它留出了后续加检测、跟踪、障碍物识别等模块的计算余量。
1.3 这个模型适合谁来复现
我个人觉得UFLD适合三类人来跑：
- 做ADAS算法预研的工程师：需要快速验证车道线检测模块能否在目标平台实时运行。
- 做毕业设计或课程项目的学生：模型结构清晰，代码不算复杂，Tusimple和CULane数据集都是公开的，非常适合完整走一遍“数据集→训练→评测→优化”的流程。
- 想做车道线检测技术栈迁移的人：UFLD的思路可以迁移到其他结构化输出任务上，比如边界线检测、地面标线检测等，复现一遍就能吃透这个套路。
2. 复现前必须弄清楚的几个问题：硬件、环境与数据
2.1 硬件需求与GPU选择
UFLD的训练并不像很多大模型那样吃显卡。以Tusimple数据集为例，输入图像会被缩放到288×800左右，主干网络用的是ResNet18或ResNet34，默认batch size是12。我当时用的是一张RTX 3090，显存占用大概在8GB到10GB之间，训练起来很舒服。
如果你的机器只有4GB显存，也不是不能跑。把batch size降到4，或者换更小的backbone（ResNet18），一样能训练，只是收敛速度和稳定性会差一些。这里有个细节：模型里有一个辅助分割分支，虽然在推理时会被去掉，但训练时它占用的显存比较大。如果显存吃紧，可以先把辅助分支的权重调小，或者从更小的输入尺寸开始。
2.2 环境搭建的细节
复现这个项目其实不需要特别新的框架。官方仓库老一些的版本是基于PyTorch 1.0写的，但我在实际环境里用Python 3.8 + PyTorch 1.8.1就完全没问题。如果你手头是PyTorch 2.x，需要注意个别API的变化，这个我在后面踩坑章节会专门讲。
安装依赖时建议直接用requirements文件，核心依赖包括：
torch>=1.0 torchvision>=0.2.1 opencv-python numpy scipy tensorboardX tqdm pandas matplotlib scikit-learn个人建议把tensorboard的版本锁定一下，有些新版本和旧代码的SummaryWriter用法不兼容，会导致训练时日志模块直接报错。
还有一个容易忽略的点：这个项目里用到了torchvision.models来加载预训练backbone。如果你用的是torchvision新版（0.13以上），pretrained=True这个参数已经废弃，需要改成weights=ResNet34_Weights.DEFAULT这样的写法。这也是很多人环境装好后一跑就挂的第一道坎。
2.3 数据集下载与目录组织
UFLD官方支持两个公开数据集：Tusimple和CULane。Tusimple数据量小、标注是json格式，更适合第一次复现。CULane数据量大、场景更复杂，适合做精度验证。
Tusimple数据集需要去官网注册下载，内容包括：
train_set/：约3600张图像，带label.json标注test_set/：约2800张图像，带test_label.json（用于评测）train_set/里还有对应的label_data_xxxx.json
数据集的目录结构建议这样组织：
TUSIMPLE/ ├── train_set/ │ ├── clips/ │ ├── label_data_0313.json │ ├── label_data_0531.json │ └── label_data_0601.json └── test_set/ ├── clips/ └── test_label.jsonCULane数据集组织方式不一样，是按driver_xx_xxframe/目录存放图片，标注文件是.txt格式。如果只做Tusimple复现，可以先不用管CULane。
2.4 配置文件修改注意事项
UFLD的配置方式是Python文件而非yaml/json，官方放在configs/目录下。打开tusimple.py，你需要改这几个地方：
data_root = "/你的实际路径/TUSIMPLE" train_url = data_root + "/train_set" test_url = data_root + "/test_set" epochs = 100 batch_size = 12 lr = 3e-4 griding_num = 100 num_lanes = 2 row_anchor = 56 backbone = "resnet34"griding_num表示把每行划分成多少个网格位置，num_lanes是数据集中最多出现的车道线数量（Tusimple标注里固定为2条，CULane一般为4条），row_anchor是有效行锚点数量。这几个参数直接影响模型输出尺寸，也直接影响速度和精度，不要轻易改。我一开始手贱把griding_num改成200，显存直接涨了一截，精度却没有提升，最后又改了回来。
3. 拆开模型看原理：按行分类和结构损失是怎么协同的
3.1 整体流水线：从图像到坐标
整个推理过程可以用一句话概括：输入一张图，经过backbone提取特征，再经过分类头，输出每个车道线在每个行位置上的概率分布，取最大概率对应的网格位置，就得到车道线的坐标点。
具体来说，模型前向得到一个形状为(batch, num_lanes, h, w)的输出。这里的h对应row_anchor的数量，w对应griding_num。对每个车道线标签，在每一行上做softmax，取概率最大的网格坐标，再乘上一个缩放系数，就还原成真实图像下的x坐标。
这个思路最大的好处是：车道线检测被简化成了分类问题，模型只需要在少量候选位置上做判断，计算量比逐像素分割小一个数量级。而且由于是在全局特征上直接分类，感受野天然就是全图的，不需要额外设计大的空洞卷积来扩大视野。
3.2 row anchor 与 griding cell 到底是什么
这两个概念是理解UFLD的关键。
row_anchor：在垂直方向上，把图像均匀分成若干个水平线。模型只在这些水平线上预测车道线位置，而不是在图像的每个像素行上预测。这是为了减少计算量并保持足够精度。Tusimple上官方用56个row anchor。griding_num：在每条row anchor水平线上，把宽度方向分成若干个网格cell。模型预测的是“车道线中心落在哪个cell里”。Tusimple上官方用100个网格。
用个比方：传统分割是“穷举每一个像素”，UFLD则是“每隔一定距离设一个关卡，判断车道线从哪个关卡通过”。关卡少了，计算量小了，但分辨率会下降；关卡多了，精度提升但计算量增加。复现时最好保持官方参数，先跑通再谈优化。
3.3 训练时的三个损失与两个分支
UFLD训练时有两个分支：主分支（分类分支）输出车道线位置的概率分布，辅助分支（分割分支）输出像素级的分割图。推理时辅助分支会被丢弃，只保留分类分支。
损失函数由三部分组成：
- 分类损失（交叉熵）：衡量预测位置与真实位置的差异。这是最主要的损失。
- 结构损失：对车道线形状施加约束，包括平滑性、连续性、以及左右车道线之间的平行性。这部分保证了输出不是一堆孤立点，而是连贯的车道线。具体实现里用到了L1平滑损失和车道线间距一致性约束。
- 辅助分割损失（只在训练时用）：让辅助分割分支也能学到车道线的语义特征，帮助主分支更快收敛。
训练时，整体损失可以写成：
L_total = L_cls + λ1 * L_structure + λ2 * L_seg官方代码里默认系数大概是λ1=0.4、λ2=1.0这个量级，具体可以在配置里调。我复现时的经验是：结构损失的权重不要调太大，否则模型会过度追求车道线平滑，导致弯道场景精度下降；辅助分割分支的权重可以保留，在训练早期对收敛帮助明显。
3.4 推理时的后处理逻辑
推理时模型输出的概率图并不能直接画到图像上，还需要处理几个细节：
- 对每个车道线类别，在每一行上做softmax，取最大概率对应的网格索引。
- 通过
griding_num和输入图像宽度的比例关系，把网格索引映射回像素坐标。 - 用局部最大值（
local_maximum）做精细调整，因为分类得到的索引是离散的，直接用它画线会显得不够平滑。 - 对多个车道线类别做非极大值抑制（NMS），防止重复检测同一条车道线。这个在CULane数据集上尤其重要，因为弯道和遮挡会导致同一条线被预测成两根。
后处理这部分代码在utils/里，看起来不多，但改错一个比例因子，画出来的车道线就会全部偏移。最好的调试方法是拿官方demo图片跑一遍，对比画出来的车道线和原图的贴合程度。
4. 完整复现流程：训练、评测与可视化
4.1 训练脚本与超参数设定
我的复现以Tusimple为基准。数据集准备好、配置改好后，直接执行：
python train.py --config configs/tusimple.py训练过程中日志会打印每个epoch的loss和accuracy。Tusimple数据集不大，在RTX 3090上训练100个epoch大概需要4到6小时，具体看batch size和backbone。如果你想快速验证流程是否通顺，可以先只训练5个epoch看loss能不能降下来，再开完整训练。
几个关键超参数我再强调一下：
lr=3e-4，优化器用的SGD，momentum=0.9，weight_decay=1e-4。batch_size=12，Tusimple数据集小，batch太大容易过拟合。epochs=100，官方训练了很长时间，但复现时80到100个epoch基本能收敛。- 数据增强包括水平翻转、亮度饱和度调整、旋转、裁剪等，Tusimple上不需要太强的增强，因为本身是高速路场景，变化不大。
训练过程中的accuracy提升速度不会像图像分类那么快，因为车道线检测任务的评价指标本身比较严格。看到准确率在70%~80%徘徊不要慌，多等几个epoch，通常到40个epoch以后会明显上升。
4.2 训练日志怎么看
官方代码默认接入TensorBoard，可以用：
tensorboard --logdir runs观察训练集loss、验证集accuracy的变化。我复现时的经验是：
- 前10个epoch，loss下降明显，accuracy可能只有60%左右。
- 30~50个epoch，accuracy开始稳步上升，能到90%以上。
- 70个epoch后，accuracy增长放缓，这时候如果验证集波动大，说明需要提前停止或者调整学习率。
Tusimple的accuracy指标计算方式是：对每条车道线的每个row anchor，预测位置和真实位置的距离小于一定阈值就算对，最终统计所有点的正确率。官方最终能达到96%左右，我复现时在95%附近，差别不大。
4.3 评测：准确率与速度的合理口径
训练完后，用测试集做正式评测：
python test.py --config configs/tusimple.py --test_model ./logs/epoch_99.pth --test_work_dir ./test_result输出结果里包含accuracy和每帧耗时。需要留意的是，官方代码里的准确率评测没有做非常严格的Tusimple官方评测协议，它计算的是点级别的准确率，而不是官方leaderboard上的完整指标。所以复现结果和论文报告的96.93%有一点波动是正常的，不必纠结那零点几个百分点。
如果要做严格的Tusimple官方评测，需要把预测结果转成官方json格式，用他们提供的Python脚本评测。官方仓库里有转换脚本，但依赖库略老，我建议先用项目自带test.py拿到一个大致的精度参考即可。
速度方面，官方论文的322 FPS是在Tesla V100上测的，还用了半精度和某些加速手段。我自己在RTX 3090上测，ResNet34结构，输入288×800，纯PyTorch推理，大概能到200 FPS以上，已经足够实时。如果你在边缘设备上跑，帧率会低一些，但比分割方案好太多。
4.4 可视化demo测试流程
跑demo很简单：
python demo.py --config configs/tusimple.py --test_model ./logs/epoch_99.pth这会加载一张示例图片，画出检测到的车道线并保存。也可以自己指定图片路径，比如拿测试集里任意一张图试试效果。我建议多拿几张不同场景的图测，包括强光、阴影、弯道、被车辆遮挡的情形，这样能直观看出模型的鲁棒性。
UFLD在正常高速公路上效果非常好，车道线清晰连续。但在强逆光和车道线被车挡住的情况下，容易出现短暂断线或预测偏移，这属于正常现象，后续可以通过融合相邻帧信息或加时序跟踪来缓解。
5. 踩坑记录：复现路上最花时间的五个地方
5.1 数据集解析失败：json编码与路径分隔符
我第一次跑加载数据就报错，提示json解析失败。检查后发现不是编码问题，而是Windows环境下的路径分隔符问题。数据集脚本用的是os.path.join，在Windows上会生成反斜杠路径，而json里的路径是正斜杠。解决办法有两个：一是干脆在Linux环境下跑，二是修改data/里的路径拼接逻辑，统一用正斜杠。
如果你在Windows上复现，我想提醒你：这个仓库的很多脚本默认没考虑Windows，遇到和文件路径相关的报错，优先往路径分隔符方向查。
5.2 预训练权重加载失败的排查链路
加载resnet34预训练权重时报错，提示键名不匹配。排查过程大概是这样的：
- 首先想到的是PyTorch版本差异，因为新版torchvision的state_dict键名改了。
- 打印
model.state_dict()和预训练权重的键名对比，发现确有很多后缀不同。 - 最终解决方式是修改
model/resnet.py里的加载方式，改成model.load_state_dict(checkpoint, strict=False)，或者自己写一个键名映射函数。
这个坑很常见，尤其是从旧仓库拉代码配新环境时。我的建议是：网上搜一下官方仓库的issue区，很多前人已经给出了适配新版本torchvision的补丁，照着改比从零排查快得多。
5.3 新GPU上跑老代码的兼容问题
RTX 30系列及以上显卡默认走CUDA 11+，如果PyTorch版本太低，会直接报“no kernel image available”的错误。这个问题的根源是老版PyTorch的CUDA kernel不支持新GPU架构。
我最终确定的稳定组合是：
Python 3.8 PyTorch 1.8.1 + CUDA 11.1 torchvision 0.9.1如果非要用PyTorch 2.x，记得把代码里的torch.nn.functional.upsample改成torch.nn.functional.interpolate，并处理一下pretrained参数问题。会多花一点时间，但不是不能跑。
5.4 显存爆炸与batch size的取舍
我的第一轮训练batch size设成官方默认的12，结果在3090上勉强能跑，但到训练后期随着feature map变化偶尔会爆显存。这时候不需要换显卡，把batch size从12降到8，或者把输入尺寸从288×800降到256×720，都能解决问题。
不过要注意：直接改输入尺寸会影响模型精度，因为row anchor和griding_num是跟输入尺寸绑定的。如果只改batch size，就不影响精度。我后面固定用batch size=8，训练稳定，精度和batch size=12时几乎没有差别。
5.5 后处理坐标偏移：一个让人头秃的细节
有一次demo画出来的车道线整体往左偏了一段距离。排查了很久，最后发现问题出在坐标映射系数上。模型输出的网格索引要乘上(原图宽度 / griding_num)才能映射回真实像素坐标，但如果中途resize过图像，缩放因子要重新算，不能用写死的常数。
官方demo.py里默认输入是按原始尺寸的比例resize的，如果你自己写推理脚本，一定要注意resize比例和坐标还原的一致性。类似的偏移问题在CULane数据集上更隐蔽，因为那里还有裁剪操作。
6. 从复现到二次开发：换backbone、换数据集、上设备
6.1 替换backbone：精度和速度的另一个平衡点
官方代码里默认支持resnet18和resnet34。实际工程里完全可以把backbone换成MobileNetV3、EfficientNet-Lite这类轻量结构，进一步压榨速度。
替换backbone需要做两件事：一是把model/model.py里backbone的输出通道调整到分类头输入要求的通道数；二是把分类头的第一层卷积的in_channels对应改掉。别的都不用动，UFLD的分类头很薄，接入成本很低。
我自己试过用MobileNetV3-Large替换，精度比ResNet18低1个百分点左右，但推理速度快了将近40%。如果你的目标平台是Jetson Nano或树莓派级别，这个方向值得投入时间。
6.2 适配自己的标注数据
如果你要检测的不只是普通车道线，比如还要检测停止线、导流线、斑马线边缘，那就需要定义自己的数据集格式。最简单的做法是仿照Tusimple的json格式，把自己的标注转成三个字段：lanes（每条线的x坐标列表）、h_samples（固定的行坐标列表）、raw_file（图像路径）。
这里有个坑：你的标注行坐标必须和代码里的row_anchor对应上。如果自己的标注没有按固定行坐标取点，需要在数据预处理时做插值。官方data/里给的转换脚本写得很明白，直接参考即可。
6.3 上设备部署的思路
UFLD的模型结构非常规整，backbone + 分类头都是标准卷积，导出ONNX几乎不需要改动。用torch.onnx.export导出时，把辅助分割分支去掉，只保留分类分支。
导出成ONNX后在TensorRT上做FP16推理，速度能再提一截。我在Jetson Orin上跑过ResNet18版本的UFLD，TensorRT FP16下大约能到500 FPS以上（输入288×800），这数据已经非常漂亮了。唯一要注意的是，ONNX导出时输入尺寸最好固定死，动态shape虽然灵活，但在TensorRT上会带来额外的显存和延迟开销。
结尾想说的几句话
整个复现过程下来，我最深的一个体会是：UFLD这个项目的“工程思维”很值得学习。它没有硬刚分割精度，而是换了一个问题定义方式，把计算复杂度降了一个量级。这也是为什么它在学术界和工业界都有不少人关注——思路比堆参数重要太多了。
最后分享一个小技巧：如果你只是想让模型快速跑起来看效果，可以直接去官方仓库下载训练好的权重文件，不用自己从头训练。但如果你要适配自己的数据或者做性能优化，那就老老实实从训练开始走一遍，把每个模块的输入输出形状都看清楚，后面改起来才顺手。复现经典项目这件事，永远不是跑通就结束，跑通之后能改、能裁剪、能部署，才算真的吃透了。
