NVIDIA/Isaac-GR00T
GitHub: NVIDIA/Isaac-GR00T
NVIDIA 推出的通用人形机器人视觉-语言-动作基础模型，支持零样本推理、自定义微调和多种硬件平台部署。
Stars: 6806 | Forks: 1150
## 目录
- [NVIDIA Isaac GR00T](#nvidia-isaac-gr00t)
- [GR00T N1.7 的新功能](#whats-new-in-gr00t-n17)
- [安装](#installation)
- [模型权重与具身标签](#model-checkpoints--embodiment-tags)
- [数据格式](#data-format)
- [推理](#inference)
- [微调](#fine-tuning)
- [评估](#evaluation)
- [贡献](#contributions)
- [许可证](#license)
- [引用](#citation)
## NVIDIA Isaac GR00T
NVIDIA Isaac GR00T N1.7 是一个用于通用人形机器人技能的开放式视觉-语言-动作 (VLA) 模型。这个跨具身模型接收多模态输入，包括语言和图像，以在各种环境中执行操作任务。
GR00T N1.7 在包含双臂、半人形和广泛人形数据集在内的多种机器人数据混合上进行训练。它可以通过后期训练针对特定的具身形式、任务和环境进行适配。
GR00T N1.7 可在 Apache 2.0 下完全商业化授权。它提供了与 N1.6 相当的性能，并且由于在预训练中加入了 2 万小时的 EgoScale 人类视频数据，其泛化能力和语言跟随能力得到了提升。
GR00T N1.7 的神经网络架构结合了视觉-语言基础模型和对连续动作进行去噪的扩散 Transformer 头。以下是架构示意图：
### 工作流程概述
1. **准备数据** — 收集机器人演示（视频、状态、动作）并将其转换为 [GR00T LeRobot 格式](#data-format)。其中包含了演示数据集以便快速测试。
2. **运行推理** — 在[预训练具身](#embodiment-tags)上使用基础模型尝试零样本推理，或使用[微调后的权重](#checkpoints)进行基准测试任务。
3. **微调** — 使用 [`launch_finetune.py`](#fine-tuning) 结合您自己的数据和模态配置，使模型适配您的机器人。
4. **评估** — 通过[开环评估](#open-loop-evaluation)进行验证，然后在[仿真基准测试](#benchmark-examples)中测试，或通过 [Policy API](getting_started/policy.md) 在真实硬件上测试。
5. **部署** — 将 `Gr00tPolicy` 连接到您的机器人控制器，可选择使用 [TensorRT](scripts/deployment/README.md) 进行加速。
## GR00T N1.7 的新功能
GR00T N1.7 在 N1.6 的基础上构建，采用了新的 VLM 骨干网络并进行了代码层面的改进。
1. **相对 EEF 动作空间** — N1.7 采用了在机器人和人类具身之间共享的相对末端执行器 (EEF) 动作空间。将动作表示为相对于当前位姿的增量（而不是绝对目标）提高了泛化能力，这是模型实现跨具身性能的关键因素。有关为您的机器人配置相对 EEF 的指南，请参见 [`getting_started/finetune_new_embodiment.md`](getting_started/finetune_new_embodiment.md)。
2. **人类视频预训练** — N1.7 在 2 万小时的 EgoScale 人类视频数据和多种机器人演示上进行了预训练。由于相对 EEF 动作表示在人类和机器人数据中是一致的，因此模型可以将从人类视频中学到的操作先验直接迁移到机器人控制中。
### 相较于 N1.6 的主要更改
- **新的 VLM 骨干网络：** Cosmos-Reason2-2B (Qwen3-VL 架构)，取代了 N1.6 中使用的 Eagle 骨干网络。支持灵活的分辨率，并以图像的原始宽高比进行编码，无需填充。
- 简化了数据处理流水线 (`processing_gr00t_n1d7.py`)。
- 增加了完整的流水线导出到 ONNX 和 TensorRT 的功能，并提高了运行频率。
## 安装
### 硬件要求
**推理：** 1 块具有 16 GB 以上显存的 GPU（例如 RTX 4090、L40、H100、Jetson AGX Thor/Orin、DGX Spark）。
**微调：** 建议使用 1 块或多块具有 40 GB 以上显存的 GPU。为了获得最佳性能，我们推荐使用 H100 或 L40 节点。其他硬件（例如 A6000）也可工作，但可能需要更长的训练时间。有关详细规格，请参见[硬件推荐指南](getting_started/hardware_recommendation.md)。
**各平台的 CUDA / Python：** dGPU 上使用 CUDA 12.8 和 Python 3.10；Jetson Orin 上使用 CUDA 12.6 和 Python 3.10；Jetson Thor 和 DGX Spark 上使用 CUDA 13.0 和 Python 3.12。各平台的安装脚本和 Dockerfile 位于 `scripts/deployment/` 目录下；有关完整矩阵，请参见[部署与推理指南](scripts/deployment/README.md)。
### 克隆仓库
GR00T 依赖于某些子模块。克隆时请包含它们：
**注意：** `git-lfs` 是下载 `/demo_data` 中的 parquet 数据文件所**必需**的。请在克隆前安装它：`sudo apt install git-lfs && git lfs install`。
```
git clone --recurse-submodules https://github.com/NVIDIA/Isaac-GR00T
cd Isaac-GR00T
```
如果您在克隆时未包含子模块，请单独初始化它们：
```
git submodule update --init --recursive
```
### 设置环境
GR00T 使用 [uv](https://github.com/astral-sh/uv) 进行快速、可重现的依赖项管理。请首先安装 uv：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
#### dGPU (x86_64) — 默认
安装 FFmpeg（`torchcodec` 即默认视频后端需要）：
```
sudo apt-get update && sudo apt-get install -y ffmpeg
```
创建环境并安装 GR00T：
```
uv sync --python 3.10
```
GPU 依赖项（flash-attn、TensorRT 等）已包含在默认安装中。
验证安装：
```
uv run python -c "import gr00t; print('GR00T installed successfully')"
```
有关避免系统级依赖冲突的容器化设置，请参见我们的 [Docker 设置指南](docker/README.md)。
## 模型权重与具身标签
### 权重
| 权重 | 类型 | 具身标签 | 描述 |
|------------|------|---------------|-------------|
| [`nvidia/GR00T-N1.7-3B`](https://huggingface.co/nvidia/GR00T-N1.7-3B) | 基础 | 参见[预训练标签](getting_started/policy.md#--embodiment-tag) | 基础模型（3B 参数） — 在预训练具身上进行零样本推理，或针对新任务进行微调 |
| [`nvidia/GR00T-N1.7-LIBERO`](https://huggingface.co/nvidia/GR00T-N1.7-LIBERO) | 微调 | `LIBERO_PANDA` | 在 [LIBERO](https://libero-project.github.io/) 基准测试 (Franka Panda) 上进行微调 |
| [`nvidia/GR00T-N1.7-DROID`](https://huggingface.co/nvidia/GR00T-N1.7-DROID) | 微调 | `OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT` | 在 [DROID](https://droid-dataset.github.io/) 数据集上进行微调 |
| [`nvidia/GR00T-N1.7-SimplerEnv-Bridge`](https://huggingface.co/nvidia/GR00T-N1.7-SimplerEnv-Bridge) | 微调 | `SIMPLER_ENV_WIDOWX` | 在 SimplerEnv Bridge (WidowX) 上进行微调 |
| [`nvidia/GR00T-N1.7-SimplerEnv-Fractal`](https://huggingface.co/nvidia/GR00T-N1.7-SimplerEnv-Fractal) | 微调 | `SIMPLER_ENV_GOOGLE` | 在 SimplerEnv Fractal (Google Robot) 上进行微调 |
### 具身标签
每次推理或微调命令都需要一个 `--embodiment-tag`。该标签决定了模型使用哪种模态配置（状态/动作键、归一化）。标签**不区分大小写**。
有关预训练和后训练标签的完整列表，请参见 [Policy API 指南 — 具身标签](getting_started/policy.md#--embodiment-tag)。
## 数据格式
GR00T 使用了一种 [LeRobot v2 数据集格式](https://github.com/huggingface/lerobot) 的变体，并附加了一个描述状态/动作/视频结构的 `meta/modality.json` 文件。数据集结构如下所示：
```
my_dataset/
meta/
info.json # dataset metadata
episodes.jsonl # episode index and lengths
tasks.jsonl # language task descriptions
modality.json # state/action/video key mapping (GR00T-specific)
data/chunk-000/ # parquet files (state, action per timestep)
videos/chunk-000/ # mp4 video files per episode
```
`modality.json` 映射了拼接的状态/动作数组如何拆分为命名字段（例如 `x`、`y`、`z`、`gripper`）以及有哪些可用的视频键。这就是具身标签用来解释数据的方式。
**包含的演示数据集**（开箱即用，无需下载）：
| 数据集 | 机器人 | 具身标签 | 用例 |
|---------|-------|---------------|----------|
| `demo_data/droid_sample` | DROID (3 个片段) | `OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT` | 零样本或微调推理 (DROID) |
| `demo_data/libero_demo` | LIBERO Panda (5 个片段) | `LIBERO_PANDA` | 使用微调权重进行推理 |
| `demo_data/simplerenv_bridge_sample` | WidowX (SimplerEnv Bridge) | `SIMPLER_ENV_WIDOWX` | 使用微调的 SimplerEnv Bridge 权重进行推理 |
| `demo_data/simplerenv_fractal_sample` | Google Robot (SimplerEnv Fractal) | `SIMPLER_ENV_GOOGLE` | 使用微调的 SimplerEnv Fractal 权重进行推理 |
| `demo_data/cube_to_bowl_5` | SO100 机械臂 (5 个片段) | `NEW_EMBODIMENT` | 微调自定义具身示例 |
| `demo_data/cube_to_bowl_5_with_mask` | SO100 机械臂 + 逐帧掩码 | `NEW_EMBODIMENT` | [掩码引导的背景抑制](examples/mask-guided-background-suppression/README.md)示例 |
**使用您自己的数据：** 将您的演示转换为上述格式。如果来自 LeRobot v3，请使用转换脚本：`python scripts/lerobot_conversion/convert_v3_to_v2.py`。有关 Schema 详细信息和示例，请参见完整的[数据准备指南](getting_started/data_preparation.md)。
## 推理
### 零样本推理（基础模型）
包含的 `demo_data/droid_sample` 数据集开箱即适用于基础模型 — 无需微调或下载权重：
```
uv run python scripts/deployment/standalone_inference_script.py \
--model-path nvidia/GR00T-N1.7-3B \
--dataset-path demo_data/droid_sample \
--embodiment-tag OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT \
--traj-ids 1 2 \
--inference-mode pytorch \
--action-horizon 8
```
这会在 2 个 DROID 片段上运行开环推理，将预测的动作与真实值进行比较。基础模型会在首次运行时自动从 HuggingFace 下载（约 6 GB）。
### 微调推理
对于后训练的具身形式，请使用微调后的权重。大多数微调权重（例如 DROID、SimplerEnv）具有扁平的文件结构，可以直接作为 HuggingFace 模型 ID 传入 — 无需手动下载：
```
uv run python scripts/deployment/standalone_inference_script.py \
--model-path nvidia/GR00T-N1.7-DROID \
--dataset-path demo_data/droid_sample \
--embodiment-tag OXE_DROID_RELATIVE_EEF_RELATIVE_JOINT \
--traj-ids 1 2 \
--inference-mode pytorch \
--action-horizon 8
```
某些权重（例如 LIBERO）使用嵌套文件夹结构，模型文件位于子文件夹中。HuggingFace 不支持在 `--model-path` 中使用嵌套仓库路径，因此您必须先下载：
\
--embodiment-tag NEW_EMBODIMENT \
--model-path \
--traj-ids 0 \
--action-horizon 16
```
这将在 `/tmp/open_loop_eval/traj_{traj_id}.jpeg` 处生成一张可视化图像，包含真实值与预测动作以及 MSE 指标。使用 `--save-plot-path ` 将图表保存到自定义位置。
### 闭环评估
使用服务器-客户端架构在仿真或真实硬件中测试您的模型：
```
# Start the policy server
uv run python gr00t/eval/run_gr00t_server.py \
--embodiment-tag NEW_EMBODIMENT \
--model-path \
--device cuda:0 \
--host 0.0.0.0 --port 5555
```
```
from gr00t.policy.server_client import PolicyClient
policy = PolicyClient(host="localhost", port=5555)
env = YourEnvironment()
obs, info = env.reset()
action, info = policy.get_action(obs)
obs, reward, done, truncated, info = env.step(action)
```
**使用 ReplayPolicy 进行调试：** 要在不使用训练模型的情况下验证您的环境设置，请使用 `--dataset-path `（省略 `--model-path`）启动服务器，以从数据集中重放记录的动作。
有关观测/动作格式、批量推理和故障排除，请参见完整的 [Policy API 指南](getting_started/policy.md)。
### 基准测试示例
我们支持使用服务器-客户端架构在公共基准测试上进行评估。策略服务器复用项目根目录的 uv 环境；仿真客户端有单独的设置脚本。
您可以使用[验证脚本](scripts/eval/check_sim_eval_ready.py)来验证所有依赖项是否已正确配置。
**零样本**（使用基础模型进行评估，无需微调）：
- [DROID](examples/DROID/README.md) — 真实世界 DROID 机器人（也可作为微调后的 `nvidia/GR00T-N1.7-DROID` 权重使用；`examples/DROID/README.md` 涵盖了这两种途径）
**微调**（使用微调权重进行评估）：
- [DROID](examples/DROID/README.md) — 真实世界 DROID 机器人，通过 `nvidia/GR00T-N1.7-DROID`
- [LIBERO](examples/LIBERO/README.md) — LIBERO 基准测试 (Franka Panda)
- [SimplerEnv](examples/SimplerEnv/README.md) — Google Robot (Fractal) 和 WidowX (Bridge)
- [SO100](examples/SO100/README.md) — SO100 自定义具身工作流
# 贡献
在抢先体验期间，当代码库趋于稳定时，我们暂不接受 Pull Request。如果您遇到问题或有建议，请在此仓库中提交一个 [Issue](https://github.com/NVIDIA/Isaac-GR00T/issues)。
# 支持
抢先体验期间的支持是尽力而为的。我们将继续迭代，朝着更稳定的正式发布 (GA) 版本迈进。
## 许可证
- **代码：** Apache 2.0 — 参见 [LICENSE](LICENSE)
- **模型权重：** [NVIDIA Open Model License](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/)
```
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
```
## 引用
[论文网站](https://research.nvidia.com/labs/lpr/publication/gr00tn1_2025/)
```
@inproceedings{gr00tn1_2025,
archivePrefix = {arxiv},
eprint = {2503.14734},
title = {{GR00T} {N1}: An Open Foundation Model for Generalist Humanoid Robots},
author = {NVIDIA and Johan Bjorck and Fernando Castañeda, Nikita Cherniadev and Xingye Da and Runyu Ding and Linxi "Jim" Fan and Yu Fang and Dieter Fox and Fengyuan Hu and Spencer Huang and Joel Jang and Zhenyu Jiang and Jan Kautz and Kaushil Kundalia and Lawrence Lao and Zhiqi Li and Zongyu Lin and Kevin Lin and Guilin Liu and Edith Llontop and Loic Magne and Ajay Mandlekar and Avnish Narayan and Soroush Nasiriany and Scott Reed and You Liang Tan and Guanzhi Wang and Zu Wang and Jing Wang and Qi Wang and Jiannan Xiang and Yuqi Xie and Yinzhen Xu and Zhenjia Xu and Seonghyeon Ye and Zhiding Yu and Ao Zhang and Hao Zhang and Yizhou Zhao and Ruijie Zheng and Yuke Zhu},
month = {March},
year = {2025},
booktitle = {ArXiv Preprint},
}
```
|
|
|
替代方案：pip install（不使用 uv）
如果您更倾向于使用 pip/conda 而不是 uv，请创建一个 Python 3.10 虚拟环境并安装： ``` python3.10 -m venv .venv && source .venv/bin/activate pip install -e . ``` 注意：GPU 依赖项（flash-attn、TensorRT）可能需要使用 pip 手动安装。`uv` 工作流会自动处理这些依赖。DGX Spark (已在 DGX Spark GB10 上测试)
``` bash scripts/deployment/spark/install_deps.sh source .venv/bin/activate source scripts/activate_spark.sh ``` 有关 Docker 和裸机详细信息，请参见 [Spark 设置指南](scripts/deployment/README.md#dgx-spark-setup)。Jetson AGX Thor (已在 JetPack 7.1 上测试)
``` bash scripts/deployment/thor/install_deps.sh source .venv/bin/activate source scripts/activate_thor.sh ``` 有关 Docker 和裸机详细信息，请参见 [Thor 设置指南](scripts/deployment/README.md#jetson-thor-setup)。Jetson Orin (已在 JetPack 6.2 上测试)
``` bash scripts/deployment/orin/install_deps.sh source .venv/bin/activate source scripts/activate_orin.sh ``` 有关 Docker 和裸机详细信息，请参见 [Orin 设置指南](scripts/deployment/README.md#jetson-orin-setup)。添加新的仿真基准测试
每个仿真基准测试都使用 `{prefix}/{task_name}` 格式（例如 `libero_sim/LIVING_ROOM_SCENE2_put_soup_in_basket`）的 gym env_name 注册其环境。评估框架使用前缀通过 [`gr00t/eval/sim/env_utils.py`](gr00t/eval/sim/env_utils.py) 中的映射查找相应的 `EmbodimentTag`。 要添加新的基准测试： 1. 在 `gr00t/eval/sim/env_utils.py` 中的 `ENV_PREFIX_TO_EMBODIMENT_TAG` 添加一个条目： ENV_PREFIX_TO_EMBODIMENT_TAG = { ... "my_new_benchmark": EmbodimentTag.MY_ROBOT, } 2. 如果基准测试有多个 env_name 前缀（例如 `my_benchmark_v1`、`my_benchmark_v2`），所有相关前缀**必须**映射到同一个 `EmbodimentTag`。 3. 在 `tests/gr00t/eval/sim/test_env_utils.py` 中添加相应的测试用例，并更新 `test_all_known_prefixes_present` 测试。标签：AI开发框架, Apex, CNCF毕业项目, DLL 劫持, Hugging Face, Isaac GR00T, NVIDIA Isaac, Physical AI, Vectored Exception Handling, VLA, 人工智能, 人形机器人, 具身智能, 凭据扫描, 半人形机器人, 双臂机器人, 多模态大模型, 大语言模型, 开源模型, 机器人, 机器人学, 机器人操作, 机器人数据集, 机器学习, 模型微调, 模型推理, 深度学习, 物理AI, 用户模式Hook绕过, 视觉语言动作模型, 计算机视觉, 请求拦截, 跨 embodiment, 逆向工具, 通用机器人