1. 拆解 Apollo 6.0 Planning 模块的 Protobuf 定义从消息结构到工程实践Apollo 6.0 的 Planning 模块是整个自动驾驶系统里最“烧脑”的部分之一它负责把上游感知、定位、地图、预测的结果揉在一起算出一条安全、平滑、可执行的轨迹。而 Protobuf 定义就是这套复杂逻辑的“骨架”和“接口契约”。很多刚接触 Apollo 的朋友一上来就扎进 EM Planner、Lattice Planner 的算法细节结果被各种proto文件里的字段绕得晕头转向。其实把 Planning 模块的 Protobuf 定义吃透你就能像看地图一样清楚知道数据从哪来、到哪去、中间经过了哪些关键节点。这篇文章我就结合自己实际调试和二次开发的经验把 Apollo 6.0 Planning 模块的 Protobuf 定义从头到尾捋一遍。不管你是刚入行的自动驾驶软件工程师还是想基于 Apollo 做二次开发的爱好者只要你想搞清楚 Planning 模块到底怎么“思考”、怎么“决策”这些内容都能直接拿来参考。1.1 为什么 Protobuf 在 Planning 模块里如此关键Apollo 是一个典型的分布式、模块化系统。感知、预测、规划、控制这些模块可能跑在不同的进程甚至不同的计算单元上。它们之间要交换数据就得有一套高效、跨语言、结构化的序列化方案。Protobuf 正好满足这些需求二进制传输效率高、字段兼容性好、代码生成机制成熟。在 Planning 模块里Protobuf 不仅仅是“数据容器”它更是模块间通信的“合同”。比如预测模块输出一个PredictionObstacles规划模块拿到后会把它转换成内部需要的障碍物信息再结合地图和定位生成最终的ADCTrajectory。如果你不理解这些 proto 里每个字段的含义调试时看到一堆二进制或者 JSON 输出根本无从下手。我刚开始调 Planning 的时候遇到过一个典型问题车辆在路口莫名其妙急刹。查了半天最后发现是PredictionObstacles里某个障碍物的priority字段被错误地设成了高优先级导致规划器把它当成了必须避让的目标。如果当时我能快速定位到 proto 定义看看这个字段的取值逻辑可能几分钟就解决了。所以熟悉 Protobuf 定义不只是“看懂代码”更是提升调试效率、避免踩坑的基本功。1.2 Apollo 6.0 Planning 模块的 Proto 文件组织方式Apollo 的代码仓库里modules/planning/proto目录下存放着 Planning 模块所有的 Protobuf 定义。这些文件大致可以分成几类第一类是规划器配置类比如planning_config.proto、planner_config.proto它们定义了各种规划算法的参数和开关第二类是决策与场景类比如decision.proto、scenario.proto描述了规划器在不同场景下的决策逻辑第三类是轨迹与调试类比如ADCTrajectory.proto、planning_internal.proto它们定义了最终输出的轨迹和内部调试信息。这些 proto 文件之间互相引用形成了一个有层次的依赖关系。比如PlanningConfig里会包含PlannerConfig而ADCTrajectory里又会引用Decision和PlanningDebug。理解这种组织方式你就能在需要修改或扩展功能时快速找到对应的文件而不是像无头苍蝇一样乱翻。2. 核心 Proto 消息逐个拆解从配置到轨迹2.1 PlanningConfig规划模块的“总控面板”PlanningConfig是 Planning 模块的顶层配置它决定了规划器用哪种算法、以什么频率运行、在哪些场景下启用哪些功能。这个 proto 里最关键的字段是planner_type它指定了当前使用的规划器类型比如EM、LATTICE、NAVI等。Apollo 6.0 默认使用的是PUBLIC_ROAD模式内部会根据场景动态切换规划器。另一个重要字段是default_task_config它包含了任务级别的配置比如DP_POLY_PATH_OPTIMIZER、QP_SPEED_OPTIMIZER等。这些任务配置直接影响了轨迹生成的平滑度和计算耗时。在实际项目中我经常需要调整PlanningConfig里的planning_cycle_time和emergency_planning_cycle_time。前者是正常规划周期默认 100ms后者是紧急情况下的规划周期默认 50ms。如果你发现车辆在紧急避障时反应不够快可以适当降低这个值但要注意计算负载。另外PlanningConfig里还有一个enable_scenario_based_planning开关打开后会启用基于场景的规划框架这是 Apollo 6.0 的一个重要特性。我建议在调试新场景时先把这个开关打开这样能更清晰地看到每个场景的决策过程。2.2 ADCTrajectory规划模块的“最终答卷”ADCTrajectory是 Planning 模块输出的核心消息它包含了车辆未来一段时间内的完整轨迹。这个 proto 里最重要的字段是trajectory_point它是一个数组每个点包含了path_point和v、a、relative_time等信息。path_point里又有x、y、z、theta、kappa、s等字段分别表示位置、航向角、曲率、纵向位移。这些数据直接送给控制模块控制模块再根据它们计算油门、刹车和转向。我踩过的一个坑是ADCTrajectory里的trajectory_point数组长度不是固定的。它取决于规划的时间窗口和采样间隔。如果你在代码里硬编码了数组长度一旦配置改变就会越界。正确的做法是动态遍历或者用trajectory_point_size()获取实际长度。另外ADCTrajectory里还有一个estop字段当规划器无法生成安全轨迹时会置位这个字段控制模块收到后会执行紧急停车。调试时如果看到车辆突然停下先检查这个字段往往能快速定位问题。2.3 Decision规划器的“思考过程”Decision这个 proto 记录了规划器在每个规划周期做出的决策比如跟车、换道、避让、停车等。它里面最核心的是main_decision包含了stop、cruise、follow、overtake等子决策。每个子决策又有自己的参数比如stop里有stop_point和reasonfollow里有target_obstacle_id和distance。这些信息对于调试非常有用因为它们能告诉你规划器“为什么”这么做。举个例子有一次车辆在跟车时距离前车过近我查看Decision里的follow决策发现target_obstacle_id指向的障碍物并不是正前方的车辆而是一个相邻车道被误判的物体。顺着这个线索我检查了预测模块的输出发现那个障碍物的位置估计有偏差。如果没有Decision这个 proto我可能得花大量时间在日志里大海捞针。所以我强烈建议在调试时把Decision信息打印出来或者用 Apollo 的可视化工具查看它能极大提升排查效率。2.4 PlanningInternal调试信息的“百宝箱”PlanningInternal是 Planning 模块内部使用的调试信息 proto它包含了大量的中间计算结果比如DP_StGraph、SpeedPlan、PathPlan等。这些信息在正常运行时不会输出但当你需要深入分析规划器的行为时它们就是无价之宝。比如DP_StGraph里的total_s和total_t能告诉你动态规划在时空图上的搜索范围SpeedPlan里的speed_point能展示速度曲线的细节。我通常会在planning.conf里把enable_planning_debug设为true这样PlanningInternal就会被填充并发布到/apollo/planning_internal话题上。然后用rosbag录下来再用 Python 脚本解析。这个过程虽然有点繁琐但当你需要优化轨迹平滑度或者分析规划器为什么选择某条路径时这些数据能提供最直接的证据。需要注意的是打开调试信息会增加计算和通信开销所以只在调试阶段使用上线时要关掉。3. 实操如何基于 Proto 定义进行二次开发与调试3.1 环境准备与 Proto 编译在开始二次开发之前你需要确保 Apollo 的编译环境已经就绪。Apollo 6.0 使用 Bazel 作为构建工具Proto 文件的编译也是通过 Bazel 自动完成的。你不需要手动运行protoc只要在BUILD文件里正确声明依赖Bazel 就会生成对应的 C 和 Python 代码。不过如果你需要单独查看某个 proto 生成的代码可以在bazel-bin目录下找到。比如modules/planning/proto/ADCTrajectory.pb.h就是编译后生成的 C 头文件。我建议在修改任何 proto 之前先运行一次完整的编译确保基线是干净的。命令很简单./apollo.sh build。如果编译失败先解决环境问题再动代码。另外Apollo 的 Proto 文件里有很多optional和repeated字段修改时要注意兼容性。比如如果你把一个optional字段改成repeated可能会导致旧版本的代码解析失败。所以在团队协作中修改 proto 一定要谨慎最好遵循“只增不改”的原则。3.2 自定义规划器配置的实操步骤假设你想调整 EM Planner 的路径优化权重让轨迹更贴近车道中心线。这个参数在EMPlannerConfig里具体是path_optimizer_config下的lateral_weight。你可以直接修改modules/planning/proto/em_planner_config.proto里的默认值但更推荐的做法是在planning.conf里覆盖。Apollo 的配置系统支持从文件加载配置你可以在modules/planning/conf/planning.conf里添加一行--lateral_weight1.5。这样就不需要重新编译改完重启 Planning 模块即可生效。不过这里有个细节planning.conf里的参数名必须和 proto 里的字段名完全一致包括大小写。我见过有人写成--lateralWeight1.5结果配置没生效查了半天才发现是命名风格不匹配。另外修改配置后最好用cyber_monitor看一下/apollo/planning话题的输出确认轨迹确实发生了变化。如果没变化可能是配置没加载成功或者被其他配置覆盖了。3.3 利用 PlanningInternal 进行轨迹分析的完整流程前面提到PlanningInternal是调试利器这里我详细说一下怎么用。首先确保planning.conf里enable_planning_debug为true。然后启动 Apollo让车辆或模拟器跑一段。接着用rosbag record /apollo/planning_internal录制数据。录完后你可以用 Apollo 自带的planning_trajectory_analyzer工具或者自己写 Python 脚本解析。解析时重点关注DP_StGraph里的total_s和total_t它们能告诉你规划器在时空图上的搜索范围。如果total_s太小可能意味着规划器没有充分考虑远距离的障碍物如果total_t太大可能会增加计算负担。我通常会把SpeedPlan里的speed_point画成速度-时间曲线直观地看加速、减速是否平滑。有一次我发现曲线在某个点突然抖动检查后发现是QP_SPEED_OPTIMIZER的max_acceleration设得太大导致求解器在边界附近震荡。把值调小后曲线就平滑了。这个经验告诉我调试规划器不能只看最终轨迹中间过程的数据往往更能说明问题。4. 常见问题与排查技巧实录4.1 Proto 字段解析失败或默认值异常在实际调试中最常见的问题之一是 Proto 字段解析失败或者读出来的值是默认值。这通常有几个原因一是 proto 文件版本不匹配比如你用的代码是旧版但数据是新版序列化的二是字段被optional修饰但发送方没有设置接收方就会拿到默认值三是网络传输过程中数据被截断。排查时可以先检查cyber_monitor里话题的发布频率和消息大小如果消息大小异常小可能是序列化出了问题。另外Apollo 的日志里通常会有protobuf相关的错误信息比如Failed to parse看到这类日志就要警惕。我遇到过一次ADCTrajectory里的trajectory_point数量总是 0。查了半天发现是发送方在填充 proto 时忘记调用add_trajectory_point()而是直接用了mutable_trajectory_point()但没有设置大小。这种错误在 C 里很隐蔽因为编译不会报错。所以在写填充 proto 的代码时一定要仔细检查add_和mutable_的使用场景。4.2 规划器决策与预期不符的排查思路当规划器的决策和你的预期不符时比如该换道时不换道该停车时不停车第一步应该是查看Decisionproto 里的main_decision。如果main_decision是cruise但你认为应该follow那就要检查PredictionObstacles里是否有障碍物被正确识别。有时候障碍物的priority或is_static字段设置不当会导致规划器忽略它。第二步是检查PlanningInternal里的PathPlan和SpeedPlan看看路径和速度曲线是否合理。如果路径规划正常但速度规划异常那问题可能出在QP_SPEED_OPTIMIZER的约束上。我总结了一个简单的排查顺序先看Decision再看PlanningInternal最后看ADCTrajectory。这个顺序能帮你快速缩小问题范围。另外Apollo 提供了一个planning_visualizer工具可以把这些 proto 信息可视化出来比看日志直观得多。如果条件允许我强烈建议用可视化工具辅助排查。4.3 性能问题与 Proto 大小的权衡Planning 模块对实时性要求很高通常要在 100ms 内完成一次规划。如果 Proto 消息太大序列化和反序列化的开销就会增加进而影响整体性能。PlanningInternal虽然有用但它包含大量中间数据如果一直开启会显著增加 CPU 和内存负担。所以我的经验是只在调试阶段开启enable_planning_debug并且尽量缩小录制范围只录关键话题。另外ADCTrajectory里的trajectory_point数量也要控制一般 50-100 个点就足够控制模块使用了太多点不仅浪费带宽还可能引入不必要的抖动。还有一个容易被忽视的点Proto 里的string字段。比如Decision里的reason字段如果填充了很长的字符串也会增加消息大小。在性能敏感的场合可以考虑用枚举代替字符串或者限制字符串长度。这些细节在开发初期可能不明显但到了系统集成阶段往往会成为性能瓶颈。4.4 常见问题速查表问题现象可能原因排查方法解决建议轨迹点数量为 0发送方未正确填充trajectory_point检查add_trajectory_point()调用确保每次规划都添加至少一个点规划器忽略障碍物PredictionObstacles里priority或is_static设置错误查看Decision里的follow或stop决策调整预测模块的优先级逻辑速度曲线抖动QP_SPEED_OPTIMIZER的max_acceleration过大分析PlanningInternal里的SpeedPlan适当降低加速度上限配置不生效planning.conf里参数名与 proto 字段名不匹配对比 proto 文件和配置文件确保命名完全一致包括大小写调试信息缺失enable_planning_debug未开启检查planning.conf调试时设为true上线时关闭这个表是我在实际项目中慢慢积累的每次遇到新问题我都会补充进去。现在它已经成了我排查 Planning 问题的第一手资料。5. 从 Proto 定义看 Planning 模块的扩展与优化5.1 如何安全地扩展 Proto 字段Apollo 的 Planning 模块还在不断演进你很可能需要添加新的字段来支持新功能。比如你想在ADCTrajectory里增加一个confidence字段表示轨迹的置信度。这时候一定要遵循 Protobuf 的兼容性规则新增字段必须用新的字段编号不能复用已删除字段的编号。另外新字段最好是optional或repeated避免用required因为required在跨版本通信时容易出问题。修改完 proto 后记得重新编译并更新所有依赖该 proto 的代码。如果团队里有多个分支最好提前沟通避免冲突。我个人的习惯是在修改 proto 时会在文件头部加一行注释说明修改日期和原因。这样以后回溯时能快速知道这个字段是为什么加的。虽然看起来有点繁琐但在长期维护的项目里这个习惯能省下很多沟通成本。5.2 基于 Proto 的规划器性能调优经验Planning 模块的性能调优很大程度上是在 Proto 配置里调参数。比如DP_POLY_PATH_OPTIMIZER里的sample_points数量直接影响路径搜索的精度和耗时。如果sample_points太少路径可能不够平滑太多计算时间会线性增长。我通常的做法是先在模拟环境里用默认值跑一遍记录耗时和轨迹质量然后逐步增加sample_points观察变化找到一个平衡点后再在实车上验证。这个过程需要耐心但效果通常很显著。另一个关键参数是planning_cycle_time。Apollo 默认是 100ms但在某些复杂场景下规划器可能算不过来。这时候你可以考虑降低规划频率比如改成 150ms给规划器更多时间。但要注意降低频率会影响控制的实时性所以必须配合控制模块的调参。我试过在低速园区场景下把planning_cycle_time调到 200ms车辆依然运行平稳但高速场景下就不行了。所以这个参数一定要结合具体场景来定。5.3 利用 Proto 进行跨模块协同调试Planning 模块不是孤立的它和感知、预测、控制都有紧密的交互。通过 Proto 定义你可以清晰地看到模块间的数据流。比如PredictionObstacles从预测模块传到规划模块规划模块处理后生成ADCTrajectory再传给控制模块。如果车辆行为异常你可以沿着这条数据流逐个模块检查 Proto 消息。我常用的方法是在cyber_monitor里同时打开/apollo/prediction、/apollo/planning和/apollo/control三个话题对比它们的输出。如果预测模块输出的障碍物位置和规划模块使用的障碍物位置不一致那问题就出在数据传递或转换环节。这种跨模块调试方法能帮你快速定位问题是在哪个模块产生的而不是盲目地改代码。我见过很多新手一遇到问题就怀疑规划算法结果查了半天发现是感知模块的误差。所以熟悉 Proto 定义不仅能让你看懂 Planning 模块还能让你对整个自动驾驶系统的数据流有更全面的认识。5.4 一个真实的调试案例换道决策异常最后分享一个我实际遇到的案例。有一次车辆在高速上应该换道超车但规划器一直不执行。我按照前面的排查顺序先看Decision发现main_decision是cruise没有overtake子决策。然后看PlanningInternal里的PathPlan发现路径规划器确实生成了一条换道路径但速度规划器没有跟上。再查QP_SPEED_OPTIMIZER的配置发现max_lateral_acceleration设得太小导致速度规划器认为换道时横向加速度会超限于是拒绝了换道。把max_lateral_acceleration从 1.0 调到 1.5 后换道就正常了。这个案例说明Proto 里的参数不是孤立的它们之间会相互影响。调试时不能只看一个字段要结合多个 Proto 消息一起分析。另外这个案例也提醒我配置参数的默认值不一定适合所有场景必须根据实际道路条件和车辆特性进行调整。每次调整后最好用rosbag录下来反复回放分析确保改动确实解决了问题而不是引入了新的问题。5.5 关于 Proto 定义维护的个人体会在长期维护 Planning 模块的过程中我最大的体会是Proto 定义不仅仅是技术文档它更是团队协作的“共同语言”。当算法工程师、软件工程师和测试工程师都基于同一套 Proto 定义来沟通时很多歧义和误解就会自然消失。所以我建议在项目初期就建立 Proto 定义的评审机制任何修改都要经过团队讨论确保每个人都理解字段的含义和影响。另外定期更新 Proto 定义的注释把每个字段的用途、取值范围、默认值都写清楚这对后来者非常友好。还有一点不要害怕修改 Proto。虽然修改 Proto 可能会带来一些兼容性问题但只要遵循规则这些问题都是可控的。相反如果因为害怕修改而把一些临时逻辑硬编码在代码里后期维护会更痛苦。我在早期项目中就犯过这个错误把一些配置写死在 C 代码里结果每次调整都要重新编译效率极低。后来改成 Proto 配置后调试效率提升了好几倍。所以该用 Proto 的地方就用 Proto这是 Apollo 设计哲学的一部分。