Kimodo.cpp：本地运行 NVIDIA 文本转动作，没有显卡也行

本文中使用的工具

你输入「一个人做旋转武术踢腿」，就能得到一段可用的动画，在自己的机器上完成，不需要 Python 环境，也不联网。这就是 NVIDIA 的动作扩散模型 Kimodo，现在有人把它移植到了 C++ 和 GGML 上，可以在 Vulkan 或普通处理器上运行，占用内存不到 2 GB。

我花了一天时间在 Windows 上从零安装、生成片段，并把结果套到 Mixamo 骨骼和虚幻引擎里。这篇指南是我踩过的所有坑，包括最花时间、任何 README 里都没写的两件事：你到底被允许使用哪些模型，以及为什么整件事的瓶颈是硬盘而不是显卡。

整套流程一句话说清

文本提示 → kimodo.cpp 在 Vulkan 或 CPU 上运行（低于 2 GB，约 20 秒实际算力）→ GLB → 两个脚本送上虚幻 mannequin，或用名称映射送上 Mixamo 骨骼 → 成品动画。SOMA 和 G1 检查点采用 NVIDIA Open Model License，允许商业使用。

1. Kimodo 是什么，C++ 移植改变了什么

NVIDIA 在 2026 年 3 月发布了 Kimodo。这是一个运动学动作扩散模型，用 700 小时可商用的光学动捕数据训练，能把文本提示和稀疏的运动学约束转化为 3D 人体与仿人机器人动作。它提供三种骨骼格式：NVIDIA 自家的 SOMA 参数化人体、Unitree G1 仿人机器人，以及 SMPL-X。

最初的版本是一个 PyTorch 项目。你得先把完整的 CUDA 环境搭起来才能生成一个片段，对于机器是为 3D 工作而不是为机器学习配置的人来说，这是一道真实的门槛。

kimodo.cpp 是原生的 C++ 和 GGML 移植版。它加载 GGUF 权重，在 Vulkan 或处理器上运行，并附带一个小巧的本地网页界面。生成时不需要 Python，不需要 CUDA，也不联网。故事就这么简单，但意义比听上去更大，因为它把 Kimodo 从「搞机器学习的人才会跑的东西」变成了「在你工作站上直接打开的东西」。

自带的网页界面。模型选择器、提示词、帧数、实时骨架预览和一个 Download GLB 按钮，全部由本地服务提供。

2. 授权状况，8 月 26 日刚刚变过

这是大多数文章写错的部分，因为它最近才变，而且是同时朝两个方向变的。

移植版最初附带转换好的 SMPL-X 权重。那些权重已被撤下。作者注意到该检查点上游的 NVIDIA 授权明确禁止分发衍生模型，于是撤掉了 GGUF、清单和校验和。取而代之的模型卡片把原因讲得很清楚，而不是留下一个莫名其妙的 404，这一点比我预期的更让我欣赏。

几乎在同一时刻，另外四个检查点以完全不同的授权上线了，移植版也加上了对它们的支持。

模型	骨骼	授权	商业使用
SOMA RP v1.1	SOMA，30 关节	NVIDIA Open Model	允许
SOMA SEED v1.1	SOMA，30 关节	NVIDIA Open Model	允许
G1 RP v1	Unitree G1，34 关节	NVIDIA Open Model	允许
G1 SEED v1	Unitree G1，34 关节	NVIDIA Open Model	允许
SMPL-X RP v1	SMPL-X，22 关节	NVIDIA Internal Scientific R&D	仅限研究

如果你打算发布成品，请用 SOMA 或 G1

SMPL-X 检查点被限制在内部、非生产性研究范围内，且不可再分发。你仍然可以自己在 Hugging Face 上接受 NVIDIA 的授权条款，然后用仓库里的转换脚本在本地转换权重，但这并不赋予你商业权利。可以放进产品里的是 SOMA 和 G1 检查点。

界面在这件事上很坦诚，这是我没料到一个周末项目会做到的。选一个模型，它会在你生成任何东西之前告诉你适用哪种授权。

模型选择器会打印骨骼、上游检查点和授权条款。非商业模型这一行显示的是警告。

3. 你真正需要什么样的硬件

要求很低，而且这个「低」值得理解，而不只是照表读一遍。

资源	最低	宽裕
可用磁盘	25 GB	35 GB，放在 NVMe 硬盘上
系统内存	4 GB	32 GB，并参见第 5 节
显存（GPU 路径）	1.2 GB	2 GB
处理器	2 核	6 核

无论 GPU 还是处理器，任何配置下峰值内存都低于 2 GB。控制项是 KIMODO_TEXT_LAYER_CHUNK，它接受的数字是 层数，不是 GB：chunk 2 占 1.2 GB 显存，chunk 4 占 1.8 GB，默认的 chunk 8 占 3.5 GB。调大它不会让速度变快，因为无论 chunk 多大，编码器每次运行都只读一遍。

硬下限大约在 1.3 GB。嵌入表是一块 1.05 GB 的单一分配，在任何 chunk 设置下都无法拆分，低于这个值程序根本无法启动。

显卡的帮助比你以为的小得多

在作者的测试机上，RTX 5090 笔记本版生成三秒片段用了 25.9 秒，16 核处理器用了 33.7 秒，Intel Arc 核显用了 32.5 秒。旗舰显卡和处理器之间只有 1.3 倍差距。工作量集中在读取 15.2 GB 的文本编码器，而不是算力。显卡的价值体现在高去噪步数上，而不是更长的片段。

4. 在 Windows 上安装

项目文档写的是 Linux。Windows 可以用，CMake 文件里也有明确的 MSVC 分支，但有四个地方能让你白白花掉一小时。下面是精简版，完整流程可以在本节末尾下载。

安装工具链，然后打开一个新终端

Git、带 C++ 工作负载的 Visual Studio Build Tools、Vulkan SDK，如果你想用网页界面还需要 Go。

winget install Git.Git
winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --includeRecommended"
winget install KhronosGroup.VulkanSDK
winget install GoLang.Go

VC.CMake.Project 这个组件不是可选的。少了它你会拿到编译器但没有 CMake 和 Ninja，而随后出现的错误信息里完全不会提到这一点。然后关掉所有终端：Vulkan 安装程序设置的 VULKAN_SDK 是机器级的，已经打开的终端永远看不到它。

连同子模块一起克隆

git clone --recurse-submodules https://github.com/localai-org/kimodo.cpp
cd kimodo.cpp

GGML 是一个子模块。普通克隆会把它留空，出于同样的原因，以 ZIP 形式下载仓库完全没法用。

打两个源码补丁，然后构建

在 src/denoiser.cpp、src/generate.cpp 和 src/llm_tokenizer.cpp 里加上 #include <stdexcept>，并把 src/llm_text_encoder.cpp 里的 path.c_str() 改成 path.string().c_str()。这两处改动在任何平台上都是正确的，只是还没有合并到上游。然后在运行过 vcvars64.bat 的终端里：

cmake -S . -B build-win -G Ninja -DCMAKE_BUILD_TYPE=Release -DKIMODO_ENABLE_VULKAN=ON -DKIMODO_BUILD_TESTS=OFF
cmake --build build-win

下载权重

文本编码器是所有模型共用的，所以只需一次性下载 15.2 GB。每个动作模型在此之上只有约 1.13 GB。

pip install huggingface_hub
hf download LocalAI-io/Llama-3-Kimodo-GGML --local-dir . --include "generated/llm2vec-text-bundle/*"
hf download LocalAI-io/Kimodo-SOMA-RP-v1.1-GGML --local-dir . --include "models/*"

四个开放授权模型全部加上大约只需 4.5 GB，而不是四倍的 17 GB，因为编码器是共用的。

一个让我损失一小时的静默失败

如果某个 Hugging Face 仓库在上游被清空了，就像 SMPL-X 那个一样，那么带 --include 的 hf download 会匹配不到任何文件，并且以成功状态退出。没有错误，没有文件，退出码为零。我的安装脚本报告一切正常，直到生成失败我才发现模型没下来。永远要检查 .gguf 是否真的落到了 models\ 里。

下载完整的 Windows 安装指南

每一条命令、两处源码补丁及其对应的错误信息、全部环境变量，以及一张把每个症状对应到真实原因的排错表。这是在一台完全没有装编译器的机器上实际做完之后写的。

kimodo-windows-setup.md

5. 生成你的第一个片段

命令行参数是位置式的，而 GGML 的 DLL 位于构建目录的 bin 文件夹里，而不是在可执行文件旁边。忽略这一点，程序会立刻退出且没有任何输出，看上去和崩溃一模一样，实际上是 Windows 加载 DLL 失败。

Command Prompt

set PATH=%CD%\build-win\bin;%PATH%
build-win\kmd-generate.exe models\kimodo-soma-rp-v1.1-f32.gguf generated\llm2vec-text-bundle prompt.txt 90 20 41 out

这是 30 fps 下的 90 帧，也就是三秒，20 个去噪步数，种子 41。如果想用网页界面：

go run ./demo -addr 127.0.0.1:8094 -generator build-win/kmd-generate.exe

有两个数字决定成品质量。帧数在 300 帧左右、也就是十秒以内能保持连贯。到 400 帧片段开始抖动，到 600 帧会在大约第 300 帧之后垮成噪声。有点反直觉的是，越短的片段动作越有力：同一条提示词在 120 帧下比在 300 帧下更利落、更有运动感，因为模型会去填满多出来的时间，而不是把同一个动作做得更用力。

步数指去噪次数，20 对草稿和成品都够用。成本是线性的，所以 100 步要花五倍的代价却看不出提升。自带的界面目前在 demo/index.html 里把它写死成了 100，在认真使用之前值得先改成 20。

为什么第一次运行要好几分钟，问题不在模型

每次生成都会读取 15.2 GB 的编码器。如果你的文件缓存放不下，这个读取每一次都会重复。

在我的机器上，Ryzen 7 7800X3D、31 GB 内存、权重放在 SATA 固态硬盘上，三秒片段耗时 399 秒。其中大约 380 秒是磁盘读取，只有 10 秒是 CPU。RTX 4070 SUPER 全程空闲。硬盘的速度是 40 MB/s，而 15.2 GB 按 40 MB/s 算正好是 380 秒，数字完全对得上。

6. 把动作套到真正的骨骼上

生成只是简单的那一半。这个移植版之所以对 3D 美术师而不只是对研究者有意思，是因为它的输出几乎不用折腾就能落到普通角色骨骼上。

网页界面上有一个 Download GLB 按钮。演示服务器自己构建 glTF，所以你拿到的文件在 Blender 里打开就已经带好了骨骼层级和关键帧。对大多数工作来说这就是全部答案，下面所有格式细节都可以跳过。

五个 Mixamo 骨骼，五条提示词，一个模型。这里没有任何一帧是手动做的。

SOMA 在这里成了一个意外的好运。它完全没有使用 SMPL-X 的命名约定。它的 30 个关节叫 Hips、Spine1、LeftShoulder、LeftForeArm 等等，几乎就是 Mixamo 的命名习惯。大多数骨骼只要加上 mixamorig: 前缀就能对应上，别的什么都不用做。

腿是个陷阱，名字撞车了

SOMA 的 LeftLeg 是大腿。Mixamo 的 mixamorig:LeftLeg 是小腿。正确的对应是 SOMA LeftLeg 映射到 mixamorig:LeftUpLeg，SOMA LeftShin 映射到 mixamorig:LeftLeg。只加前缀的映射会让角色的膝盖从胯部开始弯，重定向看起来不对时第一个要检查的就是这里。

虚幻这边我已经不再手动做了。下面有一个两段式脚本工具，把一个片段目录丢进去，最后直接在 mannequin 上得到烘焙好的 Anim Sequence。三种骨骼都不用配置，因为关节数量本身就能确定是哪一种。

第一步：片段转文件，在你自己的电脑上

纯 Python 3.8 或更高版本。不需要 Blender，不需要额外的包。指向 Kimodo 写出的那个文件夹，你就得到一个 .glb。

python kimodo_to_glb.py path/to/clip
python kimodo_to_glb.py clips/* --outdir glb

它在写出文件之前会自检：用刚生成的文件重建姿势，再和输入对比，所以坐标轴搞反或者四元数分量顺序写错，会在这一步被抓住，而不是拖到虚幻里才暴露。它打印的数字应该在 1e-08 附近。

第二步：文件转角色，在虚幻内部

打开 Output Log，把底部的输入框从 Cmd 切换到 Python，然后粘贴：

py "C:/path/to/unreal_retarget.py" "C:/path/to/walk_150.glb"

这会导入文件、构建 IK Rig 和 IK Retargeter、应用下面那两处修正、烘焙，并在 /Game/Kimodo/Retargeted/ 留下一个 Anim Sequence。把 mannequin 拖进关卡，把 Animation Mode 设成 Use Animation Asset，选中那个序列即可。传多个路径可以批量处理，最后再加一个 Skeletal Mesh 路径就能换成别的角色。

它会逐个片段汇报结果，不用你自己肉眼判断：

kick_120: SMPL-X, 22 joints
    9 chains mapped, 19 left at rest (Root, LeftThumb, ...)
    reach 102 cm to 95 cm, arms corrected by up to 48 deg
    arms match 0.998 (worst lowerarm_r), pelvis 93 cm, lowest toe -1 cm,
    travelled 123 cm over 4.0 s

arms match 表示角色手臂的指向与源动作手臂指向的吻合程度，在整个片段上采样。高于 0.95 就算好。lowest toe 应该接近零：明显大于零角色会浮空，明显小于零则会陷进地面。

两处修正，以及手工搭重定向为什么少了它们就会出问题

源骨架有一半在地面以下。Kimodo 把胯部放在原点，腿垂在下面，所以骨架一开始就沉在地板里，重定向器没有剩余的垂直余量。脚本会按静止姿势的腿长把它抬起来。注意是静止姿势，不是动画第一帧：否则一个以蹲姿开场的片段会被烘焙成站直的。

两边的静止姿势不一致。mannequin 的静止姿势是 A-pose，Kimodo 不是。放着不管，重定向器会把这个差值当成动作，整个片段里手臂的位置都是错的。脚本会分别测量两者并按手臂段逐级抵消，先父级后子级，通常相当于 45 到 55 度。

要留意的是 G1

三种骨骼都能重定向到 mannequin，但 Unitree G1 是机器人。它没有锁骨、脖子和头，所以角色上那四条链会保持静止姿势；而且它把每侧髋部拆成三个单轴关节，mannequin 只有一个，因此髋部旋转会部分丢失。手臂和腿则完全没问题。SOMA 和 SMPL-X 可以完整映射。

重定向并不局限于人类。这只生物由与上面那些 Mixamo 角色完全相同的 30 关节输出驱动。

一次批量运行。每个角色都有自己的提示词，提示词渲染在角色上方，方便你读出文本到动作的对应关系。

如果你已经有 SMPL-X 的重定向代码，它会失效

原始输出是两个 float32 文件：local_rotations_xyzw.f32 形状为 [FRAMES, JOINTS, 4]，以及 root_positions.f32 形状为 [FRAMES, 3]。公开的格式表写的是 22 个关节，那只适用于 SMPL-X。SOMA 是 30 个，G1 是 34 个。

一段 90 帧的 SOMA 片段正好是 90 x 30 x 4 x 4 = 43,200 字节。用 22 关节的步长去读，不会有异常也不会有警告，只会得到一段像是骨骼在抽搐的动画。请根据文件大小推算关节数，不要写死。

下载工具与格式笔记

两个脚本、一个示例片段（让你不用先生成任何东西就能测试虚幻那一半），以及笔记：完整的 30 关节 SOMA 层级与父级索引、包含无法直接对应骨骼在内的完整 Mixamo 名称映射、四元数顺序的坑，以及 Blender 的操作流程。

kimodo_to_glb.py unreal_retarget.py 重定向笔记示例片段

看看这些 3D AI 工具的真实排名

Kimodo 生成的是动作，不是网格。流程中模型那一侧，可以看我们的盲测 Arena，它让各个生成器在匿名对局中互相较量，按投票而不是按宣传来排名；以及排行榜，它汇总社区在网格质量、低模和贴图上的评分。

小结

阶段	代价	说明
安装工具链	约 30 分钟，约 3 GB	Build Tools、Vulkan SDK、Go
构建	约 2 分钟	先打两个单行源码补丁
权重	15.2 GB + 每个 1.13 GB	编码器为所有模型共用
生成（缓存已热）	约 20 秒算力	另加磁盘读取，参见第 5 节
重定向到 Mixamo	几分钟	名称映射，加上腿部那个修正

重点不在于「有了一个文本转动作的模型」。重点在于这一个现在能跑在你已经拥有的硬件上，授权允许你发布成果，而且一个下午就能落到 Mixamo 骨骼上。最让我意外的是瓶颈竟然是一次磁盘读取而不是显卡，这意味着对认真做这件事的人来说，最便宜的升级是一块 NVMe 硬盘，而不是更好的 GPU。

如果你想了解通向这一步的其余流程，我们还有这些指南：完整的 AI 3D 角色流程、非人形角色的 AI 绑定，以及 HY-Motion，另一个值得了解的文本转动画模型。

常见问题

Kimodo 可以不用显卡运行吗？

可以。设置 KIMODO_BACKEND=cpu 即可在处理器上运行。整个流程的瓶颈是读取 15.2 GB 的文本编码器，而不是算力，所以在作者的测试机上，RTX 5090 生成三秒片段也只比 16 核处理器快约 1.3 倍。官方标注的最低配置是 2 个核心。

Kimodo.cpp 需要多少显存？

在任何配置下峰值内存都低于 2 GB。控制项是 KIMODO_TEXT_LAYER_CHUNK：chunk 2 占用 1.2 GB，适合 2 GB 显卡；chunk 4 占用 1.8 GB；默认的 chunk 8 占用 3.5 GB。

Kimodo 生成的动画可以商用吗？

取决于你用的检查点。SOMA 和 G1 模型以 NVIDIA Open Model License 发布，允许商业使用。SMPL-X 检查点适用的是 NVIDIA Internal Scientific Research and Development Model License，仅限内部非生产性研究，且禁止再分发。发布任何成果前先确认你用的是哪一个模型。

为什么第一次生成这么慢？

每次运行都会从磁盘读取 15.2 GB 的文本编码器。如果文件缓存放不下，这个读取会在每次生成时重复。在一台 Ryzen 7 7800X3D、权重放在 SATA 固态硬盘上的机器上，三秒片段耗时 399 秒，其中约 380 秒是磁盘读取，只有 10 秒是 CPU 时间。把权重放到 NVMe 硬盘上，并在生成前释放内存。

换成 SOMA 之后我的重定向脚本为什么输出乱码？

关节数量变了。SMPL-X 是 22 个关节，SOMA 是 30 个，G1 是 34 个，而原始输出格式本身不会告诉你是哪一种。用 22 关节的步长去读 SOMA 文件不会报错，只会静默出错。请根据文件大小推算关节数，不要写死。