系列文章目录目录系列文章目录前言亮点一、安装1.1 配置 Hugging Face 令牌1.2 Kimodo 安装选项 1包安装1.3 Kimodo 安装选项 2源代码安装1.3.1 克隆 Kimodo 代码库1.3.2 选择安装方式1.4 在虚拟环境中安装1.4.1 创建环境1.4.1.1 使用 venv1.4.1.2 使用 Conda1.4.2 安装依赖项1.4.2.1 安装 PyTorch1.4.2.2 (可选) 克隆修改版 Viser 库1.4.3 安装 Kimodo1.5 使用 Kimodo-SMPLX 模型1.5.1 申请模型访问权限1.5.2 下载 SMPL-X 身体模型二、快速入门2.1 概述Kimodo 模型2.1.1 推荐硬件2.2 运行文本编码器服务2.3 命令行文本转动作生成2.4 交互式运动创作演示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 代码库的访问权限后请在此处创建访问令牌。然后在命令行中使用该令牌登录hf auth login或者将令牌粘贴到 ~/.cache/huggingface/token 文件中。如果您尚未安装 hf则需要先运行 pip install --upgrade huggingface_hub。1.2 Kimodo 安装选项 1包安装最简单的入门方式是直接将 Kimodo 作为软件包安装无需克隆代码库。这样您就可以生成动作并以黑盒模式运行演示程序。我们建议为安装创建一个新的 Python 环境例如使用 venv 或 condaconda create -n kimodo python3.10 conda activate kimodo为确保您使用的 PyTorch 版本与您的系统及 CUDA 版本兼容建议在安装 Kimodo 之前先手动安装最适合您的 PyTorch 版本。PyTorch 2.0 及更高版本均可满足需求。我们强烈建议使用支持 GPU 的 PyTorch 版本以便在合理的时间内生成运动轨迹。安装 Kimodo 基础包后您即可通过命令行生成运动轨迹pip install githttps://github.com/nv-tlabs/kimodo.git如果你还想运行交互式演示请使用以下命令来安装额外的依赖项pip install kimodo[all] githttps://github.com/nv-tlabs/kimodo.git现在应该可以开始使用 Kimodo 了。请查阅快速入门指南了解如何生成动作。如果您在使用上述安装方法时遇到软件包或系统兼容性问题建议您下载代码库并按照下文所述使用 Docker 进行安装。1.3 Kimodo 安装选项 2源代码安装如果您计划在 Kimodo 上进行构建或深入研究代码库建议您克隆并安装该代码库。1.3.1 克隆 Kimodo 代码库git clone https://github.com/nv-tlabs/kimodo.git cd kimodo1.3.2 选择安装方式Kimodo 可以通过在虚拟环境例如 conda中构建并运行或在 Docker 容器内进行安装。1.4 在虚拟环境中安装注意该仓库已在 Python 3.10 和 PyTorch 2.0 环境下经过测试。1.4.1 创建环境我们建议为 Kimodo 单独设置一个虚拟环境以避免依赖冲突。1.4.1.1 使用 venvpython -m venv venv source venv/bin/activate1.4.1.2 使用 Conda1.4.2 安装依赖项1.4.2.1 安装 PyTorch首先请确保安装的 PyTorch 版本与您的系统及 CUDA 版本兼容。我们建议使用 PyTorch 2.0 以上的版本。为了在合理的时间内生成运动轨迹我们强烈建议使用支持 GPU 的 PyTorch 版本。1.4.2.2 (可选) 克隆修改版 Viser 库交互式演示依赖于 Viser 的一个分支该分支实现了时间轴界面等功能。如果您希望安装可编辑的 Viser 版本即计划对其进行修改请使用以下命令将其克隆并安装到 kimodo 目录中git clone https://github.com/nv-tlabs/kimodo-viser.git pip install -e kimodo-viser1.4.3 安装 Kimodo接下来在仓库根目录下运行以下命令安装 Kimodopip install -e .这样就生成了一个可供编辑的 Kimodo 和 MotionCorrection 包的安装包。如果您打算使用演示版本可以改为运行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 目录的位置python -c from kimodo.assets import skeleton_asset_path; print(skeleton_asset_path(smplx22))二、快速入门本页面简要介绍了如何使用 Kimodo 生成动作。如需详细说明建议查阅各章节中提供的完整文档链接。在运行以下命令之前请按照安装指南在虚拟环境中或使用 Docker 安装 Kimodo。2.1 概述Kimodo 模型可以使用多种经过训练的 Kimodo 模型来生成动作这些模型根据骨骼和训练数据集的不同而有所差异。注意当您尝试通过命令行界面 (CLI) 或交互式演示生成动作时模型会自动下载因此无需手动下载。ModelSkeletonTraining DataRelease DateHugging FaceLicenseKimodo-SOMA-RP-v1SOMABones Rigplay 1March 16, 2026LinkNVIDIA Open ModelKimodo-G1-RP-v1Unitree G1Bones Rigplay 1March 16, 2026LinkNVIDIA Open ModelKimodo-SOMA-SEED-v1SOMABONES-SEEDMarch 16, 2026LinkNVIDIA Open ModelKimodo-G1-SEED-v1Unitree G1BONES-SEEDMarch 16, 2026LinkNVIDIA Open ModelKimodo-SMPLX-RP-v1SMPL-XBones Rigplay 1March 16, 2026LinkNVIDIA RD 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 调用时此方法效率更高因为它避免了每次都需要实例化大型文本编码器的操作。要启动文本编码器服务kimodo_textencoder该服务首次运行时需要一些时间来下载嵌入模型。建议在后台运行或在另一个终端中运行这样该终端将保持打开状态其他脚本仍可使用。如果您使用的是 Docker 环境也可以通过以下命令在容器中启动该服务docker compose up text-encoder注意在初始化文本编码器时transformers 库会报告 LLM2Vec 存在若干意外层和缺失层。这是预期的行为可以安全地忽略。2.3 命令行文本转动作生成CLI 文档您可以使用 generate 脚本通过命令行生成动作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 交互式运动创作演示演示文档该演示通过直观的控制界面支持文本提示和约束条件可轻松生成运动轨迹。可通过以下方式启动演示kimodo_demo该演示程序是一个将在 http://localhost:7860 上运行的 Web 应用。请在浏览器中打开此网址以访问界面。如果您使用的是 Docker可通过以下命令启动该演示程序docker compose up demo或者如果您想同时启动演示和文本编码服务详见下文请使用docker compose up2.4.1 Docker 的其他提示如果您在 Docker 容器中运行 Kimodo以下命令可能会对您有所帮助。在下面的示例命令中您也可以将 demo 替换为 text-encoder查看日志docker compose logs demo停用服务docker compose stop demo重启服务docker compose restart demo停止并移除所有内容docker compose down