Text-to-CAD这几年在AI与设计制造交叉领域几乎成了必聊话题。简单说，它就是用自然语言描述一段设计意图，AI直接给你吐出一个可编辑、可制造的三维CAD模型，而不是一张不能用的图片或者不带特征历史的三角网格。这个方向想解决的终极问题，是把“建模”从一门需要长时间训练的操作技能，变成“说清楚需求”的沟通问题。不管你是做结构设计的机械工程师，还是只想要一个手机支架STL文件的DIY爱好者，又或者是想给3D打印机用户做智能建模平台的开发者，这条技术链路都值得你花时间摸一遍。本文的主角就是我实际跑通的一套基于CadQuery的Text-to-CAD工作流，我会把技术路线、工具选型、代码细节和踩坑记录全部摊开来讲。
1. 从一句描述到CAD模型，中间发生了什么
1.1 这不是“让AI写脚本”，而是一个工程闭环
很多人第一次听到Text-to-CAD，第一反应是“这不就是让ChatGPT写OpenSCAD代码吗”。这个认知不能说错，但确实把问题想简单了。如果你真的让大模型什么都不管直接写一段CAD脚本，生成结果的可用率低到你怀疑人生。原因在于，Text-to-CAD表面上是“文本到代码”，实际上需要一整套闭环：先理解用户描述里的设计意图，再把它转成结构化需求，接着生成符合CAD内核语法的特征操作序列，最后还要验证生成的模型是否符合原始描述。
这个闭环里最难的不是最后一步代码生成，而是前两步。人类描述设计意图时天然会省略信息。你说“给我一个带四个安装孔的法兰盘”，这里面没有外径、没有厚度、没有孔间距、没有公差等级，但模型必须把这些全部定下来。语言模型要做的不是“猜一个尺寸”，而是结合行业惯例和上下文推断一套合理参数，并且把推断结果明确暴露出来让用户确认。这与普通代码生成有本质区别：代码生成错了能立刻编译报错，CAD模型生成错了可能要到加工阶段才发现尺寸全对不上。
我自己的经验是，真正可用的Text-to-CAD工作流，必须有“生成 → 执行 → 验证 → 反馈”四段式结构。大模型每生成一次代码，CAD内核就把模型真正构建出来，然后程序自动检查关键尺寸、特征数量和空间关系，检查不过就带着具体报错信息让模型重新生成。这个过程听起来不复杂，但正是这个循环让成功率有了质的提升。没有验证环节的生成，本质上只是在碰运气。
1.2 为什么程序化建模路线更值得押注
Text-to-CAD有好几条技术路线可以走，直接生成网格、生成隐式场、生成代码脚本。我之所以坚定押注程序化建模路线，核心原因只有一个：制造业的底层语言是参数、特征是B-Rep曲面，而代码恰好是描述这些复杂结构最精确的载体。
直接生成网格的路线做出来的是“雕塑泥巴”，看起来像那么回事，但你想修改一个孔的位置，想加一个沉台，想在加工软件里直接读取特征树，全都无从下手。程序化建模路线做出来的是“积木系统”，每一步操作都有明确语义，圆柱拉伸、挖槽、倒角、阵列，这些操作天然就是制造工程师脑子里思考的方式。用生活化的类比来说，直接生成网格像是请人画了一幅非常像的油画，程序化建模则是给你一份带参数标注的建筑施工图。
CadQuery这类工具相比OpenSCAD有个更大优势：底层直接基于OpenCASCADE内核，这是工业级CAD软件普遍采用的几何内核，导出的STEP文件和SolidWorks、Fusion 360、NX都能真正无缝对接。这意味着AI生成的模型不是一个只能在浏览器里看的对象，而是可以直接进入工程流水线的产品。这种“能上车床的AI建模”和“只能看效果的AI建模”，在整个项目价值上完全是两个量级。
2. 主流技术路线与工具选型解析
2.1 用LLM驱动CadQuery和OpenSCAD：最务实的方案
目前最容易被个人开发者复制到本地的工作流，就是让大模型生成CadQuery或者OpenSCAD脚本。我强烈推荐CadQuery而不是OpenSCAD，原因有三条：第一，CadQuery是真正的Python语法，大模型训练语料里Python含量极高，模型生成代码的语法正确率明显更高；第二，CadQuery的建模语义贴近现代CAD（槽、阵列、倒角、选择面），而OpenSCAD的CSG布尔操作表达复杂曲面非常吃力；第三，CadQuery输出STEP和STL都极其方便。
举个例子，一个法兰盘的CadQuery代码是这样的：
import cadquery as cq # 外径60mm，厚度10mm，中心孔直径20mm，四孔均布在直径45mm的圆上 result = ( cq.Workplane("XY") .circle(60 / 2) .extrude(10) # 拉伸成盘体 .faces(">Z") # 选择顶面 .workplane() .hole(20) # 中心通孔 .faces(">Z") .workplane() .rect(45, 45, forConstruction=True) # 构造参考矩形 .vertices() .hole(6) # 四个安装孔 ) cq.exporters.export(result, "flange.step")这段代码读起来相当直白，你甚至可以把它当作文档来看。大模型生成这类代码的难度远低于从零写一个算法，因为CadQuery API的“段落感”很强，模型很容易通过少量few-shot示例掌握模式。基于这套思路，现在国外不少初创平台做的Text-to-CAD产品，底层跑的就是这类脚本化建模引擎，只是在上层包装了更友好的交互界面、参数编辑器和在线预览。
2.2 扩散模型与三维生成路线：适合“看效果”，不适合“做工装”
讨论Text-to-CAD绕不开另一条路线，就是DreamFusion、Point-E、Shap-E这类文本生成三维模型的方法。这些方法确实热门，也确实在视觉质量上不断刷新纪录，在游戏资产、影视概念设计、虚拟现实领域有明确应用价值，但放在CAD语境下就有些不接地气。
扩散模型输出的是网格或者隐式场，这类数据天生不具备参数化特征。工程师拿到一个STL后想改某段圆弧的半径，想改孔位间距，完全没有操作入口，只能整体重新生成。更麻烦的是，这类模型输出的几何经常存在非流形的边、重叠面、微小裂缝，直接丢给3D打印切片软件都有概率翻车，更不用说CAM编程和数控加工了。
我用过几次之后给出的判断是：文本到网格是“创意玩具”，文本到CAD是“生产工具”。它们未来可能会融合，但现阶段不应该混为一谈。如果你做的是玩具手办、艺术摆件，那扩散模型路线完全够用；如果你做的是非标自动化设备里的一个安装底座、一块盖板、一只轴承座，那你需要的必然是参数化CAD模型，老老实实走程序化建模路线吧。
2.3 工程级方案：CAD内核API语义解析与AI的结合
再往上一层看，学术界和工业界也在探索更完整的工程级方案。研究方向上已经出现了端到端的Text-to-B-Rep框架，用指令微调的语言模型把自然语言描述映射成CAD建模命令序列，输出标准B-Rep表示。这类工作本质上和我上面提到的CadQuery路线是一致的，只是把建模命令从Python脚本换成了更底层的内核API调用。
工业界的动作更直接。主流CAD软件厂商都在自家产品里做AI助手，接受文字或语音指令帮助用户完成重复性建模操作。专业软件的优势是天生拥有完整的设计特征树和约束管理器，AI不需要自己处理几何内核，只需要把用户意图翻译成内核能听懂的操作指令。这条路线在装配体设计、异形曲面、拓扑优化这些复杂场景上潜力更大，但普通开发者基本接触不到内部接口，只能等商业产品逐步对外开放。
对个人开发者和中小团队来说，最稳妥的切入点仍然是CadQuery和LLM的组合。它性能足够、成本可控、迭代速度快，并且完全掌握在你自己手里，不被第三方平台锁死。
3. 实操：搭一套可用的Text-to-CAD工作流
3.1 环境准备与模型选型
先说环境。CadQuery 2.x现在已经把OpenCASCADE内核直接打包成wheel发布，安装非常省心：
python -m venv .venv source .venv/bin/activate pip install cadquery jupyter-cadquery装完后我建议你顺手验证一下CadQuery是否正常工作。在Jupyter里跑通一个简单的拉伸圆柱，同时把jupyter-cadquery装好，它可以在Jupyter Notebook里直接渲染出三维预览，这个对调试帮助极大。你会发现CadQuery渲染的模型可以旋转缩放、切换显示模式、查看特征树，调试体验甚至你想象中还要舒服。
模型选型方面，如果追求生成效果，我实测下来云端API的闭源模型明显比本地开源模型好，尤其在遵守复杂约束方面。如果考虑数据隐私和成本，本地推荐试试Qwen2.5-Coder-7B或者DeepSeek-Coder-V2-Lite，配合场外扩展可以实现基础建模。我的建议是：日常开发用便宜的开源模型，遇到效果死活不达标的情况再切换强模型。大部分人实际使用过程中，90%的问题不是模型能力不够，而是提示词框架没设计好。
3.2 提示词框架与示例库：把成功率提上来的核心
Text-to-CAD的提示词设计，不能是“帮我做一个法兰盘”一句话丢给模型。你需要一套结构化的两段式提示：第一段是固定的系统提示词，告诉模型它的角色、输出格式、命名规范和代码约束；第二段是用户需求，伴随历史代码上下文。
我自己常用的一套系统提示词模板大致是：
你是一名高级CadQuery建模专家。你的任务是接受用户的中文设计需求，输出可直接执行的CadQuery 2.x Python代码。 硬性要求： 1. 只输出Python代码块，不输出任何解释和Markdown说明 2. 所有尺寸在代码中显式赋值，不允许使用未命名变量 3. 最终生成的Workplane对象必须命名为 result 4. 优先使用工作平面选择器(>Z, <Z, >X等)，不要通过坐标平移定义草绘平面 5. 需要孔特征时区分通孔与盲孔，盲孔必须指定深度 6. 代码必须保证在CadQuery 2.4及以上版本运行除了系统提示词，我强烈建议在每个请求里带两到三个few-shot示例。示例不追求多复杂，但要覆盖常见结构模式，比如带孔底板、加圆角法兰、异形壳体。带示例之后生成成功率提升非常明显，实测可以把一次生成通过率从三成以下拉到六成以上。
设计提示词的关键思维是“给模型铺路而不是给模型设限”。不要在提示词里写“不要使用已废弃API”这种抽象规则，直接给一份可用的API速查表或一个正确代码示例，模型自然会照着模仿。CadQuery的API一直在演进，大模型训练语料容易过期，把最新API示例塞进提示词里，解决版本旧知识带来的语法错乱问题，比让模型自己“回忆”靠谱得多。
3.3 核心代码：生成、执行、验证三条腿走路
这里给出一个经过我验证的简化版核心流程，你可以直接改写使用。整个流程分为四个步骤：解析需求、生成代码、执行模型、自动修复。
import io import contextlib import json import cadquery as cq def call_llm(prompt: str) -> str: """ 对接你的模型服务，本地Ollama或云端API均可。 这里不展开具体实现，只留一个接口。 """ raise NotImplementedError("请接入你的模型服务") def extract_requirements(description: str) -> dict: """ 前处理：让LLM把自然语言描述解析成结构化需求JSON。 这一步是Text-to-CAD和普通代码生成的最大区别。 """ prompt = f""" 请将下面的CAD建模需求解析为严格JSON，不要输出任何多余文本。 规则： - 所有尺寸统一为毫米 - fields必须包含 overall_dimensions（整体尺寸）、features（特征列表）、constraints（约束条件） - features里区分 hole / slot / fillet / boss / groove 等类型 - constraints必须写明通孔还是盲孔、是否中心对称、参考位置 需求：{description} """ content = call_llm(prompt) return json.loads(content) def generate_cad_code(description: str, requirements: dict) -> str: system = "你是一名高级CadQuery建模专家……（按上文系统提示词填充）" user = f"""当前需求：{description} 结构化需求：{json.dumps(requirements, ensure_ascii=False)} 请只输出完整Python代码。 """ return call_llm(system + "\n" + user) def execute_cad(code: str, ns: dict) -> cq.Workplane: """ 在独立命名空间执行代码，防止环境变量污染。 """ with contextlib.redirect_stdout(io.StringIO()): exec(code, {"cq": cq}, ns) result = ns.get("result") if result is None: raise RuntimeError("生成代码未定义 result 变量，请检查代码语义") return result def validate_model(model: cq.Workplane, requirements: dict): """ 核心验证函数：检查尺寸、特征数、流形合法性。 这个环节能挡住一半以上的“能跑但不对”的模型。 """ bbox = model.val().BoundingBox() dims = requirements.get("overall_dimensions", {}) tol = 2.0 # 毫米容差，按实际需求调整 if "length" in dims and abs((bbox.xmax - bbox.xmin) - dims["length"]) > tol: raise ValueError(f"长度不满足要求: 期望{dims['length']}，实际{bbox.xmax - bbox.xmin}") if "width" in dims and abs((bbox.ymax - bbox.ymin) - dims["width"]) > tol: raise ValueError(f"宽度不满足要求: 期望{dims['width']}，实际{bbox.ymax - bbox.ymin}") if "thickness" in dims and abs((bbox.zmax - bbox.zmin) - dims["thickness"]) > tol: raise ValueError(f"厚度不满足要求: 期望{dims['thickness']}，实际{bbox.zmax - bbox.zmin}") if not model.val().isManifold(): raise ValueError("模型不是流形实体，导出后无法可靠制造") # 更多验证可按需求扩展…… def text_to_cad(description: str, max_retries: int = 4): requirements = extract_requirements(description) code = generate_cad_code(description, requirements) for attempt in range(max_retries): try: ns = {} model = execute_cad(code, ns) validate_model(model, requirements) return model, code, requirements except Exception as e: print(f"第 {attempt + 1} 次生成失败: {e}") if attempt == max_retries - 1: raise code = call_llm( f"你上一轮生成的CadQuery代码执行或校验失败，错误信息如下：\n{e}\n" f"请分析原因，修正后只输出完整代码：\n{code}" ) # 使用示例 model, code, req = text_to_cad("尺寸120x80x10的底板，中心开一个40x30的矩形通槽，四角安装M6通孔，倒角半径5") cq.exporters.export(model, "base_plate.step") cq.exporters.export(model, "base_plate.stl")这套流程的关键在于validate_model这一步。大多数Text-to-CAD示例代码只会执行生成而不会校验结果，导致模型生成的东西“语法完全正确，逻辑完全跑偏”。有了结构化的需求JSON和自动校验，程序才能在“模型看着差不多但尺寸完全不对”时及时发现，把错误信息反馈给模型进行第二轮修复。我实测下来，加了这一轮验证之后，最终可靠成功率可以从不到一半提升到七成以上。
4. 常见问题与排查技巧实录
4.1 CadQuery版本兼容性：最常见的翻车现场
大模型生成的CadQuery代码里最常见的问题是API版本不兼容。大模型训练数据里的CadQuery代码往往来自旧版本博客和教程，而CadQuery 2.4之后不少API的语法变了，特别是面选择器、顶点选择操作、布尔合并函数都有调整。
我的解决措施有三个。第一，在系统提示词里明确写“使用CadQuery 2.4以上API”，并提供一份简短的最新API速查表。第二，在few-shot示例里特意使用新版写法，让模型跟着范例走。第三，如果真的遇到执行报错，不要把原始报错直接丢给大模型就完事，我把报错信息里夹带一个“建议按CadQuery 2.x官方文档写法替代旧API”的提示，修复速度会快很多。
这类问题本质上不是模型笨，而是训练语料太旧。出现一次修复一次，修复后的正确代码积累成新的few-shot示例，慢慢你会发现同一个错误很少再犯第二次。所以建议从第一天起就维护一个“已验证代码库”，每次调试通过的代码都归档，作为后续提示词的素材。
4.2 语义理解偏差：语言和几何之间的断层
文本到CAD碰到的另一个大坑是语义理解偏差。最常见的有三类：孔直径和半径不分、盲孔和通孔不分、中心位置理解错。
“直径40mm的孔”在CadQuery的hole()函数里参数代表的就是直径，但模型经常在circle(40 / 2)和hole(40)之间精神分裂，导致孔尺寸翻倍。解决方式是在系统提示词里明确写：“hole(参数)接收的是直径还是半径，请在代码注释中标明”。这个东西看似简单，实际运行中坑了我好几次。
中心位置问题更隐蔽。用户说“底板的右下角开一个圆孔”，这里的“右下角”在工程坐标里有无数种理解方式。我现在的经验是不要指望模型能自动想清楚，而是前期就给它一份“位置描述规范”：凡是涉及方位的描述，代码里必须使用相对面的几何选择器，比如faces(">X")表示正X方向的面，而不是通过裸坐标平移。用几何选择器代替坐标定位，能大幅减少偏移错位。
4.3 质量评估：别只看“像不像”，还得看“能不能用”
辅助文本生成模型类工具看结果时要训练自己的三维观察力。我给自己定的质量标准有以下几条：
| 检查项 | 检查方法 | 合格标准 |
|---|---|---|
| 流形体检查 | model.val().isManifold() | 返回True |
| 关键尺寸 | BoundingBox 对比需求 | 偏差小于容差，通常±2mm |
| 特征数量 | 遍历特征树逐个确认 | 与需求一致 |
| 装配一致性 | 导出STEP后在Fusion 360打开检查 | 无缺失元素 |
| 可打印性 | STL导入切片软件预检 | 无悬空、无闭环漏洞 |
一般生成模型后在CadQuery里看渲染结果，我至少会检查上述前三条。不要省掉流形体检查这一步，“看起来完整”和“实际上闭合”是两回事，尤其布尔运算生成的模型很容易出现内部破面，肉眼完全看不出来，但导成STL后切片软件会直接报错。
有一条独家的经验：当你让模型基于已有代码做修改时，一定要把之前的代码完整贴回去，只给增量描述。大模型的上下文注意力对增量修改特别敏感，如果只给“在上次基础上加个凸台”而没贴原始代码，十次有八次会生成一个从零开始、完全对不上的新模型。把这个习惯养成，你会少掉很多重做的活。
5. 应用落地场景与我对这个方向的看法
5.1 真正适合落地的三个场景
第一条线是3D打印快速原型。个人创客、教育场景、产品设计早期验证，这类需求通常结构不复杂、制造精度要求不高、迭代速度快，Text-to-CAD生成的参数化模型直接导出STL丢给切片软件，能大大缩短“有了想法到握在手里”的路径。我自己拿它做过定制手机支架、传感器外壳、线缆固定座，从自然语言描述到拿到实物，一次完整的流程可以控制在十几分钟以内，这个速度和传统CAD建模没法比。
第二条线是机械设计的非标自动化变体设计。现在很多设备厂面临的问题是，同一类零件（安装底座、防护罩壳、电机支架）只是尺寸不同，结构形状基本一样。把过去积累的建模经验沉淀成示例库和参数模板，再用LLM按新尺寸生成变体，效率提升非常可观。这种场景天然适合CadQuery，因为代码本身就是参数化的，改一个变量整个模型自动更新。
第三条线是教学培训。CAD软件的操作门槛一直不低，学生既要记命令又要懂空间关系。Text-to-CAD可以把训练重点从“鼠标操作”拉回到“设计思维”上：你描述、AI生成、你检查、你修改约束。这种交互方式在概念设计课程里特别合适，能让学生把精力放在方案推敲而不是按钮位置。
5.2 我对Text-to-CAD走向的一点经验判断
我的判断是，Text-to-CAD短期不会替代桌面CAD软件，但它正在改变“建模”这个动作的准入门槛。未来三年大概率会看到三类趋势：一是从单零件走向装配体，你的描述不再只是一个底座，而是“一个电机加上两个安装架还有四颗螺钉”的完整装配约束；二是从尺寸推断走向约束深化，AI会主动反问你“这里的公差等级是多少”“要不要保留拔模斜度”，而不是默默替你下决定；三是从脚本生成走向设计意图管理，你维护的不再是模型本身，而是一组自然语言描述的设计约束，模型和图纸都从同一份意图声明里派生出来。
对普通开发者而言，现在正是动手学习CadQuery和搭建AI建模工作流的好时机。工具已经足够成熟，开源模型的能力也在快速追赶，缺的不是技术，而是对“从需求到制造”整条链路的理解。把这条路跑通的人，三年后回头看会发现自己比同行多走了一个身位。
我个人在实际操作中最大的体会是，Text-to-CAD的稳定性瓶颈很大程度上可以通过工程手段补齐。多轮修复机制、结构化需求解析、已验证示例库这三个东西组合起来，效果比单纯换更大更贵的模型要明显得多。最后再分享一个小技巧：每次生成的成功案例一定保留原始描述和最终代码，过一个月回头再看，这些记录就是你训练更好系统最宝贵的数据，比任何公开教程都有说服力。
