> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 训练与评测

> 训练 reorient PPO 策略、回放 checkpoint、评测成功率，并把训练好的策略导出为部署用的 ONNX。

训练通过顶层 `pixi` 任务进行，用 `--task` 传入任务 ID。

## 训练

```bash theme={null}
pixi run train --task WujiHand_Reorient --agent.upload-model False
```

`--agent.upload-model False` 表示 checkpoint 只存本地。移除该参数并设置 `WANDB_API_KEY`，最后一次迭代的 checkpoint 还会作为 model artifact 上传到 W\&B。无论是否上传，本地 `.pt` 都会在每个 `save_interval` 触发点写入。

Checkpoint 与 W\&B 日志写入 `logs/rsl_rl/<run_name>/`。

### 任务配置

两个任务 ID 共享同一 MDP，在 GPU 显存与策略质量之间权衡。

| 任务 ID | Envs × 迭代 | GPU 显存 | 说明 |
| - | - | - | - |
| `WujiHand_Reorient` | 8192 × 5000 | 约 20 GB | release 配置，复现已发布 checkpoint |
| `WujiHand_Reorient_Light` | 4096 × 7500 | 约 12 GB | 低显存变体，策略明显较弱 |

<Info>
  如果 `pixi run train` 显存不足，切换到低显存变体：

  ```bash theme={null}
  pixi run train --task WujiHand_Reorient_Light
  ```

  `WujiHand_Reorient_Light` 可在约 12 GB 显存的 GPU 上运行，但收敛到较弱的策略，在较难的翻转上偶尔掉 cube、出现卡手。
</Info>

## 回放与评测

在交互式 viewer 里回放训练好的 checkpoint，或在多次试验上跑成功率评测：

```bash theme={null}
# Interactive viewer with a trained checkpoint
pixi run play --task WujiHand_Reorient --checkpoint-file <path-to-ckpt.pt>

# Success-rate eval over N trials (consumes ONNX)
pixi run python -m wuji_mjlab.tasks.reorient.scripts.eval_success_rate <path-to-policy.onnx>
```

需要 headless、机器可读的输出（适合 CI 或 sweep）：

```bash theme={null}
pixi run python -m wuji_mjlab.tasks.reorient.scripts.eval_success_rate <onnx_path> \
    --num-trials 100 --no-viewer --json-output result.json
```

### 编程式评测

评测核心可 import，因此可从 Python 直接驱动批量评测，无需走 CLI：

```python theme={null}
from pathlib import Path
from wuji_mjlab.tasks.reorient.tooling.eval_core import EvalConfig, run_eval

result = run_eval(EvalConfig(
    onnx_path=Path("<path-to-policy.onnx>"),
    num_trials=50,
    no_viewer=True,
))
print(f"success_rate = {result.success_rate:.2%}")
print(f"mean min ori error = {result.mean_min_ori_error_rad:.3f} rad")

# Per-trial data for custom analysis
for trial in result.trials:
    if trial.status == "success":
        print(f"trial {trial.trial_idx}: t_first_succ={trial.time_to_first_success_s:.2f}s")
```

## 导出为 ONNX

部署消费一个 ONNX 策略，外加一个 sidecar JSON——记录导出时捕获的控制模式参数（`action_scale`、`ema_alpha`、`warmup_time_s`、`control_mode`、`history_len`、`ctrl_dt`）：

```bash theme={null}
pixi run python -m wuji_mjlab.tasks.reorient.scripts.export_onnx <path-to-ckpt.pt>
```

Sidecar 让部署推理与产出该 ONNX 的仿真策略完全一致。继续到 [Sim-to-real 部署](/docs/wuji-mjlab/sim2real) 在真机上运行它。

## 开发工具

```bash theme={null}
# 列出所有已注册的任务 ID
pixi run list-envs

# 用 dummy 策略查看任务场景
pixi run python -m wuji_mjlab.tasks.reorient.scripts.view_task WujiHand_Reorient
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.