插花（wall-oss-0.5） - 量子一号Pro 1.0

任务目标

机器人从桌面取起花材，将其移动到花瓶口上方并插入指定深度。该任务包含目标识别、精细抓取、空间对准、柔性物体操作和安全释放，适合用于验证双臂或单臂操作、数据采集和模型微调链路。

数据准备：

按照数据采集指南进行操作：参考下面三个视角（左臂视角、主视角、右臂视角）的视频进行数采

模型训练

代码说明参考地址：https://github\.com/X\-Square\-Robot/wall\-x/blob/main/workspace/TRAIN\_ARRANGE\_3\_FLOWERS\.md

模型训练以真机 LeRobotDataset v3 为例，任务为双臂机器人 三花插花（arrange 3 flowers）。

创建训练配置

双臂、448 px、三相机场景可参考：

cp workspace/example/arrange_3_flowers_wrc_red.yml \
  /path/to/arrange_3_flowers_train.yml

核心路径示例：

model_type: qwen2_5

model:
  backbone: qwen2_5
  config_path: /path/to/wall-oss-0.5/config.json
  processor_path: /path/to/Qwen2.5-VL-3B-Instruct
  pretrained_path: /path/to/Qwen2.5-VL-3B-Instruct
  attn_deterministic: true
  use_ema: false
  flow_loss_weight: 1.0
  ar_loss_weight: 0.01

data:
  dataset_type: lerobot
  lerobot_config:
    repo_id: /path/to/arrange_3_flowers_lerobot
    root: null
  key_mappings:
    camera:
      observation.images.faceImg: face_view
      observation.images.leftImg: left_wrist_view
      observation.images.rightImg: right_wrist_view
    state: observation.state
    action: action
  norm_stats_path: /path/to/arrange_3_flowers_norm_stats.json
  train_test_split: 0.95
  num_workers: 0
  max_length: 1024
  resolution:
    face_view: 448
    left_wrist_view: 448
    right_wrist_view: 448

checkpoint:
  save_path: /path/to/arrange_3_flowers_ckpt
  resume_from: /path/to/wall-oss-0.5/model.safetensors

数据要求： 数据集需包含 observation.state、action 及三视角图像键 observation.images.faceImg / leftImg / rightImg。若 state / action 为 26 维（含额外 DOF），训练时按 dof_config 自动截取前 20 维双臂分量。

配置动作与状态维度

以下是插花任务的双臂相对动作示例。开发者必须按自己的机器人和数据修改：

task:
  dof_config:
    follow_left_ee_cartesian_pos_relative: 3
    follow_left_ee_rotation_6D_relative: 6
    follow_left_gripper: 1
    follow_right_ee_cartesian_pos_relative: 3
    follow_right_ee_rotation_6D_relative: 6
    follow_right_gripper: 1
    action_padding: 6

  ar_dof_config:
    follow_left_ee_cartesian_pos_relative: 3
    follow_left_ee_rotation_6D_relative: 6
    follow_left_gripper: 1
    follow_right_ee_cartesian_pos_relative: 3
    follow_right_ee_rotation_6D_relative: 6
    follow_right_gripper: 1
    action_padding: 6

  agent_pos_config:
    follow_left_ee_cartesian_pos: 3
    follow_left_ee_rotation_6D: 6
    follow_left_gripper: 1
    follow_right_ee_cartesian_pos: 3
    follow_right_ee_rotation_6D: 6
    follow_right_gripper: 1
    action_padding: 6

  action_horizon: 32
  action_horizon_flow: 32
  use_state_string_representation: false

dof_config 定义模型预测的动作维度（20 维有效双臂 + 6 维 action_padding = 26 维，对齐 Wall-OSS-0.5 预训练空间），agent_pos_config 定义 observation state 维度。各项维度总和必须与归一化统计文件一致。底盘、升降、头部等维度不预测，通过 action_padding 补齐，loss 不反传至填充部分。

训练超参数示例

hyperparams:
  num_epoch: 50
  batch_size_per_gpu: 4
  gradient_accumulation_steps: 4
  seed: 10222
  optimizer:
    optimizer_type: adamw
    learning_rate: 5.0e-05
    max_grad_norm: 1.0
    enable_grad_clip: true
    betas: [0.9, 0.95]
    weight_decay: 1.0e-8
    eps: 1.0e-8
  scheduler:
    scheduler_type: cosine
    num_warmup_steps: 1000
    num_training_steps: 200000
    min_lr: 1.0e-6

distributed:
  use_fsdp: true
  use_mixed_precision: true
  bf16: true

logging:
  log_name: arrange_3_flowers
  log_project: wall_oss_flowers
  log_entity: your_wandb_entity
  use_wandb: true
  log_interval: 10
  save_interval: 2000
  val_interval: 1000000
  epoch_save_interval: 1

debug:
  profile: false
  nvtx: false

以上参数来自插花任务示例，不是所有任务的统一推荐值。应根据数据规模、GPU 和任务效果调整，并保存实际使用的配置。

注意： 网络文件系统上 data.num_workers > 0 可能触发 Errno 95，插花任务示例建议保持 num_workers: 0。

生成归一化统计

python scripts/compute_norm_stats.py \
  --train_config /path/to/arrange_3_flowers_train.yml \
  --data_root /path/to/arrange_3_flowers_lerobot \
  --output_path /path/to/arrange_3_flowers_norm_stats.json

脚本会依据配置中的字段和 DOF 转换计算统计，对 _relative 键做与训练 loader 一致的相对位姿统计。生成后确认 data.norm_stats_path 指向同一文件，并检查 state/action 的有效维度为 20（不含 action_padding）。

启动训练

冒烟测试（推荐先做）：

cp workspace/example/arrange_3_flowers_wrc_red_smoke.yml \
  /path/to/arrange_3_flowers_smoke.yml

CUDA_VISIBLE_DEVICES=0 \
torchrun --nproc_per_node=1 \
  wall_x/trainer/fsdp_trainer/train_fsdp.py \
  --config /path/to/arrange_3_flowers_smoke.yml

或使用启动脚本的 DEBUG=1 模式：

DEBUG=1 CONFIG=/path/to/arrange_3_flowers_train.yml \
  bash workspace/example/run_oss_wandb_local.sh

多 GPU（4 卡示例）：

CUDA_VISIBLE_DEVICES=0,1,2,3 \
torchrun --nproc_per_node=4 \
  wall_x/trainer/fsdp_trainer/train_fsdp.py \
  --config /path/to/arrange_3_flowers_train.yml \
  --log_to_file

集群 / 本地统一脚本：

CONFIG=/path/to/arrange_3_flowers_train.yml \
  bash workspace/example/run_oss_wandb_local.sh

单卡训练至少需要 48 GB 显存（448 分辨率）。多卡训练建议开启 FSDP。4 卡 × batch 4 × grad_accum 4 = 有效 batch 64。具体显存需求会受分辨率、相机数量、序列长度和 batch size 影响。

Checkpoint 与断点续训

单个 .safetensors 用于加载预训练权重（resume_from 指向 wall-oss-0.5/model.safetensors）；
完整恢复优化器、调度器和随机状态时，应将 checkpoint.resume_from 指向历史 Checkpoint 目录；
FSDP 产生分片权重时，推理前需要合并：

python scripts/merge_sharded_weights.py \
  /path/to/sharded_checkpoint \
  /path/to/merged_checkpoint

Checkpoint 输出目录示例：

/path/to/arrange_3_flowers_ckpt/
├── 3_2000/
├── 3_4000/
├── 3_50000/
│   ├── model.safetensors      # 约 17GB
│   ├── config.json
│   ├── config.yml             # 训练配置快照
│   ├── norm_stats.json
│   └── preprocessor_config.json
└── ...

训练结果检查

训练和验证 loss 是否异常；
是否出现 NaN、显存不足或数据加载错误；
Checkpoint、配置和归一化文件是否一并保存；
训练使用的相机、state 和 action 是否与真机运行一致；
是否记录代码版本、数据版本、随机种子和硬件环境。

默认训练参数参考

参数	默认值	配置项
单卡批次大小	4	`hyperparams.batch_size_per_gpu`
梯度累积步数	4	`hyperparams.gradient_accumulation_steps`
学习率	5e-5	`hyperparams.optimizer.learning_rate`
训练轮数	50	`hyperparams.num_epoch`
动作 horizon	32	`task.action_horizon`
FSDP 分布式训练	true	`distributed.use_fsdp`
Checkpoint 保存间隔	2000 步	`logging.save_interval`
数据加载 workers	0	`data.num_workers`

这些值来自插花任务示例配置，是复现实例的起点，不是所有任务的固定最优参数。

模型评估

模型评估位于训练之后、持续真机运行之前，回答两个问题：

模型是否学会了插花任务；
模型能否在目标机器人上正确、安全地运行。

评估顺序

Checkpoint 加载检查：模型、处理器、配置和归一化文件可完整加载。
数据回放 / 离线推理：在测试 episode 上运行，确认输入输出结构正确。
开环评估：对比预测动作与数据集真实动作，不向机器人执行。
输入输出对齐：检查相机（三视角）、状态、动作、坐标系、单位和频率。
推理性能：检查推理耗时、显存、吞吐和 action horizon（32 步）。
受控真机 Rollout：低速、限幅、短时，随时可急停；任务指令示例：arrange 3 flowers。
结果记录：统计成功、失败、超时和人工干预。

开环效果验证

先启动推理服务，再新开终端运行：

python scripts/draw_openloop_plot.py \
  --uri ws://127.0.0.1:44660 \
  --dataset-root /path/to/arrange_3_flowers_lerobot \
  --train-config /path/to/arrange_3_flowers_train.yml \
  --episode-indices 0,1,2 \
  --save-dir ./openloop_plots

结果会保存到 ./openloop_plots。检查重点不是曲线完全重合，而是：

动作维度、方向和范围合理；
抓取、移动、插入花瓶等关键阶段与演示大致一致；
无异常尖峰、持续饱和或明显延迟；
双臂夹爪与末端动作时序合理。

真机评估指标

任务成功率 / 任务进度：三朵花是否全部插好，或完成到哪个阶段。
完成时间：从任务开始到成功或停止。
失败类型：感知、抓取、轨迹、放置、超时、网络、系统等。
人工干预：急停、接管、重置或手动纠正。
推理耗时：单次或单个 action chunk 的耗时（warmup 后参考～0.2–0.3 s）。
控制稳定性：抖动、跳变、越界和动作不连续。

插花任务的成功标准可按「完成插花数量」定义。现阶段链路验收重点仍是「数据 → 训练 → 推理 → 真机执行是否正确」，不强制所有任务使用统一成功率门槛。

模型推理与真机运行

代码说明参考地址：https://github\.com/X\-Square\-Robot/wall\-x/blob/main/workspace/rtx5090/DEPLOY\.md

注意：真机推理之前需要将机器调整到初始姿态

腰高：0.35
头部：0.25

本节把推理和真机运行放在同一开发任务中。当前范围是启动推理服务、连接 Client、执行 action 并完成受控验证，不等同于具备完整的生产级容器部署、进程守护、监控、回滚和长期运维体系。

启动 WebSocket 推理服务

方式 A：一键脚本（RTX 5090 推荐）

# 1. 配置路径
cp workspace/rtx5090/env.example workspace/rtx5090/local/env.sh
# 编辑 local/env.sh，设置 CHECKPOINT_PATH 等

# 2. 启动
bash workspace/rtx5090/run_server.sh

方式 B：通用启动命令

export HOST=0.0.0.0
export ENABLE_FAST_PREPROCESS=false
export WALLX_VISION_ATTN_IMPLEMENTATION=flash_attention_2
export ENABLE_CUDA_GRAPH=1
export ENABLE_EXPERIMENTAL_ENGINE=1

bash scripts/run_serving.sh \
  --checkpoint-path /path/to/arrange_3_flowers_ckpt/3_50000 \
  --train-config-path /path/to/arrange_3_flowers_ckpt/3_50000/config.yml \
  --port 44660 \
  --cuda-id 0 \
  --robot-type ex001 \
  --serialize-actions \
  --enable-cuda-graph \
  --enable-experimental-engine \
  -- \
  --model-config.norm-key ex_normal

默认连接地址：

ws://<推理机IP>:44660

健康检查：

curl http://<推理机IP>:44660/healthz
# 期望输出: OK

--serialize-actions 返回机器人可直接执行的序列化动作（follow1_pos、follow2_pos 等）。开环评估时可去掉该参数，使用原始模型 action chunk。

进阶启动方式：

export ENABLE_CUDA_GRAPH=True
export ENABLE_EXPERIMENTAL_INFERENCE_ENGINE=True
export ENABLE_FAST_PREPROCESS=false

CKPT_PATH=/path/to/arrange_3_flowers_ckpt/3_50000

python -m wall_x._vendor.harrix.serving.launch_serving \
  --env X2ROBOT \
  --host 0.0.0.0 \
  --port 44660 \
  --serialize-actions \
  --enable-cuda-graph \
  --enable-experimental-engine \
  model-config:server-model-config \
  --model-config.checkpoint-path "$CKPT_PATH" \
  --model-config.train-config-path /path/to/arrange_3_flowers_train.yml \
  --model-config.action-horizon 32 \
  --model-config.robot-action-interpolate-multiplier 1 \
  --model-config.robot-action-end-ratio 1.0 \
  --model-config.robot-type ex001 \
  --model-config.norm-key ex_normal

插花任务使用 robot-type ex001（双臂 + 三相机），须与训练数据、checkpoint 中的 config.yml 及 SDK Adapter 一致，不能直接照搬其他机型示例值。

客户端 payload 示例（ex001 + base64 图像）

{
    "state": {
        "follow1_pos": [7维 float],   # 左臂位姿 + 夹爪
        "follow2_pos": [7维 float],   # 右臂位姿 + 夹爪
    },
    "views": {
        "camera_front": "<base64 JPEG>",
        "camera_left": "<base64 JPEG>",
        "camera_right": "<base64 JPEG>",
    },
    "instruction": "arrange 3 flower",
}

连接后服务端先发送 metadata（msgpack），客户端再发送 observation，服务端返回序列化动作。

真机运行流程

确认 Checkpoint、训练 YAML 和归一化文件匹配；
启动推理服务并完成一次健康检查；
在 SDK Client 中读取三相机图像与双臂状态；
构造与训练时一致的 observation（相机键名、state 维度）；
发送 observation 和任务文本 arrange 3 flower；
接收 action chunk；
完成反归一化、维度映射、限幅和时效检查；

通过 SDK 下发动作；

cd samples/quanta_x1
USE_MAP_NAVIGATION=1 bash scripts/start_sdk_ex001.sh 39.101.65.229 44660 \
  "arrange flower" \
  end_pose 8

当终端输出“Do you want to build new map?"时建议选择 n

持续检查机器人状态、急停、网络和模型耗时；
任务完成、超时或异常时停止。

运行安全

首次仅运行短时 episode；
使用低速度和小动作范围；
观察值过期或缺失时不继续推理；
推理超时、断连或 action 非法时立即停止；
机器人状态不允许控制时不下发动作；
保留物理急停和软件停止；
记录 Checkpoint、配置、任务、环境和失败原因。

真机部署检查清单

已制作 LeRobot v3 格式真机数据集（三相机 + 双臂 state/action）；
相机、state、action 字段映射及维度与训练配置一致；
已生成并绑定对应的归一化统计文件；
微调 Checkpoint 可以完整加载（model.safetensors 约 17GB）；
WebSocket 推理服务已在 ws://<IP>:44660 启动，/healthz 返回 OK；
开环绘图结果不存在明显动作尖峰、方向错误或持续饱和；
SDK Client 已配置限幅、超时、断连停止和急停；
首次真机验证采用低速、小范围和短 Episode；
RTX 5090 推理机上已设置 ENABLE_FAST_PREPROCESS=false。

本页内容