# Wall-OSS-0.5

Wall-OSS-0.5 là mô hình thị giác-ngôn ngữ-hành động 4B từ [XSquare Robot](https://x2robot.com/en/research/68bc2cde8497d7f238dde690). Nó kết hợp bộ khung thị giác-ngôn ngữ Qwen2.5-VL với chuyên gia hành động khớp dòng liên tục.

LeRobot cung cấp Wall-OSS-0.5 thông qua loại policy `wall_oss_05` và checkpoint [`lerobot/wall-oss-0.5`](https://huggingface.co/lerobot/wall-oss-0.5).

`wall_oss_05` và chính sách `wall_x` hiện có nhắm đến các bản phát hành WALL khác nhau. Hãy sử dụng `wall_oss_05` với checkpoint Wall-OSS-0.5.

## Tổng quan về Mô hình

Wall-OSS-0.5 điều kiện hóa việc tạo hành động dựa trên quan sát từ camera, trạng thái robot và tác vụ bằng ngôn ngữ tự nhiên. Chính sách dự đoán một khối các hành động liên tục bằng flow matching. Chuyên gia thị giác-ngôn ngữ của nó cũng có thể tạo văn bản cho chú thích, trả lời câu hỏi thị giác, grounding và các tác vụ con về ngôn ngữ.

Mô hình đã phát hành sử dụng:

- biểu diễn trạng thái và hành động chính tắc 26 chiều;
- các khối hành động 32 bước;
- chuẩn hóa theo khoảng q01/q99;
- bộ lấy mẫu luồng 10 bước;
- Qwen2.5-VL cho đầu vào thị giác và ngôn ngữ.

Checkpoint cơ bản được thiết kế để tinh chỉnh trên bộ dữ liệu robot và tác vụ đích trước khi triển khai.

### Những gì Tích hợp LeRobot Bao Gồm

- Cấu hình `policy.type=wall_oss_05` chuẩn và tải checkpoint từ Hub.
- Xử lý thị giác-ngôn ngữ Qwen2.5-VL bản địa và các chuyên gia hành động Wall.
- Huấn luyện luồng dự đoán x liên tục và lấy mẫu Euler 10 bước.
- Tối ưu hóa chéo entropy văn bản và tinh chỉnh kết hợp văn bản/hành động dựa trên công thức.
- Tạo văn bản gốc cho các tác vụ VQA, grounding, chú thích và các tác vụ con về ngôn ngữ.
- Tạo văn bản trực tiếp thông qua rollout tương tác của LeRobot.
- Đầu vào trạng thái và hành động 26D chuẩn hóa bằng bộ xử lý q01/q99 của LeRobot.
- Fine-tuning bằng `lerobot-train` và suy luận thông qua các API chính sách tiêu chuẩn.

## Yêu cầu cài đặt

Wall-OSS-0.5 yêu cầu GPU NVIDIA có CUDA. Cài đặt LeRobot với các phụ thuộc của policy:

```bash
pip install "lerobot[wall_oss_05]"
```

Đối với bản checkout mã nguồn LeRobot:

```bash
uv sync --extra wall_oss_05
```

Chính sách này được triển khai bản địa trong LeRobot. Phụ thuộc duy nhất cụ thể cho chính sách là Transformers; không cần checkout Wall-X riêng. Xử lý dựa trên recipe cũng yêu cầu dataset extra. Đối với truy vấn ngôn ngữ hoặc huấn luyện, hãy cài đặt `uv sync --extra wall_oss_05 --extra training` (training bao gồm hỗ trợ dataset). Đặt `--policy.recipe=null` để xử lý chỉ hành động mà không cần dataset extra.

## Điểm kiểm tra

| Biến thể | LeCheckpoint của LeRobot                                                    | Mục đích sử dụng                             |
| ------- | --------------------------------------------------------------------- | ---------------------------------------- |
| Base 4B | [`lerobot/wall-oss-0.5`](https://huggingface.co/lerobot/wall-oss-0.5) | Tinh chỉnh và triển khai 26D chuẩn |

Checkpoint bao gồm cấu hình chính sách, bộ xử lý và tokenizer Qwen, trọng số mô hình, bộ tiền xử lý/sau xử lý LeRobot đã lưu, thống kê chuẩn hóa và metadata chuyển đổi. Đây là checkpoint cơ sở: hãy tinh chỉnh nó trên robot và tác vụ đích trước khi báo cáo kết quả ở cấp độ tác vụ.

## Cách sử dụng

Chọn chính sách với:

```bash
--policy.type=wall_oss_05
```

Khởi tạo từ checkpoint LeRobot với:

```bash
--policy.path=lerobot/wall-oss-0.5
```

Sử dụng `--policy.path=your-org/your-finetuned-checkpoint` khi đánh giá hoặc triển khai một checkpoint LeRobot đã lưu.

### Văn bản và VQA

Wall-OSS-0.5 sử dụng hợp đồng văn bản chính sách chung. Runtime cung cấp `query_kind` và `query_text`, sau đó chạy bộ xử lý đầu vào chính sách thông thường:

```python
request = {
    **observation,
    "query_kind": "vqa",
    "query_text": "Which object is closest to the right gripper?",
}
processed_batch = preprocessor(request)
answer = policy.generate_text(processed_batch)
```

`vqa` giữ nguyên câu hỏi của người gọi. `next_subtask` áp dụng công thức do `WallOSS05Config` sở hữu. Chính sách kế thừa `generate_text(processed_batch)` và ghi đè `supports_text_generation` cùng `generate_text`. Quá trình sinh sử dụng đầu từ vựng Qwen được liên kết trong checkpoint và chuyên gia thị giác-ngôn ngữ; nó không gọi một VLM riêng biệt.

Runtime ngôn ngữ có thể tạo ra một tác vụ con và sau đó điều kiện hóa dự đoán hành động của Wall dựa trên nó:

```bash
lerobot-rollout \
  --policy.path=your-org/your-finetuned-wall-oss-0.5 \
  --policy.device=cuda \
  --task="clear the table" \
  --interactive=true
```

Sau `/start`, hãy sử dụng `/vqa <question>`, `/autosteer <goal>` hoặc `/subtask <text>`.

Wall giữ lại các khả năng VQA và grounding hữu ích, nhưng nó được chuyên biệt hóa cho quan sát của robot và không được thiết kế để thay thế một VLM đa dụng.

## Yêu cầu về dữ liệu

Wall-OSS-0.5 hoạt động bên trong trên bố cục trạng thái và hành động chuẩn 26D. Các đặc trưng trạng thái và hành động hẹp hơn được chuẩn hóa bằng thống kê tập dữ liệu gốc của chúng, sau đó được đệm bằng số 0 lên 26D cho mô hình. Các chiều hành động được đệm bị loại trừ khỏi tổn thất huấn luyện. Đầu ra được cắt xén theo chiều rộng hành động của tập dữ liệu trước khi khử chuẩn hóa: một trạng thái 8D với hành động 7D sẽ trả về hành động 7D. `postprocess_action_dim` có thể áp dụng một lần cắt xén đầu ra bổ sung. Việc đệm không ánh xạ lại tọa độ khớp hoặc quy ước bộ điều khiển; hãy cung cấp các giá trị tương thích.

Cấu hình đầu vào hình ảnh bằng `camera_key_mapping`. Bản ánh xạ này liên kết mỗi đặc trưng hình ảnh LeRobot với một khe camera Wall. Điểm kiểm tra mặc định sử dụng `face_view` và `right_wrist_view`.

Chuỗi nhiệm vụ của tập dữ liệu được truyền cho chính sách dưới dạng hướng dẫn ngôn ngữ. Hãy sử dụng các mô tả nhiệm vụ nhất quán khi ghi lại, huấn luyện và đánh giá.

Chuẩn hóa trạng thái và hành động q01/q99 được xử lý bởi bộ tiền xử lý và hậu xử lý LeRobot đã lưu. Khi suy luận, các thống kê được lưu cùng checkpoint sẽ được khôi phục. Khi tinh chỉnh với `lerobot-train`, thống kê của tập dữ liệu huấn luyện sẽ thay thế thống kê của bộ xử lý được huấn luyện trước và được lưu cùng checkpoint mới.

Checkpoint đã công bố sử dụng từ điển trạng thái chính sách LeRobot gốc và định dạng pre/postprocessor hiện tại. Trọng số được nạp và lưu thông qua mã lưu trữ chính sách dùng chung, bao gồm cả các thao tác thu thập phân tán và cổng ghi của tiến trình chính. Cấu hình giữ nguyên tham chiếu tài sản tokenizer ổn định và có thể được nạp từ bất kỳ thư mục làm việc nào.

## Huấn luyện

Tinh chỉnh checkpoint gốc với lệnh huấn luyện LeRobot tiêu chuẩn:

### Ví dụ lệnh huấn luyện

```bash
lerobot-train \
  --dataset.repo_id=your-org/your-dataset \
  --policy.path=lerobot/wall-oss-0.5 \
  --policy.repo_id=your-org/wall-oss-0.5-your-task \
  --output_dir=outputs/train/wall_oss_05 \
  --job_name=wall_oss_05_finetune \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

Bắt đầu với kích thước lô nhỏ vì Wall-OSS-0.5 là mô hình 4B tham số. Tăng kích thước lô theo bộ nhớ GPU khả dụng, hoặc sử dụng tích lũy gradient thông qua cấu hình huấn luyện phân tán của bạn.

Đối với các bộ dữ liệu có tên camera khác nhau, hãy ánh xạ các khóa đặc trưng của chúng vào các vị trí camera Wall. Ví dụ, thêm tùy chọn sau cho `top` và `wrist`:

```bash
--policy.camera_key_mapping='{"observation.images.top":"face_view","observation.images.wrist":"right_wrist_view"}'
```

Fine-tuning xác định hình dạng camera và chiều rộng state/action từ dataset, kể cả khi nạp checkpoint cơ sở bằng `--policy.path`.

### Huấn luyện với chú thích ngôn ngữ

Công thức do `WallOSS05Config` sở hữu sử dụng các cột ngôn ngữ tùy chọn của LeRobot theo mặc định. Công thức con tác vụ khớp của nó giám sát phản hồi của trợ lý và khối hành động liên tục trong một chuỗi nhân quả duy nhất:

```bash
lerobot-train \
  --dataset.repo_id=your-org/your-language-annotated-dataset \
  --policy.path=lerobot/wall-oss-0.5 \
  --policy.use_language_recipe=true \
  --policy.text_loss_weight=0.1 \
  --policy.flow_loss_weight=1.0 \
  --policy.device=cuda \
  --batch_size=1 \
  --steps=20000
```

Các luồng công thức xác định các mục tiêu nào được thực thi cho mỗi mẫu:

- một lượt phản hồi của trợ lý được nhắm mục tiêu nhận entropy chéo của văn bản token tiếp theo;
- một lượt `low_level` nhận được sự giám sát liên tục về dòng hành động; và
- Một công thức `low_level` với lượt phản hồi của trợ lý được nhắm mục tiêu sẽ nhận cả hai tổn thất, trong đó các token hành động chú ý đến văn bản được giám sát.

Chỉ payload của assistant được nhắm mục tiêu và token `<|im_end|>` của nó được sử dụng làm nhãn ngôn ngữ. Prompt của user, padding, hình ảnh, proprioception và các token action-query liên tục bị che (mask) khỏi cross-entropy của text. Các dòng không có chú thích sẽ giữ nguyên prompt chỉ chứa action và loss gốc. Đặt `use_language_recipe=false` để vô hiệu hóa việc render chú thích, hoặc `recipe=null` để vô hiệu hóa cả hai bộ render recipe. Một `recipe_path` được chỉ định rõ sẽ ghi đè lên recipe tích hợp sẵn. Fine-tuning mới sẽ xây dựng lại processors từ recipe đó và các thống kê huấn luyện; huấn luyện tiếp tục và rollout sẽ khôi phục các processors và thống kê đã lưu trong checkpoint.

Xem [Các cột ngôn ngữ và công thức](./language_and_recipes) để biết về schema chú thích và cấu trúc công thức. `recipe_path` có thể trỏ đến một tệp YAML ghi đè bên ngoài cụ thể; LeRobot không cung cấp các tệp công thức mặc định chung.

## Các tham số cấu hình chính

| Tham số                 | Mặc định                    | Mô tả                                                    |
| ------------------------- | -------------------------- | -------------------------------------------------------------- |
| `pretrained_name_or_path` | `lerobot/wall-oss-0.5`     | Nguồn tài sản tokenizer và image-processor                     |
| `tokenizer_revision`      | `None`                     | Bản ghim tokenizer cơ sở tùy chọn, tách biệt khỏi bản sửa đổi trọng số |
| `chunk_size`              | `32`                       | Số lượng hành động được dự đoán cho mỗi khối                          |
| `n_action_steps`          | `32`                       | Số lượng hành động dự đoán được thực hiện trước khi lập kế hoạch lại         |
| `camera_key_mapping`      | góc nhìn mặt và cổ tay phải | Gán các khóa tính năng hình ảnh với các vị trí camera của mô hình          |
| `use_language_recipe`     | `true`                     | Bật công thức được lưu trong cấu hình chính sách                 |
| `recipe_path`             | `None`                     | Ghi đè công thức bên ngoài rõ ràng tùy chọn                     |
| `text_loss_weight`        | `0.1`                      | Trọng số cho entropy chéo của token trợ lý có giám sát            |
| `flow_loss_weight`        | `1.0`                      | Trọng số cho tổn thất hành động-luồng liên tục                         |
| `tokenizer_max_length`    | `1000`                     | Độ dài tối đa của chuỗi token kết hợp thị giác-ngôn ngữ-hành động     |
| `device`                  | auto                       | Sử dụng `cuda` cho Wall-OSS-0.5                                    |

## Đánh giá và Suy luận

Sử dụng checkpoint đã fine-tune với các workflow đánh giá LeRobot chuẩn hoặc robot rollout bằng cách truyền repository Hub hoặc thư mục cục bộ của nó làm đường dẫn policy.

Wall-OSS-0.5 tạo ra các khối hành động liên tục bằng trình lấy mẫu luồng (flow sampler) của nó. Chính sách hiện tại hỗ trợ nhánh luồng liên tục; nhánh hành động tự hồi quy (autoregressive) không được công khai.

Mỗi chunk mã hóa các hình ảnh camera của nó và prefill tiền tố quan sát/văn bản một lần. Mười bước Euler tái sử dụng các key và value của tiền tố và chỉ giải mã các token hành động. Bộ nhớ đệm được xây dựng lại cho mỗi quan sát mới.

Đối với trình mô phỏng được hỗ trợ, hãy cung cấp checkpoint đã tinh chỉnh và các tùy chọn cụ thể cho môi trường thông qua `lerobot-eval`:

```bash
lerobot-eval \
  --policy.path=your-org/your-finetuned-wall-oss-0.5 \
  --policy.device=cuda \
  --env.type=<environment> \
  --env.task=<task> \
  --eval.batch_size=1 \
  --eval.n_episodes=10
```

Không đánh giá checkpoint gốc như thể nó là một chính sách dành riêng cho tác vụ. Đại diện chính tắc, thống kê chuẩn hóa và phân phối tác vụ phải khớp với checkpoint đã tinh chỉnh.

## Tham khảo

- [Trang dự án Wall-OSS-0.5](https://x2robot.com/en/research/68bc2cde8497d7f238dde690)
- [Checkpoint Wall-OSS-0.5 LeRobot](https://huggingface.co/lerobot/wall-oss-0.5)

## Giấy phép

Wall-OSS-0.5 và Wall-X được phát hành theo Giấy phép Apache 2.0.