text-to-cad 实战：从自然语言到 STEP/URDF/G-code 的完整技术链路

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

第一次听到 “text-to-cad” 这个词，很多人脑子里浮现的画面大概是：对着电脑敲一行字，比如“一个长宽高 100×60×30 的带圆角法兰底座”，然后软件自动吐出一个可以旋转查看的三维模型。这个想象方向没错，但真正落地的时候，它牵扯到的东西比“输入文字、输出模型”要复杂得多。我前后折腾过几套不同的实现路径，也踩了不少坑，这里把整个思路、技术选型、实操细节和排查经验完整梳理一遍。

先把概念说清楚。text-to-cad，字面意思就是“文本到 CAD 模型”。它的核心目标是把自然语言描述或者结构化文本，转换成计算机辅助设计软件能够识别和编辑的几何模型文件。这里的“CAD”不是单指某一个软件，而是一大类工具链，包括参数化建模工具、机械设计软件、建筑制图工具等等。而输出格式也不止一种，常见的有STEP、URDF、G-code、STL、DXF 等，每种格式对应不同的下游用途。

为什么这件事值得做？因为传统 CAD 建模的门槛并不低。一个熟练的工程师画一个中等复杂度的零件，可能需要几十分钟到几个小时，而且每次修改尺寸都要回到草图重新约束。如果能把“描述”直接变成“模型”，哪怕只是生成一个初版骨架，也能省掉大量重复劳动。更关键的是，在批量生成、参数化变体、自动化流水线这些场景里，人工建模根本跟不上节奏。

这个方向适合谁来参考？我总结下来有三类人最需要：一是做机械设计或工业设计的工程师，想用脚本批量生成标准件；二是做机器人仿真的人，需要快速产出 URDF 模型导入仿真环境；三是做增材制造或数控加工的人，想把设计意图直接转成 G-code 或 STEP 去驱动设备。哪怕你只是刚接触 CAD 制图入门，理解这套流程也能帮你建立“描述—几何—文件”的完整认知。

需要提前说明的是，text-to-cad 目前并不是一个“万能翻译器”。自然语言本身有歧义，而 CAD 对几何精度的要求是硬性的。所以真正可用的方案，通常是在“自然语言”和“精确几何”之间加一层结构化表达，比如用 JSON、DSL 或者参数表来约束。这一点在后面会详细展开。

2. 整体方案设计与技术选型思路

2.1 为什么不能直接让大模型输出 STEP 文件

很多人第一反应是：既然大模型能写代码，那让它直接生成 STEP 文件不就行了？我试过，结论是：能生成，但基本不能用。原因在于 STEP 文件本质上是一种精确的边界表示（B-Rep）格式，里面记录的是点、线、面、曲面方程的精确数学定义。大模型擅长的是语言和代码结构，它对空间几何的数值精度、拓扑关系、曲面连续性并没有真正的“理解”。

举个实际例子。我让模型生成一个“带 4 个 M6 螺栓孔的 120×80×10 的板”，它给出的 STEP 文本里孔的位置是近似值，孔壁和板面的交线也没有正确闭合。导入 CAD 软件后直接报错，或者显示成一个破面实体。这不是模型能力不够，而是 STEP 这种格式本身就不适合用文本逐行“写”出来。

所以正确的思路是：让文本先变成参数和结构，再由几何内核去生成精确模型。这就引出了下面的分层架构。

2.2 三层架构：文本解析层、几何构建层、格式导出层

我最终稳定下来的方案是三层结构，每一层职责清晰，出了问题也容易定位。

第一层是文本解析层。输入可以是一句自然语言，也可以是一段结构化描述。这一层的任务是把“人话”翻译成机器能执行的参数集合。比如“一个外径 50、内径 30、厚度 8 的垫圈”，解析后应该得到{outer_d: 50, inner_d: 30, thickness: 8, type: "washer"}这样的结构。如果输入本身已经是 JSON 或参数表，这一层就可以跳过。

第二层是几何构建层。这一层调用几何内核，用参数去构造实体。常用的内核有 OpenCASCADE、CGAL、Manifold 等。OpenCASCADE 是最成熟的选择，它对 STEP、IGES 的支持非常完整，布尔运算也稳定。Python 环境下可以用pythonocc-core或者cadquery来调用它。CadQuery 的优势是 API 更友好，写起来像在描述几何，而不是在操作底层数据结构。

第三层是格式导出层。根据下游需求，把构建好的实体导出成 STEP、STL、URDF 或 G-code。STEP 用于后续编辑和交换，STL 用于 3D 打印预览，URDF 用于机器人仿真，G-code 用于数控加工。每一层的导出参数都不一样，后面会细说。

2.3 工具选型对比：CadQuery、OpenSCAD、FreeCAD 脚本

在几何构建这一层，我实际用过三种方案，各有取舍。

我最后选的是 CadQuery 作为主力，原因是它在“代码简洁”和“几何精确”之间平衡得最好。比如画一个带孔的法兰，CadQuery 里几行就能搞定，而且导出的 STEP 在 SolidWorks 和中望 CAD 里都能正常打开。OpenSCAD 虽然上手快，但它导出的模型是网格化的，转 STEP 会丢失精确曲面信息，做机械件不太合适。

2.4 输出格式的选择逻辑

输出格式不是随便选的，它取决于你下一步要干什么。这里列一个我常用的判断表。

这里要特别提一下 URDF。很多人搜“urdf 导入 coppeliasim”，其实就是想把模型放进仿真环境。URDF 本身是 XML 格式，描述的是连杆和关节的层级关系，不是单纯的几何。所以从 text-to-cad 生成 URDF，需要在几何之外额外定义运动学结构。这一点在机器人场景里非常关键，后面会单独讲。

3. 核心细节解析与实操要点

3.1 文本解析：从自然语言到参数表的关键转换

文本解析这一层，最容易出问题的地方是歧义。比如“一个 100 的圆”，这个 100 是直径还是半径？在工程语境里默认是直径，但模型不一定知道。所以我在实际项目里加了一条规则：所有尺寸必须带单位或明确标注直径/半径。如果输入是“直径 100 的圆”，解析结果就是{diameter: 100}；如果是“半径 50”，就是{radius: 50}。这样后续几何构建就不会搞错。

另一个坑是复合描述。比如“一个底板，上面有 4 个孔，孔距 80，孔径 6”。这句话里其实包含了三个层次：底板尺寸、孔的数量和位置、孔的直径。如果直接丢给模型解析，很容易漏掉孔距。我的做法是先把描述拆成“主体 + 特征”两部分，主体是底板，特征是孔阵列。然后分别解析，最后在几何层组合。

实际操作中，我会用一个简单的 JSON Schema 来约束解析结果。比如：

{ "type": "plate", "dimensions": {"length": 120, "width": 80, "thickness": 10}, "features": [ {"type": "hole", "diameter": 6, "count": 4, "spacing": {"x": 80, "y": 40}} ] }

这样即使自然语言描述有出入，最终落到几何层的参数是确定的。如果输入本身就是这种结构，那解析层可以直接跳过，效率更高。

提示：如果你的输入来源是 Excel 参数表或者数据库，建议直接跳过自然语言解析，用脚本读取表格生成 JSON。这样精度最高，也最容易批量处理。

3.2 几何构建：用 CadQuery 构造精确实体的核心步骤

几何构建是整个流程里最“硬”的部分。我以 CadQuery 为例，讲一个完整零件的构建过程。假设我们要生成一个带圆角和螺栓孔的安装板。

第一步是建立基础草图。CadQuery 里用Workplane来定义工作平面，然后画矩形。代码大概是这样：

import cadquery as cq length = 120 width = 80 thickness = 10 fillet_radius = 5 base = ( cq.Workplane("XY") .rect(length, width) .extrude(thickness) )

这段代码的意思是：在 XY 平面上画一个 120×80 的矩形，然后向上拉伸 10 毫米。extrude的方向默认是 Z 轴正方向，厚度就是拉伸距离。

第二步是倒圆角。圆角不是随便加的，它会影响后续孔的定位。如果先打孔再倒角，孔边缘可能会被圆角切掉。所以正确顺序是先倒角，再打孔。CadQuery 里用edges("|Z")选中竖直边，然后fillet：

base = base.edges("|Z").fillet(fillet_radius)

这里|Z表示平行于 Z 轴的边，也就是四个竖直棱边。倒角半径 5 毫米，实际加工中这个值不能太大，否则会削弱结构强度。

第三步是打孔。假设 4 个孔分布在四角，孔距边缘 15 毫米，孔径 6 毫米。可以用faces(">Z")选中顶面，然后hole或者cboreHole：

hole_d = 6 margin = 15 base = ( base.faces(">Z") .workplane() .rect(length - 2*margin, width - 2*margin, forConstruction=True) .vertices() .hole(hole_d) )

这段代码的逻辑是：在顶面建立一个工作平面，画一个辅助矩形（forConstruction=True表示只用于定位，不参与实体），然后选中矩形的四个顶点，在每个顶点处打一个直径 6 的孔。这样孔的位置就自动算好了，不需要手动输入坐标。

第四步是导出 STEP。CadQuery 的导出很简单：

cq.exporters.export(base, "mounting_plate.step")

导出的 STEP 文件可以在中望 CAD、SolidWorks、Fusion 360 里直接打开。我实测下来，OpenCASCADE 导出的 STEP 兼容性很好，国产 CAD 也能正常读取。

注意：导出前一定要检查实体是否闭合。如果布尔运算失败，导出的 STEP 可能是空文件或者破面。CadQuery 里可以用base.val().isValid()来校验。

3.3 参数化设计的核心：变量驱动与约束传递

text-to-cad 真正的价值不在于生成一个固定模型，而在于参数化。也就是说，同一个脚本，改几个变量就能生成一系列不同规格的零件。这在标准件库、系列化产品设计里非常实用。

我通常会把所有可变参数集中放在脚本开头，用一个字典或者单独的配置文件管理。比如：

PARAMS = { "length": 120, "width": 80, "thickness": 10, "fillet_radius": 5, "hole_diameter": 6, "hole_margin": 15 }

然后在几何构建时引用这些变量。这样改一个值，整个模型自动更新。更进一步，可以把参数表做成 CSV，用循环批量生成不同规格的 STEP 文件。我做过一个测试，用 20 组参数生成 20 个法兰模型，整个过程不到 30 秒，比手动建模快了几百倍。

这里的关键是约束传递。比如孔的位置依赖于板的尺寸和边距，如果板长变了，孔的位置也要跟着变。所以在写脚本时，孔的位置不能用绝对坐标，而要用length - 2*margin这样的表达式。这样参数一变，所有相关尺寸自动联动。

3.4 URDF 与 G-code 的特殊处理

URDF 和 G-code 跟 STEP 不太一样，它们不只是几何格式，还带有额外的语义信息。

先说 URDF。URDF 是机器人描述格式，它描述的是连杆（link）和关节（joint）的树状结构。从 text-to-cad 生成 URDF，除了几何形状，还需要定义每个连杆的质量、惯性矩阵、关节类型和运动范围。我一般的做法是：先用 CadQuery 生成每个连杆的 STEP 或 STL，然后在 URDF 文件里引用这些网格文件，再补充运动学参数。比如一个简单的两连杆机械臂：

<robot name="arm"> <link name="base_link"> <visual> <geometry> <mesh filename="base.stl"/> </geometry> </visual> </link> <joint name="joint1" type="revolute"> <parent link="base_link"/> <child link="link1"/> <axis xyz="0 0 1"/> <limit lower="-3.14" upper="3.14" effort="10" velocity="1"/> </joint> </robot>

导入 CoppeliaSim 时，只要把 URDF 和对应的 STL 放在同一目录，仿真环境就能自动加载。这里常见的坑是单位不一致。URDF 默认用米，而 CAD 模型常用毫米。如果不做缩放，导入后模型会大 1000 倍。我的做法是在导出 STL 时统一用米，或者在 URDF 里加scale属性。

再说 G-code。G-code 是数控加工指令，它不是模型格式，而是刀具路径。从 text-to-cad 到 G-code，中间需要 CAM 处理。也就是说，先有 STEP 模型，再用 CAM 软件生成刀路，最后后处理成 G-code。这一步我通常不直接在 Python 里做，而是把 STEP 导出后，用 FreeCAD 的 Path 工作台或者专用 CAM 工具处理。如果只是简单的 2.5D 铣削，也可以用 Python 直接生成 G-code，但复杂曲面就不建议了。

4. 完整实操流程与关键环节实现

4.1 环境搭建：Python 与 CadQuery 的安装配置

环境搭建这一步，我踩过最多的坑是依赖冲突。CadQuery 依赖 OpenCASCADE 的 Python 绑定，而不同版本的 OCC 对 Python 版本有要求。我目前稳定用的组合是 Python 3.10 + CadQuery 2.4 + OCP 7.7。

安装方式我推荐用 conda，因为 conda 能自动处理二进制依赖：

conda create -n text2cad python=3.10 conda activate text2cad conda install -c conda-forge cadquery

如果用 pip 安装，有时候会遇到 OCC 库找不到的问题，尤其是在 Windows 上。conda 的包管理更省心。安装完成后，用下面这行代码验证：

import cadquery as cq print(cq.__version__)

如果输出版本号，说明环境没问题。如果报ImportError，大概率是 OCC 的动态库没加载上，可以检查 conda 环境是否激活正确。

提示：如果你同时装了多个 Python 环境，一定要确认当前终端用的是正确的那个。我见过有人装了 CadQuery 但跑脚本时用的是系统 Python，结果一直报模块找不到。

4.2 从文本到 STEP 的完整脚本示例

下面是一个完整的脚本，从参数定义到 STEP 导出，覆盖了前面讲的各个环节。我把它拆成几个函数，方便复用。

import cadquery as cq import json def parse_params(json_str): """解析 JSON 参数""" return json.loads(json_str) def build_plate(params): """构建带孔安装板""" length = params["length"] width = params["width"] thickness = params["thickness"] fillet_r = params["fillet_radius"] hole_d = params["hole_diameter"] margin = params["hole_margin"] # 基础板 plate = ( cq.Workplane("XY") .rect(length, width) .extrude(thickness) ) # 倒圆角 plate = plate.edges("|Z").fillet(fillet_r) # 打孔 plate = ( plate.faces(">Z") .workplane() .rect(length - 2*margin, width - 2*margin, forConstruction=True) .vertices() .hole(hole_d) ) return plate def export_step(model, filename): """导出 STEP""" if not model.val().isValid(): raise ValueError("模型无效，请检查布尔运算") cq.exporters.export(model, filename) print(f"已导出: {filename}") if __name__ == "__main__": param_json = ''' { "length": 120, "width": 80, "thickness": 10, "fillet_radius": 5, "hole_diameter": 6, "hole_margin": 15 } ''' params = parse_params(param_json) model = build_plate(params) export_step(model, "mounting_plate.step")

这个脚本可以直接运行，生成的 STEP 文件用中望 CAD 或 SolidWorks 打开都能正常显示。如果你想批量生成，只需要把参数 JSON 换成列表，循环调用build_plate和export_step就行。

4.3 批量生成与参数表驱动

批量生成是 text-to-cad 最实用的场景之一。我通常会把参数放在 CSV 里，每行一组规格，然后用 pandas 读取，循环生成。

import pandas as pd df = pd.read_csv("params.csv") for idx, row in df.iterrows(): params = row.to_dict() model = build_plate(params) export_step(model, f"plate_{idx}.step")

这里要注意的是参数校验。如果 CSV 里某个值缺失或者类型不对，脚本会直接报错。我的做法是在build_plate开头加一层检查，比如length必须大于 0，hole_diameter必须小于width - 2*margin。这样能在生成前就发现问题，避免导出无效模型。

另外，批量生成时建议加日志。每生成一个文件就打印一行，方便追踪进度。如果某个参数组合失败，也能快速定位是哪一行。

4.4 导出后的校验与下游对接

模型导出后，不要直接丢给下游，一定要做校验。我常用的校验方式有三种。

第一种是文件大小检查。正常的 STEP 文件大小跟模型复杂度相关，如果只有几 KB，很可能是空文件或者破面。第二种是重新导入检查。用 CadQuery 或 FreeCAD 重新读取 STEP，看能否正常加载。第三种是可视化检查。用cadquery.vis或者导出 STL 后用网格查看器看一眼，确认形状符合预期。

下游对接方面，如果是要导入 CoppeliaSim，记得把 STL 和 URDF 放在同一目录，并检查单位缩放。如果是要加工，STEP 导入 CAM 软件后要检查刀具路径是否覆盖所有特征。如果是要 3D 打印，STL 导出时注意网格精度，太粗会丢细节，太细文件会很大。

5. 常见问题与排查技巧实录

5.1 模型导出失败或破面的排查思路

这是最常见的问题。表现是导出的 STEP 文件打不开，或者打开后显示为破面实体。原因通常有三个：布尔运算失败、实体不闭合、导出参数不对。

排查顺序我一般是这样的。先检查model.val().isValid()，如果返回 False，说明实体本身有问题。然后检查布尔运算，比如打孔时孔是否完全穿透，如果孔深等于板厚，可能会产生零厚度面，导致实体无效。解决办法是让孔深稍微大于板厚，比如thickness + 1。再检查倒角半径，如果圆角半径大于板厚的一半，也会导致几何无效。

还有一个隐蔽的坑是工作平面选择错误。比如在faces(">Z")上打孔，如果模型被旋转过，>Z可能指向错误的方向。我的习惯是在关键步骤后打印一下当前工作平面的法向量，确认方向正确。

5.2 单位与坐标系不一致导致的下游问题

单位问题我吃过好几次亏。CAD 脚本里默认用毫米，但 URDF 默认用米，STL 没有单位概念但切片软件通常按毫米处理。如果不统一，导入仿真环境后模型会大得离谱或者小得看不见。

我的做法是在项目开始就定一个基准单位，所有脚本都用这个单位。如果下游需要不同单位，在导出时统一转换。比如导出 URDF 用的 STL 时，把毫米除以 1000 转成米。坐标系也一样，CAD 里 Z 轴向上，但有些仿真环境 Y 轴向上，导入后需要旋转。这些转换最好在脚本里写死，不要手动调。

5.3 自然语言歧义导致的参数错误

自然语言解析最大的风险是歧义。比如“一个 50 的孔”，可能是直径 50，也可能是半径 50，还可能是深度 50。我的经验是：在解析层加确认机制。如果描述里没有明确单位或类型，就抛出异常，要求输入方补充。不要猜，猜错了后面全错。

另一个技巧是用模板约束输入。与其让用户自由输入，不如提供一个模板，比如“直径 [D] 的孔，深度 [H]，位置 [X,Y]”。这样解析起来确定性高，出错概率低。如果输入来源是人工填表，模板就更重要了。

5.4 常见问题速查表

提示：遇到问题时，先把模型简化到最小可复现的程度。比如只画一个矩形拉伸，确认能导出 STEP，再逐步加特征。这样能快速定位是哪一步出的问题。

5.5 几个我踩过的坑和独家技巧

第一个坑是中文路径。CadQuery 在导出文件时，如果路径包含中文，有时候会报编码错误。我的解决办法是全部用英文路径，或者用os.path处理后再传入。

第二个坑是并发导出。我试过用多线程批量生成 STEP，结果 OpenCASCADE 不是线程安全的，偶尔会崩溃。后来改成多进程，每个进程独立初始化，就稳定了。

第三个技巧是缓存中间结果。如果几何构建很耗时，可以把中间实体序列化成 BREP 文件，下次直接加载，省去重复计算。CadQuery 支持exporters.export(model, "temp.brep")和importers.importBrep。

第四个技巧是用版本控制管理脚本。参数化脚本改来改去很容易乱，用 Git 管理，每次改动都有记录。特别是当你要回退到某个旧版本时，版本控制能救命。

6. 从 CAD 到制造：text-to-cad 的延伸场景

6.1 与 3D 打印切片流程的衔接

text-to-cad 生成的 STEP 或 STL，可以直接进入 3D 打印流程。我的做法是：先用 CadQuery 导出 STL，然后用切片软件（如 Cura 或 PrusaSlicer）加载，设置层高、填充率、支撑等参数，最后导出 G-code。如果只是简单零件，这一步可以全自动完成。

这里要注意的是网格精度。CadQuery 导出 STL 时可以指定tolerance和angularTolerance。 tolerance 越小，网格越细，文件越大。我一般用 0.01 毫米的线性公差和 0.1 弧度的角度公差，兼顾精度和文件大小。

6.2 机器人仿真中的 URDF 生成与导入

机器人仿真场景里，text-to-cad 的价值在于快速生成连杆模型。我通常先用 CadQuery 生成每个连杆的 STL，然后手写 URDF 描述关节关系。如果连杆形状复杂，也可以从 STEP 转成 STL 再引用。

导入 CoppeliaSim 时，把 URDF 和 STL 放在同一目录，然后用File > Import > URDF加载。如果模型显示异常，先检查单位缩放，再检查关节轴方向。CoppeliaSim 对 URDF 的兼容性不错，但有些标签不支持，比如gazebo扩展标签会被忽略。

6.3 数控加工与 G-code 生成的注意事项

从 text-to-cad 到 G-code，中间必须经过 CAM。我一般把 STEP 导出后，用 FreeCAD 的 Path 工作台生成刀路。FreeCAD 支持 2.5D 铣削、钻孔、轮廓加工等常用操作。生成刀路后，用后处理器输出 G-code。

这里的关键是刀具选择和切削参数。刀具直径决定了哪些特征能加工，比如孔径 6 毫米的孔，至少要用 5 毫米以下的刀具。切削参数包括主轴转速、进给速度、切削深度，这些要根据材料来定。我通常先在仿真里跑一遍刀路，确认没有碰撞再上机床。

6.4 二维图纸与 DXF 输出的补充

有些场景不需要三维模型，只需要二维图纸。比如钣金展开、激光切割、线切割。这时候可以从 CadQuery 导出 DXF。CadQuery 支持把草图或者投影导出为 DXF：

cq.exporters.export(base.faces(">Z").wires(), "plate.dxf")

导出的 DXF 可以在 AutoCAD 或中望 CAD 里打开，继续编辑。如果要做钣金展开，需要先做展开计算，再导出 DXF。这一步比较复杂，建议用专业钣金软件处理。

7. 我个人的实操体会与后续扩展方向

这套 text-to-cad 流程我前后迭代了大概半年，从最开始的手写 STEP 文本，到后来的 CadQuery 脚本，再到现在的参数表驱动批量生成，每一步都是被实际问题逼出来的。最大的体会是：不要追求一步到位，先把最小闭环跑通。哪怕只是生成一个最简单的方块并导出 STEP，也比空想架构强。跑通之后，再逐步加特征、加参数、加批量。

另一个体会是格式选择比建模本身更重要。很多人花大量时间优化几何，结果导出格式不对，下游根本用不了。所以一开始就要明确：这个模型最终要干什么？是给人看、给机器加工、还是给仿真用？不同的用途决定了不同的格式和精度要求。

后续如果继续扩展，我会往两个方向走。一是接入更多输入源，比如从 Excel 参数表、数据库、甚至语音描述生成模型。二是增加自动校验，比如生成后自动检查壁厚、孔径、圆角是否合理，提前发现设计缺陷。这些在批量生成场景里特别有价值，能省掉大量人工检查的时间。

如果你也在做类似的事情，建议从一个小零件开始，把整个链路跑通，再逐步放大。踩坑是必然的，但每解决一个问题，这套流程就更稳一分。