Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Articraft

用于可扩展关节式 3D 资产生成的智能体（Agentic）系统。

论文 | 项目主页 | 数据集

Articraft 将关节式 3D 资产的创建转变为由 LLM 驱动的程序化、代码生成工作流。它现在是一个本地优先（local-first）的运行框架：本仓库包含生成/查看器逻辑，而公开数据集单独托管于 mattzh72/articraft-data.

安全提示： Articraft 通过将生成记录的 model.py 文件作为 Python 代码执行来编译和检查这些记录。仅运行来自可信来源的生成记录和模型脚本。

---

快速入门

1. 前置要求

• 推荐使用 Python 3.12（或 3.11）。注意：目前不支持 3.13+。
• uv，用于极快的 Python 包管理。
• just 作为命令运行器。
• npm（可选，但本地查看器前端需要）。

2. 安装配置

在仓库根目录运行：

just setup

若从其他工作目录进行安装，请传入仓库根目录：

just setup ./path/to/checkout

Articraft 将记录存储在 git 忽略的数据根目录中。默认为 <repo-root>/data。要浏览已发布的数据集，请克隆 mattzh72/articraft-data 并将 Articraft 指向它：

git clone https://github.com/mattzh72/articraft-data.git ../articraft-data
export ARTICRAFT_DATA_DIR="$(cd ../articraft-data && pwd)"
uv run articraft status
uv run articraft library check --require-records

你也可以通过 --data-dir 显式指定任意数据文件夹。

3. 添加 API 密钥

打开 .env 并设置一个或多个提供商密钥（例如 OPENAI_API_KEY、GEMINI_API_KEYS、ANTHROPIC_API_KEYS、DASHSCOPE_API_KEY）。

没有 API 密钥？ 没关系。你可以改用 Claude Code、Codex 或 Cursor 等外部 AI 智能体。有关 Codex 配置（包括如何添加 Codex 插件），请参阅 Codex 插件配置。然后将智能体指向本仓库并提示：

"在 Articraft 中创建一个逼真的关节式 [object name]。请遵循 EXTERNAL_AGENT_DATA.md。"

4. 创建资产

使用 articraft generate 直接从提示词生成你的第一个模型：

uv run articraft generate "Create a realistic articulated desk lamp with a weighted base, two hinged arms, and an adjustable lamp head."

若不指定覆盖项，当 .env 中存在时将使用其中的 ARTICRAFT_MODEL 和 ARTICRAFT_THINKING_LEVEL，否则使用 --model gpt-5.5-2026-04-23 --thinking-level high。你可以更改模型和上限：

uv run articraft generate --max-cost-usd 1.5 "Create a compact desk fan with adjustable tilt."

要从参考图像生成，请参阅 图像条件生成。

5. 打开查看器

浏览你刚生成的对象。可使用以下命令启动本地查看器 API 和 React 前端：

just viewer

要显式浏览外部数据文件夹：

uv run articraft viewer --data-dir /Users/mzhou/articraft-data

6. 编辑现有资产

当你要修改现有记录时，可对其进行分叉（fork）：

uv run articraft fork <record_id> "make the handle longer"

分叉会创建新的子记录，且父记录保持不变。有关模型选项和历史查看，请参阅 编辑现有记录。

---

本地库

使用精简的库界面来检查和维护数据文件夹：

uv run articraft library list
uv run articraft library rebuild-manifest
uv run articraft library check --require-records
uv run articraft library set-category <record_id> <category_slug>

数据使用与许可
向 Articraft 项目贡献数据即表示你确认并同意：你的提交将用于构建、评估和改进机器学习模型，并可能作为 Articraft 数据发布的一部分公开发布。你明确同意所有贡献的数据均在 Creative Commons Attribution 4.0 International (CC-BY 4.0) 许可下发布。

---

文档与高级用法

• 架构与项目结构
• Qwen / DashScope 快速入门
• Codex 插件配置
• 编辑现有记录
• 图像条件生成
• 贡献规范与工作流
• 安全策略

引用

@article{zhou2026articraft,
  title     = {Articraft: An Agentic System for Scalable Articulated 3D Asset Generation},
  author    = {Zhou, Matt and Li, Ruining and Lyu, Xiaoyang and Song, Zhaomou and Huang, Zhening and Zheng, Chuanxia and Rupprecht, Christian and Vedaldi, Andrea and Wu, Shangzhe},
  journal   = {arXiv preprint arXiv:2605.15187},
  year      = {2026}
}

本仓库在 Apache-2.0 License 许可下发布。