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 脚本在几何构建这一层我实际用过三种方案各有取舍。方案优势劣势适合场景CadQueryAPI 简洁基于 OpenCASCADESTEP 导出稳定学习曲线中等文档偏工程化参数化零件批量生成OpenSCAD语法简单纯代码建模社区大基于 CSG曲面能力弱STEP 导出需转换简单结构、教学演示FreeCAD 脚本功能全可操作完整工作台API 繁琐运行慢依赖重复杂装配、需要 GUI 校验我最后选的是 CadQuery 作为主力原因是它在“代码简洁”和“几何精确”之间平衡得最好。比如画一个带孔的法兰CadQuery 里几行就能搞定而且导出的 STEP 在 SolidWorks 和中望 CAD 里都能正常打开。OpenSCAD 虽然上手快但它导出的模型是网格化的转 STEP 会丢失精确曲面信息做机械件不太合适。2.4 输出格式的选择逻辑输出格式不是随便选的它取决于你下一步要干什么。这里列一个我常用的判断表。下游用途推荐格式原因继续编辑、装配STEP保留精确 B-Rep兼容主流 CAD3D 打印预览STL网格格式切片软件通用机器人仿真URDF带关节和连杆结构仿真环境直接读数控加工G-code直接驱动机床需配合 CAM 后处理二维图纸交换DXF兼容 AutoCAD 及国产 CAD这里要特别提一下 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)选中竖直边然后filletbase base.edges(|Z).fillet(fillet_radius)这里|Z表示平行于 Z 轴的边也就是四个竖直棱边。倒角半径 5 毫米实际加工中这个值不能太大否则会削弱结构强度。第三步是打孔。假设 4 个孔分布在四角孔距边缘 15 毫米孔径 6 毫米。可以用faces(Z)选中顶面然后hole或者cboreHolehole_d 6 margin 15 base ( base.faces(Z) .workplane() .rect(length - 2*margin, width - 2*margin, forConstructionTrue) .vertices() .hole(hole_d) )这段代码的逻辑是在顶面建立一个工作平面画一个辅助矩形forConstructionTrue表示只用于定位不参与实体然后选中矩形的四个顶点在每个顶点处打一个直径 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 namearm link namebase_link visual geometry mesh filenamebase.stl/ /geometry /visual /link joint namejoint1 typerevolute parent linkbase_link/ child linklink1/ axis xyz0 0 1/ limit lower-3.14 upper3.14 effort10 velocity1/ /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 python3.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, forConstructionTrue) .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, fplate_{idx}.step)这里要注意的是参数校验。如果 CSV 里某个值缺失或者类型不对脚本会直接报错。我的做法是在build_plate开头加一层检查比如length必须大于 0hole_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 导出后打不开实体无效或破面检查isValid()调整布尔运算顺序避免零厚度导入仿真环境模型过大单位不一致检查 URDF 和 STL 单位统一转换为米孔位置偏移工作平面方向错误打印法向量重新选择工作面批量生成中途报错参数缺失或越界查看日志定位行号加参数校验G-code 刀具路径不完整CAM 参数设置不当检查刀路覆盖范围调整刀具直径和步距URDF 导入后关节不动关节类型或轴定义错误检查 joint 标签修正 type 和 axis提示遇到问题时先把模型简化到最小可复现的程度。比如只画一个矩形拉伸确认能导出 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 支持把草图或者投影导出为 DXFcq.exporters.export(base.faces(Z).wires(), plate.dxf)导出的 DXF 可以在 AutoCAD 或中望 CAD 里打开继续编辑。如果要做钣金展开需要先做展开计算再导出 DXF。这一步比较复杂建议用专业钣金软件处理。7. 我个人的实操体会与后续扩展方向这套 text-to-cad 流程我前后迭代了大概半年从最开始的手写 STEP 文本到后来的 CadQuery 脚本再到现在的参数表驱动批量生成每一步都是被实际问题逼出来的。最大的体会是不要追求一步到位先把最小闭环跑通。哪怕只是生成一个最简单的方块并导出 STEP也比空想架构强。跑通之后再逐步加特征、加参数、加批量。另一个体会是格式选择比建模本身更重要。很多人花大量时间优化几何结果导出格式不对下游根本用不了。所以一开始就要明确这个模型最终要干什么是给人看、给机器加工、还是给仿真用不同的用途决定了不同的格式和精度要求。后续如果继续扩展我会往两个方向走。一是接入更多输入源比如从 Excel 参数表、数据库、甚至语音描述生成模型。二是增加自动校验比如生成后自动检查壁厚、孔径、圆角是否合理提前发现设计缺陷。这些在批量生成场景里特别有价值能省掉大量人工检查的时间。如果你也在做类似的事情建议从一个小零件开始把整个链路跑通再逐步放大。踩坑是必然的但每解决一个问题这套流程就更稳一分。
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 脚本在几何构建这一层我实际用过三种方案各有取舍。方案优势劣势适合场景CadQueryAPI 简洁基于 OpenCASCADESTEP 导出稳定学习曲线中等文档偏工程化参数化零件批量生成OpenSCAD语法简单纯代码建模社区大基于 CSG曲面能力弱STEP 导出需转换简单结构、教学演示FreeCAD 脚本功能全可操作完整工作台API 繁琐运行慢依赖重复杂装配、需要 GUI 校验我最后选的是 CadQuery 作为主力原因是它在“代码简洁”和“几何精确”之间平衡得最好。比如画一个带孔的法兰CadQuery 里几行就能搞定而且导出的 STEP 在 SolidWorks 和中望 CAD 里都能正常打开。OpenSCAD 虽然上手快但它导出的模型是网格化的转 STEP 会丢失精确曲面信息做机械件不太合适。2.4 输出格式的选择逻辑输出格式不是随便选的它取决于你下一步要干什么。这里列一个我常用的判断表。下游用途推荐格式原因继续编辑、装配STEP保留精确 B-Rep兼容主流 CAD3D 打印预览STL网格格式切片软件通用机器人仿真URDF带关节和连杆结构仿真环境直接读数控加工G-code直接驱动机床需配合 CAM 后处理二维图纸交换DXF兼容 AutoCAD 及国产 CAD这里要特别提一下 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)选中竖直边然后filletbase base.edges(|Z).fillet(fillet_radius)这里|Z表示平行于 Z 轴的边也就是四个竖直棱边。倒角半径 5 毫米实际加工中这个值不能太大否则会削弱结构强度。第三步是打孔。假设 4 个孔分布在四角孔距边缘 15 毫米孔径 6 毫米。可以用faces(Z)选中顶面然后hole或者cboreHolehole_d 6 margin 15 base ( base.faces(Z) .workplane() .rect(length - 2*margin, width - 2*margin, forConstructionTrue) .vertices() .hole(hole_d) )这段代码的逻辑是在顶面建立一个工作平面画一个辅助矩形forConstructionTrue表示只用于定位不参与实体然后选中矩形的四个顶点在每个顶点处打一个直径 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 namearm link namebase_link visual geometry mesh filenamebase.stl/ /geometry /visual /link joint namejoint1 typerevolute parent linkbase_link/ child linklink1/ axis xyz0 0 1/ limit lower-3.14 upper3.14 effort10 velocity1/ /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 python3.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, forConstructionTrue) .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, fplate_{idx}.step)这里要注意的是参数校验。如果 CSV 里某个值缺失或者类型不对脚本会直接报错。我的做法是在build_plate开头加一层检查比如length必须大于 0hole_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 导出后打不开实体无效或破面检查isValid()调整布尔运算顺序避免零厚度导入仿真环境模型过大单位不一致检查 URDF 和 STL 单位统一转换为米孔位置偏移工作平面方向错误打印法向量重新选择工作面批量生成中途报错参数缺失或越界查看日志定位行号加参数校验G-code 刀具路径不完整CAM 参数设置不当检查刀路覆盖范围调整刀具直径和步距URDF 导入后关节不动关节类型或轴定义错误检查 joint 标签修正 type 和 axis提示遇到问题时先把模型简化到最小可复现的程度。比如只画一个矩形拉伸确认能导出 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 支持把草图或者投影导出为 DXFcq.exporters.export(base.faces(Z).wires(), plate.dxf)导出的 DXF 可以在 AutoCAD 或中望 CAD 里打开继续编辑。如果要做钣金展开需要先做展开计算再导出 DXF。这一步比较复杂建议用专业钣金软件处理。7. 我个人的实操体会与后续扩展方向这套 text-to-cad 流程我前后迭代了大概半年从最开始的手写 STEP 文本到后来的 CadQuery 脚本再到现在的参数表驱动批量生成每一步都是被实际问题逼出来的。最大的体会是不要追求一步到位先把最小闭环跑通。哪怕只是生成一个最简单的方块并导出 STEP也比空想架构强。跑通之后再逐步加特征、加参数、加批量。另一个体会是格式选择比建模本身更重要。很多人花大量时间优化几何结果导出格式不对下游根本用不了。所以一开始就要明确这个模型最终要干什么是给人看、给机器加工、还是给仿真用不同的用途决定了不同的格式和精度要求。后续如果继续扩展我会往两个方向走。一是接入更多输入源比如从 Excel 参数表、数据库、甚至语音描述生成模型。二是增加自动校验比如生成后自动检查壁厚、孔径、圆角是否合理提前发现设计缺陷。这些在批量生成场景里特别有价值能省掉大量人工检查的时间。如果你也在做类似的事情建议从一个小零件开始把整个链路跑通再逐步放大。踩坑是必然的但每解决一个问题这套流程就更稳一分。
