MiniCPM-RobotTrack 源码实战:逐行读懂 modeling_robottrack.py 的完整前向流程

原创2026-10-21 13:40:071,699 阅读

MiniCPM-RobotTrack 源码实战:逐行读懂 modeling_robottrack.py 的完整前向流程

想读懂 MiniCPM-RobotTrack 是怎么"看图说话、直接输出机器人轨迹"的吗?本文带你进入模型核心源码 modeling_robottrack.py,逐步拆解它的完整前向流程(forward):从 DINOv3 + SigLIP 视觉特征输入,到语言指令拼接,再到最后输出 8 个 [x, y, yaw] 航点的每一步。全文不堆代码,只用最关键的几行帮你建立直觉,适合刚接触具身智能和 VLA(Vision-Language-Action)模型的新手。

MiniCPM-RobotTrack 户外避障跟随目标演示

上图:MiniCPM-RobotTrack 在户外场景中避障跟随行人的实际效果,轨迹即由本文讲解的前向流程实时产生

一分钟了解 MiniCPM-RobotTrack 是做什么的

MiniCPM-RobotTrack 是一个紧凑的视觉-语言-动作(VLA)策略模型,基于 MiniCPM4-0.5B 构建,用于具身智能体的目标跟随(比如让机器狗跟随"穿红衣服的人")。它的特点是:

  • 语言条件追踪:自然语言指令 + 融合视觉特征,直接预测未来 8 个 [x, y, yaw] 航点;
  • 端侧高效推理:在 Unitree Go2 机器人板载计算平台上稳定 5+ FPS、约 180 ms 端到端延迟。

MiniCPM-RobotTrack 跟随目标基准测试指标

上图:MiniCPM-RobotTrack 的跟随目标(target tracking)基准测试结果

模型由两部分组成:MiniCPMModel 语言骨干(定义在 modeling_minicpm.py)+ 一组为"输出动作"而生的附加模块。下面进入 modeling_robottrack.py 内部。

先看架构:4 个核心组件各司其职

整个文件可以拆成 4 个关键部分,建议先建立全局印象:

组件 作用 源码位置
VisionProjector 把视觉特征映射到 MiniCPM 的隐藏空间 modeling_robottrack.py#L44-L57
TemporalMarkerEncoder 为每帧生成一个"时间标记" token modeling_robottrack.py#L60-L77
FunnelTrajectoryHead 六层漏斗式 MLP,预测固定航点轨迹 modeling_robottrack.py#L80-L121
MiniCPMRobotTrackModel 总控类,串联完整前向流程 modeling_robottrack.py#L132-L320

组件 1:VisionProjector —— 视觉特征的"翻译官"

相机看到的画面先经过 DINOv3 和 SigLIP 两个视觉编码器,得到 1536 维特征(见 configuration_robottrack.py 中 vision_feature_dim = 1536)。但语言骨干的隐藏维度是另一个数值,不能直接拼接。VisionProjector 就是一个 LayerNorm → 线性层 → GELU → 线性层 的两层 MLP,负责把视觉特征"翻译"到 MiniCPM 空间。

组件 2:TemporalMarkerEncoder —— 给每帧打上"时间戳"

机器人追踪是时序任务:过去 31 帧的画面信息需要模型知道"哪张是哪一刻"。TemporalMarkerEncoder 用三组可学习 Embedding 相加:

  • 时间步嵌入(time_embedding,最多 4096 步)
  • 流嵌入(stream_embedding:0 表示历史流,1 表示当前流)
  • 相机嵌入(camera_embedding,目前只有 1 路相机,为多相机预留)

每帧的视觉 token 前面会插入这样一个"标记 token",相当于告诉模型:"接下来这几个视觉 token 属于第 N 帧"。

组件 3:FunnelTrajectoryHead —— 输出轨迹的"漏斗头"

这是全模型最有辨识度的设计:一个六层逐层变窄的 MLP——

hidden → 4096 → 1024 → 512 → 256 → 128 → 航点数×3

像漏斗一样把信息层层压缩,最后一次性输出 num_waypoints × action_dim(默认 8 × 3 = 24 个数),再 reshape 成 [8, 3] 的航点序列。若 use_tanh_actions=True,输出会先过 tanh 把数值压到 [-1, 1],保证动作幅度有界。

前向流程第一步:_build_sequence 组装输入序列

前向流程的入口是 forward()(modeling_robottrack.py#L263),但它真正做的事大部分委托给了 _build_sequence(modeling_robottrack.py#L214-L258)。这一步把 4 类输入拼成一条序列:

[ 文本指令 token | 历史视觉 token(带时间标记) | 当前帧视觉 token(带时间标记) | 控制查询 ]

具体流程:

  1. 两路视觉投影:历史帧特征(coarse_tokens,每帧 4 个 token)和当前帧特征(fine_tokens,64 个 token)分别过 VisionProjector;
  2. 插入时间标记:_insert_temporal_markers(modeling_robottrack.py#L179-L212)按 time_indices 把同一帧的 token 归组,在每组前面插入该帧的标记 token。这里还做了防御性校验:时间索引越界、批次维度不一致都会直接抛 ValueError;
  3. 文本嵌入:指令经 tokenizer 得到 input_ids,再查表得到文本 embedding;
  4. 控制查询:control_query 是一个单独的可学习向量(初始化为 N(0, 0.02)),expand 到批次维度后拼在序列最末尾;
  5. 对齐 attention_mask:文本部分沿用传入的 mask,视觉和控制查询部分补全 1。

💡 为什么要放"控制查询"? 它是一个可学习的"提问符",放在序列末端让它能看到前面所有的文本、历史和当前视觉信息,最终从它的位置取出"全局决策状态"。

前向流程第二步:MiniCPM 骨干处理整条序列

组装好的 inputs_embeds 直接送入 MiniCPMModel(modeling_robottrack.py#L284-L289)。这里注意两个细节:

  • 传入的是嵌入向量而非 token id,因为序列里混入了视觉和查询 token,无法用词表查表;
  • use_cache=False:一次性处理完整序列,不需要自回归推理的 KV 缓存。

骨干输出的 last_hidden_state 形状为 [B, 序列长度, hidden_size]。

前向流程第三步:取出控制状态并生成轨迹

接下来的三步非常精炼(modeling_robottrack.py#L290-L296):

  1. 取最后一个位置的隐藏状态 output.last_hidden_state[:, -1] —— 恰好是控制查询所在的位置,这就是模型对"我该往哪走"的集中表达;
  2. 送入 FunnelTrajectoryHead,得到归一化空间的轨迹 normalized_trajectory,形状 [B, 8, 3];
  3. 乘回 output_scale:训练和推理时 x、y 方向都除以 xy_scale(默认 2.0)来归一化,让梯度更稳;输出时再乘回来还原到真实尺度(yaw 方向缩放为 1,不受影响)。

这种"归一化训练 + 缩放还原"的套路,是动作回归模型常见的稳定化技巧。

前向流程第四步:训练时的 Loss 计算

forward() 的最后一段(modeling_robottrack.py#L298-L316)只在做训练(传入了 labels)时执行:

  • 预测轨迹和标签先各自归一化,再做逐元素平方误差;
  • 若提供 valid_mask,只对有效航点求平均,无效样本(如演示中断的帧)不计入损失;
  • 最终返回 MiniCPMRobotTrackOutput(modeling_robottrack.py#L124-L129),包含 loss 和 trajectories 两个字段。

模型是怎么"搭起来"的:__init__ 里的关键决定

读完前向流程,再回头看构造函数(modeling_robottrack.py#L143-L171)会更顺:

  • 混合精度设计:骨干默认以 bfloat16 构建(backbone_dtype),而 output_scale 保持 float32,兼顾速度与数值稳定;
  • 继承能力声明:supports_gradient_checkpointing、_supports_flash_attn_2 = True 表明支持显存优化和 FlashAttention-2 加速;
  • 超参数都来自配置:航点数(8)、动作维度(3)、dropout(0.4)等默认值定义在 configuration_robottrack.py#L14-L44,配置类还会做校验——比如强制 action_dim 必须为 3(即 [x, y, yaw] 格式)。

上手体验:一次推理需要传什么

结合 README.md 中的示例,一次前向调用需要 5 组输入:

输入 形状(单样本) 含义
input_ids [1, L] 语言指令的 token 序列
coarse_tokens [31×4, 1536] 过去 31 帧的粗粒度视觉特征
coarse_time_indices [31×4] 每个 token 属于哪一帧
fine_tokens [64, 1536] 当前帧的细粒度视觉特征
fine_time_indices [64] 均为当前帧的索引

输出是 <a href="https://link.gitcode.com/i/f14ed9a2ebfa11b349b87d24748ae7dc" target="_blank">1, 8, 3] 的轨迹张量——机器人据此连续执行 8 步移动。环境要求 transformers>=4.56,<5,依赖见 [requirements.txt。

小结:一条序列看懂整个 VLA 模型

回顾这次逐行之旅,MiniCPM-RobotTrack 的前向流程其实就是一条清晰的流水线:

视觉双路投影 → 时间标记插入 → 与语言指令拼接 → 控制查询收尾 → MiniCPM 骨干编码 → 漏斗头解码出 8 个航点

它没有用任何花哨的自回归动作生成,而是"一个可学习查询 + 一个回归头"直接输出轨迹,这正是它能在机器人板载算力上跑通 5+ FPS 的关键。想继续深入,可以顺着 modeling_minicpm.py 看骨干的注意力实现,或从 config.json 核对实际部署时的全部超参数。

掌握这套"视觉 token 与语言 token 同序列"的设计模式后,你再去看其他 VLA 模型源码,会发现大同小异——恭喜,你已经迈进了具身智能的大门 🤖

登录后查看全文
MiniCPM-RobotTrack