text-to-cad：用自然语言直接生成参数化三维模型的Agent CAD工具箱

自然语言直接出模型听着是不是有点像拿嘴画画text-to-cad 这个项目确实就是这么干的——你给它一句“做一个法兰盘外径80、内径40、厚10均布4个直径6的安装孔”它能在几分钟内给你产出一个带尺寸的三维实体模型而且不是你想象的那种粗糙的 mesh 皮囊而是真正能导进 CAD 软件继续编辑的参数化实体。它在 GitHub 上拿了 15K 星在 CAD 这个相对垂直的赛道里已经算是现象级了。我连着测试了两个星期踩了不少坑也摸清了它什么时候靠谱、什么时候翻车这篇东西就是我的完整使用报告。不管你是做机械结构、搞 3D 打印还是单纯对 AI Agent 这个方向感兴趣这篇文章应该都能给你省下不少时间。1. text-to-cad 项目概览1.1 它到底是什么先把这个项目拆开看。text-to-cad 的核心目标很简单把“自然语言描述”转成“可用于工程的三维模型”。这和市面上常见的 text-to-3D 不是一回事。那些项目通常生成的是网格模型比如 obj、glb 文件适合做游戏资产、影视预览但没法直接用因为网格模型没有厚度、尺寸不可控、也不能参数化修改。text-to-cad 走的是另一条路它直接产出程序化建模脚本再从脚本生成真正的实体模型。我自己的理解是它其实是一个套了 Agent 外壳的 CAD 编程助手。从拿到文本提示词到最终输出模型中间经历了 LLM 推理、代码生成、自动执行、反馈修正等多个环节这也是为什么标题里叫它“Agent CAD 工具箱”——它不是单次生成的死流程而是带反馈循环的活流程。实际使用下来它能处理的类型比较集中机械零件、连接件、标准件、简单外壳、几何组合体这些效果都不错。但如果你让它生成一个带有复杂曲面造型的消费电子产品外壳它基本会翻车这不是项目不好而是当前这类工具的能力边界就在那儿。1.2 为什么能在开源社区拿到 15K 星CAD 这个领域相当垂直能拿到 15K 星说明它确实戳中了一大波人的刚需。我分析下来核心原因有三个。第一传统 CAD 建模门槛高。会画图的人和不会画图的人之间有一道很高的墙而“用嘴描述一个零件”天然适合降低这道门槛。第二程序员背景的工程师特别吃这一套。很多做硬件、做创客、做开源硬件的人建模能力一般但写代码很溜text-to-cad 把“建模”变成了“写提示词 改代码”这完全踩中了他们的舒适区。第三它没有停留在 demo 阶段而是真的能输出 STEP、STL、DXF 这类工业格式可以直接对接 3D 打印和加工流程实用性足够了。另外一个不能忽略的因素是Agent 这个方向本身正处于风口期。一个把 LLM Agent 和 CAD 这种硬核工具结合起来的开源项目天然会被推到聚光灯下。它拿到了流量红利而流量又吸引了更多人提交 issue、贡献代码、优化提示词工程形成了正向循环。2. Agent CAD 的技术选型与架构思考2.1 从自然语言到参数化模型的关键链路要理解 text-to-cad 是怎么工作的得先理解一个核心分岔点生成几何体到底有几条路可以走。路线一是让模型直接输出三角网格顶点这是很多 text-to-3D 项目用的方案。它的好处是自由度高能表达复杂曲面坏处是精度低、不可编辑、容易产生非流形几何在工程场景里基本不可用。路线二是让模型生成参数化建模脚本也就是用 CadQuery、OpenSCAD 这类程序化建模语言写代码再通过脚本生成实体模型。text-to-cad 走的显然是第二条路。这个选择非常聪明。你看LLM 写代码这件事现在已经比较成熟了而 CadQuery 这类库的语法又相对稳定、可预测模型在训练时看过大量相关代码生成的脚本只要语法正确、逻辑基本合理执行出来就是一个符合尺寸约束的实体模型。比起直接生成几何让模型“写代码”的容错空间大得多而且输出结果天然就是参数化的用户可以随时改尺寸、改约束重新生成。整个链路大致是这样用户输入自然语言 → Agent 把需求拆解为建模步骤 → 生成对应的参数化脚本 → 执行脚本得到实体模型 → 渲染预览并检查几何有效性 → 如果失败或不符合要求Agent 根据错误信息自动修正再跑一轮直到成功或达到最大迭代次数。2.2 Agent 循环的核心设计我之所以说这是一个 Agent 框架而不是一个简单的模型接口关键在于它的循环结构。单次生成在复杂任务里基本没法用大模型写代码免不了出错可能是 API 用错、尺寸计算错误也可能是 r 角顺序不对。text-to-cad 的做法是把“执行结果”反馈给模型让模型自己看报错信息、自己改代码。这个机制非常像真人工程师的工作方式。我画图的时候也是先出一个版本然后看哪里干涉、哪里倒角不对再改再试。Agent 只是把这个“试错-修正”过程自动化了。当然这也意味着它比单次生成的工具慢因为每次迭代都要调用一次模型推理复杂零件跑十几轮是常有的事。几何校验也是循环里的关键环节。模型生成完脚本、执行出实体后系统还要检查这个实体是不是有效的流形有没有开面、有没有零厚度、布尔运算有没有产生退化几何。这一步相当重要因为很多 LLM 生成的代码能跑通但几何上其实是个坏体直接拿去切片或加工会出问题。2.3 为什么选用程序化建模后端从我实际用下来的体会看选择一个好的后端是这类项目成败的决定性因素。text-to-cad 这类 Agent 工具箱输出结果的“可编辑性”比“自动化程度”更重要因为没有一个模型能一次就生成完美结果用户几乎必然要二次修改。如果后端选的是网格模型那用户拿到手之后基本只能干瞪眼。网格模型改一个孔的位置需要手动操作网格顶点这在工程软件里非常痛苦。但如果后端是 CadQuery 这类程序化建模库情况完全不一样——孔的位置就是代码里一个坐标和一个半径改起来跟改配置一样简单重新生成一下就是新模型。另外参数化建模后端的兼容性也更好。CadQuery 可以导出 STEP 格式这是几乎所有主流 CAD 软件都能打开的通用交换格式OpenSCAD 可以导出 DXF 做激光切割STL 直接喂给 3D 打印机。我在测试过程中最常用的流程就是让 text-to-cad 生成 CadQuery 脚本然后导出 STEP 文件再拖进 FreeCAD 或者 SolidWorks 继续做配合和装配这个链路非常顺。3. 部署安装与运行环境准备3.1 基础环境与依赖安装先说结论在自己机器上跑 text-to-cad 并没有想象中那么复杂但有几个坑是绕不过去的提前知道能省很多时间。第一步还是老规矩把仓库拉下来。项目通常依赖 Python 3.9 到 3.11 之间我不建议用最新的 Python 3.12 或 3.13因为 CadQuery 这类底层库对 Python 版本的跟进经常滞后容易碰到编译错误或者依赖装不上的情况。实际踩坑经历是我一开始用 Python 3.12 装依赖OCC 相关组件直接编译失败换成 3.10 就很顺利。git clone https://github.com/xxx/text-to-cad.git cd text-to-cad python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install -r requirements.txt安装过程比较久因为核心依赖里包含 OpenCascade 这样的几何内核光这一个包就要下载几百 MB。这个阶段最考验网络和耐心多等一会儿就好不用反复中断重试。看到 pip 把依赖全部解析完并且没有报冲突基本上就成功一大半了。3.2 模型推理方案怎么选依赖装好之后还要选一个 LLM 推理后端。text-to-cad 本身是一个 Agent 框架它需要调用一个大语言模型来干活。我在测试中用过的方案大致有两种各有利弊。第一种是本地模型方案。好处是免费、数据不出机器、可以反复调试跑很多轮坏处是显存要求高。普通 7B 量级的模型跑这种长上下文代码生成任务至少要 12GB 显存才比较流畅如果用量化后的 4bit 版本8GB 显存的卡也能勉强跑起来但速度不太乐观一个简单零件可能要等好几分钟。如果你的显卡不够又不愿意花钱调 API那体验会比较煎熬。第二种是云端 API 方案。这个方案基本不挑机器只要能发 HTTP 请求就行速度也快但每跑一次要花钱。text-to-cad 的本质是迭代式的 Agent不是一次性请求一个零件动辄调用十几轮模型推理所以 API 费用会随着任务复杂度快速上涨。我的建议是先拿本地小模型跑通流程理解清楚整个工具链再切换到云端大模型处理真正复杂的零件。无论选哪条路配置方式都比较统一通常在项目的配置文件或者环境变量里填入模型的 endpoint、api key、模型名称框架会自己拉取模型并处理推理请求。4. 实操从一句描述到可加工的三维模型4.1 跑通最小示例我建议你第一次测试不要太贪心选一个特别简单的零件比如 M8 六角螺栓、矩形垫片、或者带圆角的法兰盘。拿法兰盘举例这是我测试时用的第一句提示词创建一个法兰盘外径80毫米内径40毫米厚度10毫米 在直径60毫米的分度圆上均匀分布4个直径6毫米的安装孔。整个生成过程我观察下来大致分三个阶段。第一阶段是规划Agent 会把这句需求拆成几个建模动作先画外圆拉伸成圆柱再挖内孔再定位安装孔最后打孔。第二阶段是代码生成模型根据规划写出 CadQuery 脚本这个阶段可以在输出面板里看到完整的 Python 代码。第三阶段是执行与导出框架自动运行脚本把结果保存成 STEP 和 STL 文件同时渲染一张预览图。我第一次跑通的时候生成出来的法兰盘尺寸完全正确孔位也准确落在分度圆上那一刻确实有点颠覆认知。不过要泼一盆冷水简单零件效果惊艳不代表复杂任务也能一次过后面我会细说。4.2 控制尺寸与精度的几个技巧自然语言转 CAD 最痛苦的问题就是尺寸精度。人类语言天然是模糊的“大一点”“厚一些”“差不多就行”这类词模型根本没法把握。我在反复测试中总结出一个特别有效的技巧提示词里必须用明确的数值加单位而且最好把单位统一成毫米。下面是几个实测效果很不错的提示词写法明确给出外径、内径、厚度、孔数、孔径等全部关键尺寸不留模糊量。需要圆周分布时直接说“在直径XX的圆上均布N个孔”模型能精准理解分度圆概念。涉及倒角圆角时给出具体半径值例如“所有外边缘倒圆角R2”。需要阵列时说“沿X方向阵列5个间距20毫米”比“一排几个”要可靠得多。另外一个很实用的工作流是“先出大形再出细节”。不要妄想让模型一步到位生成一个完整零件正确做法是分两步、三步来第一轮只给整体尺寸和基本外形让 Agent 先跑通第二轮再说“在外表面增加安装凸台”“在四角增加直径6的沉头孔”这种增量修改模型基于已有代码继续迭代成功率会高很多。4.3 导出格式与二次编辑text-to-cad 最让我满意的部分是导出格式非常贴近实际工程需求。默认情况下它会同时导出 STEP 和 STL 两种格式STEP 用于 CAD 软件交换STL 用于 3D 打印这个设计很贴心。实际测试中我把生成的 STEP 文件导入 FreeCAD几何特征是完整的可以继续做配合约束、装配、工程图。我还试过把同一份 STEP 文件丢进 SolidWorks同样没有问题。这种格式兼容性在开源项目里很难得很多工具能导出 STL 就算不错了支持 STEP 说明项目方是真的懂工程设计需求。如果项目默认没有开启某种格式的导出你也可以在 CadQuery 脚本里手动加一行比如把模型导出成 DXF 用来做激光切割import cadquery as cq result ( cq.Workplane(XY) .circle(80 / 2) .extrude(10) .faces(Z) .workplane() .circle(40 / 2) .cutThruAll() .faces(Z) .workplane() .rect(60, 60, forConstructionTrue) .vertices() .hole(6) ) cq.exporters.export(result, flange.step) cq.exporters.export(result, flange.stl)拿到脚本之后你可以像改普通 Python 代码一样改尺寸、改特征改完重新执行新模型马上就能出来。这种自由度是纯图形化软件给不了的也是我喜欢这个工具链的原因。5. 常见问题与排查技巧实录5.1 生成结果不稳定、脚本频繁报错我在连续测试中遇到的第一个问题就是生成结果不稳定。同一个提示词连续跑三次可能第一次成功、第二次孔位乱掉、第三次直接脚本报错。这其实不是 text-to-cad 项目本身的问题而是底层 LLM 的随机性导致的。解决思路有两个方向。一是把温度参数调低让模型输出更保守、更可预测代价是会损失一点表达灵活性二是在提示词层面做约束把关键数值和建模步骤写得更明确。我的实际感受是温度调到 0.2 左右在“稳定性”和“灵活性”之间算是一个比较舒服的平衡点。脚本报错的时候不要急着重新开始先看报错信息。Agent 本身有自动纠错机制它会自己读取报错、修改代码再来一轮大多数情况下几轮之后就能跑通。如果连续五六轮都在同一个地方翻车说明思路从一开始就偏了这时候最有效的做法不是继续让 Agent 死磕而是换一种描述方式重新输入需求用词更接近 CadQuery 的建模逻辑成功率会明显上升。5.2 尺寸精度不够怎么办尺寸精度是这类工具最容易暴露短板的地方。自然语言描述哪怕包含了数值模型在计算坐标、圆角位置、阵列间距时仍然可能犯错。我测过一个矩形法兰提示词里明确写了“四角各一个直径6的孔”结果四个孔里有一个偏差了 0.8 毫米。对于一般的 3D 打印件 0.8 毫米可能不算什么但对于需要过盈配合的零件来说这足以导致装配失败。我的建议是一定不要把 text-to-cad 的输出当成最终图纸它的定位是概念设计和初步模型生成器。拿到生成的参数化脚本之后花五分钟检查一遍关键尺寸和位置关系然后再导出加工。如果你用的是 CadQuery 后端直接在脚本里改数值就行不用重新生成这么一操作精度完全掌握在自己手里。5.3 中文输入和本地模型性能问题中文输入方面用云端 API 基本没什么问题主流模型的中文理解和中文单位提取能力都够用。但如果你在本地跑小参数模型中文能力可能不太稳定尤其涉及“直径”“均布”“分度圆”这类专业术语时模型可能理解偏。我测试时发现一个规律整体提示词用中文没问题但关键的建模参数最好单独列出比如“外径80mm / 内径40mm / 厚度10mm”这种结构化写法无论中英文都能被模型稳定解析。性能方面本地推理的瓶颈主要在显存和推理速度。我的建议是关闭预览渲染的实时显示等所有迭代完成再看结果另外尽量缩短提示词中的冗余描述减少上下文长度也能降低每次推理的耗时。如果你的卡只有 8GB 显存建议直接用 API 方案省时也省心。6. 扩展玩法把 text-to-cad 接进自己的工具链6.1 批量生成标准件用自然语言一个个生成零件已经不错了但我觉得 text-to-cad 的真正威力在于配合脚本做批量生成。你可以在生成的 CadQuery 代码基础上套一层 Python 循环把关键参数变成变量一次跑出几十个规格的螺栓、垫片、法兰或者支架。举个例子我需要一端带法兰的轴套规格从直径 10 到 50 每隔 5 一种手工建模要做一个小时用参数化脚本只需要写一个循环import cadquery as cq for diameter in range(10, 51, 5): result ( cq.Workplane(XY) .circle(diameter / 2) .extrude(20) .faces(Z) .circle(6) .cutThruAll() ) cq.exporters.export(result, fbushing_{diameter}mm.step)这个思路再往前一步就是建立自己的标准件库。每次让 text-to-cad 生成一个新零件我都把最终的脚本按零件类型归档下次遇到相似需求直接在脚本库里改参数完全不需要再让模型重新生成。6.2 与已有设计流程配合的几种思路如果你平时不用 CadQuery 而是用 FreeCAD 或者商业 CAD 软件text-to-cad 也能融入工作流中。我目前用得最顺的模式是“概念阶段用 text-to-cad 快速出方案确定方向后再进入正式 CAD 软件细化”。以前接一个定制零件需求我得先花半小时建个初步模型给客户确认现在用 text-to-cad 几分钟就能出一个带真实尺寸的 STEP 文件效率提升非常明显。还可以把它当成学习工具。对于刚学 CAD 建模的新手来说看 text-to-cad 怎么把一句描述翻译成建模代码能直观理解一个零件在参数化建模里是怎么分解成拉伸、切割、阵列这些操作的。我看过几个初学者用这个项目入门 CadQuery上手速度比啃教材快不少。另外如果你做机械臂、机器人底盘这类开源硬件项目text-to-cad 生成的参数化脚本可以直接嵌进你的开源仓库里用户改几个尺寸就能适配自己买的型材和电机这是纯静态模型文件做不到的灵活性。我自己这两周用下来最大的感受是text-to-cad 这类工具不是来替代 CAD 工程师的它替代的是“从需求到初步建模”这段重复劳动。以前画一个标准法兰从查手册到建完模型再检查尺寸再怎么快也得十几分钟现在一个自然语言描述加上几次迭代修正几分钟就能拿到可以用的 STEP 文件这个效率提升是实打实的。当然它现在还有很多明显的问题——复杂曲面基本没法处理尺寸一致性还要靠人把最后一道关Agent 迭代过程的耗时也比较长。但作为 15K 星的项目它已经证明了“用嘴建模”这个方向是可行的而且后续社区只要持续优化提示词库、丰富后端支持这个工具链会越来越靠谱。如果你也在做硬件、做 3D 打印、做开源机械设计我建议现在就把它装起来试一下重点试的是那个“迭代修正”的 Agent 流程真的能带来不少启发。