Text-to-CAD 这个方向，我断断续续研究了快一年。它要解决的事说起来很简单：把"用嘴描述一个零件"变成"拿到一个能编辑、能出图、能直接给加工厂用的CAD模型"。这些年大家见过不少 text-to-3D 工具，输入一句话给你吐一个网格体，看着很炫，但真做产品的工程师拿到那种结果基本是废的——没有参数、没有特征树、没法改尺寸，更转不出工程图。text-to-cad 跟它们最大的区别，是它生成的是"活的"模型，底层是参数化特征和代码，你可以像改普通CAD文件一样改它。这篇文章我不讲虚的，直接把技术路线、核心原理、完整实操流程和踩过的坑都摊开来说，适合正在做AI辅助设计工具、或者想把这套能力接入自己工作流的工程师和产品经理。
1. 项目整体设计与思路拆解
1.1 一句话理解 text-to-cad
所谓 text-to-cad，就是用自然语言描述一个零件的形状、尺寸和功能需求，由大语言模型把它转换成一段可执行的CAD建模脚本，再由CAD内核执行这段脚本，最终生成参数化三维模型。
这个流程里最关键的认知是：它不是让AI直接"捏"出几何体，而是让AI"写"出几何体。就像你让一个熟练的建模师按你的话去操作软件，而不是让AI凭空生成一个模型文件。整个管线可以拆成四个环节：
- 语言理解：LLM 把自然语言里的尺寸、约束、特征拆解成结构化意图。
- 代码生成：把意图翻译成 CAD 建模库的 API 调用序列。
- 内核执行：CAD 内核执行脚本，生成带特征树的三维模型。
- 结果反馈：把渲染截图反馈给 LLM，让它自我纠错，形成闭环。
这个设计思路决定了它的上限和下限。上限是，只要 LLM 的代码能力够强，理论上什么零件都能描述出来；下限是，如果建模库的 API 本身表达能力弱，LLM 再聪明也变不出花来。所以选建模库是整个项目的头等大事。
1.2 为什么选择代码生成路线，而不是直接出网格体
刚开始接触这个方向的人都会问一个问题：现在有不少 text-to-3D 工具，一段文字直接生成网格或者 NeRF 隐式场，效果还挺惊艳，为什么还要绕一圈去写代码？
因为工业场景要的是"管得住"的模型。网格体的本质是一堆三角面片，它没有特征概念，你不知道哪块面是平面、哪块是圆角，改一个圆角直径等于在一堆顶点里手工挑选，加工和仿真软件对网格体的支持也远不如对实体模型的支持好。而代码生成的模型是水密的实体，自带特征历史：拉伸、切除、倒角、旋转这些操作都记录在脚本里。
用生活里的类比来说，网格体是一张照片，参数化模型是一份菜谱。照片看着好看，但你没法从中反推出"少放点盐"该怎么操作；菜谱每一步都写清楚了，改一个量整道菜跟着变。做设计的本质需求就是不断修改，所以 text-to-cad 必须走代码生成这条路。
另外，代码生成还有一个隐藏优势：可审计。生成的每一步操作都在脚本里，工程师可以检查"你这里为什么切了5毫米"，而不是面对一个黑盒模型不知从何下手。这对工程信任的建立非常重要。
1.3 这个项目适合谁去用
我自己测下来，text-to-cad 目前最合适的定位是"草图加速器"和"标准件生成器"，而不是"设计替代品"。
如果你是需要快速验证一个装配思路的机械工程师，比如"给我一个带四个安装孔的L型支架，底板长100宽60，立板高40"，用 text-to-cad 一两分钟就能拿到能用的模型，省掉打开CAD软件新建文件、选基准面、画草图、添加约束的一整套流程。如果你是做夹具、治具、料架这类非标件的设计人员，这类零件结构相对固定，描述清楚需求之后 AI 生成的准确率很高。
不适合的情况也很明确：复杂的曲面造型、需要精密的配合公差（比如 ±0.01那种）、多层级的装配体，目前这些场景 LLM 还驾驭不了。它不是不好用，是用了之后你检查成本可能比从头画还高。
2. 核心技术拆解：从自然语言到参数化模型
2.1 整体管线是怎么串起来的
一个标准的 text-to-cad 系统，核心是一条"意图解析 + 代码生成 + 内核执行 + 视觉反馈"的闭环。下面把每个环节讲透。
先看输入。用户的自然语言里通常包含三类信息：形状描述（"L型支架"）、尺寸约束（"底板100×60"、"孔直径8"）、加工要求（"边缘倒圆角"）。LLM 需要先把这些信息从口语里抽取出来，转成结构化的建模指令。
然后是代码生成。这一步是整个系统的灵魂。以 CadQuery 为例，用户说"在底板四角打四个通孔"，LLM 要能拆解成：确定扁平面作为基准、计算四个孔的位置坐标、执行四次开孔操作。位置坐标不会出现在用户的话里，但如果 LLM 不理解"四角均布"这个工程常识，生成出来的孔就是错位的。
代码生成之后是内核执行。这一步看起来是纯技术操作，其实暗藏一个关键选择：用哪个几何内核处理 BRep（边界表示）运算。CadQuery 走的 OCC（Open CASCADE）内核，它对布尔运算和圆角倒角的稳定性比轻量级内核好很多，这正是我推荐用它而不是纯自研内核的原因——没必要重复造轮子。
最后一步最容易被忽略，也是最出效果的一步：把渲染结果喂回给 LLM。生成的模型渲染成多角度截图，连同用户原始指令一起再丢给模型，让它判断"形状对不对、孔位对不对、比例对不对"。实测中加入这一步，一次成功率能提升三成以上，因为LLM会自己发现"我上次把孔径写成了半径"这种低级错误。
2.2 CadQuery 和 OpenSCAD 到底怎么选
这是我在项目里纠结最久的一个问题，直接说结论：通用机械零件用 CadQuery，纯形状原型用 OpenSCAD。
OpenSCAD 是老牌的代码建模工具，语法简单，文档多，LLM 容易学会，它的 CSG（构造实体几何）方式非常适合表达"两个圆柱相交""盒子上减去一个球"这类布尔造型。但它有个致命弱点：做圆角很难。OpenSCAD 里一个 minkowski 运算就能把你卡住半天，而机械零件里圆角倒角几乎是标配。
CadQuery 是面向机械设计的 Python 库，语法上更像"在CAD软件里一步步操作"：选面、建工作平面、拉伸、开孔、倒角，每一步都有明确的对象和方法。它基于 OCC 内核，圆角、拔模、抽壳都很稳。缺点是 API 层级深，新手理解faces(">Z").workplane()这种链式调用需要一点时间。
我给的选型建议是：如果你主要做的是支架、底板、外壳这一类需要圆角倒角和装配孔的零件，直接选 CadQuery，它的特征建模方式更接近工程师思维。如果你只是快速验证一个概念形状，比如做一个异形花瓶的轮廓，怎么简单怎么来，选 OpenSCAD。还有一个折中方案：CadQuery 2.x 自带的cq.importers.importScad可以兼容 OpenSCAD 的一部分语法，但别指望无缝，混合用的维护成本不低。
2.3 必须守住的几个关键参数
用 text-to-cad 做零件，有几个设计参数是实践中反复踩坑总结出来的，你在提示词里不写明，AI 就会替你"自由发挥"。
第一是基准点和默认单位。我会在系统提示词里固定写死"模型单位为毫米，原点位于零件左下角底面中心"。如果不写，LLM 有时会按英寸计算，或者把原点放在一个莫名其妙的位置，后续装配对齐全乱。
第二是孔位的定位方式。描述孔的时候尽量给相对约束，比如"距离边缘10mm"，而不是"位于第一象限"。相对约束符合工程标注习惯，代码实现是rect(...)定中心再加偏移，LLM 对这种描述的理解准确度高得多。
第三是特征顺序。模型的创建顺序影响可修改性。先拉伸主体、再切通孔、最后倒角，这个顺序跟加工顺序接近，后续想改参数也方便。如果 LLM 先倒角再切孔，倒角会被孔打断，几何上没错，但特征树关系混乱。
第四是壁厚与圆角的最小值。要主动约束"最小壁厚不小于3mm，圆角半径不小于2mm"，这个数根据你的加工工艺来定。不写，LLM 经常给你生成一个 0.8mm 的壁厚，拿去 3D 打印一碰就断，换成 CNC 加工更是直接废刀。
3. 实操全流程：生成一个真正能用的零件
3.1 环境搭建：十分钟跑通最小系统
我推荐的最小可用组合是CadQuery 2.x + Python 3.10+ + 本地LLM或API。如果你想先体验，Zoo 团队的 text-to-cad 开源项目是最快的入口，它封装好了完整的后端和前端，装好依赖就能在本地浏览器里对话生成模型。
手动搭环境也很简单：
pip install cadquery pip install jupyter然后安装一个能在 Jupyter 里实时预览模型的扩展，比如jupyter-cadquery，它能在每个建模语句后面直接渲染出三维视图，调试时有图像反馈会舒服很多。
如果你打算接 LLM，国内推荐用主流大模型的 API，或者直接部署一个开源的代码模型（比如 Qwen-Coder 系列）。实测下来，参数的推理能力比模型的"炫技"重要得多，7B 量级的模型在简单零件上也能跑出不错的结果，但复杂装配体还是得靠大模型。
3.2 提示词怎么组织，成功率差一倍
这是实操里最值钱的经验。同样一个"底座"，你给 LLM 的提示词不同，结果质量天差地别。我整理了一个高成功率提示词模板：
请用 CadQuery 生成一个【零件名称】。 功能需求：【它用在什么场景，比如连接电机和安装板】 形状描述：【主体的大致形状、相对位置关系】 关键尺寸： - 底板：长100mm，宽60mm，厚10mm - 安装孔：4个，直径8mm，通孔，距边缘10mm均布 - 立板：高40mm，厚8mm，与底板长边垂直 加工要求： - 所有外部边缘倒R2圆角 - 内部锐角改为R1 约束：单位毫米，原点位于底板底面中心，特征顺序为拉伸-切孔-倒角。 只输出可直接运行的Python代码，不要解释。注意几个细节。一是"功能需求"要写在形状描述前面，LLM 对"这个零件是干嘛的"形成先验认知后，生成的形状会更合理。二是尺寸格式统一用"长×宽×厚"，不要一会儿说"长100、宽60"一会儿说"60mm宽"，格式不一致 LLM 容易在换算时出错。三是明确"只输出代码"，否则一堆解释文本混在代码块里，后处理解析很容易翻车。
3.3 生成与迭代：别指望一次到位
以下是我实际执行的一个例子。需求是做"电机安装支架"，完整提示词写好后，第一次生成的代码长这样：
import cadquery as cq result = ( cq.Workplane("XY") .box(100, 60, 10, centered=(True, True, False)) .faces(">Z").workplane() .pushPoints([(35, 20), (35, -20), (-35, 20), (-35, -20)]) .hole(8) )第一眼看上去没啥问题：底板、四个孔都对。但渲染出来我就发现不对，要求的"立板高40"没了，LLM 把整段描述漏了一部分。这时候把截图和缺失需求反馈回去："你遗漏了立板。立板应与底板长边重合，高40mm，厚8mm，并在立板中心开一个直径20mm的通孔。"第二轮生成的代码就有了立板，但立板的位置偏了 5mm。
新一轮反馈又把位置纠正了，最后得到的代码包含立板、安装孔、中心过孔，再补一条倒角规则后才算完整。整个过程三次迭代，耗时不到五分钟。这就是 text-to-cad 的正确使用姿势：把它当成一个需要你盯着的实习生，而不是一个全知全能的神。
3.4 批量生成场景：给相似零件做个模板
text-to-cad 真正拉开效率优势的不是单件生成，而是批量变化。比如我要给一批不同尺寸的控制盒设计底座，结构完全一样，只有长宽高不同。我可以写一个带占位符的提示词模板：
根据以下参数生成控制盒底座： 长度：{length}mm 宽度：{width}mm 高度：{height}mm 四角安装孔直径8mm，孔心距边缘10mm...然后写个脚本循环调用模型接口，自动生成一整套底座模型。我们项目里一次生成过30个不同尺寸的底座，每个模型都在1分钟内完成，人工建模的话每个至少15分钟，这个效率差距非常大。批量场景里，代码生成的稳定性反而比单件对话更高，因为模板固定，LLM 的自由发挥空间被压缩到了最小。
4. 常见问题与排查技巧实录
4.1 生成代码一执行就报错怎么排查
这是使用频率最高的问题，没有之一。LLM 生成 CadQuery 代码报错的原因，九成集中在这三类：API 名称拼错、方法参数数量不对、对象类型不匹配。比如它可能写出boss(10, 20)这种不存在的调用，或者对 Workplane 对象调用cutBlind()时遗漏了布尔运算对象。
我的排查顺序是：先看栈信息定位到具体行，然后直接问 LLM"你的代码第几行有错误，请修复并只输出修复后的完整代码"——把报错原文原样贴回去，它修复的成功率比你自己在旁边改高得多。如果连续两次报错，果断放弃整段重开，生成新代码往往比持续修修补补更快。
有一个小技巧：在环境里加一个自动单元测试钩子，每次生成代码后自动做三个检查——能否import、能否执行val()得到实体、实体体积是否大于零。这三关过了，模型至少是可用的，不用每次肉眼盯输出。
4.2 模型长出来了，但是"不可制造"
代码能跑通只是第一步，模型能不能加工是另一回事。最常见的坑是零厚度几何和非流形边。比如 LLM 生成两个正好相切的凸台，布尔运算后产生一个共享边但没有共享面的几何体，这在 CAD 里看没问题，切片软件或 CAM 软件里直接崩。
这种问题很难靠改提示词解决，因为 LLM 很难预判几何拓扑的边界情况。我的处理方式是加一道程序化检查：用 CadQuery 的validate()方法检查实体有效性，再用Volume()判断薄片体积异常。如果检测到无效实体，自动触发"重新生成+附加说明"的反馈回路，把验证错误信息喂给 LLM 让它修复。实测下来，这个自动校验环节让最终可制造率从百分之六十出头提到了接近百分之九十。
4.3 尺寸幻觉：明明说了100mm，模型却是50mm
LLM 经常会把长度和半径搞混、把直径当半径，或者把"距离边缘"理解成"中心距"。这个问题的根源在于自然语言的歧义，不完全是模型的错。
我的应对方案是两层。第一层在提示词里强制做单位标注和口径统一，所有尺寸都写成"直径8mm的通孔"而不是"8mm的孔"，减少歧义。第二层在反馈回路里加入"以渲染图比对尺寸"的步骤，让视觉模型检查长宽比是否明显失调。比如 100mm×60mm 的底板，在截图里长宽比应该是5:3，如果视觉检查发现接近1:1就要触发修正。
还有一个我自己用的土办法：生成代码后自动给模型加一个 50mm 的参考尺子（就是一个细长圆柱），渲染截图里比例一目了然。这个参考体在最终导出前删掉就行。
4.4 生成的模型后期改尺寸难
这也算是 text-to-cad 被吐槽最多的一点。LLM 生成的代码虽然可编辑，但如果它把尺寸硬编码写在30个地方而不是定义成变量，你后期改一个尺寸就要改一串数字。这不完全是 AI 的锅，很大程度上是提示词没引导好。
我给提示词固定加一条规则："所有关键尺寸定义为首字母大写的变量，并在文件末尾统一赋值"。这样生成代码的结构就是顶部变量区、中间特征区、底部实例化区。用户改尺寸只需要动顶部，和传统 CAD 改参数表的感觉一致。我还见过有人更进一步，让 LLM 生成 JSON 格式的配置参数配合 CadQuery 脚本，变成一个真正的参数化零件库。
我在实际操作中的体会是，text-to-cad 目前最成熟的用法是把它放在设计流程的最前端：先靠它快速生成一个七八成对的方案，然后由工程师接手做结构细化和工艺调整。它真正改变的不是"谁会画图"，而是"画图之前的想清楚"这个过程被压缩了——你被迫更精确地表达你的需求，这本身就是一种设计能力的提升。如果你也想试，建议从一个小支架开始，先跑通一次完整闭环，再慢慢往里加复杂特征，这条路我已经替你趟过了，值得走下去。
