Pi05_Lora

Pi05 LoRA Adapters (Kuavo-5, Leju Challenge)

LoRA 微调适配器,基于 π0.5 (PI05) 策略,在 Kuavo-5 机器人上训练。按任务(scene1/scene2)→ epoch 组织。

重要:本仓库只含 LoRA adapter,不含基座与 tokenizer。 加载前需自备 pi05_base 基座 + PaliGemma tokenizer(见下)。

仓库结构

Pi05_Lora/
├── README.md                       ← 本文件
├── scene1/                         ← 任务1(通用,203 episodes / 427274 frames)
│   ├── epoch1/   (step 6676)
│   ├── epoch2/   (step 13352)
│   ├── epoch3/   (step 20028)
│   ├── epoch4/   (step 26704)
│   └── final/    (step 30000,4.5 epoch 最终)
└── scene2/                         ← 任务2(分拣,201 episodes / 159884 frames)
    ├── epoch1/   (step 2498)
    ├── epoch2/   (step 4996)
    ├── ...
    ├── epoch12/  (step 29976)      ← 与 final 仅差 24 步,近似相同
    └── final/    (step 30000)

每个 epoch 目录的内容

即训练 checkpoint 的 pretrained_model/,~10MB:

不含 training_state/(optimizer/scheduler/rng,仅断点续训用,评测不需要)。

⚠️ 加载前必须改的 3 个绝对路径

这些 JSON 里写死了训练机的本地路径,换机器必须改成你自己的:

1. adapter_config.json → base_model_name_or_path
2. config.json → pretrained_path
3. policy_preprocessor.json → tokenizer_name

指向你本地的 pi05_base 目录 和 PaliGemma tokenizer 目录。

依赖(本仓库不包含)

• pi05_base 基座(14.4GB,model.safetensors + config.json + processor)—— LejuRobotics / Physical Intelligence π0.5 预训练权重。adapter 加载时会叠加到它上面。
• PaliGemma tokenizer(google/paligemma-3b-pt-224,gated)—— 6 个分词文件。gated 模型需 HF 授权后下载。

加载代码(LeRobot / LeTools-Learning 框架)

from lerobot.policies.pi05.modeling_pi05 import PI05Policy
from peft import PeftModel

BASE = "/path/to/pi05_base"          # 你的基座目录
ADAPTER = "/path/to/scene1/final"    # 解压出的某 epoch 目录
TOK = "/path/to/paligemma_tok"       # 你的 tokenizer 目录

# 1. 改 3 个路径(或加载后覆盖)
#    - $ADAPTER/adapter_config.json  -> base_model_name_or_path = BASE
#    - $ADAPTER/config.json          -> pretrained_path = BASE
#    - $ADAPTER/policy_preprocessor.json -> tokenizer_name = TOK

# 2. 建基座 + 载入基座权重
policy = PI05Policy.from_pretrained(BASE)

# 3. 叠加 LoRA adapter
policy = PeftModel.from_pretrained(policy, ADAPTER)

# 4.(可选)把 adapter 烘焙进基座,导出自包含模型
# merged = policy.merge_and_unload()

关键:推理必须用 adapter 目录里的 normalizer/unnormalizer 统计量(分位数,从该场景训练数据算),不能用基座的。否则动作无法正确归一化/反归一化 → 输出垃圾动作。

训练配置(两场景一致)

• 模型:π0.5(PI05)= PaliGemma 2B VLM + gemma_300m 动作专家
• 微调:LoRA r=32, alpha=8,PEFT 0.19.1
• LoRA 作用模块:动作专家 attention(q/v proj)+ state/action 投影头;视觉塔冻结
• 训练:30k 步,effective batch=64(8 GPU × 8),bf16,torch.compile(max-autotune)
• 优化器:AdamW lr=2.5e-4,warmup 1000 步,cosine 衰减 30000 步到 2.5e-5
• 归一化:STATE/ACTION=QUANTILES,VISUAL=IDENTITY
• chunk_size=50,n_action_steps=50,num_inference_steps=10
• 输入:3 路 480×848 视频(head_cam_h, wrist_cam_l/r)→ 缩放到 224×224

Epoch → Step 对照

scene1(1 epoch = 6676 步,共跑 4.5 epoch,存 5 个):

scene2(1 epoch = 2498 步,共跑 ~12 epoch,存 13 个):

scene2 数据量小(16 万帧),12 epoch 偏多,可能后期过拟合。评测建议也试中期 ckpt(epoch 4-6,step ~10000-15000),未必要用 final。