如何5分钟跑通FLUX 3 Action SO-101:面向新手的LeRobot推理完整指南
如何5分钟跑通FLUX 3 Action SO-101:面向新手的LeRobot推理完整指南
🤖 FLUX 3 Action SO-101 是 Black Forest Labs 开源的 7B 参数世界动作模型(World Action Model),专为 SO-101 机械臂打造:输入摄像头画面、机器人状态和一段文字指令,即可输出下一步动作序列。本指南带你用 LeRobot 框架在 5 分钟内完成模型下载与策略加载,跑通第一次推理,并看懂它背后的观测-动作契约与 LoRA 微调玩法。
🧭 它到底能做什么?
与"看图说话"的视觉模型不同,FLUX 3 Action 是边想象边行动的机器人策略模型:
- 输入:双摄像头画面(场景相机 + 腕部相机)+ 6 维机器人状态 + 文本指令
- 输出:未来 42 步动作,与"预测的下一帧画面"联合去噪生成
- 执行:取前 32 步以 30 Hz 执行,再重新规划(replan)
核心推理参数在 config.json 中完整定义:
| 参数 | 值 | 含义 |
|---|---|---|
n_obs_steps |
8 | 使用 8 步观测历史 |
history_snapshots |
2 | 2 个视觉快照 |
chunk_size / n_action_steps |
42 / 32 | 预测 42 步、执行 32 步 |
fps |
30 | 控制频率 |
sampler / num_inference_steps |
euler / 4 | 仅 4 步采样,推理很快 |
dtype |
bfloat16 | BF16 精度 |
📌 想直观感受效果?仓库自带演示视频:assets/flux-3-action-demo.mp4
📂 仓库文件速览:每个文件都是干什么的
| 文件 | 作用 |
|---|---|
| README.md | 模型卡:用法、观测契约、微调命令、许可条款 |
| config.json | 策略完整配置(摄像头布局、采样器、动作表示等) |
| model.safetensors | SO-101 策略权重(不含编码器,编码器自动从 base 仓库加载) |
| dataset_statistics.json | 训练数据的归一化统计量(q01/q99) |
| policy_preprocessor.json | 输入前处理流水线(批处理、设备搬运、历史归一化、相机拼接) |
| policy_postprocessor.json | 输出后处理(动作反归一化、搬回 CPU) |
| lora.json | 现成的 LoRA 微调配方 |
| LICENSE.md | FLUX Kommunity License v1.0 许可条款 |
💡 本仓库不包含重复的文本编码器与视频 VAE 权重,推理时会按
config.json中固定的 revision 自动从 base 仓库flux-3-action-base拉取,省去了大量磁盘空间。
⚡ 5 分钟上手:从零到加载策略
第 1 步:准备环境
你需要一台带 NVIDIA GPU 的机器(config.json 指定 device: cuda)和 LeRobot 的 FLUX3 集成环境:
pip install lerobot
第 2 步:下载模型文件
git clone https://gitcode.com/hf_mirrors/black-forest-labs/flux-3-action-so101
第 3 步:加载策略与前/后处理器
整个推理入口只需几行 Python(摘自 README.md):
from lerobot.policies.flux3 import Flux3Policy
from lerobot.policies.factory import make_pre_post_processors
repo_id = "black-forest-labs/flux-3-action-so101"
policy = Flux3Policy.from_pretrained(repo_id)
preprocessor, postprocessor = make_pre_post_processors(policy.config, pretrained_path=repo_id)
加载完成后,推理循环就是:采集观测 → preprocessor 归一化 → policy 去噪生成动作 → postprocessor 还原为关节目标 → 下发执行。
🔍 看懂"观测-动作契约",避坑关键
新手最容易踩的坑就是数据格式对不上。对照 config.json 记住三件事:
- 相机顺序固定:
observation.images.scene在前、observation.images.wrist在后,以side_by_side(并排)拼接成 256×512 画布 - 动作是"增量"表示(
action_representation: delta):前 5 维关节是相对位移,第 6 维夹爪是绝对值(delta_absolute_dims: [-1]) - 归一化状态是必需的:前/后处理依赖仓库内的
.safetensors状态文件(如 policy_postprocessor_step_0_flux3_action_history_unnormalizer.safetensors),与 JSON 配置必须成对使用,不能混用
采样细节(4 步 Euler、shift 6.93、guidance 3、seed 42)也已固化在配置里,开箱即用。
🎯 进阶:用 LoRA 适配你自己的任务
想让它执行你的指令?仓库提供了现成配方 lora.json:
hf download black-forest-labs/flux-3-action-so101 lora.json --local-dir models/so101
lerobot-train --config_path=models/so101/lora.json \
--policy.path=black-forest-labs/flux-3-action-so101 \
--dataset.repo_id=YOUR_DATASET --output_dir=outputs/so101-lora --job_name=so101-lora
该配方继承本检查点的机器人与模型设置,训练 rank-32 LoRA,采用 bf16 混合精度、batch size 2、梯度累积 4、10000 步——对新手来说,只需把 YOUR_DATASET 换成你自己的数据集 ID 即可。
⚠️ 安全须知(必读)
- 模型只输出关节目标值,不限制关节速度、力或工作空间,应用层必须自行限速限力,并保持硬件急停可用
- 上真机前,请先在仿真环境或开启安全限位的情况下验证
- 许可条款见 LICENSE.md(FLUX Kommunity License v1.0),注意其中的使用范围限制
✅ 小结
- FLUX 3 Action SO-101 = 7B 开源世界动作模型 + SO-101 专用策略,LeRobot 原生支持
- 5 分钟跑通三件套:装 LeRobot → clone 仓库 →
from_pretrained加载 - 记住契约:双相机并排、delta 动作 + 绝对夹爪、42 步预测 / 32 步执行
- 适配新任务就用现成的 lora.json 配方微调
按照这份 LeRobot 推理指南,你已可以开始调试自己的 SO-101 机械臂任务了。祝你跑通顺利!🚀