⚡

i4h工作流-微调Skill i4h-workflow-finetune

本技能提供了一套完整的i4h工作流，用于在LeRobot数据集上微调GR00T或openpi PI0策略，适用于医疗机器人（如手术机器人、超声扫描、移动操作等）的演示训练。涵盖从数据解析、环境预检、训练执行、参数配置到验证的各个阶段。关键词：医疗机器人、策略微调、GR00T、PI0、LeRobot、i4h、NVIDIA Isaac、演示学习、后训练、检查点评估、手术机器人、机器人工作流。

其他 0 次安装 0 次浏览 更新于 9/6/2026
名称 i4h-workflow-finetune
版本 “0.6.0”
描述 在LeRobot数据集上微调GR00T或openpi PI0策略。当被要求对演示数据进行微调、训练或后训练时使用；不用于评估检查点（使用[[i4h-workflow-validate]]）。
开源协议 Apache-2.0 metadata:
作者 “Isaac for Healthcare Team isaac-for-healthcare-support@nvidia.com” tags: - isaac-for-healthcare - i4h - agentic-workflow - finetune - training

i4h 工作流 — 微调

目的

在现有LeRobot数据集上微调GR00T或openpi PI0策略。当被要求对录制的演示进行微调、训练或后训练时使用。

基础代码

这些步骤基于i4h-workflows基础代码（workflows/agentic/目录树）。若要复用现有代码，请将I4H_WORKFLOWS设置为其路径（不再执行克隆）。否则，此操作会解析当前仓库，或克隆到~/i4h-workflows——自动选择该默认值，无需提示。在解析后的根目录下运行下面的所有命令：

# Resolve the i4h-workflows base code (provides workflows/agentic/).
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/agentic" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"
  [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

基本说明

  • 数据集路径必须是带有meta/info.json的现有LeRobot目录。
  • 训练支持由workflows/agentic/config/environments/<env>.yaml中的policy.train_module决定。值为null表示仅推理。
  • assemble_trocar 仅支持推理。

Stack Map

Env Stack CLI
scissor_pick_and_place gr00t_n15 i4h-agentic-gr00t-n15-train
locomanip_tray_pick_and_place gr00t_n16 i4h-agentic-gr00t-n16-train
locomanip_push_cart gr00t_n16 i4h-agentic-gr00t-n16-train
ultrasound_liver_scan openpi_pi0 i4h-agentic-openpi-pi0-train

N1.6 locomanip 环境共享 policy.locomanip.train。

预检

test -f "${DATASET_PATH}/meta/info.json"
nvidia-smi --query-gpu=name --format=csv,noheader | wc -l
workflows/agentic/policy/<stack>/run.sh --list-envs

运行

按顺序执行以下步骤。每一步都是独立的bash调用；变量保存在本地智能体的tmux会话中。

第1步 — 设置并解析数据集

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"
ENV_ID=scissor_pick_and_place
STACK_DIR=gr00t_n15
TRAIN_CLI=i4h-agentic-gr00t-n15-train
RUNS_ROOT="${REPO_ROOT}/workflows/agentic/runs"

# Point DATASET_PATH at a converted LeRobot dataset dir (absolute; must contain meta/info.json),
# produced by [[i4h-workflow-dataset-convert]]. List candidates:
#   find "${RUNS_ROOT}" "${HF_LEROBOT_HOME:-$HOME/.cache/huggingface/lerobot}" -name info.json -path '*/meta/*' -printf '%h
' | sed 's#/meta$##' | sort -u
DATASET_PATH="${DATASET_PATH:-}"
if [ ! -f "${DATASET_PATH%/}/meta/info.json" ]; then
  echo "finetune: set DATASET_PATH to a LeRobot dataset dir with meta/info.json (got '${DATASET_PATH:-<unset>}'). Candidates:" >&2
  find "${RUNS_ROOT}" "${HF_LEROBOT_HOME:-$HOME/.cache/huggingface/lerobot}" -name info.json -path '*/meta/*' -printf '%h
' 2>/dev/null | sed 's#/meta$##' | sort -u | head
  exit 1
fi

RUN_DIR="${RUNS_ROOT}/finetune_${ENV_ID}_$(date +%Y%m%d_%H%M%S)"
OUT="${RUN_DIR}/checkpoint"
export TMPDIR=/tmp   # short path: torch DataLoader FD-sharing socket must fit AF_UNIX's 108-byte limit
mkdir -p "${OUT}" "${RUN_DIR}/logs"
ln -sfn "${RUN_DIR}" "${RUNS_ROOT}/.latest"

第2步 — 训练

uv --directory "${REPO_ROOT}/workflows/agentic/policy/${STACK_DIR}" run "${TRAIN_CLI}" \
  --env "${ENV_ID}" \
  --dataset-path "${DATASET_PATH}" \
  --output-dir "${OUT}" \
  --max-steps 1000 \
  --save-steps 1000 \
  --num-gpus 1 \
  2>&1 | tee "${RUN_DIR}/logs/finetune.log"

Tyro 标志使用连字符格式（--max-steps，不是--max_steps）。

常用标志

  • --dataset-path PATH（必需）
  • --output-dir PATH
  • --base-model-path PATH_OR_REPO：覆盖YAML中的policy.model_repo
  • --max-steps N, --save-steps N
  • --batch-size N, --learning-rate FLOAT
  • --no-tune-visual — 冻结视觉骨干（仅训练动作头和投影器）：约2倍速度提升，约一半内存，较少过拟合。对于小数据集是好的默认选择；只有在数据量充足且存在真实视觉域差异时才解冻。
  • --num-gpus N — 不得超过可见GPU数量
  • --report-to tensorboard|wandb

验证

  • 检查点目录${OUT}/checkpoint-<N>应包含model-0000*-of-*.safetensors、experiment_cfg/、processor/。
  • 日志应包含train_loss行以及最终的'train_runtime': ...汇总。

先决条件

  • 已通过[[i4h-workflow-setup]]设置好工作流（对应stack的.venv必须存在）。
  • 一个带有meta/info.json的现有LeRobot数据集目录。
  • 支持训练的环境：workflows/agentic/config/environments/<env>.yaml中的policy.train_module非null（assemble_trocar仅推理）。
  • 至少一个可见GPU（--num-gpus不得超过可见GPU数量）。

限制

  • 仅推理环境（policy.train_module为null，例如assemble_trocar）无法进行微调。
  • 需要GPU；--num-gpus不得超过nvidia-smi可见GPU的数量。
  • N1.6 locomanip环境共享policy.locomanip.train。
  • 每个环境对应一个stack/CLI（见Stack Map）；数据集必须与该环境匹配。

故障排除

  • **错误：**训练CLI / 模块导入失败 - 原因：工作流未设置，stack的.venv缺失。解决方法：先运行[[i4h-workflow-setup]]。
  • **错误：**数据集路径被拒绝 / 缺少meta/info.json - 原因：--dataset-path不是有效的LeRobot目录。解决方法：指向转换后的LeRobot数据集（参见预检中的test -f）。
  • **错误：**环境仅推理 / 无训练支持 - 原因：该环境的policy.train_module为null。解决方法：从Stack Map中选择一个支持训练的环境。
  • **错误：**无法识别的标志，如--max_steps - 原因：Tyro标志使用连字符格式。解决方法：使用--max-steps格式。

最终响应

报告环境（env）、技术栈（stack）、数据集路径、输出检查点路径、train_loss汇总以及阻塞项。