BrickGPT

从文本生成物理稳定且可搭建的积木结构
ICCV 2025（最佳论文，马尔奖）
Ava Pun*， Kangle Deng*， Ruixuan Liu*， Deva Ramanan， Changliu Liu， Jun-Yan Zhu
卡内基梅隆大学

---

这是 BrickGPT 的官方仓库，它是首个能够根据文本提示生成物理稳定的玩具积木模型的方法。

结果

由人类组装的生成积木结构示例：

带有纹理和颜色的积木模型示例：

安装

先决条件

• Llama-3.2-1B-Instruct： BrickGPT 基于 meta-llama/Llama-3.2-1B-Instruct 进行微调，该模型属于受控访问模型。请先 申请访问权限，然后生成一个 Hugging Face 用户访问令牌，并将其设置为环境变量：export HF_TOKEN=<your_token>。运行代码时，模型将自动下载。
• Gurobi（可选但推荐）： 运行稳定性分析需要使用 Gurobi 的许可证。学术用户可以从 Gurobi 官网 申请免费许可证；获得许可证后，请将其放置在您的 主目录 或其他 推荐位置。
  • 如果您无法使用 Gurobi，可以使用 --use_gurobi False 选项来运行代码，此时将采用一种更简单但准确性较低的基于连通性的方法，而非基于物理的稳定性分析。

作为独立项目安装

本仓库使用 Python 项目管理工具 uv。要将本仓库作为独立项目安装，请先完成所有先决条件。然后：

1. 克隆仓库：git clone https://github.com/AvaLovelace1/BrickGPT.git && cd BrickGPT。
2. (可选，运行 infer 脚本和纹理化功能时必需) 按照以下步骤安装 ImportLDraw，这是渲染积木结构可视化效果所必需的：
   • 使用 git submodule update --init 初始化 ImportLDraw 子模块。
   • 下载此 背景 exr 文件，并将其放置在 ImportLDraw/loadldraw 子目录中。
   • 下载 LDraw 部件库，并将其解压到您的 主目录： (cd ~ && wget https://library.ldraw.org/library/updates/complete.zip && unzip complete.zip)。
     • 如果您希望将 LDraw 部件库放在其他目录，请设置环境变量 LDRAW_LIBRARY_PATH，指向 ldraw 目录的路径：export LDRAW_LIBRARY_PATH=path/to/ldraw。
3. 最后，安装 uv，并运行 uv sync 创建一个包含所有依赖项的 Python 虚拟环境。Python 依赖项定义在 pyproject.toml 中。

作为包安装

要将本仓库作为包安装到您自己的 Python 项目中，请先完成所有先决条件。然后，如果您使用 uv：

uv add "https://github.com/AvaLovelace1/BrickGPT.git"

或者如果您使用 pip：

pip install "https://github.com/AvaLovelace1/BrickGPT.git"

交互式推理

Gradio 演示

Gradio 演示在此处可用。 其源代码位于子目录 src/demo 中。

命令行界面 (CLI)

您可以通过命令行运行 BrickGPT 推理，命令如下：

uv run infer

该脚本会启动一个交互式会话，您可以输入提示并从模型中获取响应。模型权重将自动从 Hugging Face 下载。

如果您希望使用不同的模型权重进行推理，可以使用 --model_name_or_path 选项指定。有关完整选项列表，请参阅 uv run infer -h。

示例交互

以下是使用 infer 脚本的示例交互：

> uv run infer
请输入提示，或按回车退出：一张桌子，具有平坦的矩形桌面，由四条均匀分布的腿支撑。
请输入保存输出图像的文件名（默认为 output.png）：output.png
请输入生成种子（默认为 42）：42
正在生成...
设置参数 Username
学术许可证——仅限非商业用途——有效期至 2026 年 2 月 19 日
--------------------
生成完成，耗时 63.53 秒。
总砖块数：59
总拒绝砖块数：98
拒绝原因：{'collision': 5, 'already_rejected': 93}
总重试次数：4
结果已保存到 /home/apun/BrickGPT/output.txt、/home/apun/BrickGPT/output.ldr 和 /home/apun/BrickGPT/output.png
--------------------
请输入另一个提示，或按回车退出：

将生成三个输出文件：output.png、output.txt 和 output.ldr。

output.png 包含生成的积木结构渲染图像：

output.txt 以逐砖文本格式记录积木结构，每行格式为 hxw (x,y,z)，表示高度为 h、宽度为 w 的砖块位于位置 (x,y,z)：

1x2 (16,18,0)
1x2 (16,13,0)
2x2 (0,18,0)
2x2 (0,13,0)
1x2 (16,18,1)
[...]

最后，output.ldr 以 LDraw 格式存储积木结构，可使用任何兼容 LDraw 的软件打开。

运行纹理化

子目录 src/texture 包含根据砖块设计生成 UV 纹理或每块砖颜色的代码。 要运行纹理化，请进入 src/texture 目录，并按照该目录下的 README.md 文件中的说明操作。

运行网格转砖块

子目录 src/mesh2brick 包含将 3D 对象网格转换为砖块结构的代码。 要运行网格转砖块，请进入 src/mesh2brick 目录，并按照该目录下的 README.md 文件中的说明操作。

运行微调

BrickGPT 是通过对 Llama-3.2-1B-Instruct 模型在自定义砖块结构数据集 StableText2Brick 上进行微调而创建的，该数据集已被转换为指令格式。我们使用了 Hugging Face 的 TRL 结合 Accelerate 库来进行微调。

要复现微调过程，首先使用 uv sync --extra finetuning 安装额外的 Python 依赖包。然后按照以下步骤操作：

1. 使用 uv run prepare_finetuning_dataset --input_path AvaLovelace/StableText2Brick --output_path [FINETUNING_DATASET_PATH] 准备用于微调的砖块结构数据集。这会将数据集转换为 LLaMA 微调所需的指令格式。
   • 如果您希望使用自己的砖块结构数据集进行微调，请将 AvaLovelace/StableText2Brick 替换为您数据集的路径。该数据集应包含 “captions” 和 “bricks” 两个字段。“bricks” 字段应包含论文中描述的文本格式的砖块结构，“captions” 字段则应包含对该砖块结构的一个或多个描述。
2. 将预训练的 Llama-3.2-1B-Instruct 模型 下载到某个目录 [PRETRAINED_DIR] 中。 重要提示： 请用 finetuning_config_files 目录中的 config.json、special_tokens_map.json 和 tokenizer_config.json 文件替换原有文件。这样做是为了将 pad_token 设置为不同于 eos_token，从而解决一个微调过程中可能出现的问题——模型无法正确学习输出 EOS 标记。
3. 使用 uv run accelerate config 初始化 Accelerate 配置文件。
4. 使用 uv run ./scripts/finetune.zsh [PRETRAINED_DIR] [OUTPUT_DIR] [RUN_NAME] [FINETUNING_DATASET_PATH] 进行微调。微调后的模型将保存到 [OUTPUT_DIR]/[RUN_NAME] 目录下。

许可证

BrickGPT 模型、StableText2Brick 数据集以及 BrickGPT 代码的大部分内容均采用 MIT 许可证 许可。以下子模块可能采用不同的许可证：

• ImportLDraw：用于可视化砖块结构，我们使用了 ImportLDraw，其许可证见 LICENSE。
• FlashTex：用于纹理和着色，我们使用了 FlashTex，其许可证见 LICENSE。

引用

如果您发现本仓库对您的研究有所帮助，请引用以下文献。

@inproceedings{pun2025brickgpt,
    title     = {从文本生成物理稳定且可搭建的砖块结构},
    author    = {Pun, Ava 和 Deng, Kangle 和 Liu, Ruixuan 和 Ramanan, Deva 和 Liu, Changliu 和 Zhu, Jun-Yan},
    booktitle = {ICCV},
    year      = {2025}
}

致谢

我们感谢 Minchen Li、Ken Goldberg、Nupur Kumari、Ruihan Gao 和 Yihao Shi 提供的讨论与帮助。
同时，我们也感谢 Jiaoyang Li、Philip Huang 和 Shobhit Aggarwal 开发的双臂机器人系统。
本研究部分得到了 Packard 基金会、思科研究资助以及亚马逊教师奖的支持。此外，还得到了卡内基梅隆大学制造未来研究所通过 Richard King Mellon 基金会提供的资助支持。KD 获得了微软研究院博士生奖学金的支持。

我们的代码库基于多个优秀的开源项目：Hugging Face 的 TRL、Accelerate 以及 ImportLDraw。

BrickGPT 快速上手指南

BrickGPT 是首个能够从文本提示生成物理稳定且可搭建的乐高积木结构模型的 AI 工具（ICCV 2025 最佳论文）。本指南将帮助你快速在本地部署并运行该模型。

环境准备

系统要求

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL2)
• Python: 推荐 Python 3.10+
• 包管理器: uv (项目依赖管理工具)

前置依赖与账号配置

1. Hugging Face 账号与 Token:

   • BrickGPT 基于 Llama-3.2-1B-Instruct 微调，该模型受访问限制。
   • 访问 Llama-3.2-1B-Instruct 页面 申请访问权限。
   • 生成 User Access Token，并在终端设置环境变量：

     export HF_TOKEN=<your_token>
     

2. Gurobi 求解器 (可选但推荐):

   • 用于进行精确的物理稳定性分析。学术界可申请免费许可证。
   • 下载并安装 Gurobi，将许可证文件 (gurobi.lic) 放置在用户主目录或 Gurobi 推荐的默认位置。
   • 若无 Gurobi: 运行时需添加 --use_gurobi False 参数，将使用基于连通性的简化分析方法（精度略低）。

3. 渲染依赖 (仅用于生成可视化图片):

   • 若需生成 .png 渲染图，需配置 ImportLDraw 和 LDraw 零件库（详见安装步骤中的可选部分）。

安装步骤

本项目推荐使用 uv 进行依赖管理。

1. 克隆仓库

git clone https://github.com/AvaLovelace1/BrickGPT.git && cd BrickGPT

2. (可选) 配置渲染环境

若只需生成积木结构数据 (.ldr/.txt) 而无需渲染图片，可跳过此步。若需渲染图片：

# 初始化子模块
git submodule update --init

# 下载背景贴图并放置到指定目录
# 请手动下载 https://drive.google.com/file/d/1Yux0sEqWVpXGMT9Z5J094ISfvxhH-_5K/view?usp=share_link 
# 并将文件重命名为 background.exr 放入 ImportLDraw/loadldraw 目录

# 下载 LDraw 零件库到主目录 (国内网络不佳建议使用代理或寻找国内镜像源)
cd ~
wget https://library.ldraw.org/library/updates/complete.zip
unzip complete.zip
# 若解压后目录名为 ldraw，则无需额外配置；否则需导出变量：
# export LDRAW_LIBRARY_PATH=/path/to/ldraw
cd -

3. 安装依赖

安装 uv 工具（如未安装）：

curl -LsSf https://astral.sh/uv/install.sh | sh

同步项目依赖并创建虚拟环境：

uv sync

基本使用

安装完成后，即可通过命令行交互式地生成积木结构。

运行推理

在终端执行以下命令启动交互会话：

uv run infer

使用示例

启动后，按照提示输入文本描述。以下是一个完整交互流程示例：

> uv run infer
Enter a prompt, or <Return> to exit: Table featuring a flat rectangular surface over four evenly spaced legs.
Enter a filename to save the output image (default=output.png): output.png
Enter a generation seed (default=42): 42
Generating...
--------------------
Finished generating in 63.53s.
Total # bricks: 59
Saved results to output.txt, output.ldr, and output.png
--------------------
Enter another prompt, or <Return> to exit: 

输出文件说明

程序将生成三个文件：

• output.png: 积木结构的渲染图像。
• output.txt: 积木结构的文本描述格式（每行格式为 高 x 宽 (x,y,z)）。
• output.ldr: LDraw 格式文件，可使用任何兼容 LDraw 的软件（如 Stud.io, Blender+ImportLDraw）打开和编辑。

高级选项

若需指定本地模型路径或禁用 Gurobi，可使用：

uv run infer --model_name_or_path ./local_model_path --use_gurobi False

更多参数请运行 uv run infer -h 查看。