1. 项目概述

1.1 从一句中文描述到可用CAD模型的完整链路

"text-to-cad"，字面意思就是把文字描述变成CAD模型。你输入一句"一个直径30毫米、高度50毫米的圆柱体，顶部带一个边倒角"，系统在几十秒内就能生成对应的三维模型文件，可以直接导入主流建模软件继续编辑，或者直接送去3D打印。这不是科幻片里的桥段，而是过去两年里大模型与几何计算交叉领域最有实用价值的落地方向之一。

我最初接触这个方向是因为团队接了个定制化零部件设计的活儿，客户反复修改需求，每改一次描述就要重新调参建模，效率低到让人崩溃。后来调研了一圈text-to-cad相关的开源项目和商业工具，发现这条路已经比想象中成熟很多，只是很多人都还停留在"听说过"的阶段，不知道它到底能做什么、不能做什么、怎么接到自己的流程里。

这篇内容我会从原理、工具、实操、踩坑几个角度完整拆一遍，覆盖从输入提示词到导出STEP/STL文件的全过程，也会聊清楚哪些场景真的适合用text-to-cad、哪些场景现阶段还是老老实实手搓比较靠谱。

1.2 这个方向解决的现实痛点

传统CAD建模的门槛在于"操作"而不是"思维"。你脑子里清楚要一个什么形状，但要在软件里把这个形状表达出来，需要记住一大堆命令、快捷键、约束关系。对于机械工程师、结构工程师甚至产品经理来说，这种"想法到模型的转译损耗"是实实在在的效率杀手。

text-to-cad的核心理念是：如果能用自然语言直接描述几何需求，那么建模的门槛就从"会操作软件"降维到"能说清楚需求"。这带来的不只是效率提升，更重要的是让非专业建模人员也能参与到三维设计流程中。比如产品经理可以直接生成概念模型用于评审，工艺人员可以快速验证某个结构的可加工性，甚至学生可以用它来理解几何描述和实体模型之间的对应关系。

当然，"能说清楚需求"这件事本身也有门槛，这一点我会在后面的提示词工程部分详细展开。整体概括就是：text-to-cad不是在替代CAD软件，而是在CAD软件之前加了一层"自然语言接口"，把需求翻译成模型，再由人工精修。

2. 技术原理拆解：text-to-cad是怎么把语言变成几何的

2.1 语言模型负责"听懂"，几何引擎负责"画出来"

要理解text-to-cad的实现方式，最直观的思路是把系统拆成两个模块——语义理解模块和几何生成模块。

语义理解部分和普通的文本生成任务非常相似，用的是近年来的主流语言模型架构。模型需要从用户描述中提取出关键信息，比如几何类型（圆柱、长方体、球体）、尺寸参数（直径、高度、壁厚）、特征操作（倒角、圆角、拉伸切除）、空间关系（中心对齐、偏移、阵列）等等。模型的输出一般不是直接的CAD文件，而是某种"中间表示"。

这个中间表示就是整个系统的灵魂。目前业界主流的做法有几类：

第一类是程序化表示，典型代表是生成OpenSCAD、CadQuery、Build123D这类代码库的脚本。语言模型只需要生成符合语法的代码，再由对应的库来执行生成几何。这个路线的最大好处是可编辑性强——生成的脚本就是活参数，改一个数字重新跑一遍就能得到新模型。

第二类是结构化表示，把模型分解成CSG（构造实体几何）树，也就是若干基本几何体通过布尔运算组合。语言模型输出一个树状结构，比如"一个底板，加上两个圆柱通孔，再减去一个矩形槽"，然后由几何内核按这棵树去构建实体。

第三类是直接生成点云或体素，再用表面重建算法转成网格。这个思路更接近图像生成，灵活性高但精度和可编辑性差一些，目前主要用于概念验证阶段。

我自己的经验是，第一类方案在工程实践中最靠谱，因为输出结果可以无缝衔接现有工作流。你拿到一段CadQuery代码，意味着生成步骤是可复现的，参数是可调的，这对于制造业场景来说几乎是底线需求。

2.2 从文本到约束：挑战在于"模糊描述"如何转成"精确参数"

自然语言和CAD模型之间存在一个天然鸿沟——语言是模糊的、省略的、依赖语境的，而CAD模型是精确的、完整的、自洽的。举个例子，"一个杯子的模型"这句话，人类能猜到大概是什么样子，但机器要生成一个可用于制造的模型，就必须确定壁厚、高度、口径、底部圆角这些所有参数。

为了解决这个问题，当前系统普遍采用了两条腿走路的策略。一条腿是利用大模型的先验知识补全未说明的默认值。模型在训练时见过大量三维模型和对应描述，所以当你说"一个杯子"，它会根据训练分布自动选择一个合理的默认尺寸范围。另一条腿是人在回路中迭代，用户通过多轮对话逐步调整参数，系统根据反馈修正生成结果。

实际操作中，我发现一个关键技巧：在提示词里把"必须明确"的参数和"可以推断"的参数分开写。比如"直径50mm、高度80mm、壁厚3mm的圆柱形杯子"就比"一个杯子"可控得多。你不需要把所有参数都写全，但关键尺寸必须给到，否则模型只能靠猜，猜错了重新生成的成本反而更高。

2.3 几何约束求解和参数化建模，为什么它们决定生成质量

前面说的是从文本到中间表示的过程，但中间表示到最终几何模型之间还有一道关卡——约束求解。

很多text-to-cad系统生成的代码虽然语法正确，但跑出来的几何是断裂的、过约束的或者根本不满足设计要求。比如你要一个"直径30的圆孔，圆心距左边缘15"，生成的草图如果约束不完备，拉伸出来的孔位置可能就偏了。这个问题的根源在于语言模型并不天然理解几何约束的完整性。

解决这个问题有两个方向。一个是后置校验：几何生成后自动检查体量、布尔运算合法性、约束是否满足，不满足就触发重新生成。另一个是约束驱动生成：在中间表示里显式包含约束关系，让几何内核在求解时就能保证一致性。

从实用角度讲，后置校验更常见，因为实现成本低、对模型生成能力的要求也低。但如果你要做的是装配体级别的生成任务，约束驱动方案几乎是必须的，否则零件之间配合公差没法保证。这也是为什么目前text-to-cad在单零件场景表现尚可，但一到装配体就翻车的深层原因。

3. 工具选型解析：当前可用的主流方案对比

3.1 开源代码生成方案：CadQuery和Build123D为核心的原生路线

如果你希望完全掌控生成流程，不想被商业平台绑定，开源路线是首选。目前最活跃的两个Python库是CadQuery和Build123D，它们都属于程序化建模框架。

CadQuery的特点是封装层次清晰，提供了大量语义化的建模操作，比如box()、cylinder()、fillet()、cut()等等。语言模型需要学会的是这些API的调用方式，而不是裸写几何内核代码。Build123D在外观上和CadQuery很相似，但内部采用的是拓扑命名机制，对复杂演算的支持更稳定。

配套的语言模型可以选择通用型大模型，也可以通过微调获得更好的代码生成能力。我见过一个比较轻量级的做法：把CadQuery官方的示例代码和对应的自然语言描述组成训练语料，在一个中等规模的开源模型上做LoRA微调，就能获得不错的text-to-cad能力。整个过程可以在消费级显卡上完成，门槛不高。

下面是我常用的一个CadQuery生成杯子的示例脚本，语感上非常接近模型应该学会的输出格式：

import cadquery as cq result = ( cq.Workplane("XY") .circle(25) .extrude(80) .shell(-2) .edges("|Z") .fillet(1.5) ) show_object(result)

这段代码描述的就是"外径50mm、高80mm、壁厚2mm、底部外侧圆角1.5mm的杯子"。模型只要学会这类API的模式化调用，就能生成大量变体。

3.2 商业服务与云端API：开箱即用的多模态方案

如果不想折腾环境，市面上也已经出现了不少商业化的text-to-cad服务。它们通常在网页端提供对话框，输入描述后等待几十秒就能下载STEP、STL或原生格式文件。这类服务的底层往往结合了多种生成策略：先用语言模型解析语义，再用参数化模板库匹配，必要时结合生成式网格模型做细节补全。

商业方案的核心优势不在于单点技术多强，而在于端到端的体验完善度——无需安装环境、无需管理依赖、内置了常见后处理流程。很多服务还支持多轮对话修改，你告诉它"杯子壁再薄一点"、"底部加个防滑纹路"，它会在之前的生成结果基础上做局部修改。

选型时我建议关注几个硬指标：支持导出哪些格式、能否保持参数化特性、生成时延和失败率、私有化部署选项。如果只是做概念展示，商业方案很省心；如果要批量生成或集成到内部系统，开源方案的可控性更好。

3.3 选型对比：哪种方案适合你

从实践角度给出一个选型判断表，方便对应自己的场景：

我自己目前采用的是混合方案：前期用商业服务快速验证提示词描述是否充分，确定方向后切换到开源方案做参数化精修和批量衍生。这个流程兼顾了效率和可控性。

4. 实操过程与核心环节实现

4.1 模型搭建第一步：从零配置一个可用的text-to-cad环境

不管选哪条路线，本机有一个能跑的实验环境总是必要的。下面是我整理的快速搭建步骤，以CadQuery为例，全部在Python环境下进行。

第一步是创建虚拟环境，避免依赖冲突。建议使用Python 3.10以上版本，CadQuery对旧版本的支持不够友好：

python -m venv cad_env source cad_env/bin/activate # Windows下用 cad_env\Scripts\activate pip install cadquery

安装完成后可以先跑一个简单的box生成测试，确认环境没问题：

import cadquery as cq result = cq.Workplane("XY").box(10, 20, 30) show_object(result)

第二步是准备大模型调用。如果使用API方式，直接配置好密钥和接口地址；如果要在本地跑开源模型，则需要安装推理框架并下载模型权重。考虑到本地模型在代码生成任务上的准确率可能偏低，我在实验阶段通常直接用API，把本地算力留给调试。

第三步是编写一个简单的适配层，把模型输出的文本包装成可执行的Python脚本。这一步的关键是要做好代码净化——模型有时会输出解释性文字、注释或者多余的markdown标记，必须清洗干净再执行。

4.2 提示词工程：如何用一句话生成高质量模型

text-to-cad的成与败，一半在提示词。我总结了五条实用经验，每一条都是真金白银踩坑换来的。

第一条，给出明确的主几何体。不要只说"设计一个机械零件"，要说"设计一个底板为80x60x10mm的L形支架"。主几何体是整个模型的地基，地基描述不清晰，后面所有附加特征都无处附着。

第二条，用尺寸数字替代模糊形容词。"大一点"、"厚一些"这类词完全无法用于参数化生成，"直径40mm"、"壁厚2.5mm"才是有效描述。模型能从语境推断默认值的程度有限，不要考验它。

第三条，描述特征时带上操作语义。与其说"顶部有个凹槽"不如说"顶部挖一个宽20mm、深5mm的矩形槽，槽的中心与顶面中心对齐"。模型对"挖"、"拉伸"、"切除"这类操作词的理解远比"有"、"包含"更准确。

第四条，善用参考坐标系。描述相对位置时，尽量给出明确的参考基准，比如"孔心距离左边缘15mm"、"底面离地10mm处开一个直径8mm的通孔"。没有明确基准的定位描述很容易生成错位置。

第五条，迭代而不是一次性到位。不要期望第一句话就生成完美模型。正确的打开方式是先给一个整体描述，拿到初版后，再用"把X改成Y"、"在Z位置加一个W"这样的指令逐步精修。这个习惯能显著降低失败率。

下面是我实测效果不错的一个提示词模板：

生成一个CadQuery脚本：底板为80x60x10mm的长方体，四个角上各有一个直径8mm、深度8mm的沉头孔，孔心距相邻边缘10mm；底板上方中心位置有一个直径30mm、高度40mm的圆柱凸台，凸台与底板之间做5mm半径的圆角过渡。

这个描述覆盖了主几何、特征位置、尺寸、过渡方式，模型生成的成功率明显高于笼统描述。

4.3 代码清洗与安全执行：大模型输出上生产线前的关键一环

这里有一个容易被忽视但极其重要的环节：对模型生成的代码做安全检查和约束执行。大模型生成的代码看似正常，但可能会有语法错误、缺少导入语句，甚至偶尔出现恶意注入的情况（虽然概率极低，但不可不防）。

我的标准处理流程是：

1. 用正则或目标提取模块剥离代码块，丢弃解释性文字；
2. 检查是否包含import语句，补齐CadQuery的基础依赖；
3. 对执行环境做隔离，使用受限的临时目录，禁止网络访问；
4. 设置超时时间，防止死循环或长时间无响应；
5. 捕获执行日志，方便定位生成失败的阶段。

如果你做的是批量生成，建议把这个处理流程封装成独立的Python模块，统一处理所有模型的生成请求。我早期就是直接拼接代码来执行，结果某个异常脚本把整个进程搞崩溃了，从那以后就老老实实做了隔离。

4.4 从模型到文件：导出多种格式并完成质量校验

生成的模型最终要导出为通用格式才能交付。CadQuery的导出API很简洁：

result.export("part.step") result.export("part.stl")

STEP格式保留了精确的几何信息和拓扑关系，适合后续在专业CAD软件中继续编辑；STL格式是三角网格，适合3D打印和可视化，但精度有损失。量产场景通常两种都导。

导出之后的质检环节千万别省。我一般会用三个维度检查：

• 几何完整性：模型是否封闭？有没有破面、零厚度区域？用网格检查工具跑一下。
• 尺寸一致性：和提示词里的关键尺寸对不对得上？写个脚本自动比对。
• 可制造性：有没有倒扣、悬垂角度过大、壁厚过薄之类的问题？这取决于目标工艺，但至少要做基础检查。

质检通过后，模型才算真正"能用"。

4.5 实操案例：生成一个带安装孔的外壳底座

最后用一个完整案例把流程串起来。需求描述是"生成一个100x80x30mm的外壳底座，底部四个角有安装孔，顶面有矩形开口，侧壁厚度3mm"。

我用的提示词是：

生成CadQuery脚本：一个100x80x30mm的长方体，壁厚3mm，内部掏空（保留底面）；底面四个角各有直径5mm的通孔，孔心距相邻边缘8mm；顶面中央开一个60x40mm的矩形开口；所有外部垂直边做2mm圆角。

模型生成的第一版脚本有两个问题：矩形开口直接贯穿了整个顶面导致顶部结构被分成两半，以及圆角半径过大导致壁厚处出现几何退化。我把问题反馈给模型，追加了约束描述"矩形开口深度只到内腔顶面，不触及外壁"以及"圆角半径不得超过壁厚的2/3"，第二次生成的结果就对了。

整个过程的经验价值在于：不要指望一次生成完美结果，人和模型之间的多轮交互才是成熟用法。模型生成能力的边界可以通过补充描述和反馈来持续逼近，这个"对话式调试"的流程本身就是text-to-cad区别于传统脚本生成的最大价值。

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

5.1 问题速查表：从失败现象到解决方案

这里把实操中最高频的问题整理成速查表，每一行都是实测验证过的。

5.2 模型输出"看着对但实际用不了"的三种典型情况

比完全失败的生成更棘手的是那种表面看起来正常、实际没法用的模型。

第一种是布尔运算残留。模型要对实体做挖孔或切除操作，但生成时写错了操作顺序，导致结果里留下了独立的悬浮片体。这种问题在视觉上不容易发现，但导出STEP后其他软件打开会报错。排查方法是逐个检查模型的体、面、边数量，有异常就回查布尔操作序列。

第二种是约束缺失导致的松散几何。代码跑通了，几何也出来了，但是关键尺寸之间的联动关系没建立。比如孔的位置是靠绝对坐标指定的，而不是通过约束关系关联到底板尺寸的。这种模型在后续调整尺寸时表现极差——你改了底板长度，孔的位置不会跟着动，装配时就全偏了。需要检查生成代码中是否使用了约束语言或参数引用。

第三种是圆角/倒角导致的拓扑退化。当圆角半径大于壁厚或相邻特征间距时，几何内核可能产生自交面，轻则出现异常扭曲，重则直接生成失败。这个问题尤其隐蔽，因为失败的脚本看似忠实地执行了用户的描述，只是用户描述本身就超出了几何合理性边界。我的建议是生成后加一道自动检查，专门验证圆角半径与相邻特征尺寸的关系。

5.3 我的排查三板斧：日志、可视化、逐步回退

碰到棘手的生成失败时，我有一套固定的排查流程。

第一板斧是看日志。CadQuery和其他几何内核在报错时通常会给出明确的操作信息和位置，先看日志能排除80%的简单问题，比如某个操作引用了不存在的边。

第二板斧是逐步可视化。去掉脚本中影响执行的后半段，把模型生成拆分成多个阶段，每跑完一个阶段就把中间几何体输出一份预览。这样能精确定位是哪个特征引入的错误。举个例子，如果模型生成到"拉伸切除"那一步开始出问题，那就把切除前的几何单独跑一次，检查几何本体是否已经出现了异常。

第三板斧是简化回退。在调试无头绪时，把描述简化为只保留主几何体，确认基础生成没问题后，再逐步加回附加特征。这样做的逻辑很简单——如果基础几何和附加特征分开都正常，但合在一起就失败，那问题大概率出在特征交互上，比如两个切除区域重叠、圆角与孔位冲突等。

这三板斧组合使用，绝大多数生成问题都能在半小时内定位到根因。

5.4 避坑经验：关于尺寸单位、精度和功能性验证

最后一个避坑经验是围绕功能性验证的。很多text-to-cad生成的模型，外观和尺寸都看不出毛病，但放到真实场景里根本没法用。比如生成了一个带卡扣的外壳，卡扣的变形余量没考虑材料特性；或者生成了一个轴套，但公差配合完全没考虑。

现在text-to-cad工具本身不会替你做工程判断，所以用户必须保持"审慎验收"的心态。我的习惯是：每一批关键模型导出后，都至少做一次装配级检查或者工艺评审。哪怕只是把模型放进之前的装配体里看干涉，都比单纯看零件本身有价值得多。这套工序放在以前手工建模时代是顺理成章的，但text-to-cad的"生成感"太强，容易让人放松警惕，实际这个环节一步都不能省。

6. 经验总结与扩展方向参考

6.1 我对text-to-cad现阶段能力边界的一点体会

经过大量实测，我对text-to-cad的能力边界有了比较清醒的认识。一句话概括：它在单零件、结构化描述、参数明确的三类场景下表现可靠；在多零件装配、复杂曲面、隐含工程约束的三类场景下依然脆弱。

"可靠"的判断依据不是单次生成的成功率，而是多轮反馈后收敛到目标模型的迭代效率。我的实测结果表明，一个有经验的建模人员如果善于描述需求，通过text-to-cad生成一个中等复杂度的零件，总体上并不会比手工建模慢多少，而且在衍生变体方面效率高出一截。但如果你本身对CAD术语一窍不通，描述又模糊不清，那么生成效率的损失会抵消掉工具本身的全部优势。

工具是放大器，不是替代品。它会放大你描述需求的能力，但不会替代你理解需求的责任。这是我认为目前phase阶段使用者必须接受的基本前提。

6.2 可以继续深挖的方向

如果你已经掌握了基本流程，以下几个方向值得继续探索。

一是参数化族库的自动构建。用text-to-cad批量生成同一系列的参数化变体模型，整理成标准件库。这在机械设计场景中有直接的实用价值，比如标准法兰、轴承座、壳体等，自然语言描述配合参数扫描，能大幅扩充内部零件库的覆盖度。

二是与拓扑优化和仿真流程的对接。生成模型后直接导入仿真环境做结构分析，根据仿真结果再反馈优化提示词。这个闭环如果能跑通，本质上是把"设计-分析-优化"的传统流程变成了"描述-生成-分析-再描述"的循环，对研发效率的提升会非常可观。

三是多模态融合。有些需求单靠文字描述不清楚，比如"类似图片里的这个造型"。未来的text-to-cad自然会走向"图像+文字"的多模态输入，目前已经有一些实验性的工作，预计将进一步降低描述门槛。

四是专业领域的微调模型。通用模型对特定行业的术语理解往往不够精准，比如模具行业常说的"拔模斜度"、"分型面"，电子行业常用的"散热鳍片"、"EMI弹片"等。如果你所在领域有这类专业术语壁垒，针对性的微调模型会是持续积累的竞争壁垒。

根据我个人经验，动手做text-to-cad相关实践时，最好的方式不是一开始就追大模型、追高精度，而是先用开源工具搭一个最小闭环，跑通"描述到模型"的完整链路。那个阶段收获的直觉，远比直接调用一个商业API要来得扎实。后面随着你对提示词的掌控能力和交互调试方法越来越纯熟，再逐步引入更大的模型、更复杂的几何约束，迭代路径会非常平滑。