1. 先说清楚text-to-cad到底在解决什么问题
1.1 传统建模流程的痛点在哪
做机械设计、产品结构或者3D打印模型的人，大概率都有过这种体验：脑子里想得清清楚楚的零件，到了软件里却要花上几个小时去画草图、建基准面、拉伸切除、倒角阵列。尤其是那种只用在手头项目里、用完就不会再碰的一次性结构件，投入产出比低得让人怀疑人生。我见过不少做非标设备的朋友，建模速度完全卡在软件操作熟练度上，而不是设计思路上。设计思路三分钟就能说清楚，但把思路变成CAD文件，却要折腾一个下午。
text-to-cad这种项目，核心思路就是把最后这一步从“手动操作软件”变成“用自然语言描述意图，让程序直接生成模型”。它表面上做的是自然语言到三维模型的转换，实际上改掉的是建模流程里的沟通成本和时间成本。设计者不再需要把每个几何特征翻译成软件菜单里的命令序列，只需要说清楚“要什么”“大概多大”“用在什么场景”，剩下的几何构建交给机器去推理。
我在实际中验证过几个版本之后，最直观的感受是：它对两类人特别有价值。一类是软件操作不熟练但设计思路清晰的人，比如做工艺、做装配、做电气结构的人，他们经常需要快速出一个参考模型来验证想法；另一类是天天跟重复建模打交道的工程师，明明只是换个尺寸改个孔位，也要把整个特征树重新拖一遍，这类工作完全可以被自然语言建模吞掉。
1.2 text-to-cad的完整能力边界
需要先泼一盆冷水：text-to-cad不是一个能替代CATIA或者NX的“全能建模助手”，至少现在是。它更适合的场景是有清晰几何特征、参数边界明确、逻辑比较简单的零件建模，比如支架、外壳、法兰、收纳盒、带孔的板类件、简单的壳体结构这些。
我做过一个分类实验，把日常接触的零件按建模复杂度分成三个层级：
一级是基础体素组合，就是长方体、圆柱体、球体、锥体通过布尔运算堆出来的零件，孔位和倒角都是标准特征。这类零件text-to-cad的完成度非常高，基本能一次性生成可用的模型。
二级是带草图轮廓和拉伸/旋转特征的零件，比如异形法兰、手柄、底座这类，需要先在草图平面上画轮廓再拉伸。LLM在这个层级上表现还不错，但出错的概率明显上升，主要问题集中在草图的几何约束不够准确，比如该对称的地方不对称，该相切的线画成了直角。
三级是涉及曲面、放样、扫掠、参数化曲线的高复杂度零件，比如涡轮叶片、汽车外壳、复杂分型面。这个层级text-to-cad目前不太适合，生成结果就算能编译通过，几何质量也达不到生产要求。正确做法是让模型只做前期的概念草案，再由人在CAD软件里精修。
明确能力边界非常重要。我见过不少人一上来就拿着复杂曲面去试，结果生成出来的东西完全没法用，然后就给这种方案下了负面结论。实际上不是方案不行，是场景选错了。
1.3 这类项目最适合谁来用
从我的实际测试来看，目前受益最明显的人群是三类：
第一类是产品结构前期的方案验证人员，需要快速比较多种结构布置方案，不需要每个方案都精确到小数点后两位，但需要速度。用text-to-cad把结构草案批量生成出来，再导入CAD软件细化，效率能提升一整个量级。
第二类是3D打印爱好者。3D打印模型大多数是结构简单、尺寸要求不太严的作品，比如收纳盒、支架、外壳框架，这类模型恰好落在text-to-cad的能力高分区。我在自己的打印工作流里已经把它当作标准化的“出图前端”来用。
第三类是做设计规范沉淀的团队。把常用件的建模方式用自然语言模板固化下来，新同事不用学会全部软件操作也能出图，老师的经验直接沉淀成可复用的文字模板，对团队知识管理是个很好的补充。
2. 整体架构怎么拆：语言模型、中间表示和CAD引擎的分工
2.1 CAD执行引擎怎么选：CadQuery、OpenSCAD还是FreeCAD
架构设计的第一个决策点是选哪个CAD内核来执行生成代码。这不是随便挑一个顺手的就完事，它决定了整个项目的上限。我在先后尝试过OpenSCAD、CadQuery和FreeCAD的Python API之后，把三个方案的真实体验放在一起对比，差别非常明显：
| 引擎 | 编程方式 | 几何核心 | 适用模型复杂度 | 与LLM结合难度 | 我的推荐度 |
|---|---|---|---|---|---|
| OpenSCAD | CSG纯代码建模 | 自有核心 | 中低复杂度零件 | 低，语法简单干净 | 适合快速原型 |
| CadQuery | Python原生API | OpenCASCADE | 中高复杂度零件 | 中，需要API调用规范 | 生产环境首选 |
| FreeCAD Python API | Python脚本驱动 | OpenCASCADE | 高复杂度零件+装配 | 高，API层次深 | 适合深度集成 |
OpenSCAD是我最早用的方案，它的建模方式天然就是代码，语法简单，任何懂一点编程的人都能很快上手。LLM生成OpenSCAD代码的成功率很高，因为语法面窄、规则明确，模型不需要记大量API就能输出正确结果。但它的问题也很直接：几何核心偏弱，复杂圆角、变半径倒角、高级扫掠这些操作要么做不了要么做出来效果很差，而且模型参数化能力有限，改尺寸经常要翻源码。
CadQuery是我目前的主力方案。它本质上是Python包，建模操作全部通过链式方法调用完成，底层几何核心是OpenCASCADE，这是工业级的内核，SolidWorks这类商业软件也使用同源技术。这意味着CadQuery生成的模型可以输出STEP、IGES这种标准工业格式，直接进加工流程。更关键的是CadQuery配合LLM有天然优势：LLM生成Python代码的能力已经是验证过的，CadQuery的方法命名语义清晰，比如workplane().box(50, 30, 10).faces(">Z").hole(5)这种写法可读性极强，LLM理解起来几乎不需要额外训练。
FreeCAD的Python API功能最全，能做装配、能驱动参数表、能操作整个文档对象模型。但我个人不建议在text-to-cad的第一版架构里选它，原因是API层次太深，新手读文档都要半天，LLM生成这种深层次API代码时错误率明显高于前两者。如果后续需要做装配体级别的自然语言建模，再考虑用它。
2.2 中间表示是成败关键
我踩过最大的一个坑，是让LLM直接输出最终的CAD文件格式，比如直接生成STEP或者STL。这条路走不通，原因很现实：STEP文件是文本协议没错，但它的结构复杂度远超LLM的稳定输出范围，一个稍微像样的零件STEP文件就是几千行，让模型生成这种格式，等于让一个写作新手直接写长篇小说，写到后面必然前后矛盾。STL是纯三角网格，虽然生成难度小一些，但它丢失了全部参数化信息，导出的模型无法编辑，改一个尺寸就得重来一遍。
正确做法是设计一个中间表示层：LLM输出的是结构化的建模代码，代码通过执行引擎转换成最终的几何模型。这个中间表示是我整个架构里最关键的决策点，它决定了生成结果能不能被编辑、能不能被参数化复用。CadQuery代码就是合格中间表示最好的例子——它本身是可读的Python代码，执行后生成几何体，同时还保留了完整的建模逻辑，任何一个尺寸改动都只需要改一个参数变量，不需要重新生成整个模型。
实际项目里我建议的链路是：自然语言指令 → LLM生成CadQuery代码（中间表示）→ 执行代码生成几何体 → 导出STEP/STL。这条链路里每一步都是可验证的、可修复的，不会像直接生成STEP那样一错错一坨。
2.3 为什么不直接生成STL网格
我遇到很多读者第一时间会想：既然STL是3D打印最常用的格式，直接让AI生成STL不就行了？我的回答是：能，但你会失去整个参数化能力。
STL本质上是一堆三角形的顶点坐标，它只描述“形状是什么”，不描述“形状怎么来的”。如果你让AI直接生成STL，出来的东西确实能看、能打印，但当你想改一下壁厚、改一下孔的位置、加一个倒角的时候，你没有任何参数可改，只能重新生成一遍。这在快速设计迭代的场景里是完全不可接受的。
更隐蔽的问题是，LLM生成的网格经常存在拓扑错误。三角形网格的顶点冗余、法线朝向不一致、裂缝和重叠面，这些是LLM直接生成网格时的高频错误。网格模型一旦进入打印切片或CAM编程阶段，这些细微的拓扑问题会被放大成打印失败或者加工撞刀。而使用CadQuery这类程序化建模生成的STEP模型，几何体是水密的、流形的，天然不存在这种问题。
这也是我为什么强调“代码作为中间表示”的原因。代码执行后得到的是精确的B-Rep实体模型，导出STL只是最后一步的离散化操作，精度可控，拓扑可靠，后续想改参数随时可以改代码重新执行。
3. 文本生成CAD的核心实现链路
3.1 提示词设计：把建模规则写进系统提示
text-to-cad的提示词设计和普通对话类AI应用完全不同。普通对话要求的是“表达清晰 ”，建模要求的是“规则约束下的结构化输出”。我在反复调试后总结出一套比较稳定的提示词结构，分享出来供参考。
系统提示中必须明确以下几类信息：单位约定、坐标系约定、建模方法边界、输出格式要求。单位约定最重要，模型默认使用的长度单位是毫米，任何尺寸都必须是数字加单位的形式，比如50mm而不是5cm，因为CAD建模里毫米是行业默认单位，模型一旦混淆单位，出来的零件尺寸直接差一个数量级。
坐标系约定上，我要求所有生成的代码统一使用“俯视平面为XY平面，Z轴向上”的右手坐标系约定，这是机械设计里的常规工程约定。LLM在没有明确坐标系约束时，容易出现镜像错误和左右颠倒，这个问题在后续测试中出现的频率不低。
建模方法边界必须明确告诉模型：禁止使用网格生成类API，禁止直接构造三角面片，所有几何必须通过参数化特征构建。这是为了守住中间表示的“参数化”底线，一旦模型绕过规则直接生成网格，就退回到上一节说的坏路上去了。
输出格式要求严格规定：必须输出纯Python代码，代码块内不允许有解释性文字，模型参数必须抽成变量暴露在__main__入口中。这个约束能让后处理脚本稳定地提取尺寸变量，做批量参数扫描的时候非常有用。
3.2 推理设置和代码后处理
LLM的推理参数设置对生成质量影响非常大，在我测试的几个模型上都验证了这一点。温度参数建议保持在0.2以下，采样策略改为确定性采样，这能显著减少代码生成的随机性。建模代码不像创意写作，不需要“多态表达”，它需要的是稳定、可复现、语法正确。我实测温度0.7和温度0.2的差异非常明显：前者生成的代码间歇性出现症状包括变量名不统一、坐标系方向随机切换、尺寸计算前后矛盾；后者错误率下降了将近一半。
有一个细节是很多人在做的：LLM生成的代码直接放进执行环境跑，失败就重试。这个思路效率太低，我建议在代码进入执行环境之前，加一道静态检查。检查项包括：import语句是否完整、是否存在未定义的变量、Workplane对象的方法链是否闭合、是否有明显的语法错误。这一层检查用Python的ast模块就能解析，成本很低，但能过滤掉至少三成以上的低级错误。
执行阶段建议放在隔离的子进程中，给临时目录配好超时策略。CadQuery本身执行速度不快，复杂一点的布尔运算可能要几秒，但如果代码里出现意外循环或者疯狂的阵列操作，执行可能卡死。子进程加超时能做到“生成失败快速返回，不拖垮整个服务”。我设的超时时间一般是30秒，超过自动终止，然后让LLM基于错误信息做一次性修正。
还有一个处理细节值得单独提一下：LLM生成的代码里很可能有cq.Workplane("XY").box(50, 30, 10)这种裸调用，这类代码依赖于全局别名。后处理时我会在代码前面统一注入import cadquery as cq和from cadquery import Workplane，这样无论LLM生成时用的什么别名风格，都能在统一环境下跑通。
3.3 一个完整例子：用一句话生成收纳盒
纸上谈兵没意思，直接看一个真实跑通的例子。这是我最常用的一个测试用例，描述是“一个带分隔板的收纳盒，外尺寸120×80×50毫米，壁厚2毫米，底部四角有直径6毫米的防滑脚垫孔，中间有一块垂直分隔板把内部空间平均分成左右两部分”。
LLM生成的CadQuery代码经过整理后大致是这个样子：
import cadquery as cq outer_length = 120.0 outer_width = 80.0 outer_height = 50.0 wall_thickness = 2.0 fillet_radius = 3.0 foot_pad_diameter = 6.0 foot_pad_height = 3.0 result = ( cq.Workplane("XY") .box(outer_length, outer_width, outer_height) .edges("|Z").fillet(fillet_radius) .faces(">Z").shell(-wall_thickness) .faces(">Z").workplane() .center(-outer_length / 4, 0) .rect(outer_length / 2 - wall_thickness, outer_width - 2 * wall_thickness) .cutBlind(-(outer_height - wall_thickness)) .faces("<Z").workplane() .center(0, 0) .pushPoints([(-outer_length / 2 + 10, -outer_width / 2 + 10), (outer_length / 2 - 10, -outer_width / 2 + 10), (-outer_length / 2 + 10, outer_width / 2 - 10), (outer_length / 2 - 10, outer_width / 2 - 10)]) .hole(foot_pad_diameter) )执行这段代码后生成的模型可以直观验证：外壳是一个带圆角的盒体，内部通过shell操作掏空，中间有一块分隔板正好把内部空间平分，底部有四个防滑脚垫孔位。整个模型完全参数化，改任何尺寸变量重新执行就能得到新规格的收纳盒。
整个过程里有一个特别值得说的细节：fillet圆角操作和shell掏空操作的顺序不能颠倒。如果先shell再fillet，圆角会作用在内外两个边线上，导致壁厚不均匀；而先fillet再shell，外轮廓圆角生成一次，内部掏空时自动继承偏移后的几何，壁厚保持均匀。这类经验是LLM不一定能通过思考推理出来的，必须靠建立“测试用例回归集”来守住。我自己维护了一个包含二十多个标准测试用例的回归集，每次改提示词或者换模型都要全部跑一遍，确保这些细节不被破坏。
4. 典型错误模式与排查实录
4.1 尺寸漂移和约束断裂
我在测试中花时间最多的一类问题，是生成结果“看起来差不多，但实际尺寸不对”。典型表现是：一个要求120毫米长的零件，生成出来长119.6毫米；一个要求对称的结构，左右两边差出0.3毫米。这种问题在肉眼观察时几乎发现不了，放进装配里就露馅了。
排查到最后，问题的根源在于LLM的“数值幻觉”。模型在推理尺寸时，不是严格按照用户给定的数值执行算术，而是根据语义猜测。比如“外尺寸减去两倍壁厚”这个计算，模型可能心算出116，也可能算出116.5。我的解决办法是在系统提示词里强制要求：所有派生尺寸必须给出计算表达式，禁止直接写数值。也就是说代码里不能出现box(116, 76, 50)这种直接数值，必须写成box(outer_length - 2 * wall_thickness, outer_width - 2 * wall_thickness, outer_height)。这样尺寸的推导链条就变成可验证的了，后处理脚本可以检查每一个派生尺寸的计算逻辑是否符合预期。
约束断裂是另一个高频问题。用户描述“居中放置”，生成结果却偏了2毫米；描述“等距分布”，结果间距不均匀。这在视觉上很隐蔽，但在功能上致命。排查思路是要求LLM在代码里显式使用构建方式来表达几何约束，比如用center()明确对齐到中心点，用pushPoints()传入对称坐标数组，而不是依赖于基准面的默认位置。
4.2 布尔运算失败和面未闭合问题
CadQuery的布尔运算失败是最让人头疼的一类错误。LLM生成代码时，如果两个实体的位置关系计算稍有偏差，比如重叠区域正好共面、或者两个实体之间有极小的缝隙，布尔运算就会失败或者产生奇异几何。最典型的案例是：用户要一个带贯穿孔的方块，圆柱体的长度只比方块厚度短了0.01毫米，结果cut操作就报错。
这类问题排查时，我建议先做几何校验再报错。CadQuery里有一个很有用的方法validate()，它检查实体的有效性，包括面是否闭合、边是否连续、体量是否为正。让LLM生成的代码在最终执行前强制插入一个validate()检查，但凡几何体不满足流形条件，就记录错误信息反馈给LLM做修正。
另一个常见的布尔运算错误是操作对象搞混。CadQuery里.cut()是减除，.union()是合并，.intersect()是交集。LLM在长代码链中偶尔会出现语义混淆，把一个本意是“挖孔”的操作写成了“合并”，模型直接变成一个实心块。我在后处理里做了一层检查：对每个布尔操作做类型标注，比如注释# cut: pocket for screw，然后由静态检查脚本提取注释意图和实际调用的操作类型做一致性比对，不一致就报错重试。
4.3 生成结果“不可编辑”的常见原因
很多用户反馈“生成的模型在CAD软件里打开后没法改尺寸”。折腾了一圈后我确认，这大多数不是text-to-cad的问题，而是导出格式和建模方式导致的附带问题。生成的STEP文件在FreeCAD里打开，本质上是一个导入的B-Rep实体，没有参数化特征历史。这和你在FreeCAD里从头建模得到的带特征树的模型是完全不同的东西。STEP格式本身就不携带建模特征历史，它能保证的是几何精度，不能保证可编辑性。
要让生成结果在CAD软件里真正可编辑，目前成熟的路线是直接使用CadQuery做参数驱动，修改代码文件中的尺寸变量，重新生成模型。团队使用时，我会建议把CadQuery代码文件当作“源文件”，导出的STEP/STL只当作“产物”分发给下游。这样任何尺寸调整都从源文件出发，改动变量重新导出，整个过程可靠又快速。
我在工程上还给每个生成的模型自动配一个参数清单JSON，里面记录所有暴露的尺寸变量以及它们在代码中的位置、单位、默认值、取值范围。这个JSON伴随源文件一起管理，下游需要改尺寸时，不需要看懂代码，只要编辑JSON里的数值就能生成新规格。这个做法在团队协作里特别受用，非软件背景的工程师拿到手就能调节参数。
4.4 常见问题速查表
| 问题现象 | 根本原因 | 解决办法 |
|---|---|---|
| 生成尺寸和预期差1~2毫米 | LLM直接推算数值而非调用表达式 | 要求派生尺寸必须用计算表达式表示 |
| 镜像件左右颠倒 | 坐标系约定不明确 | 在提示词中强制右手坐标系+方向描述 |
| 布尔减除后实体消失 | 圆柱贯穿长度不足导致面未交界 | 在提示词中要求所有贯穿体两端超出至少壁厚 |
| 圆角后壁厚不均匀 | fillet和shell操作顺序错误 | 用回归测试集固定操作顺序 |
| 生成代码执行超时 | 存在意外循环或超大阵列 | 子进程限时30秒，超时返回错误重试 |
| 打开STEP后无法改尺寸 | 导出格式不携带特征历史 | 以CadQuery代码为源文件，STEP只作产物分发 |
| 模型内部出现多余空腔 | 布尔运算对象选择错误 | 代码注释操作意图，做静态一致性检查 |
| 多次生成结果不稳定 | 推理温度过高 | 温度降到0.2并启用确定性采样 |
这些错误的排查经验都是实际跑出来的，不是从文档里抄来的。text-to-cad这种项目最麻烦的地方在于错误类型高度分散，既有纯代码层面的语法错误，也有几何语义层面的理解偏差，还有CAD引擎层面的边界情况。如果不在工程层面把这三种错误分开处理，排错效率会惨不忍睹。
5. 工程化落地的一些进阶建议
5.1 从单发生成到批量生成和结果缓存
单发模式的热度消退得比我预期快得多。用户第一次觉得新鲜，第二次第三次就要开始堆量。真正让text-to-cad产生实际价值的场景，往往是批量生成：一次生成十个规格的支架、二十种孔位组合的外壳、不同尺寸的系列化零件。这时候单次生成质量已经不是瓶颈，吞吐量才是。
我的做法是引入结果缓存机制。以“自然语言指令+解析后的参数表”的组合键生成哈希，作为缓存主键，命中缓存直接返回历史生成结果，不再调用LLM。实测数据是：批量生成40个变体零件，纯LLM生成加执行的时间是47分钟，启用缓存后同类任务只要11分钟，提升接近4倍。原因很明显：变体零件之间共享大量基础结构，只有尺寸和孔位不同，缓存能命中绝大部分公共子任务。
批量生成的另一个关键点是参数扫描能力。我会在代码生成阶段就把可能变化的参数全部抽成变量，然后配合一个参数扫描脚本，遍历给定的参数组合，逐个生成模型并重命名导出。这样“生成整个系列”这件事就从“反复对话”变成了“跑一次脚本”，效率和稳定性都不可同日而语。
5.2 可编辑性和智能约束的实战经验
关于可编辑性，前面提到以CadQuery代码为源文件只是起点。更进阶的做法是建立“约束规则库”，把常见的设计规范写成可执行的检查代码。比如“所有通孔必须沉头”“钣金件的折弯半径不得小于板厚”“壳体壁厚不得低于1.2毫米”。这些规则在LLM生成代码之后、几何执行之前自动运行，不符合规则的直接打回重生成。
这套做法的本质是给LLM加一道“物理世界的护栏”。LLM对几何的理解是概率性的，它对“这个孔离边太近了会不会导致强度不足”没有概念，但这个概念对实际工程至关重要。约束规则库把工程师多年的经验沉淀成计算机可执行的逻辑，每次生成都自动校验，避免低级设计错误反复出现。
我在规则库里维护最多的是孔位边距规则和最小壁厚规则，这两个占了实际拦截量的七成以上。原因也很现实：LLM生成孔位时倾向于按照视觉美观和对称性排布，很少考虑加工工艺边界。加入规则库后，肉眼可见地提升了“能直接用的生成比例”。
5.3 参数化模板的正确打开方式
用text-to-cad做新设计是一回事，把常用的设计沉淀成模板是更高一层的玩法。我实际使用的模板思路是这样的：每个模板是一个CadQuery代码文件，文件里定义了一组参数变量、默认值和取值范围，同时配套一段模板说明文档，写清楚这个模板适用于什么场景、哪些参数可以调整、哪些参数之间存在联动关系。
例如我常用的“带安装孔的L型支架”模板，参数包括底板长度、底板宽度、竖板高度、板厚、安装孔径、安装孔位置。生成新实例时，用户只需要填写参数表，模板代码自动产生对应的三维模型。这套东西配合前面说的约束规则库，能在五分钟内从无到有产出一个加工级别的支架模型。
真正拉开差距的地方在于模板沉淀的质量。我建议每个模板至少要经过三轮迭代才算成熟：第一轮实现功能和参数化，第二轮补约束规则和异常处理，第三轮做批量生成测试覆盖边界情况。三轮走完后，这个模板才算真正可以给别人用。粗制滥造的模板表面省时间，实际遇到边界情况时返工的成本远超收益。
text-to-cad这条路走了这么久，我个人最大的体会是：真正难的从来不是让LLM生成一段能跑的建模代码，而是把“自然语言描述”这种模糊、有歧义、充满个人表达习惯的输入，转化成“几何约束明确、参数关系清晰、工程规则可校验”的精确建模指令。这中间隔着一层语义消歧的工夫，也隔着一层工程标准的沉淀。能把这两层做扎实了，text-to-cad自然会从一个“看个新鲜”的试验品，变成设计流程里一个不太起眼但离不开的齿轮。
