articraft

想象一下：如果 AI 不仅能生成一张 3D 图片，还能直接生成一个能动的、可交互的关节模型——台灯的两段灯臂能折叠、抽屉能被拉开、门能被推开——而且这些模型直接就能导入游戏引擎或仿真软件中使用，那会是什么体验？

Articraft 正是这样一套系统。它由来自牛津大学、FAIR（Meta）、上海人工智能实验室等顶尖机构的联合团队开发，将"关节 3D 资产"的生产变成了一条由大语言模型驱动的代码生成流水线。2026 年 5 月正式发布在 arXiv，随即在 GitHub 上获得超过 1200 颗星。## 背景：从人工建模到 AI 生成

关节 3D 资产（Articulated 3D Assets）是机器人、游戏和 VR 领域的基础单元。一个典型的关节资产包含几何形状（几何体网格）、语义部件（底座、臂、头部）和物理关节（铰链、滑轨、球窝）三部分。传统方式靠美术手工建模，每个资产的制作周期从数小时到数天不等，且难以规模化。

Articraft 的出现直接颠覆了这个流程。它受 Agent 系统启发，将整个资产生成变成了一段迭代式代码生成循环：LLM 编写 Python 代码 → 执行生成资产 → 验证反馈 → 修改重试，直到产出合格的关节模型。背后的论文是 arXiv:2605.15187。

图1：Articraft 方法概览## 核心功能：代码即资产，模型即评测

专用 SDK：让 AI 学会"造物"

Articraft 提供了一套专为 LLM 设计的领域特定 SDK，位于 sdk/ 目录。它封装了构建关节资产所需的全部原语：

• 几何定义：sdk/_core/v0/mesh.py 封装了 trimesh、manifold3d、cadquery 等底层库，提供 MeshPart、Box、Cylinder 等几何基元
• 关节合成：支持 RevoluteJoint（铰链）、PrismaticJoint（滑轨）、BallJoint（球窝）等关节类型
• 材质与 PBR：支持物理材质定义，可导出为游戏引擎兼容格式
• 测试框架：内置测试 API，LLM 可以为每个资产编写验证脚本（功能测试、关节范围测试）

这套 SDK 的设计原则是对 LLM 友好：文档丰富（sdk/_docs/），有大量示例（sdk/_examples/），API 命名清晰，LLM 可以通过阅读文档自主学习如何构建复杂的关节结构。

执行 Harness：编译即验证

Agent 生成代码后，不是简单执行，而是通过 agent/harness/ 体系进行编译式验证：

• harness_compile.py：将生成的代码编译为中间表示，检查几何合法性
• harness_codec.py：处理序列化/反序列化，确保资产可持久化
• harness_guidance.py：提供结构化引导信号（碰撞检测、体积合理性、关节范围）

每轮迭代后，Agent 会收到一个结构化的反馈报告，知道哪个部件几何不对、哪个关节范围超限，然后针对性地修复。这套机制让生成质量远超简单的"一次生成"方案。

批量数据集：Articraft-10K

项目还配套发布了 Articraft-10K，一个包含超过 10,000 个关节 3D 资产的大规模数据集，覆盖日常物品、家具、玩具、电子产品、机械零件等类别。每个资产都附带关节标注、语义分割和 PBR 材质，可直接用于下游任务。

可视化 Viewer：所见即所得

生成后的资产可以通过内置的 Three.js Web Viewer（viewer/）实时查看和交互：

• 拖拽旋转、缩放查看
• 点击关节查看活动范围
• 查看几何结构和材质信息
• 查看生成过程的 trace 记录

图2：基于 Game Boy 参考图生成的 3D 资产## 架构解析：模块化设计

Articraft 采用清晰的模块化架构：

技术栈方面，后端以 Python 3.11/3.12 为核心，通过 uv 管理依赖；主要库包括 cadquery（参数化 CAD）、trimesh（网格处理）、manifold3d（网格修复）、python-fcl（碰撞检测）、networkx（图结构）、scipy（科学计算）、BM25S（语义搜索）。前端使用 React 19 + TypeScript + Three.js + Vite 构建，提供沉浸式 3D 查看体验。

LLM 支持覆盖主流提供商：OpenAI（GPT-4o/5.5）、Anthropic（Claude）、Google（Gemini）、阿里（通义千问/DashScope），通过统一适配器注入（agent/models.py）。

重要限制：Python 3.13 暂不支持（cadquery 和 vtk 尚未提供兼容轮）。## 上手体验：门槛低，但需要 API Key

Articraft 的安装非常友好。克隆仓库后运行 just setup 即可完成全部依赖配置（通过 uv），然后：

# 配置 API Key（编辑 .env 文件）
OPENAI_API_KEY=sk-...

# 一句话生成关节资产
uv run articraft generate "Create a realistic articulated desk lamp"

# 可选：指定模型和预算
uv run articraft generate --max-cost-usd 1.5 "Create a compact desk fan"

# 开启本地可视化
just viewer

不过有几个实际门槛需要注意：

• API 费用：每次生成消耗 LLM token，一个高质量资产大约 0.5-2 美元
• Python 版本：必须用 3.11 或 3.12，3.13 用户需要降级或等待兼容
• 本地存储：Git LFS 管理数据集，首次 clone 需要 uv run articraft data hydrate --all 拉取资产

对于没有 API Key 的用户，项目还支持外部 AI Agent 模式（Claude Code、OpenAI Codex、Cursor），可以直接让 Agent 接管生成任务，参考 docs/codex_plugin.md。## 安全注意：代码执行风险

README 中有一个醒目的安全提示：Articraft 会执行生成的 model.py 文件。这意味着当你输入一个提示词后，系统实际上是在执行一段由 LLM 动态生成的 Python 代码。虽然有沙箱和 harness 验证，但生成的代码仍然在本地 Python 环境中运行。

项目自身提供了 SECURITY.md 策略，并使用 pre-commit hooks 进行代码质量检查，但用户仍需确保只处理来自可信来源的生成记录和 model 脚本。## 行业意义：大规模关节资产的开源破局

关节 3D 资产的高质量大规模数据集一直是 robotics、graphics、VR 领域的稀缺资源。传统上这些数据靠人工标注和建模，成本极高。Articraft-10K 的出现填补了这一空白——超过 10,000 个关节资产，全部带有关节标注和物理属性，可直接用于训练操纵策略、渲染管线或仿真环境。

更重要的是，Articraft 展示了** Agent 系统 + 专用工具 + 迭代反馈这一范式在 3D 资产生成上的可行性。与传统的 diffusion-based 3D 生成不同，它走的是代码生成**路线，产出的资产是精确的几何表示而非概率采样结果。这让它在需要精确物理属性的工业场景（机器人仿真、CAD 数据增强）中具有独特优势。

从增长曲线看，项目 2026 年 5 月发布至今（6 月中旬）已获 1284 星，考虑到关节资产生成的垂直领域特性，这个增速相当可观。作者团队来自牛津、FAIR、清华、上交等顶级机构，后续维护和迭代值得期待。