拿到 LingBot-VLA 2.0 想先跑通一条样本，最容易踩的坑通常不是模型结构，而是输入输出定义没对齐：图像分辨率、视角数量、语言指令长度、动作维度和动作时间跨度，任意一项和配置声明不一致，一般会在数据加载或前向阶段直接报形状错误，也可能在归一化环节悄悄把数值尺度搞错。建议的顺序是先读配置里的输入输出声明，再打印一条真实样本的张量形状做对照，接着用单帧前向确认模型能吐出一个动作预测，确认完再考虑改模型或写训练脚本。

想快速试跑 LingBot-VLA 2.0，先别动模型结构和权重，把图像、语言、动作三路的输入输出契约对齐再谈训练。通常按「配置文件声明 → 单条样本张量形状 → 动作取值范围与单位 → 单帧前向」四步走，每一步都能用日志或报错验证。边界是：本页只覆盖数据格式对齐，不涉及训练策略与收敛性判断；具体字段名和维度请以你本地仓库版本为准。

在官方仓库的配置文件中定位输入输出声明

具身智能基座模型仓库一般会把输入输出契约写在配置文件或模型类的默认参数里，LingBot-VLA 2.0 通常也遵循这个习惯。先在仓库里找 config.yaml、config.json、configs/*.py、model_config.py 这类文件；不确定命名时，直接按关键词全域搜索，这是最省事的定位方式。

grep -rnE 'action_dim|state_dim|image_size|resolution|num_views|chunk_size|action_horizon|max_seq_len|max_text_len' `--include`='*.py' `--include`='*.yaml' `--include`='*.json' .

如果配置是 dataclass 或普通类，也可以实例化后把字段全部打印出来，比逐个翻文件快：

from lingbot.configuration_lingbot import LingBotVLAConfig  # 导入路径按仓库实际结构调整

cfg = LingBotVLAConfig()
for k, v in vars(cfg).items():
    print(k, '=', v)

需要确认的字段大致分三类：图像侧的分辨率、通道数、视角数量、是否含时序帧、是否内置归一化；语言侧的最大 token 长度、tokenizer 路径、是否要求 attention mask；动作侧的 action_dim、action_horizon（一次预测多少步）、state_dim、以及归一化配置是否存在。字段命名在不同版本里会有差异，action_dim 也可能写成 action_size 或 act_dim，以你本地代码为准。

用一条样本数据打印各模态张量形状

配置声明说明的是「模型期望什么」，还要用一条真实样本验证「数据加载器给了什么」。建议先把 batch_size 设为 1，从 dataloader 里取一个 batch，把所有字段的形状、类型和数值范围打出来。

import torch

loader = build_dataloader(...)   # 换成仓库里的 dataloader 构造入口
batch = next(iter(loader))

def describe(name, x):
    if torch.is_tensor(x):
        print(f'{name}: shape={tuple(x.shape)} dtype={x.dtype} '
              f'min={x.min().item():.4f} max={x.max().item():.4f}')
    elif isinstance(x, (list, tuple)):
        head = tuple(x[0].shape) if len(x) and torch.is_tensor(x[0]) else type(x[0])
        print(f'{name}: len={len(x)} first={head}')
    else:
        print(f'{name}: type={type(x)} value={x}')

for k, v in batch.items():
    describe(k, v)

对比方法很直接：图像张量的通道维、高宽和视角维是否等于配置声明；语言 token 的第二维是否小于等于 max_text_len；动作张量的最后一维是否等于 action_dim，倒数第二维是否等于 action_horizon。常见的偏差有几类：分辨率被 resize 成与配置不同的值；视角数少一个（部分数据集把腕部相机放在单独的 key 里）；动作的时间跨度比模型要求少一步或多一步。发现不一致时，建议先改数据侧配置或 collate 函数，不要急着改模型结构。

检查动作归一化范围与数据集标注单位

形状对上了不等于数值对得上。动作归一化是最容易埋雷的地方：数据集里的动作可能是弧度，模型期望的是归一化后的值；也可能是绝对关节角，而模型按相对增量训练。先看数据集元数据里有没有现成统计量，常见字段名是 q01/q99、mean/std、min/max、action_mean、action_std；没有就自己统计一遍。

# 读取数据集元数据里已有的统计量（路径和字段名按实际数据集调整）
import json
meta = json.load(open('meta/stats.json'))
for k, v in meta.items():
    print(k, v)

# 没有现成统计量时自己算，务必排除 padding 帧和无效动作
import numpy as np
acts = np.concatenate([ep['action'] for ep in dataset.episodes], axis=0)
mask = np.concatenate([ep['action_valid'] for ep in dataset.episodes], axis=0)
acts = acts[mask.astype(bool)]
print('mean', acts.mean(0))
print('std', acts.std(0))
print('min', acts.min(0))
print('max', acts.max(0))
print('q01', np.quantile(acts, 0.01, axis=0))
print('q99', np.quantile(acts, 0.99, axis=0))

拿到统计量后与配置里的归一化方式对照：如果是 min-max 映射到 [-1, 1]，就必须用数据集实际 min/max 做换算；如果是分位数归一化，要看 q01/q99 是否被裁剪；如果模型侧已经内置标准化层，数据侧通常不应该再归一化一次。同时确认单位是弧度还是角度、米还是厘米、关节位置还是速度。这类不一致不会立刻报错，但容易让训练损失看似在降而动作尺度明显偏离，需要结合具体机器人本体确认合理区间。

模拟一次前向传播，只跑单帧不训练

形状和数值都确认后，用单帧前向做一次最小验证：不建优化器、不算损失、不反向传播，只看模型能否接受这条样本并输出动作预测。batch size 设成 1，时间长度设成模型允许的最短值，如果模型要求固定帧数，就先补齐再送进去。

import torch

model = build_model(cfg)          # 仓库里的模型构造入口
model.eval()                      # 评估模式，避免 dropout 与 norm 统计干扰

single = {k: (v[:1] if torch.is_tensor(v) else v) for k, v in batch.items()}

with torch.no_grad():
    out = model(single)           # 有的仓库用 model.forward(...) 或 model.predict_action(...)

print(type(out))
if torch.is_tensor(out):
    print('action shape:', tuple(out.shape))
elif isinstance(out, dict):
    for k, v in out.items():
        print(k, tuple(v.shape) if torch.is_tensor(v) else type(v))

观察三件事：输出是否为动作张量，或能否从字典里取出动作字段；最后一维是否等于 action_dim、倒数第二维是否等于 action_horizon；输出值是否落在动作的合理范围内。这一步报形状错误，说明前面的字段还有一列没对齐；如果报显存不足，可以临时把分辨率和视角数调小，只做连通性验证，但不要用这个结果判断模型的真实可用性。单帧跑通只说明接口对齐，不代表训练一定收敛。

记录对齐后的数据格式，形成团队检查清单

把确认过的字段固定成一份清单，写进仓库文档或 PR 描述里。换数据集、换机器人本体或升级仓库版本时，先按清单逐项核对，比重新排查一遍省事。清单里建议同时记下验证脚本路径和当时的仓库 commit，方便下次出现不一致时定位是哪一侧变了。

这份清单只覆盖格式对齐。训练超参、数据规模、评测方式属于另一类问题，建议分开记录，免得后面排查时把格式问题和策略问题混在一起看。