如何5分钟跑通FLUX 3 Action SO-101:面向新手的LeRobot推理完整指南

原创2026-10-18 21:21:321,423 阅读

如何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 记住三件事:

  1. 相机顺序固定:observation.images.scene 在前、observation.images.wrist 在后,以 side_by_side(并排)拼接成 256×512 画布
  2. 动作是"增量"表示(action_representation: delta):前 5 维关节是相对位移,第 6 维夹爪是绝对值(delta_absolute_dims: [-1])
  3. 归一化状态是必需的:前/后处理依赖仓库内的 .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 机械臂任务了。祝你跑通顺利!🚀

登录后查看全文