1. 从一句话到三维模型：text-to-cad 到底在解决什么问题
第一次听到 "text-to-cad" 这个词，很多人脑子里冒出来的画面是：对着电脑说一句"给我画个法兰盘"，屏幕上就自动长出一个带螺栓孔的零件。这个想象不算离谱，但真正落地到工程实践里，它解决的问题比"语音画图"要具体得多，也务实得多。
text-to-cad 的核心，是把自然语言描述转换成可用的三维 CAD 几何数据。这里的"可用"是关键词。它不是生成一张好看的渲染图，而是要产出能进入下游流程的实体模型——能被 CAD 软件打开、能导出成 STEP、STL、GLB 这些格式、能拿去 3D 打印或者做装配验证。换句话说，它要跨过"看起来像"和"工程上能用"之间那道很深的沟。
为什么这件事值得单独拿出来做？因为传统建模的流程里，有一大段工作是高度重复、低创造性的。比如你要建一批规格相近的支架、垫片、外壳，参数变一变，建模动作几乎一样。熟练的工程师用参数化建模能提效，但前提是他得先会软件、懂约束、知道怎么组织特征树。对于不熟悉 CAD 的人——比如做产品经理的、做硬件原型的、做教学演示的——从零学一套 CAD 软件的成本高得吓人。text-to-cad 想做的，就是把这段门槛削平：你用日常语言把需求说清楚，系统帮你把几何骨架搭出来。
从技术链路看，它大致要经过这么几层：语言理解层负责把"一个边长 50 毫米、厚 5 毫米、四角带 M4 沉头孔的方形底板"解析成结构化的参数；几何生成层负责把这些参数变成实际的边界表示（B-rep）或者网格；格式转换层负责把内部表示导出成 STEP、STL、GLB 等目标格式。每一层都有各自的坑，后面会逐个拆。
适合读这篇内容的人，我大致分三类。第一类是想快速验证产品外形的硬件从业者，你不需要精确到公差，但需要一个能看、能改、能打印的模型；第二类是做 AI 应用开发的工程师，你想把大模型能力和 CAD 内核接起来，但不确定中间那层怎么搭；第三类是教学和内容创作者，你需要批量产出示例模型，手工建模太慢。这三类人的需求不完全一样，但底层要打通的链路是同一套。
提示：text-to-cad 目前最成熟的定位是"快速原型"和"参数化批量生成"，不是替代精密工程设计。指望它直接输出能上机床的图纸，现阶段不现实。
2. 语言到几何之间那道坎：为什么直接让大模型"画图"行不通
2.1 大模型擅长的是符号，不是连续几何
很多人第一反应是：既然大模型能写代码、能画 SVG，那让它直接输出三维模型不就行了？实测下来，这条路走不通，原因在于大模型处理的是离散符号序列，而 CAD 几何本质是连续空间里的精确数学表示。
一个 STEP 文件里描述一个圆柱面，用的是解析几何参数——轴线位置、半径、方向向量，精度可以到小数点后很多位。大模型生成文本时，是在概率分布里采样下一个 token，它没法保证"这个圆的半径在数值上严格等于上一个特征引用的那个值"。你让它写"半径 25 的圆"，它可能这次写 25，下次写 24.9，在纯文本里无所谓，但在几何里就是两个不同的面，装配直接失败。
所以正确的做法不是让大模型直接吐几何，而是让它吐结构化的中间表示。这个中间表示可以是参数化的脚本（比如 CadQuery、OpenSCAD 的代码），也可以是一段结构化的 JSON 描述特征树。大模型负责"理解意图 + 生成参数"，真正的几何运算交给确定性的几何内核去做。这样分工，大模型的模糊性和几何内核的精确性各司其职。
2.2 中间表示选型：脚本、JSON 还是特征树
中间表示怎么选，直接决定了整个系统的上限。我对比过三种主流思路，各有取舍。
| 中间表示 | 代表工具 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 参数化脚本 | CadQuery、OpenSCAD | 表达力强、可复用、社区成熟 | 需要模型会写代码、调试成本高 | 批量参数化零件 |
| 结构化 JSON | 自定义 schema | 易校验、易解析、前后端友好 | 表达力受限、复杂曲面难描述 | 简单规则零件 |
| 特征树序列 | 类 CAD 操作序列 | 贴近工程师思维 | 实现复杂、容错差 | 交互式建模辅助 |
我个人的经验是：如果目标是快速跑通，从参数化脚本入手最省事。CadQuery 基于 OCCT（OpenCASCADE）内核，Python 语法，大模型对 Python 的生成质量本来就高，两者天然契合。你让模型生成一段 CadQuery 代码，比让它生成自定义 JSON 靠谱得多，因为训练数据里 Python 代码海量，而你的自定义 schema 它没见过。
OpenSCAD 也是常见选择，它的 DSL 更简单，但只支持网格和 CSG 布尔运算，做不了真正的 B-rep 曲面，导出 STEP 会丢精度。如果你的下游需要 STEP，CadQuery 这类基于 OCCT 的方案更合适。
2.3 一个最小可用的转换链路
把链路说清楚，大概是这样的：
- 用户输入自然语言描述
- 大模型把描述转成 CadQuery Python 脚本
- 脚本在沙箱里执行，调用 OCCT 内核生成几何
- 几何对象导出为 STEP / STL / GLB
- 返回文件路径或预览图给用户
这里面第 3 步是安全重灾区。你让大模型生成的代码直接在服务器上跑，等于把执行权限交给了一个不可控的生成器。必须做沙箱隔离，限制文件系统访问、网络访问、执行超时。我见过有人图省事直接exec()，结果模型生成了一段删库的代码——虽然概率低，但一旦发生就是事故。
# 一个典型的 CadQuery 生成示例（由模型产出，需沙箱执行） import cadquery as cq # 边长 50、厚 5 的方形底板，四角 M4 沉头孔 result = ( cq.Workplane("XY") .box(50, 50, 5) .faces(">Z") .workplane() .rect(40, 40, forConstruction=True) .vertices() .cboreHole(4.5, 8, 2.5) # 通孔直径4.5，沉孔直径8，深2.5 ) cq.exporters.export(result, "plate.step") cq.exporters.export(result, "plate.stl")这段代码里，cboreHole的参数顺序是（孔径、沉孔直径、沉孔深度），很多人第一次会写反。沉头孔和沉孔是两回事，前者是锥形，后者是圆柱形台阶，选错了装配时螺丝头会露出来。
3. 格式这关绕不过去：STEP、STL、GLB 各自的地盘
3.1 三种格式的本质差异
text-to-cad 的输出格式，热词里反复出现 STEP、STL、GLB，这三个不是随便选的，它们代表了三种完全不同的几何表达哲学。
STEP是 B-rep（边界表示）格式，用精确的数学曲面描述实体。一个圆柱面就是"轴线 + 半径"的解析表达，无限精度。它是 CAD 之间交换数据的行业标准，SolidWorks、中望 CAD、FreeCAD 都能读写。缺点是文件结构复杂，解析器实现成本高，而且不同软件对同一份 STEP 的解释可能有细微差异。
STL是网格格式，用一堆三角形面片逼近曲面。它简单到极致——就是顶点坐标加面法向量，任何 3D 打印切片软件都认。但它是"近似"，曲面越平滑需要的三角形越多，文件越大。而且 STL 没有单位、没有颜色、没有装配关系，就是一个裸网格。热词里"sw 中 stl 转 stp"这类需求，本质是想把网格重新拟合成 B-rep，这个过程叫逆向建模，精度损失不可避免。
GLB是 glTF 的二进制版本，主打 Web 和实时渲染。它支持材质、动画、场景层级，浏览器里用 Three.js 或 model-viewer 直接加载。做在线预览、电商展示、AR 体验，GLB 是首选。但它同样基于网格，不适合做精密工程交换。
3.2 导出时的单位与精度陷阱
这里有个特别容易踩的坑：单位。STL 格式本身不记录单位，很多切片软件默认按毫米处理，但如果你从某个以英寸为单位的系统导出，模型会大 25.4 倍或者小到看不见。STEP 稍微好一点，头部有单位声明，但也不是所有解析器都严格遵守。
我的做法是：在生成阶段就统一用毫米，导出时显式声明。CadQuery 默认单位就是毫米，导出 STEP 时会写入单位信息。导出 STL 时，虽然格式不记录单位，但你在下游切片软件里要手动确认一次。
精度方面，STL 的三角化容差要控制好。容差太小，文件爆炸；容差太大，圆柱变成多边形。一般做 3D 打印，线性容差 0.01 到 0.05 毫米、角度容差 0.1 到 0.5 度是合理区间。CadQuery 导出时可以传tolerance参数：
cq.exporters.export(result, "plate.stl", tolerance=0.02, angularTolerance=0.2)3.3 格式转换的常见需求与坑
热词里"sw 中 stl 转 stp"是个高频需求。这里要泼盆冷水：STL 转 STEP 不是格式转换，是逆向工程。STL 里只有三角形，没有曲面信息，转成 STEP 需要先做网格分割、特征识别、曲面拟合，才能重建出 B-rep。市面上有些工具号称一键转换，实际出来的 STEP 是一堆碎面片拼的，根本没法编辑。
如果只是想在 CAD 里打开 STL 看看，很多软件支持直接导入网格作为参考几何，不需要转 STEP。真要转，用 Geomagic、Fusion 360 的网格转 B-rep 功能，或者 FreeCAD 的"从网格创建形状"，但都要人工修。
反过来，STEP 转 STL 就简单多了，任何 CAD 都能做，本质是三角化。STEP 转 GLB 稍微麻烦点，需要先转成网格，再带上材质信息打包，通常用 Blender 或者专门的转换库处理。
4. 把链路跑起来：从环境搭建到第一个模型落地
4.1 环境准备里最容易被忽略的依赖
CadQuery 的安装看起来简单，pip install cadquery一行搞定，但 OCCT 内核的依赖在有些系统上会出问题。Windows 上一般没事，Linux 服务器上如果缺了 OpenGL 相关的库，导入时会报错。做无头（headless）导出的话，其实不需要图形界面，但某些版本的 OCCT 会尝试初始化显示驱动。
我的建议是：服务器端用 cadquery 的 conda 包，它把 OCCT 依赖打包得比较完整，比 pip 版本省心。如果坚持用 pip，遇到libGL相关报错，装一下libgl1和libglu1-mesa通常能解决。
# conda 方式（推荐服务器端） conda install -c conda-forge cadquery # pip 方式 pip install cadquery # Linux 缺库时补装 apt-get install -y libgl1 libglu1-mesa4.2 大模型提示词的设计要点
让大模型生成 CadQuery 代码，提示词设计直接决定成功率。我试过很多版本，总结出几个关键点。
第一，给足 API 上下文。CadQuery 的 API 不算小，模型不可能全记住。在系统提示里塞一份常用 API 速查，比如box、cylinder、hole、cboreHole、fillet、chamfer的签名，生成质量立刻上一个台阶。
第二，强制输出可执行代码块。要求模型只输出 Python 代码，不要解释、不要 markdown 之外的废话，方便程序直接提取。
第三，要求模型自检单位。在提示里明确"所有尺寸单位为毫米"，并在生成后做一次数值范围校验，防止出现 5000 毫米的"小零件"。
第四，给几个 few-shot 示例。放两三个"描述 → 代码"的样例，模型会模仿这个模式，比纯指令有效得多。
一个简化版的系统提示大概长这样：
你是 CAD 代码生成助手。用户用自然语言描述零件，你输出 CadQuery Python 代码。 规则： 1. 所有尺寸单位为毫米 2. 只输出代码，不要解释 3. 使用 cadquery 的 Workplane API 4. 导出 STEP 和 STL 两个格式 5. 代码必须能独立运行 常用 API：box(l,w,h), cylinder(r,h), hole(d), cboreHole(d, d2, depth), fillet(r), chamfer(d)4.3 沙箱执行与超时控制
代码生成出来必须隔离执行。我用的是子进程 + 资源限制的方案，简单可靠。
import subprocess import tempfile import os def run_cadquery_safely(code: str, timeout: int = 30): with tempfile.TemporaryDirectory() as tmpdir: script_path = os.path.join(tmpdir, "model.py") with open(script_path, "w") as f: f.write(code) try: result = subprocess.run( ["python", script_path], cwd=tmpdir, timeout=timeout, capture_output=True, text=True ) if result.returncode != 0: return {"ok": False, "error": result.stderr} # 收集生成的模型文件 files = [f for f in os.listdir(tmpdir) if f.endswith((".step", ".stl", ".glb"))] return {"ok": True, "files": files, "dir": tmpdir} except subprocess.TimeoutExpired: return {"ok": False, "error": "执行超时"}超时设 30 秒是个经验值。正常零件生成都在几秒内，超过 30 秒要么是代码死循环，要么是模型生成了极其复杂的几何，两种情况都该掐掉。资源限制方面，Linux 下可以用resource模块限制内存和 CPU 时间，Windows 下相对麻烦，用容器隔离更彻底。
注意：千万不要在主进程里
exec()模型生成的代码。哪怕加了过滤，也挡不住精心构造的绕过。子进程隔离是底线。
4.4 第一个完整案例：从描述到可打印文件
拿一个具体例子走一遍。用户输入："一个直径 60 毫米、高 40 毫米的圆柱杯，壁厚 3 毫米，底部厚 5 毫米，顶部开口。"
模型生成的代码：
import cadquery as cq outer_r = 30.0 height = 40.0 wall = 3.0 bottom = 5.0 # 外圆柱 cup = cq.Workplane("XY").circle(outer_r).extrude(height) # 内腔：从底部往上挖 inner_r = outer_r - wall cavity = ( cq.Workplane("XY") .workplane(offset=bottom) .circle(inner_r) .extrude(height - bottom + 1) # 多挖一点保证顶部开口 ) result = cup.cut(cavity) cq.exporters.export(result, "cup.step") cq.exporters.export(result, "cup.stl", tolerance=0.02)这里有个细节：内腔的拉伸高度是height - bottom + 1，多出来的 1 毫米是为了确保顶部完全切穿，避免因为浮点误差留下薄薄一层膜。这种"多切一点"的技巧在布尔运算里很常用，尤其是做通孔的时候。
跑完之后，STEP 文件可以丢进任何 CAD 软件检查，STL 直接拖进切片软件就能打印。整个链路从输入到出文件，熟练的话十几秒。
5. 实测中那些文档不会告诉你的坑
5.1 布尔运算失败：几何内核的脾气
OCCT 内核做布尔运算时，偶尔会失败，尤其是两个面几乎重合、或者相切的情况。比如你要在一个圆柱侧面打一个刚好相切的孔，内核可能算不出来，报一个模糊的错误。
应对办法有几个。一是留微小间隙，把相切改成过盈 0.01 毫米，避开临界状态。二是调整运算顺序，先做大的布尔再做小的，减少中间状态的复杂度。三是换内核，CadQuery 底层是 OCCT，如果某个操作死活过不去，可以试试用 trimesh 走网格路线，虽然精度差但鲁棒性好。
我遇到最坑的一次是做一个薄壁件，壁厚 0.5 毫米，布尔运算反复失败。后来发现是内核的容差设置问题，把cq.OCCT_MAKE_TOLERANCE调大一点就过了。这类问题没有通用解，只能靠试。
5.2 大模型生成的代码"看起来对但跑不通"
这是最常见的失败模式。模型生成的代码语法没问题，逻辑也说得通，但一跑就报错。原因通常是 API 用错了——比如cboreHole的参数顺序、workplane的偏移方向、faces选择器的语法。
我的处理策略是分级重试。第一次失败，把错误信息喂回给模型，让它修正。第二次还失败，就降级到更简单的几何——比如把沉头孔换成普通通孔，把圆角去掉。第三次失败，返回一个"无法生成"的提示，让用户改描述。硬撑着重试十几次没意义，浪费 token 也浪费时间。
错误信息回喂的时候，要截取关键部分。OCCT 的报错经常是一大段堆栈，把最底层的异常信息提取出来给模型就够了。
5.3 复杂曲面的表达力边界
CadQuery 擅长的是规则几何——拉伸、旋转、扫掠、布尔。遇到自由曲面，比如流线型外壳、有机形状，它就力不从心了。你让模型生成一个"符合空气动力学的汽车外形"，它生成的代码要么是简单几何拼凑，要么直接报错。
这不是模型的问题，是工具链的边界。自由曲面需要 NURBS 建模，CadQuery 的 API 对 NURBS 支持有限。真要做曲面，得换到 Rhino、Blender 这类工具，或者用 OpenCASCADE 的底层 API 手写。text-to-cad 在这个方向上的能力，目前还停留在"能生成简单曲面"的阶段。
实际项目里，我的做法是明确告诉用户能力边界。规则零件走 text-to-cad，自由曲面走传统建模，不要硬凑。
5.4 批量生成时的性能与稳定性
做批量参数化生成时，单个模型几秒，一百个就是几分钟。如果串行跑，用户等得着急；并行跑，OCCT 内核不是线程安全的，多线程容易崩。
我的方案是多进程 + 队列。每个进程独立加载内核，处理一个任务，进程之间不共享状态。用multiprocessing.Pool控制并发数，一般设成 CPU 核心数的一半，留点余量。这样既利用了多核，又避开了线程安全问题。
from multiprocessing import Pool def generate_one(params): # 每个进程独立执行，互不干扰 code = build_code(params) return run_cadquery_safely(code) with Pool(processes=4) as pool: results = pool.map(generate_one, param_list)内存方面要注意，OCCT 对象不及时释放会累积。每个任务结束后确保临时文件清理干净，进程定期重启（比如每处理 50 个任务重启一次），防止内存泄漏拖垮服务。
6. 这套东西能用在哪些真实场景
6.1 硬件原型的快速迭代
做硬件产品，早期最需要的是"快速看到形状"。结构工程师画一版要半天，产品经理改个需求又要半天。用 text-to-cad，产品经理自己描述"一个 80x60x20 的盒子，顶部开个 30 毫米的圆孔，侧面开 USB 口"，几秒钟出模型，直接 3D 打印验证手感。不合适就改描述，迭代速度完全不一样。
这个场景里，精度不重要，重要的是快和能改。STEP 格式保证后续能进 CAD 细化，STL 保证能打印，GLB 保证能在网页上给远程同事看。
6.2 教学演示与内容创作
做 CAD 教学的人，经常需要准备大量示例模型。手工建一百个不同规格的零件，枯燥且耗时。用 text-to-cad 批量生成，参数一改就是一套新模型，配合脚本还能自动出图、自动标注。内容创作者做 3D 打印教程，需要各种形状的演示件，同样适用。
6.3 参数化零件库的自动构建
标准件库、常用零件库，本质就是参数化模板。螺栓、垫片、法兰、支架，规格变一变，几何跟着变。传统做法是人工建库，工作量大且容易出错。用 text-to-cad 的思路，把每个零件的描述模板化，输入规格参数，自动生成全套模型和图纸。这个方向在制造业的数字化流程里很有价值。
6.4 和下游流程的衔接
生成的模型怎么进下游？STEP 进 CAD 做详细设计，STL 进切片软件做 3D 打印，GLB 进 Web 做展示。如果下游是仿真，STEP 也能导入 CAE 软件划分网格。如果下游是渲染，GLB 带材质直接出图。
衔接的关键是元数据。模型文件本身只记录几何，但实际使用需要知道材料、公差、版本。我的做法是在生成时同步产出一份 JSON 元数据，记录这个模型的所有参数和来源描述，和模型文件一起归档。这样追溯起来方便，也便于后续批量修改。
7. 关于工具链选型的一些个人判断
CadQuery 不是唯一选择。OpenSCAD 更轻量，适合简单几何；FreeCAD 有 Python API，功能全但重；Blender 的 bpy 适合做渲染和网格处理。选哪个，取决于你的下游需求。
如果下游要 STEP，CadQuery 或 FreeCAD 是首选，因为它们基于 OCCT，B-rep 精度有保证。如果下游只要 STL 和 GLB，OpenSCAD 和 Blender 也能胜任，而且更轻。如果要做复杂曲面，那这些都不够，得上 Rhino 的 Grasshopper 或者直接用 OpenCASCADE 底层。
我自己的项目里，主力是 CadQuery，因为它 Python 原生、API 清晰、社区活跃，和大模型的配合最顺。遇到它搞不定的曲面，再单独用 Blender 补。工具是拿来用的，不是拿来站队的，哪个顺手用哪个。
大模型这边，代码生成能力强的模型都行，关键是提示词工程和错误处理要做扎实。模型再强，生成的代码也有失败率，工程上的容错设计比选哪个模型更重要。
最后说个我踩过的坑：别在提示词里塞太多 API 文档。我一开始把整个 CadQuery 文档塞进系统提示，结果模型反而抓不住重点，生成质量下降。后来精简到只放最常用的十几个 API，效果反而好。上下文不是越多越好，精准才重要。
