Kimodo 入门教程（一）英伟达开源人形机器人动捕数据集训练运动学动作扩散模型

系列文章目录

前言

亮点

一、安装

[1.1 配置 Hugging Face 令牌](#1.1 配置 Hugging Face 令牌)

[1.2 Kimodo 安装选项 1：包安装](#1.2 Kimodo 安装选项 1：包安装)

[1.3 Kimodo 安装选项 2：源代码安装](#1.3 Kimodo 安装选项 2：源代码安装)

[1.3.1 克隆 Kimodo 代码库](#1.3.1 克隆 Kimodo 代码库)

[1.3.2 选择安装方式](#1.3.2 选择安装方式)

[1.4 在虚拟环境中安装](#1.4 在虚拟环境中安装)

[1.4.1 创建环境](#1.4.1 创建环境)

[1.4.1.1 使用 venv](#1.4.1.1 使用 venv)

[1.4.1.2 使用 Conda](#1.4.1.2 使用 Conda)

[1.4.2 安装依赖项](#1.4.2 安装依赖项)

[1.4.2.1 安装 PyTorch](#1.4.2.1 安装 PyTorch)

[1.4.2.2 (可选) 克隆修改版 Viser 库](#1.4.2.2 (可选) 克隆修改版 Viser 库)

[1.4.3 安装 Kimodo](#1.4.3 安装 Kimodo)

[1.5 使用 Kimodo-SMPLX 模型](#1.5 使用 Kimodo-SMPLX 模型)

[1.5.1 申请模型访问权限](#1.5.1 申请模型访问权限)

[1.5.2 下载 SMPL-X 身体模型](#1.5.2 下载 SMPL-X 身体模型)

二、快速入门

[2.1 概述：Kimodo 模型](#2.1 概述：Kimodo 模型)

[2.1.1 推荐硬件](#2.1.1 推荐硬件)

[2.2 运行文本编码器服务](#2.2 运行文本编码器服务)

[2.3 命令行文本转动作生成](#2.3 命令行文本转动作生成)

[2.4 交互式运动创作演示](#2.4 交互式运动创作演示)

[2.4.1 Docker 的其他提示](#2.4.1 Docker 的其他提示)

前言

Kimodo 是一个基于大规模（700 小时）商用友好型光学动作捕捉数据集训练而成的运动学动作扩散模型。该模型可生成高质量的人体和机器人 3D 动作，并通过文本提示以及一系列约束条件（如全身姿态关键帧、末端执行器位置/旋转、2D 路径和 2D 路点）进行控制。详情请参阅项目页面。

亮点

受控生成
- 结合文本提示与全身、根节点及末端执行器约束。
人类（类人）支持
- 同时提供数字人类和类人机器人的模型变体。
交互式演示
- 时间轴编辑、实时3D可视化及示例预设。

一、安装

注意：本项目将下载并安装额外的第三方开源软件项目。使用前请仔细阅读这些开源项目的许可条款。
注意：本仓库是在 Linux 系统上开发并主要进行测试的

安装 Kimodo 有两种方式：(1) 作为软件包安装，或 (2) 下载源代码并安装。两种方式都需要配置 Hugging Face 令牌，以便在生成时使用文本编码器。

1.1 配置 Hugging Face 令牌

Kimodo 文本编码器依赖于 gated meta-llama/Meta-Llama-3-8B-Instruct 模型，该模型要求：

您的 HF 账户已获得该模型页面的访问权限。
您需提供一个用于运行时的 HF 令牌

获得 Llama 代码库的访问权限后，请在此处创建访问令牌。然后在命令行中使用该令牌登录：

bash 复制代码

hf auth login

或者，将令牌粘贴到 ~/.cache/huggingface/token 文件中。如果您尚未安装 hf，则需要先运行 pip install --upgrade huggingface_hub。

1.2 Kimodo 安装选项 1：包安装

最简单的入门方式是直接将 Kimodo 作为软件包安装，无需克隆代码库。这样您就可以生成动作并以黑盒模式运行演示程序。

我们建议为安装创建一个新的 Python 环境，例如使用 venv 或 conda：

bash 复制代码

conda create -n kimodo python=3.10
conda activate kimodo

为确保您使用的 PyTorch 版本与您的系统及 CUDA 版本兼容，建议在安装 Kimodo 之前，先手动安装最适合您的 PyTorch 版本。PyTorch 2.0 及更高版本均可满足需求。我们强烈建议使用支持 GPU 的 PyTorch 版本，以便在合理的时间内生成运动轨迹。

安装 Kimodo 基础包后，您即可通过命令行生成运动轨迹：

bash 复制代码

pip install git+https://github.com/nv-tlabs/kimodo.git

如果你还想运行交互式演示，请使用以下命令来安装额外的依赖项：

bash 复制代码

pip install "kimodo[all] @ git+https://github.com/nv-tlabs/kimodo.git"

现在应该可以开始使用 Kimodo 了。请查阅快速入门指南，了解如何生成动作。

如果您在使用上述安装方法时遇到软件包或系统兼容性问题，建议您下载代码库，并按照下文所述使用 Docker 进行安装。

1.3 Kimodo 安装选项 2：源代码安装

如果您计划在 Kimodo 上进行构建或深入研究代码库，建议您克隆并安装该代码库。

1.3.1 克隆 Kimodo 代码库

bash 复制代码

git clone https://github.com/nv-tlabs/kimodo.git
cd kimodo

1.3.2 选择安装方式

Kimodo 可以通过在虚拟环境（例如 conda）中构建并运行，或在 Docker 容器内进行安装。

1.4 在虚拟环境中安装

注意：该仓库已在 Python 3.10+ 和 PyTorch 2.0+ 环境下经过测试。

1.4.1 创建环境

我们建议为 Kimodo 单独设置一个虚拟环境，以避免依赖冲突。

1.4.1.1 使用 venv

bash 复制代码

python -m venv venv
source venv/bin/activate

1.4.1.2 使用 Conda

1.4.2 安装依赖项

1.4.2.1 安装 PyTorch

首先，请确保安装的 PyTorch 版本与您的系统及 CUDA 版本兼容。我们建议使用 PyTorch 2.0 以上的版本。为了在合理的时间内生成运动轨迹，我们强烈建议使用支持 GPU 的 PyTorch 版本。

1.4.2.2 (可选) 克隆修改版 Viser 库

交互式演示依赖于 Viser 的一个分支，该分支实现了时间轴界面等功能。如果您希望安装可编辑的 Viser 版本（即计划对其进行修改），请使用以下命令将其克隆并安装到 kimodo 目录中：

bash 复制代码

git clone https://github.com/nv-tlabs/kimodo-viser.git
pip install -e kimodo-viser

1.4.3 安装 Kimodo

接下来，在仓库根目录下运行以下命令安装 Kimodo：

bash 复制代码

pip install -e .

这样就生成了一个可供编辑的 Kimodo 和 MotionCorrection 包的安装包。

如果您打算使用演示版本，可以改为运行：

bash 复制代码

pip install -e ".[all]"

这将安装我们的 Viser 分支（如果上一步尚未安装）以及 SOMA 身体模型。

接下来，请前往"快速入门"页面，通过生成一些动作来测试您的安装。

1.5 使用 Kimodo-SMPLX 模型

使用 Kimodo-SMPLX-RP-v1 模型需要进行一些额外的安装步骤。

1.5.1 申请模型访问权限

Kimodo 的 SMPL-X 版本是受限的，因此在尝试通过命令行界面 (CLI) 或演示环境生成动作之前，请前往 Hugging Face 模型页面申请访问权限。如安装流程所述，请确保您的 HF 令牌已正确配置，以便对模型访问进行身份验证。

1.5.2 下载 SMPL-X 身体模型

如果您希望在演示中可视化生成的 SMPL-X 动作，则需要下载 SMPL-X 身体模型。请访问 SMPL-X 网页，登录或创建账户后进入"下载"页面。点击"下载已移除发髻的 SMPL-X (NPZ)"，然后将 SMPLX_NEUTRAL.npz 文件复制到 Kimodo 代码库中，路径应为 kimodo/kimodo/assets/skeletons/smplx22/SMPLX_NEUTRAL.npz。

请注意，如果您是通过安装包方式安装 Kimodo 且未下载源代码库，则需通过运行以下命令查找 assets 目录的位置：

bash 复制代码

python -c "from kimodo.assets import skeleton_asset_path; print(skeleton_asset_path('smplx22'))"

二、快速入门

本页面简要介绍了如何使用 Kimodo 生成动作。如需详细说明，建议查阅各章节中提供的完整文档链接。

在运行以下命令之前，请按照安装指南在虚拟环境中或使用 Docker 安装 Kimodo。

2.1 概述：Kimodo 模型

可以使用多种经过训练的 Kimodo 模型来生成动作，这些模型根据骨骼和训练数据集的不同而有所差异。

注意：当您尝试通过命令行界面 (CLI) 或交互式演示生成动作时，模型会自动下载，因此无需手动下载。

Model	Skeleton	Training Data	Release Date	Hugging Face	License
Kimodo-SOMA-RP-v1	SOMA	Bones Rigplay 1	March 16, 2026	Link	NVIDIA Open Model
Kimodo-G1-RP-v1	Unitree G1	Bones Rigplay 1	March 16, 2026	Link	NVIDIA Open Model
Kimodo-SOMA-SEED-v1	SOMA	BONES-SEED	March 16, 2026	Link	NVIDIA Open Model
Kimodo-G1-SEED-v1	Unitree G1	BONES-SEED	March 16, 2026	Link	NVIDIA Open Model
Kimodo-SMPLX-RP-v1	SMPL-X	Bones Rigplay 1	March 16, 2026	Link	NVIDIA R&D Model

默认情况下，我们建议您使用基于完整的Bones Rigplay数据集（700小时动作捕捉数据）训练的模型来满足您的动作生成需求。基于BONES-SEED训练的模型仅使用了288小时的公开动作捕捉数据，因此性能稍弱，但可用于在同一数据集上对比您自己训练的模型。我们即将发布一个基准测试工具，以便您轻松对比基于BONES-SEED训练的动作生成模型。

2.1.1 推荐硬件

Kimodo 本地生成需要约 17GB 的显存，这主要归因于文本嵌入模型的体积。

该模型已在 GeForce RTX 3090、GeForce RTX 4090 和 NVIDIA A100 GPU 上进行了最全面的测试，但只要显存充足，其他新款显卡也应能正常运行。

2.2 运行文本编码器服务

动作生成依赖于对输入文本提示词的嵌入，该嵌入结果将成为 Kimodo 的输入。虽然单独运行 CLI 命令和演示程序也可行，但建议在后台启动文本编码器服务，以便所有动作生成请求共享该服务。当连续执行多次 CLI 调用时，此方法效率更高，因为它避免了每次都需要实例化大型文本编码器的操作。

要启动文本编码器服务：

bash 复制代码

kimodo_textencoder

该服务首次运行时需要一些时间来下载嵌入模型。建议在后台运行，或在另一个终端中运行，这样该终端将保持打开状态，其他脚本仍可使用。

如果您使用的是 Docker 环境，也可以通过以下命令在容器中启动该服务：

bash 复制代码

docker compose up text-encoder

注意：在初始化文本编码器时，transformers 库会报告 LLM2Vec 存在若干意外层和缺失层。这是预期的行为，可以安全地忽略。

2.3 命令行文本转动作生成

CLI 文档

您可以使用 generate 脚本通过命令行生成动作：

bash 复制代码

kimodo_gen "A person walks forward." \
    --model Kimodo-SOMA-RP-v1 \
    --duration 5.0 \
    --output output

--model 命令对应上表中的模型名称。生成的运动将使用 --output 指定的根名称，以 Kimodo 输出格式保存。有关所有生成参数的详细说明（包括如何生成带约束的运动），请参阅完整的 CLI 文档。

如果您使用 Docker 配置 Kimodo，则可以在 Docker 容器内运行生成操作，将 `kimodo_gen XXX` 替换为 `docker compose run --rm demo kimodo_gen XXX`。如果您需要多次运行生成操作，建议先启动 demo 容器（例如在另一个终端或后台运行），然后在其中使用 `docker compose exec demo kimodo_gen XXX` 执行命令。

2.4 交互式运动创作演示

演示文档

该演示通过直观的控制界面，支持文本提示和约束条件，可轻松生成运动轨迹。

可通过以下方式启动演示：

bash 复制代码

kimodo_demo

该演示程序是一个将在 http://localhost:7860 上运行的 Web 应用。请在浏览器中打开此网址以访问界面。

如果您使用的是 Docker，可通过以下命令启动该演示程序：

bash 复制代码

docker compose up demo

或者，如果您想同时启动演示和文本编码服务（详见下文），请使用：

bash 复制代码

docker compose up

2.4.1 Docker 的其他提示

如果您在 Docker 容器中运行 Kimodo，以下命令可能会对您有所帮助。在下面的示例命令中，您也可以将 demo 替换为 text-encoder：

查看日志：

bash 复制代码

docker compose logs demo

停用服务：

bash 复制代码

docker compose stop demo

重启服务：

bash 复制代码

docker compose restart demo

停止并移除所有内容：

bash 复制代码

docker compose down