deploy/README_checkpoint_0617_deploy.md

# checkpoint_0617（22 维吸盘搬铝板 GO-1 模型）部署与测试 README

> **早期部署文档，部分内容已过时**：当前规范命令、路径配置（`go1_env.py` / `GO1_*`）、最新结论（头下俯+开腰使闭环起手）以 [COMMANDS_v2.md](COMMANDS_v2.md) + [../README.md](../README.md) 为准。本文档作历史记录保留。

> 任务 prompt：`reach into the bin, attach both suction cups to the part and lift it out level`
> 机器人：智元 G2（agibot-g2），30Hz，3 路彩色相机 + 22 维 qpos/action。
> 本文档汇总：模型路径、所需文件、22 维布局、环境、初始位姿、到位脚本、三级测试命令、已知问题。

---

## 1. 模型路径与所需文件

模型目录：`/data/agi/checkpoint_0617/`

| 文件 | 说明 | 必需 |
|---|---|---|
| `model-00001-of-00002.safetensors` (4.99GB) | 权重分片 1 | ✅ |
| `model-00002-of-00002.safetensors` (0.65GB) | 权重分片 2 | ✅ |
| `model.safetensors.index.json` | 权重索引（total 5.64GB）| ✅ |
| `config.json` | GO1ModelConfig（action_dim=22, state_dim=22, chunk=30）| ✅ |
| `dataset_stats.json` | 归一化统计（state/action 各 22 维 min/max/mean/std）| ✅ |
| `tokenizer.model` / `tokenizer_config.json` / `added_tokens.json` / `special_tokens_map.json` / `tokenization_internlm2.py` | 分词器 | ✅ |

推理引擎（venv）：`/data/agi/venvs/go1_torch/bin/python`
模型代码库：`/data/agi/AgiBot-World`（脚本里 `sys.path.insert`）

---

## 2. 22 维 state/action 布局

顺序 = `go2_data_recorder.config.DEFAULT_JOINT_NAMES_Go2`（已验证与 hdf5 `joint_names_json` 一致）。
**注意：吸盘不在 action 内**（模型不预测吸盘，吸盘独立 on/off 控制）。

| 维度 | 关节 | 含义 |
|---|---|---|
| `[0:5]`   | idx01-05_body | **腿/腰**：踝 / 膝 / 髋 / 腰roll / 腰yaw（下蹲式下半身，靠蹲下提供下探行程）|
| `[5:8]`   | idx11-13_head | 头 3 轴 |
| `[8:15]`  | idx21-27_arm_l | 左臂 7 |
| `[15:22]` | idx61-67_arm_r | 右臂 7 |

---

## 3. 环境设置（每个新终端先执行）

```bash
ssh agi@172.16.64.220
source /home/agi/workspace/env.sh
export TMPDIR=/data/agi/tmp
export PYTHONPATH=/home/agi/workspace:$PYTHONPATH
PY=/data/agi/venvs/go1_torch/bin/python
```

---

## 4. 推理所需「初始位姿」

来源：`go2_suction_extract_v1` 共 60 个 episode 的**第 0 帧 qpos 均值**（std≈0.007，高度一致的固定起手姿）。
重要事实：**此初始位姿 == 机器人 home/收拢位**，演示都是从该姿态起手，躯干前倾探框发生在 episode 过程中。

```
WAIST idx01-05 = [-0.865, 1.439, -0.632, 0.000, 0.000]   # 踝/膝/髋/roll/yaw
HEAD  idx11-13 = [ 0.012, 0.000, 0.192]
LEFT  idx21-27 = [ 1.729, -1.150, -1.600, -1.799, 1.330, 0.000, 0.000]
RIGHT idx61-67 = [-1.729, -1.150,  1.600, -1.799, -1.330, 0.000, 0.000]
```

### 到位脚本 `go_to_init_pose_0617.py`

机制：复用 `g2_t2_go_home.py` 的 DDS 规划器通路（`control_type=3` 绝对关节角 → 发到
`/MotionControlService/MotionControl/request` → 由 `genie_motion_control` 规划安全轨迹，处理 COM/碰撞）。
非裸 servo。保活节点重发若干次（修掉原脚本 publish 即退、可能投递不到的问题）。

```bash
python3 /data/agi/go_to_init_pose_0617.py --speed 0.3 --hold-s 4 --verify
```
- `--speed`  speed_scale（默认 0.3，慢）
- `--hold-s` 保活并重发的秒数
- `--verify` 结束后读关节角，打印 `max|err|`

**前置条件**：遥操必须**空闲/已交还控制权**，否则规划器忽略请求（teleop 持权是第一优先级）。
判断未生效：`--verify` 的 err 没下降 / 关节角不变 → 多半是遥操在持权。

---

## 5. 三级测试命令（从安全到危险，务必按序）

### 1 级 — 纯加载冒烟（不接机器人）
```bash
$PY /data/agi/check_model_load_0617.py
```
预期：加载成功，2.82B 参数 / ~11.5GB 显存 / 输出 `(1,30,22)` / ~665ms。

### 2 级 — 真机只读（抓相机+关节→推理→只打印，不动机器人）
```bash
$PY /data/agi/infer_stage_a_0617.py
```
预期：3 相机正常、输出 `(30,22)` 无 NaN。
**关键看 `|action[0]-state|`**：策略正确时应接近 0（见第 6 节已知问题）。

### 3 级 dry-run — 闭环全流程 + 安全门控（不动机器人）
```bash
$PY /data/agi/infer_stage_c_0617.py --max-chunks 3
```
打印每 chunk 的 waist/head/armL/armR 预测 + 安全判定；不发任何运动。

### 3 级 live — 真闭环动机器人（⚠️ 危险，需有人守急停）
```bash
# 保守起见先冻结腰；先确认 dry-run 的 d0max<0.3 再加 --live
$PY /data/agi/infer_stage_c_0617.py --live --no-waist --max-chunks 3 --exec-frames 15
```
下发通路：臂→`joint_servo_control`(14名)，头→`move_head_joint_servo`(3值)，腰→`move_waist_joint_servo`(5值)。
安全门控：NaN/Inf、首步 delta、步间 delta、训练 range clamp、3 连败停。
分组开关：`--no-waist` / `--no-head`。其它参数：`--max-chunks`/`--max-time-s`/`--exec-frames`/`--first-step-delta`/`--step-delta`/`--priority`。

---

## 6. ⚠️ 已知问题（live 前必须先查清）

演示数据里 **action[t] ≈ qpos[t]（绝对位置，全程 mean 误差≈0）**，所以策略正确运行时
**action[0] 应 ≈ 当前状态、首步 delta 接近 0**。但实测推理 action[0] 离正确起点差 **~2.95rad**。
这是**推理侧异常**信号，不是"任务要前倾"。嫌疑（按可能性排序）：

1. **观测不在分布内**：推理时料框/铝板不在相机视野、光照/背景与训练差异大。→ 复现训练场景（料框+铝板就位）再试。
2. **图像/相机映射**：3 路相机顺序或内容与训练不一致。
3. **归一化口径**：核对 ctrl_freq、state 归一化、action 反归一化与训练 deploy 代码一致。

**必须**：到位后先单独验证一次推理，确认相机里有料框和铝板，且 stage_a 的 `|action[0]-state|`
回落到接近 0，stage_c live 才安全有意义。

---

## 7. 文件清单（均在 `/data/agi/`）

| 文件 | 用途 |
|---|---|
| `check_model_load_0617.py` | 1 级 加载冒烟 |
| `infer_stage_a_0617.py` | 2 级 真机只读推理 |
| `infer_stage_c_0617.py` | 3 级 闭环（默认 dry-run，`--live` 才动）|
| `go_to_init_pose_0617.py` | 驱动到推理初始位姿（DDS 规划器，安全）|
| `ramp_to_start_0617.py` | 旧版裸 servo ramp（⚠️ 腰 servo 会被拒，已弃用，保留备查）|
| `checkpoint_0617/` | 模型权重 + config + dataset_stats |

参考实现（吸盘作业 + 腰/臂控制 + 取控制权）：`/home/agi/workspace/demos/demo_03_suction_extract/scripts/`
官方到位脚本（内置预设，非模型起始位姿）：`/home/agi/workspace/bin/motion-control/bin/tools/g2_t2_go_home.py -i 0..4`

---

## 8. 状态小结（截至 2026-06-21）

- ✅ 1 级 / 2 级 / 3 级 dry-run 全通过
- ✅ dataset_stats.json（权威版，22 维）就位
- ✅ 初始位姿确定 + 到位脚本就绪
- ⏳ 待办：①遥操交还控制权后跑 `go_to_init_pose_0617.py` 验证到位 ②排查第 6 节推理异常 ③确认料框/铝板场景在分布内 ④再做 stage_c live