README.md

---
title: Pi0.5
emoji: 🔥
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 5.49.1
python_version: '3.10'
app_file: app.py
pinned: false
---

# π₀.₅ UR Action Predictor

This Hugging Face Space deploys a π₀.₅ policy trained on the local UR LeRobot
dataset. It predicts an action chunk for inspection or download; it never
connects to or commands a robot.

The `Policy config` selector supports:

- `pi05_ur_demo_no_state` (default): no discrete robot-state conditioning;
- `pi05_ur_demo_state`: uses the seven current-state values as discrete state
  conditioning.

The seven state controls remain visible in both modes so configurations can be
switched without rebuilding the page. The repository name does not select the
configuration automatically, and changing the selection reloads the policy.

## Model repository

Configure these Space variables (or enter both values in the UI):

- `PI05_MODEL_ID`: Hugging Face repository containing the trained checkpoint.
- `PI05_CHECKPOINT_PATH`: relative checkpoint directory, for example
  `checkpoints/30000`.

The selected directory must contain either `params/` (JAX checkpoint) or
`model.safetensors` (PyTorch checkpoint), plus the training statistics at:

```text
assets/**/norm_stats.json
```

The Space also accepts a root-level `norm_stats.json`. The asset directory name
is not required to be `ur_demo`; this supports checkpoints exported with the
original dataset or robot name, such as `assets/F-Fer/ur-1/norm_stats.json`.

Use a Space secret named `HF_TOKEN` when the model repository is private.

## Inputs and outputs

The two image inputs correspond to training fields `video.image_0` (fixed
camera) and `video.wrist` (wrist camera). State values must use this exact order:

```text
x, y, z, roll, pitch, yaw, gripper
```

The policy returns ten actions with columns:

```text
dx, dy, dz, droll, dpitch, dyaw, gripper
```

All state values must be finite. TCP translation uses metres and rotation uses
radians, matching the collected dataset.

## Deploy

Create a Hugging Face Gradio Space with a CUDA GPU and push this repository.
When `PI05_MODEL_ID` and `PI05_CHECKPOINT_PATH` are configured as Space
variables, the checkpoint is downloaded and validated during app startup,
before the GPU-decorated prediction call. Model initialization remains lazy on
the first prediction. If those variables are left empty, download falls back
to the first prediction. Only one inference request runs at a time to protect
GPU memory.

For local use with all dependencies installed:

```bash
PYTHONPATH=openpi_runtime python app.py
```

The Space runs on Python 3.10 and requires a compatible CUDA 12 GPU.

## Optional real-checkpoint smoke test

After installing the dependencies on a CUDA machine, opt in to the large model
download and end-to-end inference test with:

```bash
PI05_GPU_SMOKE=1 \
PI05_MODEL_ID=owner/model \
PI05_CHECKPOINT_PATH=checkpoints/30000 \
pytest tests/test_gpu_smoke.py -v
```

Do not put a Hugging Face access token in this command; use `HF_TOKEN` as a
local environment secret or a Hugging Face Space secret.

哈基米