text-to-cad 实战：从自然语言到 STEP 模型的技术链路与工程实践

1. 从一句话到三维模型：text-to-cad 到底在解决什么问题

第一次听到 text-to-cad 这个词，很多做机械设计或者三维建模的朋友第一反应是：又来个噱头。毕竟我们习惯了在 CAD 软件里一根线一根线地画，一个约束一个约束地加，突然说打一行字就能出模型，听起来像是把设计师的饭碗往地上摔。但实际用下来你会发现，它压根不是来替代谁的，它解决的是一个非常具体的痛点——从“脑子里有个大概形状”到“屏幕上有个能看能改的几何体”之间那段最枯燥的重复劳动。

举个很常见的场景。客户在电话里说：“我想要一个法兰盘，外径 120，内径 60，厚度 15，均匀分布 6 个直径 10 的孔，孔心圆直径 90。”你听完之后，打开 SolidWorks 或者 FreeCAD，新建草图，画圆，标注，拉伸，再画孔，阵列，倒角……一套下来熟练工也得五六分钟。但如果有一个工具能让你把上面那句话直接敲进去，三秒钟生成一个 STEP 文件，你只需要打开检查一下尺寸对不对，微调一下倒角，是不是省事多了？text-to-cad 干的就是这个活。它把自然语言描述翻译成 CAD 内核能理解的几何指令，输出标准格式如 STEP、GLB、STL，然后你拿着这些文件继续在专业软件里做后续处理。

这个方向适合谁呢？我总结了三类人最值得关注。第一类是经常需要做概念验证的机械工程师，前期方案阶段不需要精确到公差，只需要快速把想法可视化，拿去和团队讨论。第二类是做 3D 打印的创客，脑子里有个小零件想打出来，但不想为了一个简单的支架去学半个月的 CAD 操作。第三类是做参数化设计研究的开发者，想看看大语言模型在几何推理方面到底能做到什么程度，text-to-cad 是一个非常好的试验场。

但这里必须先把预期说清楚。text-to-cad 目前的能力边界非常明确：它擅长生成规则几何体——圆柱、长方体、孔、阵列、简单的布尔运算组合。你让它生成一个复杂的自由曲面，比如汽车车身或者涡轮叶片，它基本无能为力。这不是模型不够聪明的问题，而是自然语言本身就不适合描述复杂曲面。你试试用文字描述一个 A 级曲面的控制点分布，写三千字也说不清楚。所以它的定位是快速原型和简单零件生成，不是替代高精度建模。

还有一个关键点：text-to-cad 输出的 STEP 文件是边界表示（B-rep），不是网格。这意味着你拿到的是一个有精确数学定义的实体，可以在任何主流 CAD 软件里继续做特征操作，比如打孔、倒角、抽壳。而 STL 和 GLB 是网格格式，适合 3D 打印和可视化展示，但不适合做精确的工程修改。理解这个区别，你才知道什么时候该用哪种输出格式。

2. 拆开看核心：text-to-cad 的技术链路与关键选型

2.1 从文字到几何：中间到底发生了什么

很多人以为 text-to-cad 就是一个大模型直接输出一个模型文件，其实中间隔了好几层。我把它拆成四个阶段，每个阶段都有不同的技术选型和坑。

第一阶段是意图解析。你输入的那句“外径 120 内径 60 厚度 15 的圆环”，模型需要识别出这是一个圆环体，提取出三个关键参数，并且理解它们分别对应外径、内径和厚度。这一步用的是大语言模型的自然语言理解能力，但光理解还不够，它还得把参数映射到正确的几何属性上。我试过一些早期的实现，经常把“内径”和“外径”搞反，或者把“厚度”理解成“高度”，生成出来的东西完全不对。

第二阶段是几何表示转换。解析出来的参数需要变成一种中间表示。目前主流有两种路线：一种是基于代码的表示，比如生成 OpenSCAD 脚本或者 CadQuery 的 Python 代码；另一种是基于约束图的表示，直接输出一个几何约束网络。基于代码的路线更成熟，因为大语言模型本身就很擅长写代码，而且 CadQuery 和 OpenSCAD 都有清晰的文档和语法规则，模型容易学会。基于约束图的路线更接近 CAD 内核的原生逻辑，但训练数据少，实现难度大。

第三阶段是几何内核执行。中间表示被送入几何内核，比如 OpenCASCADE 或者 CGAL，执行实际的布尔运算、倒角、抽壳等操作，生成精确的 B-rep 实体。这一步的稳定性取决于内核本身，跟大模型关系不大。但这里有个隐藏问题：大模型生成的代码可能语法正确但几何上不可行，比如要求在一个厚度为 2mm 的板上打一个深度 5mm 的盲孔，内核会直接报错。

第四阶段是格式导出。B-rep 实体可以导出为 STEP，网格化之后可以导出为 STL 或 GLB。STEP 适合工程用途，STL 适合 3D 打印，GLB 适合网页展示。导出参数比如网格精度、法线计算方式，会直接影响 STL 文件的质量和大小。

2.2 为什么选 CadQuery 而不是 OpenSCAD

如果你要自己搭一套 text-to-cad 流程，中间表示选什么直接决定了后续的开发难度和生成质量。我两种都试过，最后偏向 CadQuery，原因有几个。

OpenSCAD 的语法更简单，本质上是一种声明式的 CSG（构造实体几何）语言，写起来像这样：

difference() { cylinder(h=15, d=120, center=true); cylinder(h=16, d=60, center=true); for (i = [0:5]) { rotate([0, 0, i*60]) translate([45, 0, 0]) cylinder(h=16, d=10, center=true); } }

这段代码生成的就是前面说的那个法兰盘。语法很直观，大模型学起来也快。但 OpenSCAD 的局限在于它只支持网格操作，导出的 STL 是三角面片，没有精确的 B-rep 表示。你没法在 SolidWorks 里打开一个 OpenSCAD 生成的模型然后修改孔的直径，因为它已经变成了一堆三角形。

CadQuery 则不同，它基于 OpenCASCADE 内核，生成的是真正的 B-rep 实体。同样的法兰盘，CadQuery 代码是这样的：

import cadquery as cq result = ( cq.Workplane("XY") .circle(60) .circle(30) .extrude(15) .faces(">Z") .workplane() .polarArray(45, 0, 360, 6) .hole(10) )

这段代码生成的实体可以导出为 STEP，在任意 CAD 软件里打开后，你能看到特征树，能修改孔的直径，能添加新的倒角。这才是工程上可用的东西。代价是 CadQuery 的学习曲线比 OpenSCAD 陡一些，而且大模型生成 CadQuery 代码的出错率略高，因为它的 API 更复杂。

我的建议是：如果你只做 3D 打印，OpenSCAD 够用；如果你要做工程交付，必须上 CadQuery 或者直接调 OpenCASCADE 的 API。中间没有太多折中方案。

2.3 STEP、GLB、STL 三种格式到底怎么选

输出格式的选择经常被忽略，但它直接影响你后续的工作流。我整理了一个对比表，方便你快速判断。

实际使用中，我通常会让 text-to-cad 流程同时输出 STEP 和 STL。STEP 用来存档和后续修改，STL 直接丢进切片软件看效果。GLB 只在需要做网页演示的时候才导出，因为它的材质系统跟工程无关，反而会增加文件复杂度。

注意：STL 导出时的网格精度参数非常关键。精度设得太低，圆柱面会变成明显的多边形；设得太高，文件体积爆炸。一般建议线性偏差控制在 0.01mm 到 0.05mm 之间，角度偏差控制在 0.5 弧度以内。具体数值取决于你的零件尺寸和打印精度。

3. 动手搭一套可用的 text-to-cad 流程

3.1 环境准备与依赖安装

如果你想自己跑通一套 text-to-cad 流程，最省事的起点是 Python 生态。CadQuery 有完整的 Python 包，大模型调用也有成熟的 SDK。我下面以本地运行为例，讲一下具体的环境配置。

首先创建一个干净的虚拟环境，避免跟系统里的其他包冲突：

python -m venv text2cad-env source text2cad-env/bin/activate # Windows 下用 text2cad-env\Scripts\activate

然后安装核心依赖。CadQuery 的安装稍微麻烦一点，因为它依赖 OpenCASCADE 的 Python 绑定。推荐用 conda 安装，比 pip 省心很多：

conda install -c conda-forge cadquery

如果你坚持用 pip，可以试试：

pip install cadquery

但我在 Windows 上遇到过 OpenCASCADE 动态库找不到的问题，最后还是换回了 conda。安装完成后，跑一句简单的测试确认环境正常：

import cadquery as cq box = cq.Workplane("XY").box(10, 10, 10) cq.exporters.export(box, "test.step") print("CadQuery 环境正常")

如果当前目录下生成了一个 test.step 文件，说明几何内核工作正常。接下来安装大模型调用相关的包，具体用哪家看你的偏好，这里不展开。

3.2 提示词工程：怎么让模型生成可执行的几何代码

这是整个流程里最需要经验的部分。大模型不是万能的，你给它的提示词质量直接决定生成代码的可用性。我踩了无数坑之后，总结出一个比较稳的提示词模板结构。

第一段是角色设定，告诉模型它是一个 CAD 代码生成器，只输出 CadQuery 代码，不要解释，不要多余文字。第二段是可用 API 列表，把 CadQuery 里常用的方法列出来，比如box、cylinder、hole、fillet、chamfer、polarArray、rectangularArray，并给出每个方法的参数含义。第三段是输出格式约束，要求代码以import cadquery as cq开头，以result = ...结尾，中间不要有 print 语句。第四段才是用户的实际描述。

我实测下来，加上 API 列表之后，代码一次通过率能从不到 40% 提升到 70% 以上。原因很简单：大模型虽然见过 CadQuery 的代码，但它的训练数据里 CadQuery 的版本可能比较老，API 有变化。你明确告诉它当前版本支持哪些方法，它就不会瞎编。

还有一个技巧：把复杂零件拆成多个简单特征的组合。比如你要生成一个带法兰的轴，不要一句话描述完，而是分成三步：先生成一个圆柱轴，再在底部生成一个法兰盘，最后在法兰上打孔。每一步单独生成代码，最后用布尔运算合并。这样即使某一步出错，也容易定位和修复。

3.3 完整实操：从一句话到 STEP 文件

下面我走一遍完整的流程，生成一个带安装孔的 L 型支架。这个例子涵盖了拉伸、打孔、倒角和阵列，比较有代表性。

第一步，构造提示词。我实际用的提示词是这样的：

你是一个 CadQuery 代码生成器。根据用户的描述生成可执行的 CadQuery Python 代码。 可用 API： - Workplane("XY") 创建草图平面 - .rect(w, h) 绘制矩形 - .circle(r) 绘制圆 - .extrude(d) 拉伸 - .faces(">Z") 选择顶面 - .workplane() 在工作面上创建新草图 - .hole(d) 打孔 - .fillet(r) 倒圆角 - .edges("|Z").fillet(r) 对垂直边倒圆角 - .polarArray(radius, startAngle, angle, count) 极坐标阵列 - .rectangularArray(xSpacing, ySpacing, xCount, yCount) 矩形阵列 输出要求：只输出 Python 代码，以 import cadquery as cq 开头，以 result = ... 结尾。 用户描述：生成一个 L 型支架。底板长 80，宽 60，厚度 8。竖板在底板的一条长边上，高度 50，厚度 8。底板四个角各有一个直径 6 的安装孔，孔心距边缘 10。所有外角倒圆角 R3。

第二步，把提示词发给模型，拿到代码。我实际收到的代码大致如下：

import cadquery as cq # 底板 base = ( cq.Workplane("XY") .rect(80, 60) .extrude(8) ) # 竖板 vertical = ( cq.Workplane("XZ") .rect(80, 50) .extrude(8) ) # 合并 result = base.union(vertical) # 倒圆角 result = result.edges("|Z").fillet(3) # 打安装孔 result = ( result.faces(">Z") .workplane() .rect(60, 40, forConstruction=True) .vertices() .hole(6) ) cq.exporters.export(result, "bracket.step")

第三步，检查代码。这里有几个地方需要人工确认：竖板的位置是否正确？Workplane("XZ")创建的平面在 Y=0 处，拉伸方向是 Y 轴正方向，所以竖板会从底板的前边缘向后延伸 8mm，这符合“竖板在底板的一条长边上”的要求。安装孔的位置用构造矩形的方式定位，矩形尺寸 60x40，顶点坐标是 (±30, ±20)，对应底板边缘的距离是 40-30=10 和 30-20=10，正好符合“孔心距边缘 10”的要求。

第四步，运行代码。如果一切正常，当前目录下会生成 bracket.step。用 FreeCAD 或者任意在线 STEP 查看器打开，确认几何形状无误。

第五步，导出 STL 用于 3D 打印：

cq.exporters.export(result, "bracket.stl", tolerance=0.02, angularTolerance=0.3)

这里的tolerance是线性偏差，angularTolerance是角度偏差。对于这个尺寸的支架，0.02mm 的线性偏差已经足够精细，STL 文件大概在 200KB 左右，切片软件处理起来毫无压力。

3.4 参数化调整：让生成结果可复用

text-to-cad 最大的价值不是生成一次性的模型，而是生成可参数化的代码。你拿到 CadQuery 代码之后，可以把关键尺寸提取成变量，以后改参数就能重新生成，不需要再跟大模型对话。

比如上面的支架代码，我可以改成这样：

import cadquery as cq BASE_L = 80 BASE_W = 60 BASE_T = 8 VERT_H = 50 VERT_T = 8 HOLE_D = 6 HOLE_EDGE = 10 FILLET_R = 3 base = cq.Workplane("XY").rect(BASE_L, BASE_W).extrude(BASE_T) vertical = cq.Workplane("XZ").rect(BASE_L, VERT_H).extrude(VERT_T) result = base.union(vertical) result = result.edges("|Z").fillet(FILLET_R) hole_x = BASE_L - 2 * HOLE_EDGE hole_y = BASE_W - 2 * HOLE_EDGE result = ( result.faces(">Z") .workplane() .rect(hole_x, hole_y, forConstruction=True) .vertices() .hole(HOLE_D) ) cq.exporters.export(result, "bracket.step")

这样你只需要改最上面的几个数字，就能生成不同尺寸的支架。我通常会把这类参数化脚本存成一个模板库，下次遇到类似零件，直接改参数就行，比重新跟大模型对话快得多，而且结果完全可控。

4. 踩坑实录：text-to-cad 常见问题与排查技巧

4.1 模型生成的代码跑不通怎么办

这是最常见的问题，没有之一。大模型生成的 CadQuery 代码大概有 20% 到 30% 的概率会报错，原因五花八门。我整理了一个排查顺序，按这个顺序走，基本能解决九成以上的问题。

先看报错类型。如果是AttributeError，说明模型用了不存在的 API 方法，比如把polarArray写成了polar_array，或者用了旧版本的Workplane方法。这时候你需要把报错信息连同代码一起发回给模型，让它修正。如果是ValueError或者Standard_Failure，说明几何运算本身有问题，比如倒角半径太大导致几何退化，或者布尔运算的两个实体没有相交。这时候需要调整参数，而不是改代码结构。

再看几何合理性。有时候代码能跑通，但生成的模型是空的，或者只有一个面。这通常是因为草图没有闭合，或者拉伸方向反了。我遇到过一次，模型生成的代码里extrude的参数是负数，结果实体往反方向拉伸，跟另一个实体完全没有交集，布尔并集之后只剩下一个实体。这种问题不会报错，但结果明显不对，需要你打开模型看一眼。

最后看单位。CadQuery 默认单位是毫米，但有些模型会假设单位是米或者英寸。如果你发现生成的模型尺寸差了 1000 倍，大概率是单位问题。在提示词里明确写“所有尺寸单位为毫米”，能避免大部分单位混乱。

4.2 复杂形状生成失败怎么拆解

前面说过，text-to-cad 不擅长复杂曲面。但即使是规则几何体，如果特征太多，一次性生成的成功率也会急剧下降。我的经验是：超过五个特征，就拆成多步。

举个例子，你要生成一个带散热片的电机外壳。这个零件包含：圆柱主体、中心轴孔、六个散热片、四个安装耳、每个安装耳上有一个孔。总共十几个特征。一次性让模型生成，基本必挂。但如果你拆成三步：第一步生成圆柱主体和轴孔，第二步生成散热片并阵列，第三步生成安装耳和孔，每一步单独生成代码，最后用布尔运算合并，成功率会高很多。

拆解的时候要注意基准统一。每一步生成的实体最好都以原点为中心，或者以同一个基准面为参考。否则合并的时候位置对不上，你还得手动调整坐标。我通常会在提示词里明确要求“所有实体以原点为中心，Z 轴为拉伸方向”，这样合并的时候直接做并集就行。

4.3 导出的 STL 文件太大或太粗糙

STL 文件的质量完全由导出参数决定。CadQuery 的export函数有两个关键参数：tolerance和angularTolerance。tolerance控制线性偏差，单位是毫米；angularTolerance控制角度偏差，单位是弧度。

我做过一组对比测试，同一个法兰盘模型，不同参数下的 STL 文件大小和三角面片数量如下：

对于大多数 3D 打印场景，tolerance=0.02到0.05、angularTolerance=0.2到0.3是比较平衡的选择。如果你要做高精度的装配验证，可以降到tolerance=0.01，但文件会大很多。我的建议是先用粗参数导出一版看形状，确认无误后再用细参数导出最终版本。

注意：STL 文件只包含三角面片信息，不包含颜色、材质、单位。如果你把 STL 发给别人，对方不知道你的单位是毫米还是英寸。所以最好在文件名里标注单位，比如bracket_mm.stl，避免沟通成本。

4.4 常见问题速查表

5. 进阶玩法：把 text-to-cad 接入你的日常工作流

5.1 批量生成与自动化

如果你经常需要生成一系列相似但尺寸不同的零件，text-to-cad 可以跟脚本结合，实现批量生成。思路很简单：把参数写成一个列表，循环调用生成函数，每次输出不同的 STEP 和 STL 文件。

比如你要生成一系列不同长度的轴，直径固定 20mm，长度从 50mm 到 200mm，步长 10mm。用 CadQuery 写一个循环就行：

import cadquery as cq for length in range(50, 210, 10): shaft = ( cq.Workplane("XY") .circle(10) .extrude(length) .edges("|Z") .fillet(1) ) cq.exporters.export(shaft, f"shaft_L{length}.step") cq.exporters.export(shaft, f"shaft_L{length}.stl", tolerance=0.02)

这段代码会生成 17 个 STEP 文件和 17 个 STL 文件，每个文件的长度不同。如果你用 text-to-cad 生成基础代码，然后手动改成参数化循环，效率比一个个跟模型对话高得多。

5.2 与现有 CAD 软件的配合

text-to-cad 生成的 STEP 文件可以直接导入 SolidWorks、Fusion 360、FreeCAD、中望 CAD 等主流软件。导入之后，你看到的是一个无特征历史的实体，也就是说你不能直接修改某个孔的直径，因为软件不知道那个孔是怎么来的。但这不影响你在此基础上添加新的特征，比如倒角、抽壳、打新的孔。

如果你需要修改 text-to-cad 生成的原始特征，有两个办法。一是回到 CadQuery 代码，改参数重新生成。二是用 CAD 软件的直接建模功能，比如 SolidWorks 的 Move Face 或者 Fusion 360 的 Push/Pull，直接拖动面来修改尺寸。前者更精确，后者更灵活，看你的具体需求。

我个人的习惯是：概念阶段用 text-to-cad 快速生成，确认方案后用 CAD 软件重新建模。因为 text-to-cad 生成的模型虽然几何正确，但特征树是扁平的，不利于后续的工程管理和版本控制。正式交付的模型还是要在专业软件里从头建一遍，确保每一步特征都清晰可追溯。

5.3 精度与公差的现实边界

必须说清楚一点：text-to-cad 目前不适合生成有严格公差要求的零件。它生成的几何是名义尺寸，没有公差标注，没有配合关系，没有表面粗糙度。你拿它做一个概念模型没问题，但如果你要拿去加工，必须导入 CAD 软件重新标注公差。

我试过让模型生成一个“直径 10 毫米的轴，公差 h7”，它生成的还是一个直径 10 的圆柱，没有任何公差信息。因为 STEP 格式本身可以携带公差信息，但 CadQuery 的 API 不直接支持公差标注，大模型也没有能力理解公差配合的工程含义。

所以我的建议是：text-to-cad 负责几何形状的快速生成，公差和工程标注交给专业 CAD 软件。两者是互补关系，不是替代关系。你省下的是画草图的时间，不是做工程决策的时间。

6. 我个人的一些实操体会

用了大半年 text-to-cad 之后，我最大的感受是：它改变的不是建模的方式，而是思考的方式。以前我打开 CAD 软件，第一件事是选基准面，然后开始画草图。现在我会先想清楚这个零件的关键特征是什么，用一句话能不能说清楚。如果说不清楚，说明我自己还没想明白，那就先想明白再动手。

另一个体会是：提示词的质量比模型的能力更重要。同一个模型，我用不同的提示词，生成代码的成功率能差三倍。我现在的习惯是，每次生成之前先花两分钟写提示词，把关键尺寸、特征顺序、输出格式都写清楚。这两分钟能省下后面二十分钟的调试时间。

还有一个坑我踩过好几次：不要完全信任模型生成的尺寸。有一次我让模型生成一个“内径 50 外径 80 的垫圈”，它生成的代码里内径和外径的数值是对的，但单位搞成了厘米，结果模型大了十倍。从那以后，我每次生成完都会用卡尺量一下关键尺寸，确认无误再往下走。

最后说一个我觉得最有价值的用法：用 text-to-cad 做设计探索。以前我做一个新零件，要在 CAD 里试好几种方案，每次都要重新画。现在我可以快速生成三四个不同方案的 STEP 文件，导入软件里对比，选中最合适的那个再细化。这种快速迭代的感觉，是传统建模方式给不了的。