anteloc/ldraw-nova

来源: https://github.com/anteloc/ldraw-nova

ldraw-nova

给 AI 智能体一个模型构想，引导它、让它自己构建，然后你将得到一个 LDraw LEGO© 模型。

当构建过程结束时，你将得到：

• 它的源代码，使用 LDraw 语言 (https://www.ldraw.org/) 编写。
• 多种视图： 3D 查看器、3D 播放器、VR 交互（Meta Quest 3）、图像……
• 可在 Blender 中编辑的 glTF 文件（.glb 格式），元信息以 Blender 自定义属性的形式保存。
• 聊天记录以及智能体的思考过程。
• 以及更多内容…… 👌

看看这个视频 (https://youtu.be/YDjjxGqWpgU)：

安装

智能体用来寻找合适零件与示例模型的工具依赖于 jev-rerank (https://github.com/anteloc/jev-rerank)（我也是它的作者）。 这是一个带有重排序功能的语义搜索工具，由 TypeSafe (https://typesafe.ai/) 的 Jev System One (https://typesafe.ai/) AI 模型提供支持。

• 如果你有 TypeSafe API 密钥（TYPESAFE_API_KEY），请在网页应用的设置部分填入它的值。
• 如果你没有，重排序搜索将无法工作，智能体将退回到 FTS（全文搜索） 策略作为兜底方案，这样生成的模型可能会更差。

使用 Docker 将 ldraw-nova 作为网页应用运行。你需要 Git (https://git-scm.com/downloads) 和 Docker (https://docs.docker.com/get-started/get-docker/)。该网页应用将以容器化方式运行，而要构建 Docker 镜像，需要两个并列的仓库：

• ldraw-nova (https://github.com/anteloc/ldraw-nova)：就是本仓库 😉
• ldraw-nova-docker (https://github.com/anteloc/ldraw-nova-docker)：提供 Docker 配置以及该网页应用。

1. 克隆两个仓库，并列放在同一目录下、使用相同的版本标签，以便它们协同工作：

git clone --branch v0.6.0 https://github.com/anteloc/ldraw-nova.git
git clone --branch v0.6.0 https://github.com/anteloc/ldraw-nova-docker.git

2. 构建 Docker 镜像。首次构建需要一些时间，大约占用 5 GB 磁盘空间：

cd ldraw-nova-docker
docker compose build

3. 启动应用：

docker compose up -d

4. 在浏览器中打开它：

• https://localhost:8443：Meta Quest 3 上使用 VR 时需要这个地址。证书是自签名的，所以首次访问时请接受浏览器的安全警告。
• http://localhost:8765：普通 HTTP，没有证书警告。如果自签名证书带来了麻烦，就用这个。但它不支持 VR。

局域网内的其他设备可以用你电脑的 IP 地址代替 localhost 来访问应用，例如从 Quest 3 访问 https://192.168.1.20:8443。

该应用没有登录机制，请只在你信任的网络中运行它。

要停止它：

docker compose down

为什么要做这一切？

简单来说：我做这个是为了让具备智能体能力的大模型能够设计出可构建的实体物品！

我发现了 LDraw——一种汇编语言（双关语是有意的！😜）——它同时具备简单、低层级且可执行的特点，可以用来生成 3D CAD 模型。这让我想到可以拿 ChatGPT 和 Claude 做实验，尝试让它们用 LDraw 编写代码，就像它们用其他编程语言一样。

令我惊讶的是，尽管这种语言高度专注于数学（零件旋转、定位……），而这恰恰是大模型通常不擅长的，但在最初的测试中智能体表现得相当不错，随后的项目也取得了不错的成果，只是永远不够好，还不能认为生成的模型是正确的：

• 初始研究： ldbuilder-ai (https://github.com/anteloc/ldbuilder-ai)
• 第 1 次尝试基于智能体的 Python 工具：py2bricks (https://github.com/anteloc/py2bricks)
• 第 2 次尝试：py4bricks (https://github.com/anteloc/py4bricks)

这三次尝试，加上不少其他实验，让我得出了以下结论：

💡 结论 1： 对于几何数学，智能体存在一条最小阻力路径，即：

• 给智能体提供工具来生成 LDraw 源码，就能绕开（邪恶的！）几何数学
• ……因为它们在生成产生数学结果的 Python 代码方面要好得多
• ……远好于自己直接推导数学结果！

💡 结论 2：

• 智能体从产生模型的 Python 代码中学习，效果通常更好
• ……而不是从模型本身学习（又是 LDraw 邪恶的几何……）

于是，剩下要做的唯一一件事 🤔 就是创建一套基于 Python 的工具，包含所需的原语、动词、构造性词汇表……这样智能体就能通过示例学习，并自行完成类似的事情。

事实证明这件事即使凭感觉编程（vibe coding）也很难做对……直到 GPT-6 Astra 和 Claude Opus 5.5 横空出世……它们凭感觉就把它做对了！ 🚀🚀🚀

工作原理

ldraw-nova 提供智能体设计使用真实 LDraw 零件的模型所需的工具、示例和说明。流程如下：

1. 智能体接收一个提示词（prompt）。
2. 阅读 instructions.md 以及关于 LDraw 语言 (https://www.ldraw.org/) 和 LEGO© 模型搭建的相关文档。
3. 规划如何构建该模型：所需零件、要创建的子模型、外观风格……
4. 迭代进行：
   1. 从模型/子模型渲染出图像
   2. 检查图像，调整定位、外观……然后回到渲染步骤
5. ……直到它认为模型已完成，可以交付为止！

提供的工具在以下方面帮助智能体：

• 查找合适的零件。
• 提供示例模型和子模型作为起点。
• 对零件进行碰撞和间隙检测，确保放置正确。
• 无头渲染，用于查看当前结果。
• 以及更多内容……

智能体并不会真的从摆放零件开始，除非是诸如通过修改现有示例模型来进行原型开发和学习这类情况。它生成模型的方式更像是：

• 收集所需信息，包括实验结果、文档和规划结果。
• 构建一个或多个规划文件，完整描述模型和子模型，包含其几何信息，例如 atlas-crane.plan.json
• 并根据该规划创建一个或多个生成器脚本，例如 generate.py
• ……当这些脚本执行时，会生成 LDraw 源文件——一种非常专门化的 3D CAD 语言。
• ……例如 atlas-crane.mpd

总结来说，这就像是：

• 一个智能体创建一个生成器
• ……它生成一个 3D 模型
• ……使用一种名为 LDraw 的汇编语言 🤯

可以说，就像某种编译器 🤓

flowchart TD
agent([agent]) -- produces --> plan[plan.json]
plan -- interpretation --> gen[generator.py]
gen -- execution --> model[model.mpd]

智能体的信息来源

以下是提供给智能体、帮助它成为搭建者的一些指南和参考资料：

开发

由于这是首个版本，还有不少工作有待完成：

• Meta Quest 3 上的 VR： 模型处理存在许多问题，还有性能问题。
• 适配低配智能体： 适配当前的工具、文档和说明，以改善 Luna、Haiku 等小型模型的使用体验。
• 生成成本高： 目前只有昂贵的高端模型才能生成大尺寸且正确的模型。
• 提升效率： 生成过程目前比较缓慢。
• 新增并改进更多模型家族：
  • 人类与动物：人仔
  • Technic 模型：机器、引擎……
  • 太空飞船：目前生成的效果不太好
• 根据搭建手册构建模型： 部分可用；如果把手册页面作为图片提供，效果会更好。
• 细粒度检查： 用于检查子模型及其逐步搭建过程。

贡献

即将推出

致谢

我要感谢以下人士与项目：

• LDraw 社区 (https://www.ldraw.org/)
• LDView (https://tcobbs.github.io/ldview/) 的 Travis Cobbs (@tcobbs) 及其贡献者。
• LeoCAD (https://github.com/leozide/leocad) 的 Leonardo Zide (@leozide) 及其贡献者。
• LDCad (https://www.melkert.net/LDCad) 与 Shadow Library 的 Roland Melkert。
• ldraw.rs (https://github.com/segfault87/ldraw.rs) 的 Park Joon-Kyu (@segfault87) 及其贡献者。
• pyldraw3 (https://github.com/hbmartin/pyldraw3) 的 Harold Martin (@hbmartin) 及其贡献者。

……还要感谢许许多多其他 LDraw 创作者们！

注意： 为此项工作，我使用了来自多种来源的大量 LDraw 模型、库、工具、文档……。有许多了不起的人慷慨地为此做出了贡献，他们甚至数十年如一日地将自己的杰作无偿贡献给公共领域和开源社区。如果你认为自己应该出现在这一部分，请给我发封邮件！

商标

LEGO(R) 是 LEGO Group（乐高集团）的商标，该集团不赞助、不授权、也不认可本软件。