GitHub 地址：https://github.com/mattzh72/articraft

简介

Articraft​ 是一个由牛津大学 VGG 团队开发的开源项目，它彻底改变了传统 3D 建模的工作流。该项目将大语言模型（LLM）与程序化生成相结合，把“制作带关节的可动 3D 模型”这一复杂任务，转化为“让 AI 编写构建程序”的代码生成问题。

传统的 3D 生成工具往往输出静态的“雕塑”，而 Articraft 专注于生成语义部件清晰、关节运动逻辑正确的物体（如能开关的门、能拉伸的抽屉）。它通过一个专为 LLM 设计的 SDK 和验证框架（Harness），引导 AI 在多轮迭代中产出可直接用于机器人仿真和物理引擎的高质量资产。基于此技术，团队还发布了包含上万模型的 Articraft-10K​ 数据集。

主要功能

1. Agentic 代码生成工作流

Articraft 的核心不是直接生成网格，而是驱动 LLM 编写 Python 代码（model.py）。AI 通过调用特定的 SDK 函数来定义部件（add_part）、组合几何体、指定关节类型（铰链、滑块等）并编写验证测试。系统随后编译并执行这段代码，生成最终的 3D 资产和 URDF 文件。

2. 验证与反馈闭环（Harness）

系统内置了强大的验证框架。它会自动检查生成的资产是否存在几何错误、部件穿透、关节超限等问题，并将结构化的错误反馈返回给 LLM，驱动其进行下一轮修正。这种“编码-编译-反馈”的循环确保了最终产出的模型在物理上是合理的。

3. 大规模数据集与本地查看器

项目提供了 Articraft-10K​ 数据集（需通过 Git LFS 下载），涵盖家具、工具、器械等 245 个类别。本地集成了一套基于 React 的 Web 查看器，支持在不启动专业 DCC 软件（如 Blender）的情况下，直接预览模型的层级结构、关节运动及渲染效果。

4. 灵活的外部 Agent 集成

即使没有 OpenAI 或 Anthropic 的 API Key，用户也可以利用 Claude Code、Cursor 等外部 AI 编程助手，按照项目提供的 EXTERNAL_AGENT_DATA.md规范，通过自然语言描述来生成和贡献模型数据。

安装与配置

环境准备

• Python 版本：建议使用 Python 3.10 或更高版本。

• Git LFS：由于模型数据文件较大，需安装并配置 Git LFS（用于拉取完整的记录载荷）。

安装步骤

1. 克隆仓库：

   git clone https://github.com/mattzh72/articraft.git
   cd articraft

2. 安装依赖：

   项目推荐使用 just命令工具或 uv进行环境管理。

   # 方式一：使用 just（需预先安装 just）
   just setup
   
   # 方式二：使用 uv 或 pip
   uv pip install -e .

3. 配置 API Key：

   复制 .env.example文件为 .env，并填入你的大模型 API 密钥（支持 OpenAI、Anthropic、Gemini 等）：

   OPENAI_API_KEY=sk-...
   ANTHROPIC_API_KEY=...

数据初始化（可选）

首次克隆时，data/records/目录下的具体模型文件通常被 Git LFS 排除在自动获取之外（仅下载元数据）。若需查看或编辑具体模型，需手动拉取 LFS 文件：

git lfs pull --include="data/records/**"

如何使用

1. 通过 CLI 生成首个模型

配置好环境后，使用 articraft generate命令即可开始生成：

# 基础生成（使用默认模型）
uv run articraft generate "Create a realistic articulated desk lamp with a weighted base and two hinged arms."

# 指定模型和成本上限
uv run articraft generate "a cabinet with two doors" --model gpt-4o --max-cost 1.0

生成过程中，终端会显示 LLM 的思考过程、代码验证状态及最终输出路径。

2. 浏览与查看

启动本地查看器来浏览生成的资产：

just viewer
# 或使用 uv
uv run articraft viewer

查看器会读取 data/records_index.jsonl构建索引。对于尚未下载具体文件（未 Hydrate）的记录，可以在界面中触发“Hydrate record”操作来拉取完整数据。

3. 派生与编辑（Fork）

如果你想基于现有模型进行修改，可以使用 fork命令：

uv run articraft fork data/records/<record_id> "make the handle longer and the base heavier"

这会在不修改原记录的前提下，创建一个新的子记录，非常适合进行迭代优化。

4. 外部 Agent 协作

对于使用 Claude Code 或 Cursor 的用户，可以直接向 AI 发送提示：

“请按照 EXTERNAL_AGENT_DATA.md的规范，为我创建一个逼真的、带铰链的笔记本电脑 3D 模型，并添加到 Articraft 数据集中。”

AI 会根据规范生成符合要求的 model.py代码和元数据文件，你只需将其放入 data/records/并提交即可。

应用场景实例（无代码）

场景一：机器人抓取仿真数据工厂

痛点：训练机器人“开柜门”或“拉抽屉”需要大量带正确关节定义的 3D 模型。手动在 Blender 中给每个柜子设置铰链和碰撞体极其耗时。

Articraft 方案：

1. 编写批量提示词（如“生成 50 种不同尺寸的带铰链门和滑轨抽屉的橱柜”）。

2. 使用 Articraft 的批处理模式自动运行，生成数千个模型。

3. 直接导出 URDF 或 OBJ+JSON 格式，无缝导入到 PyBullet、Isaac Sim 等仿真环境中。

4. 价值：将数月的建模工作压缩至几小时，为具身智能研究提供近乎无限的训练数据。

场景二：游戏道具的快速原型设计

痛点：独立游戏开发者需要设计一批“可破坏”或“可互动”的环境道具（如能打开的宝箱、可推动的杠杆），但缺乏 3D 美术资源。

Articraft 方案：

1. 输入“fantasy treasure chest with a hinged lid and metal brackets”。

2. 在本地查看器中检查生成的宝箱开合动画是否流畅。

3. 导出 GLTF 或 FBX 文件，直接导入 Unity 或 Unreal Engine，关节信息自动转换为引擎内的物理关节。

4. 价值：零美术基础也能快速产出程序化、可互动的游戏资产，极大降低原型开发门槛。

场景三：工业设计的自动化合规检查

痛点：工程师设计了一个机械臂关节，需要在仿真中验证其运动范围是否会导致部件碰撞。

Articraft 方案：

1. 将 Articraft 作为“验证器”集成到 CI/CD 流水线中。

2. LLM 根据设计图纸生成对应的 Articraft 测试代码。

3. 系统自动运行碰撞检测和运动学测试，输出结构化报告。

4. 价值：在物理原型制造前，提前发现设计缺陷，实现“设计即正确”。

数据协议与贡献

Articraft 鼓励社区贡献生成的数据。所有提交到项目的记录默认采用 Creative Commons Attribution 4.0 International (CC BY 4.0)​ 协议。这意味着你的贡献将被公开用于构建和评估机器学习模型。

GitHub 地址：https://github.com/mattzh72/articraft

项目主页与论文：https://articraft3d.github.io/