1. 项目概览text-to-cad 到底在解决什么问题先用一句话说清楚text-to-cad 是把自然语言描述直接转成可编辑三维 CAD 模型的开源工具。你输入一句带四个圆柱腿的圆角矩形桌面它就给你生成一个参数化建模的 STEP 文件拿过去就能开加工或者继续改。第一次看到这个项目标题时我其实先愣了几秒。做结构设计这些年CAD 建模一直是人肉驱动的活儿——画草图、拉特征、倒圆角、装配约束每一步都要手动点。哪怕是最熟练的工程师从想法到可用模型少说也要半小时。而这个项目text-to-cad直接把门槛砍掉一大截自然语言就是建模指令模型生成代码代码驱动 CAD 引擎最终落成真实可用的几何体。它适合谁如果你是做机械设计的、搞 3D 打印的、做产品原型验证的或者是刚接触参数化建模想试试水的新手这个项目都值得花一个下午跑一遍。对于普通用户它最大的价值不是替代你手搓模型而是把想法到雏形这段最耗时、最容易劝退的路程变得几乎无感。先说清楚一个大前提text-to-cad 不是像 DALL·E 那样直接画出 3D 模型也不是简单的文生图 模型重建。它的核心链路是LLM 语义解析 - 程序化建模代码 - CAD 引擎执行。也就是说它走的是程序化生成Procedural Modeling路线模型不是点云或网格而是一段可执行的建模脚本。这个技术选型非常关键后文我会专门拆开讲为什么这样设计是聪明的做法。2. 技术原理为什么选程序化建模这条笨路线2.1 不是生成网格而是生成建模步骤我最早看到的 text-to-cad 项目是在 Hugging Face 上发布的一个开源实现作者是 Zachary Evans。它的核心逻辑可以用一条链说明用户输入文本比如 a desk with 4 legs and a flat top - LLM 结合参考图像可选生成 CadQuery 代码 - CadQuery 引擎执行输出 STEP 文件。注意这里 LLM 输出的不是模型而是建模操作序列。CadQuery 是一种基于 Python 的参数化 CAD 建模块它用代码来描述几何特征——拉伸一个矩形、挖一个孔、倒一个圆角。text-to-cad 把语义理解和几何构建彻底拆开了LLM 只负责把自然语言翻译成建模意图真正的几何内核交给 CadQuery 处理。这个笨路线的好处我用一个类比说明。假设你要做一个木凳子方案 A 是 3D 扫描仪对着真凳子扫一圈得到点云再铺面方案 B 是拿到一张图纸按图纸一步步下料、组装。text-to-cad 走的是方案 B——它拿到的是一张可执行的图纸。这样生成的模型天然就是参数化的尺寸可以改、特征可以删、圆角可以调甚至可以批量生成一族相似模型。这在工程场景里是刚需你做完一个零件老板娘说尺寸放大 10%孔位右移 5 毫米方案 B 改一行参数就完事方案 A 就得重新扫描铺面想死的心都有。2.2 从文本到多视图渲染再到 CAD 代码的完整数据流text-to-cad 的前期训练数据准备很有参考价值。它先用 Zero-1-to-3 这个视角合成模型把模型库中的 3D 物体渲染成多视角图像再把文本描述 渲染图像喂给微调过的 LLM让它学会输出 CadQuery 代码。这一步相当于先教模型看图说话——看到某个形状的六个视角能用建模语言复述出它的几何结构。实际推理时有两套输入路径纯文本直接输入 A cylinder with a radius of 5mm and height 20mm模型直接输出代码。文本 参考图上传一张真实物体照片或手绘草图加上一句描述模型参考图像中的几何形态输出代码。第二种模式才是这个项目最杀人的功能。你拍一张桌子的照片说圆角的桌面四根圆柱腿它就能生成一个结构近似的参数化桌子。对于产品逆向、快速原型场景这个工作流几乎是一种作弊级别的效率提升——传统流程里你得先测绘再建模现在直接拍照 一句话就起步了。2.3 LLM 输出代码的容错设计这类项目的第一个灵魂拷问是LLM 生成的代码有 bug 怎么办CadQuery 脚本只要有一个参数类型不匹配整个构建就崩了。text-to-cad 在架构上做了一个很聪明的容错设计它会同时生成多份代码候选实际推理时默认生成 3 份每一份独立尝试执行只要有一份成功构建出实体模型就把它作为结果返回。这个多路并行 竞速的思路在工程上叫冗余容错实际效果非常明显——我试过连续生成十几个模型失败率大概只有两成左右而且大部分失败场景是 prompt 本身描述模糊比如说做一个好看的东西这种没法量化的输入。另外项目的推理脚本里还有一个conformation模块专门处理生成结果的自检。它会对输出的几何体做基础检查——体是否为流形、是否封闭、维度是否合理。不合格的代码直接淘汰不会进入最终输出。这个自检机制对下游加工至关重要一个非流形的网格文件进了切片软件轻则打印出废品重则把切片器干崩溃。3. 环境准备与快速启动从 GitHub 到第一个模型3.1 硬件与软件清单先交代一下我实际跑通的配置给大家一个参考基准操作系统Ubuntu 22.04Windows 用 WSL2 也可以但坑更多后面单说GPUNVIDIA RTX 3060 12GB其实 8GB 显存也够跑只是慢一点Python3.11PyTorch2.1.2 CUDA 12.1显存占用单次推理峰值约 7GB包括 Zero-1-to-3 图像编码和 LLM 推理如果你只有 CPU也不是不能跑就是慢。我在一台纯 CPU 的云服务器上试过单次推理耗时大约 8-12 分钟GPU 环境下只需要 40-60 秒。这个差距主要在 Zero-1-to-3 的图像编码器那是纯 CNN吃显存也吃算力。3.2 安装过程中的真实踩坑记录克隆仓库这一步没啥说的pip 安装依赖才是坑的开始。我建议严格按照 requirements.txt 来装不要自作主张升级包版本。尤其注意这几个包cadquery 最好用 2.1 以上版本太老版本对布尔运算的支持不行。openai 库的版本要匹配项目代码太新版 API 有 breaking change。torch 和 torchvision 的版本必须一致否则编译 CUDA 扩展时会炸。我最初图省事用了pip install -r requirements.txt一把梭结果 pyTorch 被装成了 CPU 版本跑起来慢到怀疑人生。后来重新用官方命令装 CUDA 版才正常。模型权重是另一个大坑。text-to-cad 依赖 Hugging Face 上的预训练权重项目默认是从 HF Hub 下载但国内网络环境下载大模型权重经常中断我是手动下载权重文件后放到本机缓存目录的。操作步骤是先查看~/.cache/huggingface/hub目录有没有残留文件有的话删掉再往models--zavant--text-to-cad这样的目录结构里手动放二进制文件。放完之后跑一次推理它会自动加载缓存里的文件不需要重新下载。3.3 跑通最小推理 Demo进到项目根目录创建一个最简单的 Python 脚本from text_to_cad import TextToCAD # 初始化模型 model TextToCAD() # 一句自然语言描述 prompt a rectangular table with four cylindrical legs # 生成结果 result model.generate(prompt) # 保存 STEP 文件 result.save(table_from_text.step)如果你走的是带参考图的模式需要先把图片转成 RGB 格式并缩放到 256x256 附近否则 Zero-1-to-3 的前处理会出问题。我第一次喂了一张 1200 万像素的照片进去跑了两分钟然后报了个尺寸不匹配的错误后来加了个预处理步骤才解决。跑通这个脚本之后你就拿到了第一份 text-to-cad 产出。用 FreeCAD 或者 CadQuery 自带的查看器打开 STEP 文件你会看到完整的实体模型。这个自然语言 - 真实可用三维模型的瞬间说实话比我想象中要有成就感得多。4. 核心实现细节与参数调优让生成结果更可控4.1 理解三个关键参数视点数量、候选数、温度text-to-cad 的推理接口里藏着几个直接影响输出质量的参数。我在实际测试中逐个调过记录如下参数名默认值作用我的调优建议num_images_per_prompt1每个 prompt 渲染多少视角图追求精度就调 4代价是推理时间翻几倍num_cad_sequences3生成多少份 CAD 候选代码保持默认太高没必要太低容错下降temperature0.2LLM 采样温度结构严谨类描述用 0.1-0.2创意探索类用 0.6-0.8这几个参数里temperature 对结果的影响最玄学。我在生成一个圆角矩形板这种明确几何时把温度调到 0.8结果模型输出了一段完全跑不通的代码CadQuery 直接报语法错误。后来把温度降回 0.1输出就稳定多了。经验是如果 prompt 描述非常具体低温更安全如果 prompt 只给了模糊意象比如现代风格的椅子适当高温反而能避开千篇一律的平庸结果。另一个容易被忽略的是 prompt 的措辞习惯。text-to-cad 的 LLM 在训练阶段见过大量measurement-based表达比如带数字的尺寸描述所以你的输入越像工程语言输出质量越高。我测试过几种说法a cup - 生成一个简单的圆柱杯a cylinder with radius 3cm and height 10cm - 生成精确的圆柱a large cup with a handle on the right side - 生成更复杂的异形杯第三种生成的杯把手实际是一个环形扫掠特征。这说明 LLM 对handle on the right side这类语义定位是能理解的但前提是几何形态本身在训练数据里出现过。冷门形态比如带三个环形凹槽的不规则十二面体模型大概率会给你生成一个莫名其妙的组合体。懂了这层你就知道 prompt 该往哪个方向写了交代结构、交代数量、交代相对位置不要指望它理解审美形容词。4.2 CadQuery 代码输出的常见模式text-to-cad 生成的 CadQuery 代码大多遵循一套固定语法。我截取一段典型的输出做了简化import cadquery as cq # 创建桌面 table_top ( cq.Workplane(XY) .box(60, 30, 2) # 长宽高 .edges(|Z) .fillet(2) # 桌边倒圆角 ) # 创建四条桌腿 leg cq.Workplane(XY).circle(1.5).extrude(25) leg_positions [ (25, 12), (25, -12), (-25, 12), (-25, -12) ] # 合并主体 result table_top for x, y in leg_positions: leg_moved leg.translate((x, y, -12.5)) result result.union(leg_moved) # 导出 cq.exporters.export(result, table.step)注意几个特征一是cq.Workplane(XY)这种起始平面选择决定了建模的坐标基准二是fillet倒圆角一定要在box之后单独做否则会报no edges selected三是union合并的先后顺序影响性能先小后大比先大后小更稳。这里面最大的坑是坐标基准不一致。LLM 生成的代码里有的特征用的是世界坐标(x, y, z)有的用 Workplane 局部坐标两者混用极易导致零件错位。项目作者在实现里也注意到了这个问题所以推理代码里有一个坐标规范化的预处理模块。我自己跑的时候遇到过桌腿位置偏移到桌面外面去的情况排查后发现是 prompt 里写了四条腿在角落模型给每条腿都定义了一个绝对坐标但桌面是居中的坐标体系没对齐。解决办法是在 prompt 里明确四个腿位于桌面四个角落这种相对空间描述让模型生成相对位置代码。4.3 图像输入模式里的预处理管线带参考图模式比纯文本复杂一个量级因为图像需要经过 Zero-1-to-3 的多视角渲染后才能作为条件输入给 LLM。这个管线的核心步骤是图像缩放统一到 256x256背景分割去除背景只保留主体视角估计估计图像中物体的近似朝向多视角渲染从多个虚拟相机位姿渲染出该物体的新视角图特征拼接把多视角图与文本描述一起交给 LLM我在跑这一步时遇到的最典型问题是背景没抠干净。Zero-1-to-3 自带的背景分割器对纯色背景处理得很好但遇到复杂纹理背景就会残留噪声导致渲染出的多视角图出现鬼影最终 CAD 模型表面出现奇怪的凸起。我的经验是上传图片前先用 remove.bg 之类的工具把背景处理成纯白色能显著降低生成失败率。另外图像输入模式下prompt 的描述最好和图像内容互为冗余。也就是说文本里别只写桌子要写圆角桌面的桌子桌面比四根腿都宽。模型在融合图文信息时如果文本描述与图像内容冲突它大概率会优先信任图像——这跟多模态模型的训练模式有关。所以你的文本描述应该是对图像的补充而不是对图像的复述。5. 常见问题与排查技巧实录5.1 推理失败的四个高频原因问题现象根本原因解决办法CadQuery 执行报错类型不匹配LLM 生成了非法参数调低 temperature增加 num_cad_sequences 冗余生成结果是个空壳/零厚度的面模型输出了Workplane但没有extrude或revolve检查代码中是否有厚度特征prompt 里强调solid、thickness输出模型与描述明显不符多模态信息冲突或 prompt 太模糊增加图像参考prompt 写得更结构化显存不足OOM单次推理加载了过多模型减小 batch size升级到 12GB 以上显存这里面最烦人的是第二种——代码语法没问题模型也生成了但结果是一张纸片而不是实体。原因通常在于 LLM 输出的 CadQuery 代码只定义了二维草图轮廓而忘了extrude。处理办法我上面写过最佳预防措施是把显式厚度指令写进 prompt。我在测试中对比过a solid metal plate with a thickness of 2mm 和 a metal plate 的结果差异极大前者 100% 生成实体后者约 40% 概率生成纸片。5.2 输出 STEP 文件打不开或导入失败这个坑我初期也踩过。text-to-cad 默认是直接输出 STEP 模型文件这种格式按说是最通用的但如果你拿到的 STEP 文件导入 SolidWorks 时提示文件包含无效几何体大概率是模型执行过程中产生了退化面——比如圆角半径过大导致相邻面自相交。解决方案分两步第一步在 prompt 层面约束圆角半径的合理范围比如圆角半径 5mm 以下。第二步如果已经生成了坏文件在 CadQuery 里做一次修复几何体操作再导出import cadquery as cq result cq.importers.importStep(bad_model.step) solid result.val().fix() # 尝试修复 cq.exporters.export(solid, fixed_model.step)这个fix()方法会尝试修复退化的边和面但也不是万能药。如果模型本身拓扑错误严重修复后仍然可能报错那时候我只能说重新生成这次 prompt 记得写精确点。5.3 推理速度太慢如何定位瓶颈单次推理可以拆成三段耗时LLM 生成代码约 10-20 秒、CadQuery 执行代码约 1-5 秒、Zero-1-to-3 图像推理约 30-60 秒。如果是纯文本模式图像推理环节被跳过整体速度快得多。如果你觉得慢先用time命令定位是哪段慢。实测下来瓶颈通常不在 GPU 算力而在 Zero-1-to-3 的 UNet 推理。那个模型虽然不大但前处理环节包含了图像编码和多视角渲染每一步都有大量张量操作。我试过把它从 FP32 改成 FP16 推理速度快了接近一倍精度基本无损。改法是在推理脚本里对模型调用.half()再把输入张量转成.half()注意同时要把torch.autocast打开否则某些算子会被强制转回 FP32等于白改。5.4 多候选结果的挑选逻辑生成 3 份候选代码后项目默认会挑选第一个构建成功的作为最终结果。但第一个成功不等于质量最好。我跑过一个案例三个候选里第一个成功的是一个色彩诡异但几何正确的模型第二个虽然代码报错但报错信息提示它想创建一个更复杂的结构第三个则是一个过度简化的版本。这种场景下我认为更合理的策略是按需挑选如果你追求几何保真选构建成功中最接近 prompt 描述的候选哪怕它代码有点乱。如果你追求可编辑性选 CadQuery 代码结构最简洁、特征分离最清晰的候选方便后续手动改。如果你追求加工可用选实体体积和面数最常规的那个避免出现微小碎面。项目也提供了接口手动指定候选序号你可以把三个候选都导出在 CAD 软件里快速扫一眼再决定用哪个。反正生成成本不高多导几个不亏。6. 经验总结与进阶玩法从玩具到生产力工具6.1 这个项目在实际工作中到底能不能用先说结论对于快速验证、教学演示、概念设计text-to-cad 完全够用对于直接要交付生产的精密零件它目前还不够格。原因很直白LLM 生成的代码虽然逻辑上正确但对公差、表面精度这类制造层面的约束缺乏感知。你让它做一个直径 10mm 的圆孔它可能生成 10.023mm 的孔这在 3D 打印场景无伤大雅但在 CNC 加工里可能就不符合 H7 公差要求。不过它可以帮你节省大量从零到一的时间。我的工作流是先用 text-to-cad 生成一个基础形态模型导入 FreeCAD 后手动调整关键公差面补加工艺特征拔模角、退刀槽半小时内完成一个传统流程可能要 3-4 小时的零件雏形。这个效率提升是实打实的。6.2 后续扩展方向如果你跑通了基本流程有几个方向值得继续挖一是接入自建模型服务。项目默认使用远端推理接口但你可以把模型权重部署到内部服务上这样既快又不受限。我在内网部署过一次单次推理延迟比公共接口低了近一半。二是和参数化设计工具打通。text-to-cad 输出的是 CadQuery 代码CadQuery 代码本质就是 Python 脚本你可以把这个脚本嵌入你的自动化设计流水线。比如批量生成 100 种不同尺寸的支架只要在大循环里改 prompt 参数就行。三是反向工程。把 text-to-cad 生成的模型再导入 CAD 软件用它作为参考几何重新手工建模出高精度的生产模型。这个流程我用在过一个小零件上从照片到最终交付模型总共只用了不到一个上午。6.3 最后一剂实用建议如果你打算上手这个项目我最大的建议是不要把它当成一个输入文字就出模型的黑盒而要把它当成一个LLM 与 CAD 引擎结合的参考架构。项目本身的模型权重、推理代码、数据管线拆开看都是一份很好的多模态生成教学样本。哪怕你最后不用它出模型光是把它的数据流捋一遍你对文本到强约束几何生成这件事的理解都会上一个台阶。最后分享一个小技巧text-to-cad 对 prompt 的格式非常敏感。你可以在 prompt 里用逗号分隔多个子句并用括号标注尺寸单位比如 a bracket, L-shaped, (thickness 3mm), (width 40mm), (height 30mm), with two screw holes on the vertical face, hole diameter 4mm。这种结构化 prompt 的生成成功率远超自然语言长句。我从项目文档里瞄到这个规律后把所有 prompt 都改成了这种格式失败率骤降。这就是跟模型对话的正确姿势——它擅长的是结构化语义不是文学修辞。 
长河君 · 2026/10/26 15:18:24 · 阅读 1.2k text-to-cad实战：如何把自然语言指令变成参数化三维CAD模型
1. 项目概览text-to-cad 到底在解决什么问题先用一句话说清楚text-to-cad 是把自然语言描述直接转成可编辑三维 CAD 模型的开源工具。你输入一句带四个圆柱腿的圆角矩形桌面它就给你生成一个参数化建模的 STEP 文件拿过去就能开加工或者继续改。第一次看到这个项目标题时我其实先愣了几秒。做结构设计这些年CAD 建模一直是人肉驱动的活儿——画草图、拉特征、倒圆角、装配约束每一步都要手动点。哪怕是最熟练的工程师从想法到可用模型少说也要半小时。而这个项目text-to-cad直接把门槛砍掉一大截自然语言就是建模指令模型生成代码代码驱动 CAD 引擎最终落成真实可用的几何体。它适合谁如果你是做机械设计的、搞 3D 打印的、做产品原型验证的或者是刚接触参数化建模想试试水的新手这个项目都值得花一个下午跑一遍。对于普通用户它最大的价值不是替代你手搓模型而是把想法到雏形这段最耗时、最容易劝退的路程变得几乎无感。先说清楚一个大前提text-to-cad 不是像 DALL·E 那样直接画出 3D 模型也不是简单的文生图 模型重建。它的核心链路是LLM 语义解析 - 程序化建模代码 - CAD 引擎执行。也就是说它走的是程序化生成Procedural Modeling路线模型不是点云或网格而是一段可执行的建模脚本。这个技术选型非常关键后文我会专门拆开讲为什么这样设计是聪明的做法。2. 技术原理为什么选程序化建模这条笨路线2.1 不是生成网格而是生成建模步骤我最早看到的 text-to-cad 项目是在 Hugging Face 上发布的一个开源实现作者是 Zachary Evans。它的核心逻辑可以用一条链说明用户输入文本比如 a desk with 4 legs and a flat top - LLM 结合参考图像可选生成 CadQuery 代码 - CadQuery 引擎执行输出 STEP 文件。注意这里 LLM 输出的不是模型而是建模操作序列。CadQuery 是一种基于 Python 的参数化 CAD 建模块它用代码来描述几何特征——拉伸一个矩形、挖一个孔、倒一个圆角。text-to-cad 把语义理解和几何构建彻底拆开了LLM 只负责把自然语言翻译成建模意图真正的几何内核交给 CadQuery 处理。这个笨路线的好处我用一个类比说明。假设你要做一个木凳子方案 A 是 3D 扫描仪对着真凳子扫一圈得到点云再铺面方案 B 是拿到一张图纸按图纸一步步下料、组装。text-to-cad 走的是方案 B——它拿到的是一张可执行的图纸。这样生成的模型天然就是参数化的尺寸可以改、特征可以删、圆角可以调甚至可以批量生成一族相似模型。这在工程场景里是刚需你做完一个零件老板娘说尺寸放大 10%孔位右移 5 毫米方案 B 改一行参数就完事方案 A 就得重新扫描铺面想死的心都有。2.2 从文本到多视图渲染再到 CAD 代码的完整数据流text-to-cad 的前期训练数据准备很有参考价值。它先用 Zero-1-to-3 这个视角合成模型把模型库中的 3D 物体渲染成多视角图像再把文本描述 渲染图像喂给微调过的 LLM让它学会输出 CadQuery 代码。这一步相当于先教模型看图说话——看到某个形状的六个视角能用建模语言复述出它的几何结构。实际推理时有两套输入路径纯文本直接输入 A cylinder with a radius of 5mm and height 20mm模型直接输出代码。文本 参考图上传一张真实物体照片或手绘草图加上一句描述模型参考图像中的几何形态输出代码。第二种模式才是这个项目最杀人的功能。你拍一张桌子的照片说圆角的桌面四根圆柱腿它就能生成一个结构近似的参数化桌子。对于产品逆向、快速原型场景这个工作流几乎是一种作弊级别的效率提升——传统流程里你得先测绘再建模现在直接拍照 一句话就起步了。2.3 LLM 输出代码的容错设计这类项目的第一个灵魂拷问是LLM 生成的代码有 bug 怎么办CadQuery 脚本只要有一个参数类型不匹配整个构建就崩了。text-to-cad 在架构上做了一个很聪明的容错设计它会同时生成多份代码候选实际推理时默认生成 3 份每一份独立尝试执行只要有一份成功构建出实体模型就把它作为结果返回。这个多路并行 竞速的思路在工程上叫冗余容错实际效果非常明显——我试过连续生成十几个模型失败率大概只有两成左右而且大部分失败场景是 prompt 本身描述模糊比如说做一个好看的东西这种没法量化的输入。另外项目的推理脚本里还有一个conformation模块专门处理生成结果的自检。它会对输出的几何体做基础检查——体是否为流形、是否封闭、维度是否合理。不合格的代码直接淘汰不会进入最终输出。这个自检机制对下游加工至关重要一个非流形的网格文件进了切片软件轻则打印出废品重则把切片器干崩溃。3. 环境准备与快速启动从 GitHub 到第一个模型3.1 硬件与软件清单先交代一下我实际跑通的配置给大家一个参考基准操作系统Ubuntu 22.04Windows 用 WSL2 也可以但坑更多后面单说GPUNVIDIA RTX 3060 12GB其实 8GB 显存也够跑只是慢一点Python3.11PyTorch2.1.2 CUDA 12.1显存占用单次推理峰值约 7GB包括 Zero-1-to-3 图像编码和 LLM 推理如果你只有 CPU也不是不能跑就是慢。我在一台纯 CPU 的云服务器上试过单次推理耗时大约 8-12 分钟GPU 环境下只需要 40-60 秒。这个差距主要在 Zero-1-to-3 的图像编码器那是纯 CNN吃显存也吃算力。3.2 安装过程中的真实踩坑记录克隆仓库这一步没啥说的pip 安装依赖才是坑的开始。我建议严格按照 requirements.txt 来装不要自作主张升级包版本。尤其注意这几个包cadquery 最好用 2.1 以上版本太老版本对布尔运算的支持不行。openai 库的版本要匹配项目代码太新版 API 有 breaking change。torch 和 torchvision 的版本必须一致否则编译 CUDA 扩展时会炸。我最初图省事用了pip install -r requirements.txt一把梭结果 pyTorch 被装成了 CPU 版本跑起来慢到怀疑人生。后来重新用官方命令装 CUDA 版才正常。模型权重是另一个大坑。text-to-cad 依赖 Hugging Face 上的预训练权重项目默认是从 HF Hub 下载但国内网络环境下载大模型权重经常中断我是手动下载权重文件后放到本机缓存目录的。操作步骤是先查看~/.cache/huggingface/hub目录有没有残留文件有的话删掉再往models--zavant--text-to-cad这样的目录结构里手动放二进制文件。放完之后跑一次推理它会自动加载缓存里的文件不需要重新下载。3.3 跑通最小推理 Demo进到项目根目录创建一个最简单的 Python 脚本from text_to_cad import TextToCAD # 初始化模型 model TextToCAD() # 一句自然语言描述 prompt a rectangular table with four cylindrical legs # 生成结果 result model.generate(prompt) # 保存 STEP 文件 result.save(table_from_text.step)如果你走的是带参考图的模式需要先把图片转成 RGB 格式并缩放到 256x256 附近否则 Zero-1-to-3 的前处理会出问题。我第一次喂了一张 1200 万像素的照片进去跑了两分钟然后报了个尺寸不匹配的错误后来加了个预处理步骤才解决。跑通这个脚本之后你就拿到了第一份 text-to-cad 产出。用 FreeCAD 或者 CadQuery 自带的查看器打开 STEP 文件你会看到完整的实体模型。这个自然语言 - 真实可用三维模型的瞬间说实话比我想象中要有成就感得多。4. 核心实现细节与参数调优让生成结果更可控4.1 理解三个关键参数视点数量、候选数、温度text-to-cad 的推理接口里藏着几个直接影响输出质量的参数。我在实际测试中逐个调过记录如下参数名默认值作用我的调优建议num_images_per_prompt1每个 prompt 渲染多少视角图追求精度就调 4代价是推理时间翻几倍num_cad_sequences3生成多少份 CAD 候选代码保持默认太高没必要太低容错下降temperature0.2LLM 采样温度结构严谨类描述用 0.1-0.2创意探索类用 0.6-0.8这几个参数里temperature 对结果的影响最玄学。我在生成一个圆角矩形板这种明确几何时把温度调到 0.8结果模型输出了一段完全跑不通的代码CadQuery 直接报语法错误。后来把温度降回 0.1输出就稳定多了。经验是如果 prompt 描述非常具体低温更安全如果 prompt 只给了模糊意象比如现代风格的椅子适当高温反而能避开千篇一律的平庸结果。另一个容易被忽略的是 prompt 的措辞习惯。text-to-cad 的 LLM 在训练阶段见过大量measurement-based表达比如带数字的尺寸描述所以你的输入越像工程语言输出质量越高。我测试过几种说法a cup - 生成一个简单的圆柱杯a cylinder with radius 3cm and height 10cm - 生成精确的圆柱a large cup with a handle on the right side - 生成更复杂的异形杯第三种生成的杯把手实际是一个环形扫掠特征。这说明 LLM 对handle on the right side这类语义定位是能理解的但前提是几何形态本身在训练数据里出现过。冷门形态比如带三个环形凹槽的不规则十二面体模型大概率会给你生成一个莫名其妙的组合体。懂了这层你就知道 prompt 该往哪个方向写了交代结构、交代数量、交代相对位置不要指望它理解审美形容词。4.2 CadQuery 代码输出的常见模式text-to-cad 生成的 CadQuery 代码大多遵循一套固定语法。我截取一段典型的输出做了简化import cadquery as cq # 创建桌面 table_top ( cq.Workplane(XY) .box(60, 30, 2) # 长宽高 .edges(|Z) .fillet(2) # 桌边倒圆角 ) # 创建四条桌腿 leg cq.Workplane(XY).circle(1.5).extrude(25) leg_positions [ (25, 12), (25, -12), (-25, 12), (-25, -12) ] # 合并主体 result table_top for x, y in leg_positions: leg_moved leg.translate((x, y, -12.5)) result result.union(leg_moved) # 导出 cq.exporters.export(result, table.step)注意几个特征一是cq.Workplane(XY)这种起始平面选择决定了建模的坐标基准二是fillet倒圆角一定要在box之后单独做否则会报no edges selected三是union合并的先后顺序影响性能先小后大比先大后小更稳。这里面最大的坑是坐标基准不一致。LLM 生成的代码里有的特征用的是世界坐标(x, y, z)有的用 Workplane 局部坐标两者混用极易导致零件错位。项目作者在实现里也注意到了这个问题所以推理代码里有一个坐标规范化的预处理模块。我自己跑的时候遇到过桌腿位置偏移到桌面外面去的情况排查后发现是 prompt 里写了四条腿在角落模型给每条腿都定义了一个绝对坐标但桌面是居中的坐标体系没对齐。解决办法是在 prompt 里明确四个腿位于桌面四个角落这种相对空间描述让模型生成相对位置代码。4.3 图像输入模式里的预处理管线带参考图模式比纯文本复杂一个量级因为图像需要经过 Zero-1-to-3 的多视角渲染后才能作为条件输入给 LLM。这个管线的核心步骤是图像缩放统一到 256x256背景分割去除背景只保留主体视角估计估计图像中物体的近似朝向多视角渲染从多个虚拟相机位姿渲染出该物体的新视角图特征拼接把多视角图与文本描述一起交给 LLM我在跑这一步时遇到的最典型问题是背景没抠干净。Zero-1-to-3 自带的背景分割器对纯色背景处理得很好但遇到复杂纹理背景就会残留噪声导致渲染出的多视角图出现鬼影最终 CAD 模型表面出现奇怪的凸起。我的经验是上传图片前先用 remove.bg 之类的工具把背景处理成纯白色能显著降低生成失败率。另外图像输入模式下prompt 的描述最好和图像内容互为冗余。也就是说文本里别只写桌子要写圆角桌面的桌子桌面比四根腿都宽。模型在融合图文信息时如果文本描述与图像内容冲突它大概率会优先信任图像——这跟多模态模型的训练模式有关。所以你的文本描述应该是对图像的补充而不是对图像的复述。5. 常见问题与排查技巧实录5.1 推理失败的四个高频原因问题现象根本原因解决办法CadQuery 执行报错类型不匹配LLM 生成了非法参数调低 temperature增加 num_cad_sequences 冗余生成结果是个空壳/零厚度的面模型输出了Workplane但没有extrude或revolve检查代码中是否有厚度特征prompt 里强调solid、thickness输出模型与描述明显不符多模态信息冲突或 prompt 太模糊增加图像参考prompt 写得更结构化显存不足OOM单次推理加载了过多模型减小 batch size升级到 12GB 以上显存这里面最烦人的是第二种——代码语法没问题模型也生成了但结果是一张纸片而不是实体。原因通常在于 LLM 输出的 CadQuery 代码只定义了二维草图轮廓而忘了extrude。处理办法我上面写过最佳预防措施是把显式厚度指令写进 prompt。我在测试中对比过a solid metal plate with a thickness of 2mm 和 a metal plate 的结果差异极大前者 100% 生成实体后者约 40% 概率生成纸片。5.2 输出 STEP 文件打不开或导入失败这个坑我初期也踩过。text-to-cad 默认是直接输出 STEP 模型文件这种格式按说是最通用的但如果你拿到的 STEP 文件导入 SolidWorks 时提示文件包含无效几何体大概率是模型执行过程中产生了退化面——比如圆角半径过大导致相邻面自相交。解决方案分两步第一步在 prompt 层面约束圆角半径的合理范围比如圆角半径 5mm 以下。第二步如果已经生成了坏文件在 CadQuery 里做一次修复几何体操作再导出import cadquery as cq result cq.importers.importStep(bad_model.step) solid result.val().fix() # 尝试修复 cq.exporters.export(solid, fixed_model.step)这个fix()方法会尝试修复退化的边和面但也不是万能药。如果模型本身拓扑错误严重修复后仍然可能报错那时候我只能说重新生成这次 prompt 记得写精确点。5.3 推理速度太慢如何定位瓶颈单次推理可以拆成三段耗时LLM 生成代码约 10-20 秒、CadQuery 执行代码约 1-5 秒、Zero-1-to-3 图像推理约 30-60 秒。如果是纯文本模式图像推理环节被跳过整体速度快得多。如果你觉得慢先用time命令定位是哪段慢。实测下来瓶颈通常不在 GPU 算力而在 Zero-1-to-3 的 UNet 推理。那个模型虽然不大但前处理环节包含了图像编码和多视角渲染每一步都有大量张量操作。我试过把它从 FP32 改成 FP16 推理速度快了接近一倍精度基本无损。改法是在推理脚本里对模型调用.half()再把输入张量转成.half()注意同时要把torch.autocast打开否则某些算子会被强制转回 FP32等于白改。5.4 多候选结果的挑选逻辑生成 3 份候选代码后项目默认会挑选第一个构建成功的作为最终结果。但第一个成功不等于质量最好。我跑过一个案例三个候选里第一个成功的是一个色彩诡异但几何正确的模型第二个虽然代码报错但报错信息提示它想创建一个更复杂的结构第三个则是一个过度简化的版本。这种场景下我认为更合理的策略是按需挑选如果你追求几何保真选构建成功中最接近 prompt 描述的候选哪怕它代码有点乱。如果你追求可编辑性选 CadQuery 代码结构最简洁、特征分离最清晰的候选方便后续手动改。如果你追求加工可用选实体体积和面数最常规的那个避免出现微小碎面。项目也提供了接口手动指定候选序号你可以把三个候选都导出在 CAD 软件里快速扫一眼再决定用哪个。反正生成成本不高多导几个不亏。6. 经验总结与进阶玩法从玩具到生产力工具6.1 这个项目在实际工作中到底能不能用先说结论对于快速验证、教学演示、概念设计text-to-cad 完全够用对于直接要交付生产的精密零件它目前还不够格。原因很直白LLM 生成的代码虽然逻辑上正确但对公差、表面精度这类制造层面的约束缺乏感知。你让它做一个直径 10mm 的圆孔它可能生成 10.023mm 的孔这在 3D 打印场景无伤大雅但在 CNC 加工里可能就不符合 H7 公差要求。不过它可以帮你节省大量从零到一的时间。我的工作流是先用 text-to-cad 生成一个基础形态模型导入 FreeCAD 后手动调整关键公差面补加工艺特征拔模角、退刀槽半小时内完成一个传统流程可能要 3-4 小时的零件雏形。这个效率提升是实打实的。6.2 后续扩展方向如果你跑通了基本流程有几个方向值得继续挖一是接入自建模型服务。项目默认使用远端推理接口但你可以把模型权重部署到内部服务上这样既快又不受限。我在内网部署过一次单次推理延迟比公共接口低了近一半。二是和参数化设计工具打通。text-to-cad 输出的是 CadQuery 代码CadQuery 代码本质就是 Python 脚本你可以把这个脚本嵌入你的自动化设计流水线。比如批量生成 100 种不同尺寸的支架只要在大循环里改 prompt 参数就行。三是反向工程。把 text-to-cad 生成的模型再导入 CAD 软件用它作为参考几何重新手工建模出高精度的生产模型。这个流程我用在过一个小零件上从照片到最终交付模型总共只用了不到一个上午。6.3 最后一剂实用建议如果你打算上手这个项目我最大的建议是不要把它当成一个输入文字就出模型的黑盒而要把它当成一个LLM 与 CAD 引擎结合的参考架构。项目本身的模型权重、推理代码、数据管线拆开看都是一份很好的多模态生成教学样本。哪怕你最后不用它出模型光是把它的数据流捋一遍你对文本到强约束几何生成这件事的理解都会上一个台阶。最后分享一个小技巧text-to-cad 对 prompt 的格式非常敏感。你可以在 prompt 里用逗号分隔多个子句并用括号标注尺寸单位比如 a bracket, L-shaped, (thickness 3mm), (width 40mm), (height 30mm), with two screw holes on the vertical face, hole diameter 4mm。这种结构化 prompt 的生成成功率远超自然语言长句。我从项目文档里瞄到这个规律后把所有 prompt 都改成了这种格式失败率骤降。这就是跟模型对话的正确姿势——它擅长的是结构化语义不是文学修辞。