text-to-cad 实战：从自然语言到三维实体的工程化落地

1. 从一句话到三维实体text-to-cad 到底在解决什么问题第一次听到 text-to-cad 这个词很多人脑子里浮现的画面大概是对着电脑说一句给我画个法兰盘屏幕上就自动长出一个带螺栓孔的三维模型。这个想象不算离谱但真正落地的时候它解决的问题比省几次鼠标点击要深得多。传统 CAD 工作流的本质是人肉翻译需求方用自然语言描述一个零件工程师在脑子里把它翻译成几何约束、尺寸链、特征树再用手一根根画线、一个个拉伸。这个过程中最耗时的往往不是建模本身而是反复确认你说的倒角 2mm 是内倒角还是外倒角这个孔是通孔还是盲孔。text-to-cad 想做的是把自然语言 → 几何参数这一段翻译工作交给程序让工程师从重复劳动里抽身专注在真正需要判断力的地方。它适合谁三类人最该关注。第一类是做参数化零件批量生成的工程师比如标准件库、系列化产品这类场景天然适合文本驱动第二类是做仿真前处理的人需要把一批模型转成 URDF 或 STEP 再喂给下游工具第三类是做 LLM 应用落地的开发者想找一个看得见摸得着的垂直场景练手。如果你只是偶尔画两张图那这套东西的投入产出比未必划算但如果你面对的是成百上千个结构相似、参数不同的模型text-to-cad 的价值会立刻显现。需要先泼一盆冷水当前阶段的 text-to-cad 不是一句话生成任意复杂装配体的魔法。它更现实的定位是参数化模板的自然语言前端——你预先定义好几何逻辑用文本去填充参数、选择变体、触发组合。理解这个边界后面的所有设计才不会跑偏。热词里那些 cad 制图初学入门cad 教程 的搜索者如果抱着学会这个就不用学 CAD 了的心态进来大概率会失望但如果是想给自己的建模流程加一层自动化外壳那方向就对了。2. 文本到几何的翻译链路LLM 该在哪一层介入2.1 三种介入深度决定了系统的天花板把自然语言变成 CAD 模型LLM 可以站在三个不同的位置上难度和可控性差别巨大。第一种是参数填充器。你有一个写死的参数化脚本比如用 CadQuery 或 OpenSCAD 写的法兰盘生成器LLM 只负责从文本里抽出outer_diameter80、bolt_count6、thickness12这些数值然后调用脚本。这是最稳的方案LLM 出错最多是参数错几何逻辑永远正确。第二种是代码生成器。LLM 直接输出 CadQuery/OpenSCAD 代码由 CAD 内核执行。灵活度高能处理没预定义过的形状但风险也大——生成的代码可能语法错误、可能几何自交、可能尺寸离谱。你需要一套沙箱执行 几何校验的兜底机制。第三种是特征序列生成器。LLM 输出一串抽象操作拉伸、倒角、打孔、阵列由中间层翻译成具体 API 调用。这是学术界比较热的方向工程上落地案例还不多因为特征序列的语义空间太大校验成本高。我的建议很直接生产环境从第一种做起把第二种当作探索性功能。原因很简单参数填充的失败模式是可枚举的数值越界、单位混淆、必填缺失而代码生成的失败模式几乎是无限的。你不可能为一个LLM 偶尔生成自交曲面的问题写穷举测试。2.2 为什么 STEP 是绕不开的中间格式热词里 STEP 排在前列不是偶然。text-to-cad 生成的模型最终要流向哪里可能是仿真软件、可能是 CAM 加工、可能是 PLM 系统。这些下游工具对格式的挑剔程度远超想象。STEPAP214/AP242是目前工业界接受度最广的交换格式它保留 B-rep 边界表示能携带颜色、图层、装配层级信息。相比之下STL 只有三角网格丢了拓扑关系倒角和圆角会变成一堆碎面OBJ 更偏渲染工程语义几乎为零。所以一条靠谱的 text-to-cad 流水线中间产物应该是 STEP而不是直接吐 STL。这里有个实操细节CadQuery 导出 STEP 时默认精度是 0.1做小零件比如 M3 螺纹孔时这个精度会导致圆孔变成多边形。你需要显式设置import cadquery as cq result cq.Workplane(XY).circle(40).extrude(12) cq.exporters.export(result, flange.step, tolerance0.001, angularTolerance0.1)tolerance控制线性偏差angularTolerance控制角度偏差。做精密件时把这两个值压小文件会变大但几何更准。我踩过的坑是导出时没设精度导入到下游软件做干涉检查两个本该同轴的孔因为多边形化偏差报了干涉排查了半天才发现是导出精度问题。2.3 URDF 和 G-code两个容易被混淆的下游出口热词里同时出现了 URDF 和 G-code这两个方向经常被新手搞混值得单独说清楚。URDF是机器人描述格式它关心的不是零件长什么样而是连杆之间怎么连接、关节怎么运动。text-to-cad 生成 URDF 的典型场景是你有一批机械臂连杆的 CAD 模型需要批量转成 URDF 做仿真。这时候文本输入可能是生成一个 6 自由度机械臂的 URDF基座半径 100mm大臂 300mm……系统调用 CAD 生成几何再按运动学关系组装成 URDF。热词里 urdf 导入 coppeliasim 说明很多人卡在仿真软件这一环——URDF 的origin和axis写错一个符号模型在仿真里就会飞出去。G-code是数控加工指令它关心的是刀具怎么走。从 text-to-cad 到 G-code 中间还隔着 CAM 工序规划不是简单转换。文本输入更可能是把这个零件用 6mm 立铣刀加工留 0.2mm 精加工余量系统生成刀路再后处理成 G-code。这条链路目前自动化程度还很低因为刀具选择、装夹方案、切削参数都强依赖工艺经验。我的判断是URDF 方向比 G-code 方向更容易做出可用产品因为 URDF 的规则是确定的、可校验的而 G-code 的生成质量高度依赖工艺知识很难用纯文本驱动。3. 用 CadQuery 搭一条最小可用的 text-to-cad 流水线3.1 环境准备里最容易翻车的三个点先说环境。CadQuery 的安装是新手第一道坎热词里 cad 安装安装 cad 一直出现 c2005cpi 错误 这类问题在 Python CAD 生态里同样存在只是换了个形式。第一个坑是 OCP 依赖。CadQuery 2.x 底层依赖 OCPOpenCASCADE 的 Python 绑定这个包体积大、编译复杂。用 pip 直接装经常卡在编译阶段。稳妥做法是用 condaconda create -n t2cad python3.10 conda activate t2cad conda install -c conda-forge cadqueryconda-forge 有预编译好的 OCP 二进制省去编译痛苦。如果你非要用 pip至少确保 Python 版本在 3.9-3.11 之间太新或太旧都可能没有对应的 wheel。第二个坑是显示后端。CadQuery 的可视化依赖 VTK在无头服务器上跑会报错。如果你只是做批量生成不需要交互预览可以完全不装可视化组件只装核心库。第三个坑是单位。CadQuery 默认单位是毫米但如果你从别处导入的模型是英寸混用会导致尺寸差 25.4 倍。我的习惯是在脚本开头显式注释单位并且在参数入口做一次单位归一化。3.2 一个法兰盘生成器的完整拆解光说概念没意思直接上一个能跑的完整例子。假设我们要做一个根据文本描述生成法兰盘的最小系统。先定义参数化模板import cadquery as cq from pydantic import BaseModel, Field class FlangeParams(BaseModel): outer_dia: float Field(..., gt20, lt500, description外径 mm) inner_dia: float Field(..., gt0, description内径 mm) thickness: float Field(..., gt1, lt100, description厚度 mm) bolt_count: int Field(..., ge3, le24, description螺栓孔数量) bolt_circle_dia: float Field(..., description螺栓孔分布圆直径 mm) bolt_hole_dia: float Field(8.0, description螺栓孔直径 mm) def build_flange(p: FlangeParams): if p.inner_dia p.outer_dia: raise ValueError(内径必须小于外径) if p.bolt_circle_dia p.outer_dia or p.bolt_circle_dia p.inner_dia: raise ValueError(螺栓分布圆必须落在内外径之间) body ( cq.Workplane(XY) .circle(p.outer_dia / 2) .circle(p.inner_dia / 2) .extrude(p.thickness) ) holes ( cq.Workplane(XY) .polarArray(p.bolt_circle_dia / 2, 0, 360, p.bolt_count) .circle(p.bolt_hole_dia / 2) .extrude(p.thickness) ) return body.cut(holes)注意几个设计决策。为什么用 pydantic 做参数校验因为 LLM 抽出来的参数经常越界比如把外径 80抽成 800或者把螺栓数量抽成 0。在几何生成之前拦截这些错误比生成完再检查几何要便宜得多。为什么在 build 函数里再做一次逻辑校验因为 pydantic 只能校验单字段范围跨字段的几何约束内径必须小于外径它管不了。为什么用polarArray而不是手动循环手动循环生成 N 个圆柱再布尔减在 N 大时性能会崩。polarArray是内核级操作效率高一个数量级。我实测过 24 个孔的阵列手动循环要 3 秒多polarArray 只要 0.2 秒。3.3 把 LLM 接进来的正确姿势有了模板接 LLM 就简单了。核心是用结构化输出约束 LLM而不是让它自由发挥from openai import OpenAI import json client OpenAI() SYSTEM_PROMPT 你是一个 CAD 参数抽取助手。 从用户描述中抽取法兰盘参数输出 JSON。 字段定义 - outer_dia: 外径单位 mm - inner_dia: 内径单位 mm - thickness: 厚度单位 mm - bolt_count: 螺栓孔数量整数 - bolt_circle_dia: 螺栓孔分布圆直径单位 mm - bolt_hole_dia: 螺栓孔直径单位 mm默认 8 如果用户没提到某个字段不要瞎猜返回 null。 单位换算1 英寸 25.4 mm1 cm 10 mm。 def parse_flange_text(user_text: str) - dict: resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_text}, ], response_format{type: json_object}, temperature0, ) return json.loads(resp.choices[0].message.content)这里有几个关键点。temperature 设为 0参数抽取是确定性任务不需要创造性。用 json_object 模式避免 LLM 输出一堆解释性文字。明确要求缺失字段返回 null而不是让模型合理推测——推测出来的参数比缺失更危险因为用户不知道哪个值是编的。拿到参数后缺失的字段要么用默认值要么反问用户。我的做法是关键尺寸外径、内径、厚度缺失就反问次要尺寸螺栓孔直径缺失就用默认值。这个策略在交互体验和自动化程度之间取得了平衡。4. 实测中暴露的五个真实问题与应对4.1 单位混淆最隐蔽也最致命我做过一个测试给系统输入外径 3 英寸的法兰盘LLM 抽出来的outer_dia是 3。如果直接喂给模板生成的就是一个 3mm 的迷你法兰盘肉眼几乎看不见。根因是 LLM 对单位的处理不稳定有时候换算有时候不换算。解决方案是在 prompt 里强制要求输出单位然后在代码里做二次校验def normalize_unit(value: float, unit: str) - float: factors {mm: 1.0, cm: 10.0, m: 1000.0, inch: 25.4, in: 25.4} if unit not in factors: raise ValueError(f未知单位: {unit}) return value * factors[unit]更稳的做法是让 LLM 输出{value: 3, unit: inch}这样的结构而不是直接输出换算后的数值。换算交给确定性代码做LLM 只负责识别。4.2 几何自交布尔运算的经典陷阱当螺栓孔分布圆太靠近外径时孔会切穿外壁生成的实体出现开口。更糟的是某些情况下布尔运算会生成自交曲面STEP 导出后下游软件直接报错。排查链路是这样的先看生成的模型体积是否异常自交模型体积往往偏小或为负再用Shape.isValid()检查拓扑有效性solid build_flange(params) if not solid.val().isValid(): raise RuntimeError(生成的几何无效请检查参数)但isValid()不是万能的有些自交它能过。更可靠的办法是导出 STEP 后再用独立工具校验比如用pythonocc重新读入检查。我一般会在流水线里加一道导出-重读-校验的关卡虽然慢一点但能拦住 90% 的坏模型。4.3 参数越界LLM 的合理想象用户说做一个大法兰盘LLM 可能抽出一个outer_dia1000。这在数值上合法但可能远超实际需求。这类问题的本质是自然语言里的模糊量词没有对应到具体数值。我的处理方式是在 prompt 里给出参考区间比如常规法兰盘外径在 50-300mm 之间如果用户描述模糊取中间值并标注为估计值。同时在返回结果里带上confidence字段让用户知道哪些值是确定的、哪些是猜的。4.4 批量生成时的内存泄漏做系列化零件时你可能要在一个进程里生成几百个模型。CadQuery 底层是 C 对象Python 的垃圾回收对它们不完全有效。跑几百个之后内存会持续上涨最后 OOM。解决办法是显式释放import gc for params in param_list: solid build_flange(params) cq.exporters.export(solid, f{params.outer_dia}.step) del solid gc.collect()del加gc.collect()能回收大部分内存。如果还不行就把生成任务拆成多个子进程每个进程处理一批就退出用进程隔离来兜底。4.5 下游格式转换的精度损失从 STEP 转 STL 做 3D 打印时如果精度设得太粗圆孔会变成明显的多边形。热词里 cad 转 pdfcad 图纸合并 这类需求背后其实是同一个问题格式转换时的精度参数没调对。转 STL 时关键参数是linearDeflection和angularDeflectioncq.exporters.export( solid, part.stl, tolerance0.01, # 线性偏差越小越精细 angularTolerance0.1, # 角度偏差弧度制 )经验值做 3D 打印用tolerance0.01做快速预览用0.1。文件大小和精度基本是平方关系精度提高 10 倍文件大 100 倍要按实际需求权衡。5. 从单件生成到批量流水线工程化的几个关键决策5.1 模板库怎么组织才不会被自己坑当模板从 1 个变成 20 个管理就成了问题。我见过有人把所有模板塞进一个templates.py结果改一个法兰盘参数影响了齿轮的生成。推荐的组织方式是按几何族分文件每个文件一个族族内共享基础几何函数templates/ __init__.py registry.py # 模板注册表 flanges.py # 法兰盘族 gears.py # 齿轮族 brackets.py # 支架族 common.py # 共享几何工具registry.py维护一个name - (param_model, build_func)的映射LLM 先做意图分类决定用哪个模板再抽参数。这样新增模板不用改主流程符合开闭原则。5.2 意图分类比参数抽取更容易出错的一环用户说做个连接件系统怎么知道是法兰、支架还是接头意图分类的准确率直接决定用户体验而且它比参数抽取更难因为类别之间的边界是模糊的。我的做法是用 few-shot 示例 明确的类别定义而不是让 LLM 自由判断INTENT_PROMPT 判断用户想要生成的零件类型从以下类别中选择 - flange: 法兰盘特征是圆盘状、有中心孔和一圈螺栓孔 - bracket: 支架特征是 L 形或 U 形、有安装孔 - gear: 齿轮特征是轮齿、有中心孔 - shaft: 轴特征是细长圆柱、可能有键槽 - unknown: 无法判断 示例 做个圆盘带六个孔的 - flange 做个 L 形固定件 - bracket 做个 20 齿的传动轮 - gear 如果分类结果是unknown就反问用户而不是硬猜。宁可多问一句也不要生成一个完全不对的零件后者对用户信任的伤害更大。5.3 缓存与增量生成批量场景下很多参数组合是重复的。比如生成 100 个法兰盘其中 30 个只是螺栓孔数量不同外径内径都一样。对几何结果做缓存能省大量时间。缓存的 key 是参数的哈希import hashlib import json def param_hash(params: dict) - str: canonical json.dumps(params, sort_keysTrue) return hashlib.md5(canonical.encode()).hexdigest()但要注意缓存的是几何结果还是文件路径要分清。缓存几何对象会占内存缓存文件路径更省但读取有 IO 开销。我的选择是缓存 STEP 文件路径因为下游通常也是按文件消费的。5.4 错误处理让失败可追溯流水线跑批量任务时最怕的是跑到第 73 个挂了但不知道为啥。每个生成任务都要有独立的日志和错误捕获import logging logger logging.getLogger(t2cad) def safe_generate(params: dict, out_path: str) - dict: try: solid build_flange(FlangeParams(**params)) cq.exporters.export(solid, out_path) return {status: ok, path: out_path} except Exception as e: logger.exception(f生成失败: {params}) return {status: error, params: params, error: str(e)}返回结构化结果而不是抛异常这样批量任务能继续跑最后统一汇总失败项。失败项要带上原始参数方便复现和修正。6. 这套东西的边界在哪里以及我踩过的那些坑6.1 复杂曲面text-to-cad 目前的天花板参数化模板能搞定的是规则几何圆柱、圆锥、平面、规则阵列。一旦涉及自由曲面比如涡轮叶片、人体工学手柄模板方法就无能为力了。这类形状需要 NURBS 控制点或网格驱动自然语言到控制点的映射目前还没有可靠方案。所以别指望用 text-to-cad 生成一个汽车外形。它的舒适区是标准件、系列化零件、结构件。认清这个边界能省下大量试错时间。6.2 装配体从零件到产品的鸿沟单件生成跑通后很自然会想能不能生成整个装配体。答案是能但难度陡增。装配涉及配合关系同轴、贴合、间隙、运动约束旋转副、滑动副、干涉检查。自然语言描述装配关系比描述单个零件模糊得多把轴插进孔里到底是过盈配合还是间隙配合我的建议是装配关系用结构化配置描述而不是自然语言。文本只负责生成零件装配用 YAML 或 JSON 定义assembly: - part: shaft params: {dia: 20, length: 100} - part: bearing params: {inner_dia: 20, outer_dia: 42} mate: {type: coaxial, with: shaft, offset: 30}这样职责清晰LLM 管零件参数配置文件管装配逻辑。6.3 我踩过的最大的一个坑过度信任 LLM 的数值早期我做参数抽取时没做范围校验结果 LLM 把一个厚度 5mm抽成了thickness5e-3大概是把它当成米了。生成的模型薄如蝉翼导出后下游软件直接崩溃。从那以后我所有的数值参数都加了 pydantic 的gt/lt约束宁可报错也不让离谱值流下去。另一个坑是LLM 会补全用户没说的参数。用户只说外径 80 的法兰盘LLM 可能自作主张补上inner_dia40、thickness10。这些值看起来合理但用户根本没要求。解决办法是在 prompt 里反复强调未提及的字段返回 null并且在代码里对 null 做显式处理用默认值或反问而不是让 LLM 填。6.4 关于热词里那些 CAD 安装问题的题外话热词里大量出现 cad 安装cad 激活页面脚本发生错误cad 如何彻底卸载不影响二次安装 这类问题说明很多人的痛点还停留在把软件装起来这一层。如果你正在这个阶段我的建议是做 text-to-cad 不需要装任何商业 CAD 软件。CadQuery、OpenSCAD、FreeCAD 的 Python 接口都是免费开源的装好 Python 环境就能跑。商业 CAD 的二次开发接口比如某些软件的 API反而更封闭、更贵、更难自动化。把精力放在几何逻辑和文本解析上比折腾软件安装划算得多。至于 cad 切地形cad 图纸合并cad 导入 layout 这些偏工程制图的需求和 text-to-cad 的关系不大属于另一个技术栈。text-to-cad 聚焦的是从零生成三维实体不是处理已有的二维图纸。分清楚这个区别能避免走弯路。6.5 一个实用的小技巧用自然语言做参数扫描text-to-cad 有个容易被忽略的用法批量参数扫描。做优化或 DOE实验设计时你需要生成一系列参数渐变的模型。用文本描述这个扫描过程比写循环更直观scan_spec 外径从 60 到 120步长 10其他参数固定 # 解析成参数列表 param_sets [ {outer_dia: d, inner_dia: 30, thickness: 10, bolt_count: 6, bolt_circle_dia: d - 15} for d in range(60, 121, 10) ]这个用法把 text-to-cad 从生成单个模型扩展到了生成模型族对做仿真分析的人特别有用。我实测下来用这种方式准备 50 个仿真模型比手动建模快了不止一个数量级。最后分享一个我在实际项目里总结的原则文本负责想要什么代码负责怎么实现校验负责是否合理。这三层职责分清楚系统就稳了。把 LLM 当成一个能听懂人话的参数录入员而不是全能的建模师心态摆正落地就顺了。