企业官网建设流程全解析

自然语言直接出模型，听着是不是有点像拿嘴画画？text-to-cad 这个项目确实就是这么干的——你给它一句“做一个法兰盘，外径80、内径40、厚10，均布4个直径6的安装孔”，它能在几分钟内给你产出一个带尺寸的三维实体模型，而且不是你想象的那种粗糙的 mesh 皮囊，而是真正能导进 CAD 软件继续编辑的参数化实体。它在 GitHub 上拿了 15K 星，在 CAD 这个相对垂直的赛道里已经算是现象级了。

我连着测试了两个星期，踩了不少坑，也摸清了它什么时候靠谱、什么时候翻车，这篇东西就是我的完整使用报告。不管你是做机械结构、搞 3D 打印，还是单纯对 AI Agent 这个方向感兴趣，这篇文章应该都能给你省下不少时间。

1. text-to-cad 项目概览

1.1 它到底是什么

先把这个项目拆开看。text-to-cad 的核心目标很简单：把“自然语言描述”转成“可用于工程的三维模型”。这和市面上常见的 text-to-3D 不是一回事。那些项目通常生成的是网格模型（比如 obj、glb 文件），适合做游戏资产、影视预览，但没法直接用，因为网格模型没有厚度、尺寸不可控、也不能参数化修改。text-to-cad 走的是另一条路，它直接产出程序化建模脚本，再从脚本生成真正的实体模型。

我自己的理解是，它其实是一个套了 Agent 外壳的 CAD 编程助手。从拿到文本提示词到最终输出模型，中间经历了 LLM 推理、代码生成、自动执行、反馈修正等多个环节，这也是为什么标题里叫它“Agent CAD 工具箱”——它不是单次生成的死流程，而是带反馈循环的活流程。

实际使用下来，它能处理的类型比较集中：机械零件、连接件、标准件、简单外壳、几何组合体，这些效果都不错。但如果你让它生成一个带有复杂曲面造型的消费电子产品外壳，它基本会翻车，这不是项目不好，而是当前这类工具的能力边界就在那儿。

1.2 为什么能在开源社区拿到 15K 星

CAD 这个领域相当垂直，能拿到 15K 星说明它确实戳中了一大波人的刚需。我分析下来，核心原因有三个。

第一，传统 CAD 建模门槛高。会画图的人和不会画图的人之间有一道很高的墙，而“用嘴描述一个零件”天然适合降低这道门槛。第二，程序员背景的工程师特别吃这一套。很多做硬件、做创客、做开源硬件的人，建模能力一般但写代码很溜，text-to-cad 把“建模”变成了“写提示词 + 改代码”，这完全踩中了他们的舒适区。第三，它没有停留在 demo 阶段，而是真的能输出 STEP、STL、DXF 这类工业格式，可以直接对接 3D 打印和加工流程，实用性足够了。

另外一个不能忽略的因素是，Agent 这个方向本身正处于风口期。一个把 LLM Agent 和 CAD 这种硬核工具结合起来的开源项目，天然会被推到聚光灯下。它拿到了流量红利，而流量又吸引了更多人提交 issue、贡献代码、优化提示词工程，形成了正向循环。

2. Agent CAD 的技术选型与架构思考

2.1 从自然语言到参数化模型的关键链路

要理解 text-to-cad 是怎么工作的，得先理解一个核心分岔点：生成几何体到底有几条路可以走。

路线一是让模型直接输出三角网格顶点，这是很多 text-to-3D 项目用的方案。它的好处是自由度高，能表达复杂曲面，坏处是精度低、不可编辑、容易产生非流形几何，在工程场景里基本不可用。路线二是让模型生成参数化建模脚本，也就是用 CadQuery、OpenSCAD 这类程序化建模语言写代码，再通过脚本生成实体模型。text-to-cad 走的显然是第二条路。

这个选择非常聪明。你看，LLM 写代码这件事现在已经比较成熟了，而 CadQuery 这类库的语法又相对稳定、可预测，模型在训练时看过大量相关代码，生成的脚本只要语法正确、逻辑基本合理，执行出来就是一个符合尺寸约束的实体模型。比起直接生成几何，让模型“写代码”的容错空间大得多，而且输出结果天然就是参数化的，用户可以随时改尺寸、改约束重新生成。

整个链路大致是这样：用户输入自然语言 → Agent 把需求拆解为建模步骤 → 生成对应的参数化脚本 → 执行脚本得到实体模型 → 渲染预览并检查几何有效性 → 如果失败或不符合要求，Agent 根据错误信息自动修正，再跑一轮，直到成功或达到最大迭代次数。

2.2 Agent 循环的核心设计

我之所以说这是一个 Agent 框架而不是一个简单的模型接口，关键在于它的循环结构。单次生成在复杂任务里基本没法用，大模型写代码免不了出错，可能是 API 用错、尺寸计算错误，也可能是 r 角顺序不对。text-to-cad 的做法是把“执行结果”反馈给模型，让模型自己看报错信息、自己改代码。

这个机制非常像真人工程师的工作方式。我画图的时候也是先出一个版本，然后看哪里干涉、哪里倒角不对，再改再试。Agent 只是把这个“试错-修正”过程自动化了。当然，这也意味着它比单次生成的工具慢，因为每次迭代都要调用一次模型推理，复杂零件跑十几轮是常有的事。

几何校验也是循环里的关键环节。模型生成完脚本、执行出实体后，系统还要检查这个实体是不是有效的流形，有没有开面、有没有零厚度、布尔运算有没有产生退化几何。这一步相当重要，因为很多 LLM 生成的代码能跑通，但几何上其实是个坏体，直接拿去切片或加工会出问题。

2.3 为什么选用程序化建模后端

从我实际用下来的体会看，选择一个好的后端是这类项目成败的决定性因素。text-to-cad 这类 Agent 工具箱，输出结果的“可编辑性”比“自动化程度”更重要，因为没有一个模型能一次就生成完美结果，用户几乎必然要二次修改。

如果后端选的是网格模型，那用户拿到手之后基本只能干瞪眼。网格模型改一个孔的位置，需要手动操作网格顶点，这在工程软件里非常痛苦。但如果后端是 CadQuery 这类程序化建模库，情况完全不一样——孔的位置就是代码里一个坐标和一个半径，改起来跟改配置一样简单，重新生成一下就是新模型。

另外，参数化建模后端的兼容性也更好。CadQuery 可以导出 STEP 格式，这是几乎所有主流 CAD 软件都能打开的通用交换格式；OpenSCAD 可以导出 DXF 做激光切割；STL 直接喂给 3D 打印机。我在测试过程中，最常用的流程就是让 text-to-cad 生成 CadQuery 脚本，然后导出 STEP 文件，再拖进 FreeCAD 或者 SolidWorks 继续做配合和装配，这个链路非常顺。

3. 部署安装与运行环境准备

3.1 基础环境与依赖安装

先说结论：在自己机器上跑 text-to-cad 并没有想象中那么复杂，但有几个坑是绕不过去的，提前知道能省很多时间。

第一步还是老规矩，把仓库拉下来。项目通常依赖 Python 3.9 到 3.11 之间，我不建议用最新的 Python 3.12 或 3.13，因为 CadQuery 这类底层库对 Python 版本的跟进经常滞后，容易碰到编译错误或者依赖装不上的情况。实际踩坑经历是，我一开始用 Python 3.12 装依赖，OCC 相关组件直接编译失败，换成 3.10 就很顺利。

git clone https://github.com/xxx/text-to-cad.git cd text-to-cad python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install -r requirements.txt

安装过程比较久，因为核心依赖里包含 OpenCascade 这样的几何内核，光这一个包就要下载几百 MB。这个阶段最考验网络和耐心，多等一会儿就好，不用反复中断重试。看到 pip 把依赖全部解析完并且没有报冲突，基本上就成功一大半了。

3.2 模型推理方案怎么选

依赖装好之后，还要选一个 LLM 推理后端。text-to-cad 本身是一个 Agent 框架，它需要调用一个大语言模型来干活。我在测试中用过的方案大致有两种，各有利弊。

第一种是本地模型方案。好处是免费、数据不出机器、可以反复调试跑很多轮，坏处是显存要求高。普通 7B 量级的模型跑这种长上下文代码生成任务，至少要 12GB 显存才比较流畅；如果用量化后的 4bit 版本，8GB 显存的卡也能勉强跑起来，但速度不太乐观，一个简单零件可能要等好几分钟。如果你的显卡不够，又不愿意花钱调 API，那体验会比较煎熬。

第二种是云端 API 方案。这个方案基本不挑机器，只要能发 HTTP 请求就行，速度也快，但每跑一次要花钱。text-to-cad 的本质是迭代式的 Agent，不是一次性请求，一个零件动辄调用十几轮模型推理，所以 API 费用会随着任务复杂度快速上涨。我的建议是：先拿本地小模型跑通流程，理解清楚整个工具链，再切换到云端大模型处理真正复杂的零件。

无论选哪条路，配置方式都比较统一，通常在项目的配置文件或者环境变量里填入模型的 endpoint、api key、模型名称，框架会自己拉取模型并处理推理请求。

4. 实操：从一句描述到可加工的三维模型

4.1 跑通最小示例

我建议你第一次测试不要太贪心，选一个特别简单的零件，比如 M8 六角螺栓、矩形垫片、或者带圆角的法兰盘。拿法兰盘举例，这是我测试时用的第一句提示词：

创建一个法兰盘，外径80毫米，内径40毫米，厚度10毫米， 在直径60毫米的分度圆上均匀分布4个直径6毫米的安装孔。

整个生成过程我观察下来大致分三个阶段。第一阶段是规划，Agent 会把这句需求拆成几个建模动作：先画外圆拉伸成圆柱，再挖内孔，再定位安装孔，最后打孔。第二阶段是代码生成，模型根据规划写出 CadQuery 脚本，这个阶段可以在输出面板里看到完整的 Python 代码。第三阶段是执行与导出，框架自动运行脚本，把结果保存成 STEP 和 STL 文件，同时渲染一张预览图。

我第一次跑通的时候，生成出来的法兰盘尺寸完全正确，孔位也准确落在分度圆上，那一刻确实有点颠覆认知。不过要泼一盆冷水，简单零件效果惊艳不代表复杂任务也能一次过，后面我会细说。

4.2 控制尺寸与精度的几个技巧

自然语言转 CAD 最痛苦的问题就是尺寸精度。人类语言天然是模糊的，“大一点”“厚一些”“差不多就行”这类词，模型根本没法把握。我在反复测试中总结出一个特别有效的技巧：提示词里必须用明确的数值加单位，而且最好把单位统一成毫米。

下面是几个实测效果很不错的提示词写法：

• 明确给出外径、内径、厚度、孔数、孔径等全部关键尺寸，不留模糊量。
• 需要圆周分布时，直接说“在直径XX的圆上均布N个孔”，模型能精准理解分度圆概念。
• 涉及倒角圆角时，给出具体半径值，例如“所有外边缘倒圆角R2”。
• 需要阵列时，说“沿X方向阵列5个，间距20毫米”，比“一排几个”要可靠得多。

另外一个很实用的工作流是“先出大形，再出细节”。不要妄想让模型一步到位生成一个完整零件，正确做法是分两步、三步来：第一轮只给整体尺寸和基本外形，让 Agent 先跑通；第二轮再说“在外表面增加安装凸台”“在四角增加直径6的沉头孔”这种增量修改，模型基于已有代码继续迭代，成功率会高很多。

4.3 导出格式与二次编辑

text-to-cad 最让我满意的部分是导出格式非常贴近实际工程需求。默认情况下它会同时导出 STEP 和 STL 两种格式，STEP 用于 CAD 软件交换，STL 用于 3D 打印，这个设计很贴心。

实际测试中，我把生成的 STEP 文件导入 FreeCAD，几何特征是完整的，可以继续做配合约束、装配、工程图。我还试过把同一份 STEP 文件丢进 SolidWorks，同样没有问题。这种格式兼容性在开源项目里很难得，很多工具能导出 STL 就算不错了，支持 STEP 说明项目方是真的懂工程设计需求。

如果项目默认没有开启某种格式的导出，你也可以在 CadQuery 脚本里手动加一行，比如把模型导出成 DXF 用来做激光切割：

import cadquery as cq result = ( cq.Workplane("XY") .circle(80 / 2) .extrude(10) .faces(">Z") .workplane() .circle(40 / 2) .cutThruAll() .faces(">Z") .workplane() .rect(60, 60, forConstruction=True) .vertices() .hole(6) ) cq.exporters.export(result, "flange.step") cq.exporters.export(result, "flange.stl")

拿到脚本之后，你可以像改普通 Python 代码一样改尺寸、改特征，改完重新执行，新模型马上就能出来。这种自由度是纯图形化软件给不了的，也是我喜欢这个工具链的原因。

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

5.1 生成结果不稳定、脚本频繁报错

我在连续测试中遇到的第一个问题就是生成结果不稳定。同一个提示词，连续跑三次，可能第一次成功、第二次孔位乱掉、第三次直接脚本报错。这其实不是 text-to-cad 项目本身的问题，而是底层 LLM 的随机性导致的。

解决思路有两个方向。一是把温度参数调低，让模型输出更保守、更可预测，代价是会损失一点表达灵活性；二是在提示词层面做约束，把关键数值和建模步骤写得更明确。我的实际感受是，温度调到 0.2 左右，在“稳定性”和“灵活性”之间算是一个比较舒服的平衡点。

脚本报错的时候不要急着重新开始，先看报错信息。Agent 本身有自动纠错机制，它会自己读取报错、修改代码再来一轮，大多数情况下几轮之后就能跑通。如果连续五六轮都在同一个地方翻车，说明思路从一开始就偏了，这时候最有效的做法不是继续让 Agent 死磕，而是换一种描述方式重新输入需求，用词更接近 CadQuery 的建模逻辑，成功率会明显上升。

5.2 尺寸精度不够怎么办

尺寸精度是这类工具最容易暴露短板的地方。自然语言描述哪怕包含了数值，模型在计算坐标、圆角位置、阵列间距时仍然可能犯错。我测过一个矩形法兰，提示词里明确写了“四角各一个直径6的孔”，结果四个孔里有一个偏差了 0.8 毫米。对于一般的 3D 打印件 0.8 毫米可能不算什么，但对于需要过盈配合的零件来说，这足以导致装配失败。

我的建议是：一定不要把 text-to-cad 的输出当成最终图纸，它的定位是概念设计和初步模型生成器。拿到生成的参数化脚本之后，花五分钟检查一遍关键尺寸和位置关系，然后再导出加工。如果你用的是 CadQuery 后端，直接在脚本里改数值就行，不用重新生成，这么一操作，精度完全掌握在自己手里。

5.3 中文输入和本地模型性能问题

中文输入方面，用云端 API 基本没什么问题，主流模型的中文理解和中文单位提取能力都够用。但如果你在本地跑小参数模型，中文能力可能不太稳定，尤其涉及“直径”“均布”“分度圆”这类专业术语时，模型可能理解偏。

我测试时发现一个规律：整体提示词用中文没问题，但关键的建模参数最好单独列出，比如“外径=80mm / 内径=40mm / 厚度=10mm”，这种结构化写法无论中英文都能被模型稳定解析。

性能方面，本地推理的瓶颈主要在显存和推理速度。我的建议是关闭预览渲染的实时显示，等所有迭代完成再看结果；另外尽量缩短提示词中的冗余描述，减少上下文长度也能降低每次推理的耗时。如果你的卡只有 8GB 显存，建议直接用 API 方案，省时也省心。

6. 扩展玩法：把 text-to-cad 接进自己的工具链

6.1 批量生成标准件

用自然语言一个个生成零件已经不错了，但我觉得 text-to-cad 的真正威力在于配合脚本做批量生成。你可以在生成的 CadQuery 代码基础上，套一层 Python 循环，把关键参数变成变量，一次跑出几十个规格的螺栓、垫片、法兰或者支架。

举个例子，我需要一端带法兰的轴套，规格从直径 10 到 50 每隔 5 一种，手工建模要做一个小时，用参数化脚本只需要写一个循环：

import cadquery as cq for diameter in range(10, 51, 5): result = ( cq.Workplane("XY") .circle(diameter / 2) .extrude(20) .faces(">Z") .circle(6) .cutThruAll() ) cq.exporters.export(result, f"bushing_{diameter}mm.step")

这个思路再往前一步，就是建立自己的标准件库。每次让 text-to-cad 生成一个新零件，我都把最终的脚本按零件类型归档，下次遇到相似需求直接在脚本库里改参数，完全不需要再让模型重新生成。

6.2 与已有设计流程配合的几种思路

如果你平时不用 CadQuery 而是用 FreeCAD 或者商业 CAD 软件，text-to-cad 也能融入工作流中。我目前用得最顺的模式是“概念阶段用 text-to-cad 快速出方案，确定方向后再进入正式 CAD 软件细化”。以前接一个定制零件需求，我得先花半小时建个初步模型给客户确认，现在用 text-to-cad 几分钟就能出一个带真实尺寸的 STEP 文件，效率提升非常明显。

还可以把它当成学习工具。对于刚学 CAD 建模的新手来说，看 text-to-cad 怎么把一句描述翻译成建模代码，能直观理解一个零件在参数化建模里是怎么分解成拉伸、切割、阵列这些操作的。我看过几个初学者用这个项目入门 CadQuery，上手速度比啃教材快不少。

另外，如果你做机械臂、机器人底盘这类开源硬件项目，text-to-cad 生成的参数化脚本可以直接嵌进你的开源仓库里，用户改几个尺寸就能适配自己买的型材和电机，这是纯静态模型文件做不到的灵活性。

我自己这两周用下来，最大的感受是：text-to-cad 这类工具不是来替代 CAD 工程师的，它替代的是“从需求到初步建模”这段重复劳动。以前画一个标准法兰，从查手册到建完模型再检查尺寸，再怎么快也得十几分钟，现在一个自然语言描述加上几次迭代修正，几分钟就能拿到可以用的 STEP 文件，这个效率提升是实打实的。

当然，它现在还有很多明显的问题——复杂曲面基本没法处理，尺寸一致性还要靠人把最后一道关，Agent 迭代过程的耗时也比较长。但作为 15K 星的项目，它已经证明了“用嘴建模”这个方向是可行的，而且后续社区只要持续优化提示词库、丰富后端支持，这个工具链会越来越靠谱。如果你也在做硬件、做 3D 打印、做开源机械设计，我建议现在就把它装起来试一下，重点试的是那个“迭代修正”的 Agent 流程，真的能带来不少启发。