# FLUX 3 Action

FLUX 3 Action dự đoán hành động của robot từ quan sát camera, trạng thái và chỉ thị nhiệm vụ. Một Video VAE và text encoder được đóng băng (frozen) cung cấp đầu vào cho một diffusion transformer, dự đoán video latents và các khối hành động (action chunks); chỉ có hành động được trả về khi suy luận (inference). LeRobot hỗ trợ suy luận và PEFT: LoRA điều chỉnh phần thân (trunk) trong khi các đầu ra hành động (action heads) và điều kiện (conditioning heads) của robot được huấn luyện đầy đủ.

Chúng tôi phát hành `flux-3-action-base` dưới dạng mô hình hành động cơ bản, kèm theo các bản tinh chỉnh cho robot SO-101 `flux-3-action-so101` và robot Franka Panda `flux-3-action-droid` (được tinh chỉnh trên bộ dữ liệu DROID). Ví dụ trung tâm ở đây là việc thích ứng tác vụ thông qua LoRA dựa trên mô hình `flux-3-action-so101`.

Để huấn luyện một robot mới từ mô hình cơ sở hoặc tinh chỉnh toàn bộ, hãy sử dụng kho lưu trữ [flux-action](https://github.com/black-forest-labs/flux-action) độc lập của chúng tôi.

## Cài đặt

Video VAE yêu cầu **NATTEN** 0.21.6 hoặc mới hơn, dưới dạng wheel được xây dựng cho đúng phiên bản torch và CUDA của bạn, từ https://whl.natten.org. NATTEN phát hành wheel cho torch 2.10 đến 2.13, nhưng chưa có cho torch 2.15 mà LeRobot cài đặt mặc định, vì vậy hãy cài đặt một phiên bản torch được hỗ trợ trước. Ví dụ, từ thư mục checkout của LeRobot, hãy cài torch 2.13 với CUDA 13.0 cùng với các phụ thuộc cho training, policy, PEFT và EMA. Như trong [hướng dẫn cài đặt](./installation#pytorch-cuda-variant-linux-only), TorchCodec được lấy từ chỉ mục CPU:

```bash
pip install --index-url https://download.pytorch.org/whl/cu130 \
    'torch==2.13.0+cu130' 'torchvision==0.28.0+cu130' 'numpy>=2.0,<2.3'
pip install --index-url https://download.pytorch.org/whl/cpu 'torchcodec==0.13.0+cpu'
pip install -e ".[training,flux3,peft,diffusion]" \
    'torch==2.13.0+cu130' 'torchvision==0.28.0+cu130' 'torchcodec==0.13.0+cpu'
pip install 'natten==0.21.7+torch2130cu130' --find-links https://whl.natten.org
```

Đối với trình điều khiển NVIDIA cũ hơn 580.65, hãy sử dụng bản dựng CUDA 12.6 thay thế: chỉ số `cu126`, các thẻ torch và torchvision `+cu126`, và `natten==0.21.7+torch2130cu126`. Đối với phiên bản torch khác, hãy sử dụng bánh xe NATTEN có thẻ khớp với phiên bản đó, chẳng hạn như `natten==0.21.6+torch2110cu130` cho torch 2.11 với CUDA 13.0.

## Chỉnh sửa tác vụ SO-101

Sử dụng bộ dữ liệu LeRobot v3 ở **30 Hz**, với sáu kênh hành động tuyệt đối được chỉ định và sáu kênh trạng thái đo được, có thứ tự khớp và đơn vị tương ứng. Kẹp gắp nằm ở cuối. Cung cấp các giá trị thô, hiệu chuẩn robot nhất quán và các hướng dẫn trong `task`.

### Camera

Tên, số lượng và bố cục của camera có thể cấu hình được. Gói SO-101 đặt tên cho hai camera của nó theo những gì chúng hiển thị:

| Camera | Khóa                        |
| ------ | -------------------------- |
| Cảnh  | `observation.images.scene` |
| Cổ tay  | `observation.images.wrist` |

![SO-101 scene camera (left) and wrist camera (right), showing the blue box and container](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/so101_camera_tiling.png)

Bạn có thể sử dụng `--rename_map` để ánh xạ tên camera sang các khóa mong đợi, ví dụ:

```bash
--rename_map='{"observation.images.top":"observation.images.scene","observation.images.gripper_cam":"observation.images.wrist"}'
```

Sử dụng cùng một ánh xạ cho rollout; các khóa khớp nhau không cần ánh xạ. Xem [ánh xạ đổi tên](https://huggingface.co/docs/lerobot/main/en/rename_map).

### Tải và huấn luyện

Tải chính sách SO-101 từ [`black-forest-labs/flux-3-action-so101`](https://huggingface.co/black-forest-labs/flux-3-action-so101). Cấu hình đã lưu sẽ tự động tải VAE và text encoder dùng chung từ một revision cố định của `black-forest-labs/flux-3-action-base`. Nếu quyền truy cập bị hạn chế, hãy xác thực bằng `hf auth login` với một tài khoản có quyền truy cập. Chạy từ thư mục checkout của LeRobot:

```bash
lerobot-train \
  --config_path=examples/flux3/lora.json \
  --policy.path=black-forest-labs/flux-3-action-so101 --policy.device=cuda \
  --dataset.repo_id=YOUR_ORG/YOUR_SO101_DATASET \
  --output_dir=outputs/so101_lora
```

Bộ nhớ đệm của Hub lưu giữ mô hình đã tải xuống và các bộ mã hóa dùng chung để tiếp tục và suy luận adapter.

Checkpoint SO-101-finetuned được ghim sử dụng các khóa camera `scene` / `wrist`, tám bước thời gian quan sát, hai ảnh chụp thị giác được mã hóa độc lập và điều kiện hóa bằng hành động/trạng thái trong quá khứ. Nó dự đoán 42 hành động, thực thi 32 hành động đầu tiên ở 30 Hz, sau đó lập kế hoạch lại. Các bộ xử lý được lưu kèm theo checkpoint này mang theo các thống kê chuẩn hóa tương ứng của mô hình cơ sở. Các cài đặt checkpoint này được giữ nguyên trong quá trình thích ứng tác vụ. File `examples/flux3/lora.json` dùng chung chỉ cung cấp các cài đặt huấn luyện/vận hành và ngân sách huấn luyện; cùng file này được đóng gói dưới tên `lora.json` trong mỗi gói Hub. Bố cục camera, điều kiện hóa, biểu diễn hành động và cài đặt loss được lấy từ checkpoint. Các lệnh này giữ nguyên độ dài thực thi đã lưu là 32, guidance 3/3 và chế độ thực thi eager. Để dùng guidance 4/1 và biên dịch, hãy thêm `--policy.guidance_scale=4 --policy.guidance_scale_action=1 --policy.compile_model=true`.

> **Các thí nghiệm điều kiện:** LeRobot cung cấp `n_obs_steps`, `history_snapshots` và `condition_on_past_actions`. Việc thay đổi chúng đòi hỏi các cài đặt model/processor tương thích và quá trình fine-tuning; hãy giữ nguyên các giá trị đã lưu trong checkpoint cho việc thích ứng tác vụ thông thường.

Cài đặt có sẵn kích hoạt LoRA rank/alpha 32 và EMA với decay 0.999; không có gì được tải lên tự động. Hãy bật các adapter mới thông qua các cài đặt `peft` cấp cao nhất, không phải `--policy.use_peft=true`, vốn dùng để xác định một adapter đã lưu.

Trong các thí nghiệm của chúng tôi, EMA mang lại lợi ích đáng kể trên DROID, trong khi kết quả trên SO-101 vẫn còn lẫn lộn cho đến nay. Lợi ích của nó phụ thuộc vào dữ liệu và cấu hình huấn luyện. Chúng tôi khuyến nghị giữ EMA ở trạng thái bật và đánh giá cả checkpoint thô lẫn checkpoint EMA dưới cùng một giao thức rollout trước khi chọn phiên bản để triển khai. Mất xác thực ngoại tuyến định kỳ sử dụng trọng số thô; nó không tự động so sánh cả hai biến thể.

Bắt đầu với ngân sách GPU đơn để lặp lại nhanh. Đối với ngân sách huấn luyện lớn hơn, hãy sử dụng cùng cấu hình với các ghi đè sau:

```bash
accelerate launch --num_processes=4 --multi_gpu -m lerobot.scripts.lerobot_train \
  --config_path=examples/flux3/lora.json \
  --policy.path=black-forest-labs/flux-3-action-so101 --policy.device=cuda \
  --dataset.repo_id=YOUR_ORG/YOUR_SO101_DATASET \
  --batch_size=8 --steps=14000 \
  --output_dir=outputs/so101_lora_large
```

| Ngân sách                   | GPU | Batch trên mỗi GPU | Tích lũy | Kích thước lô hiệu dụng | Microsteps (`steps`) | Cập nhật bộ tối ưu |
| ------------------------ | ---- | ------------- | ------------ | --------------- | -------------------- | ----------------- |
| Lặp nhanh (mặc định) | 1    | 2             | 4            | 8               | 10,000               | 2,500             |
| Ngân sách lớn hơn            | 4    | 8             | 4            | 128             | 14,000               | 3,500             |

Batch hiệu dụng bằng số GPU × batch trên mỗi GPU × hệ số tích lũy. LeRobot đếm `steps`, `save_freq` và `eval_steps` theo microstep; hãy chia cho hệ số tích lũy để tính số lần cập nhật optimizer. Preset lưu và đánh giá mỗi 500 microstep (tương đương 125 lần cập nhật). Khi thay đổi hệ số tích lũy, hãy đảm bảo cả ba cài đặt này đều chia hết cho hệ số tích lũy. Độ dài các giai đoạn freeze, warmup, decay và cooldown của scheduler cũng được tính bằng microstep. Hãy nhân số lần cập nhật optimizer mong muốn với hệ số tích lũy khi thiết lập độ dài cho các giai đoạn này. Cả hai ngân sách đều sử dụng cùng các cài đặt LoRA, optimizer và EMA, đồng thời giữ nguyên điều kiện, số chiều hành động và chuẩn hóa của mô hình cơ sở đã tải. Checkpoint bao gồm cả adapter thô và adapter EMA. Hãy chọn ngân sách và checkpoint dựa trên đánh giá trên tập dữ liệu giữ lại và các lần rollout; batch lớn hơn không đảm bảo kết quả tốt hơn.

Preset giữ lại 20% tập cuối cùng của mỗi tác vụ để đánh giá. Điều chỉnh kích thước lô và tích lũy cho phần cứng của bạn; xem [đào tạo đa GPU](https://huggingface.co/docs/lerobot/main/en/multi_gpu_training) và [đào tạo PEFT](https://huggingface.co/docs/lerobot/main/en/peft_training).

## Điều chỉnh tác vụ DROID

**Thử nghiệm:** `examples/flux3/lora.json` tái sử dụng các cài đặt optimizer PEFT, LoRA, dropout, EMA và ngân sách huấn luyện của SO-101. Việc nạp cấu hình đã được kiểm tra, nhưng huấn luyện PEFT DROID đầu-cuối và hiệu năng tác vụ vẫn chưa được xác thực.

Tải [chính sách DROID](https://huggingface.co/black-forest-labs/flux-3-action-droid) trực tiếp bằng ID kho; các bộ mã hóa dùng chung của nó sẽ được phân giải tự động:

```bash
lerobot-train \
  --config_path=examples/flux3/lora.json \
  --policy.path=black-forest-labs/flux-3-action-droid \
  --dataset.repo_id=YOUR_ORG/YOUR_DROID_TASK_DATASET \
  --output_dir=outputs/droid_lora
```

Cấu hình này sử dụng effective batch 8 và 2.500 bước cập nhật optimizer, với EMA được bật và lưu checkpoint raw/EMA mỗi 125 bước cập nhật. Tính năng tải lên Hub tự động bị tắt. Với ngân sách lớn hơn, hãy khởi chạy với bốn GPU như trong ví dụ SO-101 và thêm `--batch_size=8 --steps=14000`.

Preset tải camera layout, điều kiện, biểu diễn hành động, tần suất điều khiển và bộ xử lý từ checkpoint DROID, chỉ ghi đè các cài đặt huấn luyện/vận hành được liệt kê. Dữ liệu của bạn phải khớp với hợp đồng của checkpoint: gói hiện tại sử dụng ba camera, tám kênh trạng thái/hành động và lệnh vị trí khớp tuyệt đối ở 15 Hz. Ánh xạ tên camera bằng `--rename_map` nếu cần. Cả hai robot đều dùng cùng một ví dụ huấn luyện; không cần công thức riêng cho robot nào khi tải hoặc suy luận.

## Mặc định và chuẩn hóa

Các cấu hình mới sử dụng các giá trị mặc định PEFT này. Việc nạp `--policy.path` sẽ sử dụng các cài đặt đã lưu trong checkpoint; các ghi đè cấu hình/CLI rõ ràng sẽ có ưu tiên cao hơn. Các checkpoint DROID giữ nguyên cấu hình của riêng chúng.

| Cài đặt                                     | Mặc định                                                        |
| ------------------------------------------- | -------------------------------------------------------------- |
| Điều kiện                                | Hình ảnh hiện tại và trạng thái đo được; 1 ảnh chụp nhanh, không có hành động trong quá khứ |
| Hành động                                     | Chênh lệch lệnh; 32 lệnh được dự đoán và 32 lệnh được thực thi ở 30 Hz          |
| Camera                                     | Hai góc nhìn đặt cạnh nhau trên canvas 256 × 512                   |
| Tốc độ học của adapter / head                | `1e-4` / `5e-4`                                                |
| Phân rã trọng số / cắt gradient            | `0` / `1`                                                      |
| Đóng băng / khởi động                             | Không                                                           |
| Gradient checkpointing / tăng cường hình ảnh | Bật / Tắt                                                       |

Các cấu hình mới sử dụng `n_obs_steps=1`, `history_snapshots=1` và `condition_on_past_actions=false`. Việc tải một checkpoint sẽ giữ nguyên các giá trị tường minh của nó: gói SO-101 được cố định sử dụng tám bước thời gian lịch sử, hai snapshot thị giác và điều kiện hóa hành động/trạng thái trong quá khứ. `conditioning="history"` chọn mã hóa snapshot độc lập; nó không tự xác định số bước thời gian. Quá trình huấn luyện cũng đọc các khung hình và lệnh trong tương lai như các mục tiêu, cùng với lệnh trước đó để tính toán các delta hành động.

Tên và thứ tự camera, số chiều của trạng thái/hành động và các kênh hành động tuyệt đối vẫn mang tính đặc thù của từng robot. Điểm kiểm tra SO-101 giữ kênh cuối là tuyệt đối (`delta_absolute_dims=[-1]`) và sử dụng trọng số kênh `[1, 1, 1, 1, 1, 2]`. Giá trị mặc định của lớp không có ngoại lệ cho kênh tuyệt đối và sử dụng trọng số bằng nhau.

Bộ xử lý được lưu của base sở hữu các thống kê chuẩn hóa. Hãy cung cấp các trạng thái/hành động thô và giữ nguyên các thống kê đó cho huấn luyện, tiếp tục và suy luận. Các phân vị trong gói SO-101 giả định thứ tự khớp, đơn vị và hiệu chuẩn của nó; chúng không phải là các giá trị hiệu chuẩn SO-101 phổ quát. Để sử dụng các thống kê khác, hãy chuẩn bị một base riêng với các bộ xử lý tương ứng trước khi huấn luyện. Thống kê của bộ dữ liệu hành động tuyệt đối không thể thay thế cho thống kê delta lệnh.

Training lưu các adapter và các head đã huấn luyện kèm theo tham chiếu đến base hoàn chỉnh. Hãy giữ base đó cùng các tệp encoder đã đóng băng của nó ở trạng thái có thể truy cập khi nạp lại; các adapter không được tự động gộp vào base.

## Tiếp tục

```bash
lerobot-train \
  --config_path=outputs/so101_lora/checkpoints/last/pretrained_model/train_config.json \
  --resume=true
```

Tiếp tục từ checkpoint `pretrained_model` thô, khôi phục trạng thái optimizer và EMA. Đối với suy luận, bạn có thể chọn phần tử anh em `pretrained_model_ema` của nó khi EMA được bật. Giữ nguyên base và processors gốc của từng adapter; một base vừa tải về không phải là sự thay thế cho base đã được sử dụng bởi một adapter cũ hơn.

## Suy luận

Chỉ định `--policy.path` của runner LeRobot đến checkpoint adapter đã được huấn luyện; nó sẽ tải base được tham chiếu và các processor đã lưu. Đối với các cuộc gọi trực tiếp với một **base hoàn chỉnh**, hãy tải các processor cùng với nó:

```python
from lerobot.policies.factory import make_pre_post_processors
from lerobot.policies.flux3 import Flux3Policy

checkpoint = "black-forest-labs/flux-3-action-so101"
policy = Flux3Policy.from_pretrained(checkpoint).eval()
preprocessor, postprocessor = make_pre_post_processors(policy.config, pretrained_path=checkpoint)

# Run on every control tick, including while actions are queued:
prepared = preprocessor(observation)
normalized_action = policy.select_action(prepared)
absolute_command = postprocessor(normalized_action)
```

Bộ tiền xử lý đệm lịch sử quan sát/lệnh. Bộ hậu xử lý hoàn tác chuẩn hóa, tích phân các delta và cập nhật lịch sử lệnh dùng chung ở mỗi tick. Lệnh đầu tiên được neo vào trạng thái đo được; các lệnh sau tích phân từ lệnh trước đó. Đầu ra chính sách trực tiếp được chuẩn hóa và phải được hậu xử lý. Đặt lại chính sách và cả hai bộ xử lý tại ranh giới episode hoặc sau can thiệp; trình chạy đồng bộ của LeRobot thực hiện điều này. Suy luận RTC/không đồng bộ không được hỗ trợ.

Đối với chính sách một bước thời gian mặc định, hình ảnh hiện tại và trạng thái đo được là đủ. Đối với dự đoán ngoại tuyến với neo delta rõ ràng, hãy cung cấp `observation.command_history` với một lệnh trước đó; điều này neo tích hợp đầu ra mà không thêm lệnh vào điều kiện của mô hình. Các checkpoint được cấu hình rõ ràng cho nhiều bước thời gian quan sát yêu cầu `policy.config.n_obs_steps` hình ảnh/trạng thái và lịch sử lệnh. Truyền các đầu vào qua bộ tiền xử lý, gọi `predict_action_chunk`, sau đó hậu xử lý. `--policy.compile_model=true` bật biên dịch lười biếng cho các bộ mã hóa đóng băng và DiT suy luận; nó không biên dịch DiT huấn luyện.

Để giảm VRAM suy luận, hãy di chuyển Qwen sang CPU sau khi tải và sau lệnh gọi `policy.to(...)` cuối cùng:

```python
policy.frozen.text_encoder.cpu()
```

Điều này chuyển khoảng 8,3 GiB trọng số sang RAM của host; các lệnh chưa được cache mã hóa chậm hơn, trong khi các embedding vẫn được chuyển đến thiết bị policy và được cache. Nó không làm giảm bộ nhớ đỉnh trong quá trình tải, và một lệnh `policy.to(...)` sau đó sẽ chuyển Qwen trở lại cùng với policy.

## Huấn luyện các biến thể khác

Đối với các phiên bản mà chúng tôi chưa cung cấp checkpoint đã tinh chỉnh, hãy bắt đầu từ mô hình cơ sở trong [flux-action](https://github.com/black-forest-labs/flux-action). Quy trình đó yêu cầu xác định đầu hành động và điều kiện của robot, bố cục camera, biểu diễn hành động và chuẩn hóa. Việc có cùng kích thước chiều đơn thuần không đủ để các đầu của robot khác có thể tái sử dụng.

Để suy luận hoặc thích ứng tác vụ bằng LeRobot ở các bước sau, hãy đóng gói mô hình đã huấn luyện thành một chính sách LeRobot hoàn chỉnh, bao gồm cấu hình và các bộ xử lý tương ứng. Một tệp trọng số thô đơn thuần không phải là một gói `--policy.path` có thể nạp được. Hướng dẫn này tập trung vào việc thích ứng các chính sách SO-101 và DROID hiện có cho các tác vụ mới.

Tất cả các chính sách chỉ xây dựng các luồng nội dung `video` và `video_cond`, cùng với các luồng hành động của robot. Các trọng số hình ảnh/âm thanh không được sử dụng sẽ được lọc trước khi tải, giúp tiết kiệm khoảng 28% tham số DiT mà không làm thay đổi các dự đoán hành động. Các danh sách luồng đã lưu không kích hoạt các nhánh hình ảnh/âm thanh; việc tải và lưu một cơ sở đầy đủ sẽ ghi lại bố cục đã giảm. Các bộ thích ứng nhắm vào các luồng đã bị xóa yêu cầu cơ sở gốc của chúng và một bản sửa đổi mã cũ hơn.

Các chính sách hoàn chỉnh được nạp theo chế độ nghiêm ngặt (strict) mặc định. Sau khi lọc các luồng đã biết là không được sử dụng, các trọng số bị thiếu, không mong đợi hoặc có hình dạng không đúng sẽ gây ra lỗi. Việc chỉ định rõ `strict=False` chỉ cho phép khởi tạo các đầu (heads) của cơ thể (embodiment) bị thiếu hoặc thay đổi kích thước các đầu có sự không khớp; các trọng số của thân (trunk) vẫn là bắt buộc và được kiểm tra hình dạng.

## Kiểm tra

Các bài kiểm tra CPU bao gồm đóng gói, bộ xử lý, cập nhật PEFT và checkpoint/tiếp tục. Các kiểm tra H200 với trọng số thực trước đó đã diễn ra trước đợt refactor bộ xử lý hiện tại. Phiên bản chính xác này vẫn cần xác thực trên GPU và robot; các kiểm tra hiện có không chứng minh được khả năng bốn GPU hay chất lượng PEFT trên một cấu hình mới.