3. 感知软件版本命名与标识体系

在EyeQ平台的感知软件OTA体系中，版本命名与标识不是简单的字符串约定，而是一套贯穿开发、集成、测试、发布、部署与回滚全过程的“身份系统”。它要回答四个核心问题：这份软件是什么、它依赖什么、它适配什么、它从哪里来。如果标识体系设计不当，OTA升级就可能出现“版本号相同但内容不同”“标定数据与模型不匹配”“硬件适配错误导致感知降级”等严重问题。因此，本节从版本号规则、构建号、配置标识、标定数据标识、硬件适配标识五个维度展开，并给出可追溯性设计的落地方法。

一、版本号规则：语义化版本与平台扩展

EyeQ感知软件推荐采用“语义化版本+平台后缀”的复合结构。基础格式为：

MAJOR.MINOR.PATCH[-STAGE][+BUILD][_PLATFORM]

其中，MAJOR表示不兼容的架构级变更，例如感知网络从CNN切换为Transformer、输出接口协议发生破坏性修改；MINOR表示向后兼容的功能新增，例如新增一类目标检测、增加一个感知输出通道；PATCH表示向后兼容的问题修复，例如误检率优化、后处理参数微调。STAGE为可选阶段标识，如alpha、beta、rc；BUILD为构建号；PLATFORM为硬件适配标识，如eq4、eq5、eq6。

示例：2.4.1-rc+20250312_eq5表示主版本2、次版本4、补丁1、候选发布阶段、构建于2025年3月12日、适配EyeQ5平台。需要强调的是，版本号一旦发布到OTA通道，就不允许复用。即使只修改了一个标定参数，也必须递增PATCH或构建号，否则车端无法区分新旧包。

二、构建号：唯一性与可追溯的锚点

构建号是版本标识体系中最细粒度的唯一标识。它通常由CI流水线自动生成，推荐格式为“日期+流水线序号+短哈希”，例如20250312.7.a3f9c2。构建号必须满足三个条件：全局唯一、单调递增、与源码提交记录一一对应。在EyeQ感知软件中，构建号还应绑定编译工具链版本、依赖库版本和模型文件哈希，形成构建元数据。

实际落地时，可在构建产物中嵌入一个build_manifest.json，记录构建号、Git commit、模型哈希、标定文件哈希、编译器版本、目标硬件平台。车端OTA客户端在安装前读取该清单，与云端下发的期望值比对，任何一项不匹配即拒绝安装。这样，构建号就从“一个数字”升级为“可验证的追溯锚点”。

三、配置标识：区分功能组合与运行模式

同一份感知二进制，在不同车型或不同功能配置下可能启用不同的感知子模块。配置标识用于描述“这份软件在运行时启用了哪些功能组合”。推荐采用“配置名+版本”的方式，例如cfg_highway_v3、cfg_urban_v2。配置标识应独立于软件版本号，因为同一软件版本可以搭配不同配置发布。

配置标识的内容通常包括：感知目标类别集合、输出频率、融合策略、后处理阈值组、是否启用特定模型分支。在OTA包中，配置标识以独立文件形式存在，并与软件版本号建立映射关系。车端启动时，根据配置标识加载对应参数，避免将城市配置误用于高速场景。

四、标定数据标识：感知精度的隐形基石

感知软件的输出精度高度依赖相机标定、雷达标定、激光雷达外参等标定数据。标定数据标识必须与软件版本、硬件配置、车辆VIN或产线批次绑定。推荐格式为：

CAL_<类型>_<日期>_<批次>_<校验短码>

例如CAL_CAM_FRONT_20250310_LOT_A7_9f2e。标定数据标识的核心作用是防止“软件升级后标定数据未同步更新”或“不同车辆误用同一标定文件”。在OTA流程中，标定数据可以作为独立包升级，也可以与感知软件包捆绑，但无论哪种方式，都必须在校验阶段验证标定标识与当前车辆硬件配置的匹配性。

五、硬件适配标识：平台、传感器与算力约束

EyeQ系列芯片存在多个代际，不同代际的算力、内存、指令集和加速器能力不同。硬件适配标识用于声明“这份感知软件可以在哪些硬件组合上运行”。它至少应包含：EyeQ芯片型号、传感器套件版本、内存配置等级。例如：

HW_EQ5_SENSOR_V3_MEM_8G

当OTA服务器向车端推送升级包时，车端首先上报自己的硬件适配标识，服务器只下发匹配的包。若车端硬件标识不在支持列表中，升级应被阻止并记录原因。这一机制可以避免“小算力平台误装大模型包”导致的感知失效或系统崩溃。

六、可追溯性设计：从标识到日志的闭环

上述五类标识只有被记录、被校验、被关联，才真正具备可追溯性。可追溯性设计应覆盖三个层面：

• 构建追溯：每个构建号对应唯一的源码提交、模型文件、标定文件和工具链版本，存储在制品库中，保留至少两年。
• 发布追溯：每次OTA发布记录版本号、构建号、配置标识、标定标识、硬件适配标识、目标车辆范围、发布时间和操作人。
• 车端追溯：车端在安装、启动、运行和回滚时，将当前生效的完整标识组合写入本地日志，并可按需上传云端。当出现感知异常时，通过VIN即可反查该车在特定时间段内运行的软件版本、配置和标定数据。

七、常见错误与规避策略

在实际项目中，版本标识体系最容易出现三类问题。第一，版本号复用：修复了一个标定参数但未递增PATCH，导致车端认为“已是最新”而跳过升级。规避方法是强制CI流水线在每次构建时自动递增构建号，并禁止人工填写版本号。第二，标定与软件脱钩：软件升级后标定文件未同步，导致感知输出偏移。规避方法是将标定标识写入软件包的依赖清单，安装时强制校验。第三，硬件适配标识粒度过粗：只写“EQ5”而未区分传感器套件版本，导致不同传感器配置的车辆误装同一包。规避方法是细化到“芯片+传感器套件+内存等级”三元组。

总结来说，EyeQ感知软件的版本命名与标识体系，本质上是一套“身份+依赖+边界”的契约。版本号定义语义，构建号定义唯一性，配置标识定义功能组合，标定数据标识定义精度来源，硬件适配标识定义运行边界。五者协同，再配合构建清单、签名校验和车端日志，才能形成完整的可追溯闭环，为OTA升级的安全性和可运维性提供基础保障。