1. 从一段文字到三维模型：text-to-cad 到底在解决什么问题
第一次听到 text-to-cad 这个词，我的反应和大多数人一样：输入一句话，电脑就能吐出一个能直接加工或渲染的三维模型？这听起来像是把设计师从重复劳动里解放出来的关键一步。实际接触下来，它并不是什么魔法，而是一套把自然语言描述翻译成参数化几何指令、再驱动 CAD 内核生成实体或网格的完整链路。核心关键词 text-to-cad、CAD、STEP、GLB、STL 贯穿始终，理解它们之间的关系，比急着跑通某个工具重要得多。
简单说，text-to-cad 要解决的是“描述即建模”的问题。传统流程里，你脑子里有一个零件的样子，得先打开 CAD 软件，画草图、拉伸、倒角、打孔，一步步把想法变成几何体。这个过程对熟练工程师来说也要几分钟到几十分钟，对不熟悉 CAD 的人来说更是门槛。text-to-cad 试图把这段操作压缩成一句结构化的描述，比如“一个 80mm 长、40mm 宽、10mm 厚的法兰盘，四角各有一个直径 6mm 的通孔，中心有一个直径 30mm 的沉孔”，然后由系统解析语义、生成几何、导出成 STEP 或 STL 这类通用格式。
它适合谁？我观察下来有三类人最需要：一是做机械设计或产品结构的工程师，想快速验证一个初步构型，不想在建模上耗太多时间；二是做 3D 打印或手办模型的玩家，手里只有文字描述或参考图，需要快速得到可打印的 STL；三是做软件集成或自动化流程的开发者，想把建模能力嵌到自己的系统里，比如根据订单参数自动生成零件模型。这三类人的需求层次不同，但都指向同一个核心：把“语言”变成“几何”。
这里必须先把几个格式的关系讲清楚，不然后面实操会乱。CAD 是计算机辅助设计的统称，它既指软件也指整个工作方式。STEP 是面向实体的交换格式，保留完整的边界表示和拓扑关系，适合在专业 CAD 软件之间传递，后续还能继续参数化编辑。STL 是三角网格格式，只记录表面三角形的顶点和法线，没有特征信息，但几乎所有 3D 打印机和切片软件都认它。GLB 是 glTF 的二进制版本，主打轻量和实时渲染，适合在网页或移动端展示模型。text-to-cad 的输出通常要同时覆盖这三类：STEP 给工程用，STL 给打印用，GLB 给展示用。
我踩过的第一个坑就是以为所有 text-to-cad 工具都能直接输出 STEP。实际上很多方案底层是网格生成，只能吐 STL 或 OBJ，想要 STEP 还得走一步“网格转实体”的逆向操作，而这一步在复杂模型上经常丢特征、破面。所以选方案之前，先问清楚它的几何内核是什么，是直接构造边界表示，还是先网格后转换。这个区别决定了你拿到的模型能不能继续编辑，也决定了整个流程的上限。
2. 整体方案怎么搭：从语义解析到几何生成的完整链路
2.1 为什么不能只靠一个大模型硬生成
很多人第一反应是找一个多模态大模型，把文字丢进去让它直接输出模型文件。我试过几条路线，结论是：纯端到端生成在简单形状上能看，稍微复杂一点就崩。原因在于三维几何有严格的拓扑约束，顶点、边、面之间的关系不能随便编，而语言模型擅长的是概率性文本生成，它不理解“这个孔必须完全贯穿这个面”意味着什么。所以靠谱的 text-to-cad 方案一定是分层的：语言层负责理解意图，几何层负责保证合法性，中间用结构化的中间表示来衔接。
这个中间表示我习惯叫它“建模指令序列”或“参数化草图描述”。它不直接是几何，而是一组可执行的建模操作，比如创建草图平面、绘制矩形、标注尺寸、拉伸指定深度、在指定位置打孔。这样做的好处是每一步都可验证、可回退，而且能直接映射到 CAD 内核的 API。语言模型只需要把自然语言翻译成这组指令，剩下的交给确定性的几何引擎去执行。指令序列可以用 JSON 或类似 DSL 来描述，结构清晰，调试也方便。
2.2 几何内核的选择直接决定输出能力
几何内核是 text-to-cad 的心脏。目前主流的选择分两派：一派是专业 CAD 内核，比如 OpenCASCADE、Parasolid、ACIS，它们天生支持边界表示，能直接构造实体并导出 STEP；另一派是网格生成库，比如基于 OpenGL 或 Three.js 的三角化方案，输出快但只有 STL 或 GLB。如果你需要 STEP，就必须走第一派。OpenCASCADE 是开源方案里最成熟的一个，社区活跃，Python 绑定也有，适合个人和小团队起步。
我选 OpenCASCADE 的理由很实际：它能保证导出的 STEP 是真正的实体，面与面之间的缝合关系正确，后续在 SolidWorks、中望 CAD 这类软件里打开不会报错。而网格方案生成的 STL 虽然打印能用，但一旦你想在 CAD 里改个孔位，就会发现整个模型是一堆散三角形，根本没法选中特征。所以如果你的目标是“生成可继续编辑的工程模型”，内核这一层不能省。代价是 OpenCASCADE 的学习曲线偏陡，布尔运算偶尔会失败，需要花时间调参和做容错。
2.3 输出格式的转换策略与取舍
输出环节我建议做成“一次生成，多格式导出”。核心实体在内存里用边界表示维护，导出 STEP 时直接写 B-Rep 数据；导出 STL 时对实体做三角化，控制好弦高和角度容差，保证网格密度够用又不过大；导出 GLB 时把三角网格加上材质和法线，压缩成二进制。这里的关键参数是三角化精度：弦高设得太小，STL 文件会巨大，切片慢；设得太大，曲面会变成明显的多边形，打印出来有棱角。我一般对普通零件用 0.05mm 弦高、15 度角度容差，对曲面要求高的模型再收紧到 0.01mm。
还有一个容易被忽略的点是坐标系和单位。text-to-cad 生成的模型必须明确单位是毫米还是米，原点在哪里，Z 轴朝上还是朝前。我见过太多案例，模型本身没问题，但导入切片软件后发现尺寸差了一千倍，或者躺倒在地上。所以从指令序列开始就要把单位和朝向固定下来，导出时再做一次校验。STEP 文件头里会写单位，STL 没有单位概念，只能靠约定，GLB 则用米做默认单位，转换时要乘系数。
3. 核心细节拆解：语义解析、参数提取与几何构造
3.1 自然语言到结构化指令的映射规则
把一句话变成建模指令，难点不在分词，而在消歧和补全。比如“一个带孔的板”，孔在哪、多大、几个，都没说。合格的 text-to-cad 系统不能瞎猜，而应该有一套默认规则加追问机制。我的做法是定义一套“最小可建模描述”模板，包含形状类型、主要尺寸、特征列表、位置约束四类信息。语言模型的任务是把用户输入往这个模板上靠，缺失的字段用合理默认值填充，同时在结果里标注哪些是推断的，方便用户复核。
具体映射时，我会把常见表达做成规则表。比如“长 80 宽 40 厚 10”映射到长方体的三个维度，“四角各一个直径 6 的通孔”映射到在四个角点位置创建圆柱并做布尔减运算，“中心沉孔直径 30 深 5”映射到在中心位置先打一个直径 30 的通孔再扩一个深度 5 的台阶。这些规则不需要大模型，用正则加关键词匹配就能覆盖大部分场景，大模型只在描述特别口语化或复杂时兜底。这样做的原因是规则部分确定性高、速度快、可测试，大模型部分灵活但不可控，两者结合才稳。
3.2 参数提取中的单位换算与容差处理
参数提取最怕单位混乱。用户可能说“8 厘米”，也可能说“80mm”，还可能只说“80”而不带单位。我的处理策略是：优先识别显式单位，厘米乘 10、米乘 1000、英寸乘 25.4，统一转成毫米；没有单位时，根据数值范围推断，比如数值在 1 到 500 之间默认按毫米，小于 1 的可能是米，大于 1000 的可能是微米，但推断结果要标记出来让用户确认。这个推断逻辑不完美，但比直接报错或默认成米要实用得多。
容差处理是另一个细节。几何运算里，两个面贴合时如果坐标有微小差异，布尔运算就可能失败。所以我在指令执行前会把所有尺寸量化到 0.001mm 的精度，坐标对齐到网格。比如孔的中心位置如果算出来是 39.9998，就归整到 40.000。这个操作看起来粗暴，但实际效果很好，能避免大量“面不闭合”的错误。代价是极端精密零件可能受影响，但 text-to-cad 的定位本来就是快速原型和初步设计，这个精度足够。
3.3 几何构造的顺序与布尔运算避坑
几何构造的顺序很讲究。我的经验是：先做主体形状，再做减运算特征，最后做倒角和圆角。原因是倒角和圆角对拓扑变化最敏感，如果先倒角再打孔，孔可能会切掉倒角面，导致后续运算失败。先打孔再倒角，倒角能顺着孔的边缘走，结果更自然。布尔减运算也要注意顺序，多个孔最好一次性合并成一个工具体再减，而不是逐个减，这样能减少中间状态的复杂度，降低失败概率。
布尔运算失败是 OpenCASCADE 用户的常见痛点。我遇到最多的情况是工具体和目标体在某处恰好共面，或者工具体完全在目标体内部但边界接触。解决办法有几个：一是给工具体加一个微小的偏移，比如把孔的深度多切 0.01mm，保证完全贯穿；二是把工具体稍微放大，比如直径多 0.001mm，避免共面；三是在布尔运算前做一次“胶合”操作，把相邻面合并。这些技巧在官方文档里不会写，但实际项目里能省下大量调试时间。
4. 实操过程：从零搭一个可用的 text-to-cad 流程
4.1 环境准备与依赖安装
我用的技术栈是 Python 加 OpenCASCADE 的 Python 绑定，也就是 pythonocc-core。安装方式看系统，Linux 下用 conda 最省事，一条命令就能把依赖装齐；Windows 下稍微麻烦，需要先装 conda 再装 pythonocc-core，注意版本匹配，Python 3.9 到 3.11 比较稳。装完之后跑一个简单测试，创建一个立方体并导出 STEP，能成功就说明环境没问题。这一步我建议不要跳过，因为后面所有操作都依赖这个内核，环境有问题越早发现越好。
除了几何内核，还需要一个语言解析层。我一开始用正则加规则，后来发现复杂描述处理不过来，就加了一个轻量语言模型做兜底。模型不需要太大，能在本地跑就行，重点是把它约束在“输出结构化 JSON”这个任务上，而不是让它自由发挥。提示词里要明确字段名、单位、默认值，并要求它只输出 JSON，不要解释。这样解析成功率能到九成以上，剩下的边角案例再手动补规则。
4.2 指令序列的设计与执行
指令序列我用 JSON 数组表示，每个元素是一个操作对象，包含操作类型和参数。比如创建长方体是{"op": "box", "length": 80, "width": 40, "height": 10}，打孔是{"op": "hole", "diameter": 6, "depth": "through", "positions": [[5,5],[75,5],[5,35],[75,35]]}。执行器按顺序读取操作，调用 OpenCASCADE 的 API 逐步构造。这样做的好处是序列可以存下来、可以回放、可以手动改，调试时把中间结果导出看一眼就知道哪步出了问题。
执行器里我加了两个保护机制。一是每步操作后检查当前实体的有效性，如果无效就回滚到上一步并报错，避免错误累积。二是对布尔运算做重试，第一次失败后自动给工具体加微小偏移再试，还失败就换一种构造方式，比如用扫掠代替拉伸。这两个机制让整个流程的鲁棒性提升很多，用户输入稍微不规范也不至于直接崩掉。
4.3 多格式导出的参数配置
导出 STEP 时，我用的接口是STEPControl_Writer，设置单位毫米，写入实体。注意要先把实体从 AIS 显示对象转成 TopoDS_Shape，否则写出来是空的。导出 STL 时用StlAPI_Writer，关键是设置SetDeflection控制弦高，我一般设 0.05，复杂曲面设 0.01。导出 GLB 需要先把实体三角化，再用 trimesh 或 pygltflib 打包，加上法线和简单材质。三个导出可以并行做，互不影响。
导出后一定要做校验。STEP 用STEPControl_Reader读回来，检查实体数量和体积是否和原模型一致；STL 用 trimesh 读回来，检查是否水密、法线是否朝外；GLB 用在线查看器或本地渲染看一眼，确认没有破面和黑块。这个校验步骤看起来多余，但实际能拦住很多导出参数错误。我有一次弦高设成了 5，STL 出来是个多面体，校验时体积差了百分之十几，一眼就看出来了。
5. 常见问题与排查技巧实录
5.1 布尔运算失败与面修复
布尔运算失败是最高频的问题。表现是执行减运算后实体消失、报错，或者结果面数异常。排查思路是先把工具体和目标体分别导出 STL 看一眼，确认两者位置关系是否正确。如果位置对但运算失败，大概率是共面或微小间隙。解决办法前面提过，加偏移或放大工具体。还有一种情况是目标体本身有自交或破面，这种要先做修复，用ShapeFix_Shape跑一遍，把面缝合、边合并，再运算。
我整理了一个速查表，遇到问题按顺序排查：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 布尔减后实体消失 | 工具体完全包含目标体或方向反了 | 检查工具体尺寸和位置，确认减运算方向 |
| 报错“面不闭合” | 目标体有破面或自交 | 用 ShapeFix_Shape 修复后再运算 |
| 结果面数暴增 | 共面导致产生大量碎面 | 给工具体加 0.001mm 偏移，避免共面 |
| 孔没打穿 | 工具体深度不够或位置偏了 | 深度设为“through”或加大到超过实体厚度 |
| 倒角失败 | 倒角半径大于相邻面尺寸 | 减小倒角半径，或调整倒角顺序 |
5.2 导出文件在目标软件里打不开或显示异常
STEP 在 CAD 软件里打不开，常见原因是单位不对或实体无效。先确认导出时单位设的是毫米，再用BRepCheck_Analyzer检查实体有效性。如果实体有效但软件还是报错，可能是 STEP 版本兼容问题，试试导出 AP214 而不是 AP203。STL 在切片软件里显示异常，多半是法线朝内或网格不水密，用 trimesh 的fix_normals和fill_holes处理一下。GLB 在网页里显示黑块，检查材质和光照，或者把法线重新计算一遍。
还有一个坑是文件名和路径带中文或空格，某些软件读不了。我现在的习惯是导出时统一用英文加下划线命名，路径也避免中文。这个细节很小，但能省掉很多“为什么别人能打开我打不开”的困惑。
5.3 复杂描述解析失败的兜底策略
用户输入太复杂或太模糊时，解析会失败。我的兜底策略是分三步：第一步，让语言模型把描述拆成多个简单句子，逐句解析；第二步，对无法解析的部分，生成一个占位特征并标注“待确认”，而不是直接放弃；第三步，把解析结果和原始描述一起返回给用户，让用户确认或修改。这样即使不能一次到位，也能给出一个可继续编辑的中间结果，比直接报错体验好得多。
实测下来，大部分失败案例是因为描述里混了多个零件或装配关系。比如“一个底座上面有一个立柱，立柱顶端有个球”，这其实是三个实体加两个装配约束。我的处理方式是先按“和”“上面”“连接”这类词切分，识别出多个零件，分别生成后再用平移和旋转组装。装配关系用简单的坐标变换表示，不追求完整的约束求解，够用就行。
6. 一些实操心得与后续扩展方向
做 text-to-cad 这段时间，我最大的体会是：不要追求一步到位的全自动，而是把流程拆成可验证的小步，每步都留人工确认的口子。语言解析可以错，但几何生成必须对；几何生成可以慢，但导出必须稳。把确定性的事情交给代码，把不确定的事情交给模型加人工复核，整个系统才可靠。另一个心得是日志要详细，每一步的输入输出都记下来，出问题时能快速定位是哪一层出的错，而不是从头猜。
后续扩展我打算往两个方向走。一是加参考图输入，用户给一张草图或照片，系统提取轮廓和尺寸，再结合文字描述生成模型，这样对不会画图的人更友好。二是做参数化模板库，把常见零件类型做成模板，用户只需要填参数，系统直接实例化，速度和准确率都比纯生成高。这两个方向都不需要推翻现有架构，在指令序列层做扩展就行。如果你也在做类似的东西，建议先把 STEP 导出这条路走通，再考虑花哨的展示格式，因为工程可用性才是这类工具真正的价值所在。
