运行千寻 Moz 机器人

Moz 机器人是由千寻智能（Spirit AI）推出的新一代高自由度智能机器人（参见 Moz Robot）。

本文档介绍：

1. 如何基于千寻开源数据集微调 PI05 base 模型，使微调后的模型能够操控 Moz 机器人；
2. 如何部署推理环境，并使用 Moz 机器人完成特定任务。

模型微调

环境安装

推荐使用 uv 的 Python 虚拟环境。

请下载TOS Browser，并联系千寻售后获取秘钥，下载源码。

安装依赖

cd openpi
GIT_LFS_SKIP_SMUDGE=1 uv sync
GIT_LFS_SKIP_SMUDGE=1 uv pip install -e .

# 可能需要 ffmpeg 库
sudo apt-get install -y ffmpeg

替换已安装的 transformers 库

uv pip show transformers
cp -r ./src/openpi/models_pytorch/transformers_replace/* .venv/lib/python3.11/site-packages/transformers/

准备官方 checkpoint 与数据集

下载官方 checkpoint

# 使用 uv run python xxx.py 执行
from openpi.shared import download
checkpoint_dir = download.maybe_download("gs://openpi-assets/checkpoints/pi05_base")
print(checkpoint_dir)

参考官方仓库中的 “Converting JAX Models to PyTorch” 章节，将该 JAX 模型转换为 PyTorch 模型。

下载数据集：用同样TOS秘钥下载Pi源码及千寻数据集。

计算数据集的统计信息（stats），训练时会用到：

默认数据集路径为 ~/.cache/huggingface/lerobot/spirit-ai/pickplace。 如需修改，请将 src/openpi/training/config.py 中 “pi05_moz” 对应的 TrainConfig 的 repo_id，从 spirit-ai/pickplace 改为实际数据集的绝对路径。

然后执行

python scripts/compute_norm_stats.py --config-name=pi05_moz

计算得到的 norm stats 会写入 openpi/assets/pi05_moz。如果 repo_id 指定为绝对路径，则 norm stats 会保存到 repo_id 指定的目录下。

P.S.: 若数据集较大，计算全部数据的 norm stats 耗时较长，在此情况下可以 sample 一定数量的 batch 进行 norm 参数的计算，而非使用全部数据集：

max_batches = 20000 // config.batch_size
limit = min(num_batches, max_batches)
for i, batch in enumerate(tqdm.tqdm(data_loader, total=limit, desc="Computing stats")):
    if i >= limit:
        break
    for key in keys:
        stats[key].update(np.asarray(batch[key]))

执行训练

单机 4 卡示例

CUDA_VISIBLE_DEVICES=1,2,3,4 uv run torchrun --standalone --nnodes=1 --nproc_per_node=4 scripts/train_pytorch.py pi05_moz --exp_name YOUR_EXP_NAME --data.repo-id "PATH_TO_YOUR_DATASET"

如果下载的 base 模型不在默认位置，可通过设置 TrainConfig 的 pytorch_weight_path 指定模型加载路径。

推理

环境安装

首先参考“模型微调”章节的环境安装部分，完成源码下载与依赖安装。

mozrobot SDK 安装

下载mozrobot SDK 0.1.0版本（参考Moz资源包页面），按照其文档进行配置与安装。

注意事项：

• 若要正确连接机器人，需要正确配置网络 IP 段并安装 ROS 2。
• 不建议将 mozrobot 安装到先前创建的 uv 虚拟环境中，可能存在依赖冲突。建议直接安装到系统 Python，或优先考虑使用 Docker 进行环境隔离。

执行推理

启动推理服务

cd openpi/
uv run scripts/serve_policy.py --env=MOZ --default_prompt='Pick up the marker pen.'

上述命令会加载 /openpi_assets/checkpoints/pi05_pickplace/ 下的模型。

如需指定自定义模型路径：

uv run scripts/serve_policy.py --default-prompt='Pick up the marker pen.' \
    policy:checkpoint \
      --policy.config=pi05_moz \
      --policy.dir=/openpi_assets/20251120_official_pi05_cleantable_iter3w/30000/

启动机器人推理

使用系统 Python 启动机器人推理。在此之前，请先完成必要的依赖安装：

cd openpi/
uv pip compile ./packages/openpi-client/pyproject.toml -o /tmp/requirements.txt
pip install -r /tmp/requirements.txt

pip install typing_extensions tyro

export PYTHONPATH=$(pwd):$(pwd)/packages/openpi-client/src/:$PYTHONPATH
python3 examples/moz1_real/main.py

参数说明

• args.host：推理服务的 IP；
• args.port：推理服务的端口；
• args.realsense-serials：Realsense 的序列号，依次为头部相机、左腕相机、右腕相机（具体参见 mozrobot SDK 文档）；
• args.structure：机器人构型，需要与实际机器人一致，通常为 wholebody_without_base；
• args.action-horizon：执行多少个 action 后（以机器人控制频率为准）触发下一次推理；
• args.max-episode-steps：允许执行的最大 action 步数。

基于 docker 容器的推理

镜像构建。构建镜像前，请将 mozrobot-0.1.2.zip 放到 thirdparty 目录下

docker compose -f examples/moz1_real/compose.yml build

启动容器

export SERVER_ARGS="--env=MOZ --default_prompt='Pick up the marker pen.'"
docker compose -f examples/moz1_real/compose.yml up

进入 moz1_real 镜像对应的容器

docker exec -it <container_name_of_moz1_real> bash

在容器内执行机器人推理

export PYTHONPATH=$(pwd):$(pwd)/packages/openpi-client/src/:$PYTHONPATH
python3 examples/moz1_real/main.py

常见问题说明

第一次给模型推理服务发送请求时出现超时问题

首次推理时服务会执行 torch.compile，可能导致第一次请求耗时较长。

建议等待片刻后再次向推理服务发送请求。

关于 action_horizon 的说明

当前模型一次推理返回 50 帧动作（30 Hz），通过插值方式可得到 200 帧动作（匹配机器人控制频率 120 Hz）。 建议将 args.action-horizon 参数设置在 100–200 之间。

如果机器人不动，或者动作异常

请优先根据 mozrobot SDK 文档排查：机器人数据是否正常回传、摄像头图像是否正常获取；随后检查数据处理流水线（pipeline），最后再定位到模型本身的问题。

建议从简单任务入手逐步验证。