MiniCPM-RobotTrack 源码实战:逐行读懂 modeling_robottrack.py 的完整前向流程
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 是一个紧凑的视觉-语言-动作(VLA)策略模型,基于 MiniCPM4-0.5B 构建,用于具身智能体的目标跟随(比如让机器狗跟随"穿红衣服的人")。它的特点是:
- 语言条件追踪:自然语言指令 + 融合视觉特征,直接预测未来 8 个
[x, y, yaw]航点; - 端侧高效推理:在 Unitree Go2 机器人板载计算平台上稳定 5+ FPS、约 180 ms 端到端延迟。
上图: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(带时间标记) | 控制查询 ]
具体流程:
- 两路视觉投影:历史帧特征(
coarse_tokens,每帧 4 个 token)和当前帧特征(fine_tokens,64 个 token)分别过VisionProjector; - 插入时间标记:
_insert_temporal_markers(modeling_robottrack.py#L179-L212)按time_indices把同一帧的 token 归组,在每组前面插入该帧的标记 token。这里还做了防御性校验:时间索引越界、批次维度不一致都会直接抛ValueError; - 文本嵌入:指令经 tokenizer 得到
input_ids,再查表得到文本 embedding; - 控制查询:
control_query是一个单独的可学习向量(初始化为N(0, 0.02)),expand 到批次维度后拼在序列最末尾; - 对齐 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):
- 取最后一个位置的隐藏状态
output.last_hidden_state[:, -1]—— 恰好是控制查询所在的位置,这就是模型对"我该往哪走"的集中表达; - 送入
FunnelTrajectoryHead,得到归一化空间的轨迹normalized_trajectory,形状[B, 8, 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 模型源码,会发现大同小异——恭喜,你已经迈进了具身智能的大门 🤖

