BrickGPT

一句话生成能真实拼搭、站得稳的积木模型

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署数字人3D 🍴 复刻 114 🐛 待处理 3 👀 关注 21

访问官网 ↗ GitHub ↗

GitHub 星标 ★ 1733

维护状态较活跃

是否开源开源

定价模式 🏷️完全免费开源代码，免费使用

项目数据

分类数字人3D

开发团队AvaLovelace1

官网地址https://avalovelace1.github.io/BrickGPT

GitHubhttps://github.com/AvaLovelace1/BrickGPT

定价模式🏷️完全免费

价格说明开源代码，免费使用

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议MIT

主要语言Python

技术栈/模型generative-ai,lego

GitHub 星标★ 1733

上线时间2025-03-23 00:00:00

代码更新2026-10-23

仓库体积247.2 MB

本站数据更新2026-10-31

维护状态较活跃

收录时间2026-10-31

浏览次数0

项目介绍

BrickGPT 是 ICCV 2025 最佳论文的官方开源实现，首个能从文本提示直接生成物理稳定玩具积木模型的生成式方法。项目解决的核心问题是：普通文本生成3D模型往往只追求外观相似，生成的积木结构容易倒塌、无法真实拼搭。BrickGPT 将积木建模为离散砖块序列，通过自回归方式逐块生成，并在生成过程中引入物理稳定性约束，使输出模型既能贴合文本描述，又能在真实世界中稳定站立。仓库提供完整训练与推理代码、数据处理流程和评估脚本，基于 Python 实现，适合研究文本到结构化3D生成、积木设计自动化及物理约束生成的研究者与开发者复现和二次开发。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-10-31 · 当前星标 ★ 1733

技术标签

generative-ai

使用教程

难度：进阶约 30 分钟部署方式：本地安装 7 步

环境要求

Python 环境及 uv 包管理器（README 使用 uv 管理项目）
已在 Hugging Face 申请并通过 meta-llama/Llama-3.2-1B-Instruct 访问权限，并生成 access token
可选：Gurobi（README 标注为可选依赖）
可选：ImportLDraw 与 LDraw 零件库，用于积木结构可视化渲染
微调需额外依赖与可用的 GPU 训练环境

安装与启动步骤

1克隆仓库

把官方仓库拉到本地并进入项目目录，后续命令都在该目录执行。
```
git clone https://github.com/AvaLovelace1/BrickGPT.git && cd BrickGPT
```
2配置模型令牌

模型为 gated 模型，先在 Hugging Face 页面申请访问权并生成 token，再写入环境变量。
```
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
```
3安装依赖环境

先按 uv 官方文档安装 uv，然后在仓库根目录同步依赖，依赖定义在 pyproject.toml 中。
```
uv sync
```
4初始化渲染子模块

可选步骤，运行 infer 脚本与纹理生成需要；拉取 ImportLDraw 子模块。
```
git submodule update --init
```
5下载零件库

可选步骤，下载 LDraw 零件库并解压到家目录；如需换路径用 LDRAW_LIBRARY_PATH 指定。
```
(cd ~ && wget https://library.ldraw.org/library/updates/complete.zip && unzip complete.zip)
```

6准备微调数据集

先执行 uv sync --extra finetuning 装微调依赖，再把 StableText2Brick 转成指令格式。

uv sync --extra finetuning
uv run prepare_finetuning_dataset --input_path AvaLovelace/StableText2Brick --output_path /your/path/finetuning_dataset

7开始微调

先用 uv run accelerate config 初始化配置，再用脚本训练，模型存到输出目录下的运行名子目录。
```
uv run accelerate config
uv run ./scripts/finetune.zsh /your/path/llama-3.2-1b /your/path/output brickgpt_run /your/path/finetuning_dataset
```

关键配置

配置项	必填	说明	示例
`HF_TOKEN`	是	Hugging Face 访问令牌，用于自动下载 gated 的 Llama-3.2-1B-Instruct 模型	`hf_xxxxxxxxxxxxxxxxxxxx`
`LDRAW_LIBRARY_PATH`	否	LDraw 零件库目录路径，未解压到家目录时需设置	`/your/path/ldraw`

如何确认成功

uv sync 无报错即依赖安装完成；微调结束后模型保存在输出目录的 brickgpt_run 子目录下。

常见问题

Q：为什么必须先申请模型权限？

A：Llama-3.2-1B-Instruct 是 gated 模型，需在 Hugging Face 页面申请通过后再生成 access token，代码运行时才会自动下载权重。

Q：微调后模型不输出结束符怎么办？

A：用 finetuning_config_files 目录中的 config.json、special_tokens_map.json、tokenizer_config.json 覆盖预训练模型中的同名文件，使 pad_token 与 eos_token 不同。

Q：能用自己的积木数据集微调吗？

A：可以。数据集需包含 captions 与 bricks 字段，bricks 为论文所述的文本格式，把 prepare_finetuning_dataset 的 --input_path 换成你的数据集路径。

Q：只想在自己的 Python 项目里调用怎么办？

A：按包方式安装即可：使用 uv 时执行 uv add "https://github.com/AvaLovelace1/BrickGPT.git"，使用 pip 时执行 pip install 同一地址。

注意事项

渲染背景 exr 文件需手动下载后放入 ImportLDraw/loadldraw 子目录，README 未给出命令行下载方式。
纹理生成与 mesh-to-brick 功能分别在 src/texture、src/mesh2brick 子目录，需按各自 README 操作。
README 的交互式推理章节未给出具体命令，请以仓库内脚本与子目录说明为准。
微调脚本参数依次为预训练目录、输出目录、运行名、微调数据集路径，路径需替换成自己的真实路径。

核心亮点

首个面向玩具积木的文本生成方法，输出为可实际拼搭的离散砖块序列而非普通网格模型
生成过程显式考虑物理稳定性，减少外观相似但结构易倒塌的问题
ICCV 2025 最佳论文官方实现，附带训练、推理与评估代码，复现路径清晰

不足之处

依赖特定积木数据集与体素化流程，环境配置和数据准备成本较高
生成质量与稳定性受训练数据覆盖范围限制，复杂结构仍需人工调整

适用场景

根据文字描述快速生成积木拼搭方案，用于玩具设计与创意原型
研究文本到结构化3D生成及物理约束生成模型
作为教学案例，演示生成式AI在实体拼搭设计中的应用

替代项目

Text2Mesh、DreamFusion、Shape-E

上一篇：digital-human-koubo

下一篇：没有了！