c22222h/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:

文件	说明
adapter_model.safetensors (9.8MB)	LoRA r=32 低秩增量(仅此为"学到的权重")
adapter_config.json	LoRA 配置:r=32, alpha=8, peft_type=LORA
config.json	PI05 策略配置(维度/推理步数等)
policy_preprocessor.json	输入预处理流水线配置
policy_preprocessor_step_2_normalizer_processor.safetensors	该场景的归一化统计(分位数,训练时从数据算)
policy_postprocessor.json	输出后处理流水线配置
policy_postprocessor_step_0_unnormalizer_processor.safetensors	反归一化统计(动作还原成真实关节值)
train_config.json	完整训练配置(可复现)
README.md	PEFT 自动生成的 model card

不含 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 个):

目录	step	epoch
scene1/epoch1	6676	1.0
scene1/epoch2	13352	2.0
scene1/epoch3	20028	3.0
scene1/epoch4	26704	4.0
scene1/final	30000	4.5(最终)

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

目录	step	epoch
scene2/epoch1	2498	1.0
scene2/epoch2	4996	2.0
scene2/epoch3	7494	3.0
scene2/epoch4	9992	4.0
scene2/epoch5	12490	5.0
scene2/epoch6	14988	6.0
scene2/epoch7	17486	7.0
scene2/epoch8	19984	8.0
scene2/epoch9	22482	9.0
scene2/epoch10	24980	10.0
scene2/epoch11	27478	11.0
scene2/epoch12	29976	12.0(≈final)
scene2/final	30000	12.0(最终)

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