让大模型改你的建模脚本:它是怎么悄悄改坏装配的
让大模型改你的建模脚本:它是怎么悄悄改坏装配的
大模型改建模脚本时,最危险的行为是“改对了一句,改坏了整体”:一个函数、一行数字和一处轴符号,都能让代码照常执行、不抛异常、导出成功,但装好的铰链方向反了、抽屉滑进了箱体、贴在门上的把手留在了原地。
sand3d 是个把 3D 模型写成短程序的 Python 库(import sand3d as s3d,跑在 Blender 的 bpy 之上),它的明确目标读者就是模型:整套 API 约 3 600 tokens,一个零件比同等的 Blender Python 少 2~6 倍 token。但“写得短”不等于“改得对”。这篇文章把仓库里真实的装配程序、真实生成数据里统计出的失败模式,以及库自身那道“下一句就报错”的防线摆在一起,讲清楚大模型是怎么在几何层面悄悄改坏装配的,以及可以怎么防。
一、一个能跑、但已经坏了的改动
看一个真实程序:programs/washing_machine.py。滚筒洗衣机的门、玻璃、把手是一个 group,铰链落在门圈外缘的 -Y 边上,绕 -Z 打开 0~143°:
ring = s3d.at(s3d.tube("ring", door_d, 300, 45), on=front.move(0, 400)) # centred on the porthole
glass = s3d.at(s3d.cylinder("glass", 320, 16), on=front.move(0, 400).offset(14))
hinge = front.move(-door_d / 2, 400).offset(45) # the ring's outer -Y edge: it clears the cabinet
...
s3d.joint("door_hinge", door, hinge, axis="-Z", range=(0, 143))
(配套的部件树、四个关节与三种导出,见仓库里的装配示意图:)
如果模型在“帮忙整理”时把 axis="-Z" 改成了 "+Z",程序依然能跑完、依然能导出 GLB,range=(0, 143) 依然合法。变化只有一处:门不再向外开,而是朝箱体里面转。这正是 docs/guidelines.md 第 8 条里那个真实例子的形状——一个壁柜的门内摆,0/1 个关节正确;下一稿只改了符号,1/1 正确。
更值得警惕的是生成数据里的分布。同一份指南记录了一次审查:23 份“小幅改动就把关节改对”的草稿中,有 8 份只改了轴的符号,别的一个字都没动。也就是说,装配对不对,经常不由结构决定,而由那一个字符决定;而那一个字符恰恰是文本 diff 里最不显眼的东西。
二、典型失败模式:局部改动引发全局约束失配
docs/guidelines.md 的八条规则不是凭空写的,它是对生成出来的装配程序做审查后归纳的(原文自己声明“尚未作为 prompt 测试过”,这点很诚实)。其中最容易被“顺手改坏”的有四类。
1. 派生量被写成了硬编码。 冰箱柜体那段:
inner = s3d.at(
s3d.extrude("inner_tool", s3d.rect(width - 100, depth - 100), height - 90, both=True), z=475
)
tool1 = s3d.at(s3d.extrude("slot_tool1", s3d.rect(1440, 720), 20, both=True), z=910)
tool2 = s3d.at(s3d.extrude("slot_tool2", s3d.rect(1440, 740), 20, both=True), z=930)
它跑得通,也和目标形状匹配。但 475、1440、720、740、910、930 全都由 width、depth、height 推出来。模型只要改一次 height=940 去“加高柜体”,六个数字不会跟着变,切出来的内腔与开口就错位了。同一份指南给出的量化口径是:每个零件目标 15 个数字字面量、上限 40,干净程序的中位数是 15,“跟库较劲”的程序是 53;并且 31.0% 的生成程序声明了某个尺寸,却从未读取它。
2. 一个函数被写成两份。 跷跷板那段里 end_crossrail 与 opposite_crossrail 是同样六行的两次抄写:
def opposite_crossrail(width=325, d=31, height=182, stem_d=29): # ← the same six lines as end_crossrail
这种代码不会崩,但它把“一次改动”变成了“两次改动”。模型改了左边、忘了右边,几何上就是不对称——而 diff 里看不出任何异常。
3. 在世界坐标里建模,再减回去。 眼镜腿那段的 temple_arm 收下 origin_x=64.5, origin_y=-14.6, base=37.5,然后把每个点都减去这三个数:
path = s3d.spline([(62-origin_x,-72-origin_y,55-base), ...])
模型“优化”时最容易做的正是把 -origin_x 展开算成常数,或者把 head 里的 at(temple_arm(), x=64.5, ...) 调一下而忘了零件内部的反向补偿。坐标写了两遍,关系就断了。
4. 关节的 pivot 与零件用了两个不同的帧。 指南里那个旋轴例子:
f = s3d.local(body, 1, 0, 5)
spindle = s3d.at(spindle, on=s3d.local(body)) # 0 of 1 joints right
零件放到 local(body),关节却挂在 local(body, 1, 0, 5) 上。模型下一稿自己修好了:两处用同一个 f。这类错误没有任何运行时报错,只有“转起来会飞出去”。
这四类错误的共同点是:改动的文本范围很小,被破坏的约束范围很大——而约束关系恰恰不在 diff 的视野里。
三、为什么文本级正确不等于几何级正确
这个库把“几何正确”定义得非常具体,也非常脆弱。
浮点噪声就是几何。 src/sand3d/_core.py 的 world() 里写得很直白:Blender 用单精度保存位置,一个四分之一圈回来会带着 7.5e-8 而不是 0,一个面贴到另一个面上会漂几微米——对 EXACT 布尔求解器来说,这就是两个平面,于是留下一条膜。所以库把所有“接近整数”的矩阵元素吸附到整数(平移吸附到整毫米),把一个面的框从 Blender 的单精度 N 边形中心改成用 Newell 法在双精度里重算,因为“12 mm 圆盘的顶面曾经算出 z = 12.0000095”。
“贴住”和“切进去”是两件事。 在 src/sand3d/edit.py 里,切完之后会检查有没有工具实际上一个面都没留下:
if operation == "DIFFERENCE":
# a tool that leaves no face took no volume out: it only touched, and printed its
# footprint on the face it stands on, in slivers a later bevel clamps to nothing
一旦发现“没切到”,并且调用是带明确意图的(aimed=True,cut/hole/pocket 都是),就抛 NothingCut,并把双方的包围盒坐标一起打出来:
cut: no tool cuts into 'plate' — they miss it, or only touch it (its box (-30, -20, 0) .. (30, 20, 8); the tools' (75, -5, 0) .. (85, 5, 20))
测试里还钉了这个修复的来由(tests/test_regressions.py):一个立在台阶上的工具“只接触、不切削”,却在其表面印下一圈零宽碎片,后续倒角被 clamp 到零。也就是说,一段看起来“只是把 z 从 18.5 改成 19”的编辑,在几何上可能从“切”变成了“碰”。
布尔结果可能不是这个零件。 同一文件里 _Operands.check 会比较结果的包围盒与操作数应有的盒子,越界就报错,并给出提示:工具与面相切、或沿一条线贴合,或者实体自交,都会让求解器返回不是这个零件的东西。重叠的实体必须先 join。
一件工具没切到,可能被静默丢掉。 在一块不规则零件上按帧阵列打孔时,落在零件外的那个帧会被丢弃,不报错:
def pocket(ob, profile, depth=None, on=None):
...
except NothingCut as error: # one frame off an irregular part: dropped, as a hole's
missed.append(error)
if len(missed) == len(on):
raise missed[0]
只有全部帧都落空才报错。改一个阵列间距、改一个半径,结果是“孔从 8 个变成 7 个”,导出正常、日志干净。这是最典型的“文本级正确、几何级错误”。
大模型写“组合类操作”的失败率有数据。 CONTRIBUTING.md 记录了对 173 369 条 LLM 生成的 CAD→bpy 翻译的测量:以有效率为 650/1000 为基线,union 216、mirror 279、circular pattern 344、fillet 411;在合成的 CadQuery 源上(基线 518),helix 205、sweep 278、revolve 362。换句话说,装配最依赖的那几个操作,正是模型写得最差的那几个。这也解释了为什么沙箱需要一层词汇表,而不是让模型直接写 bpy。
“改了什么”需要比 diff 更严的定义。 仓库的黄金测试把每个对象的世界位置、顶点、面、边、所有命名属性、材质标签、关节 JSON 一并哈希(tests/harness.py 的 _object_digest)。一次“只是重命名变量”的整理,如果碰了浮点顺序或边的走向,摘要就会变;反过来,摘要一致才敢说几何一致。这套机制在 tests/test_golden.py 里和 tests/golden/bpy-5.2.json 对比,规则是“移动了几何的修复,必须在同一个 PR 里重录摘要,并说明哪几块动了、为什么”。
四、防呆之一:把约束写进程序结构
防不住“模型想改”,但可以让“改了会散架”变得可见。
每个尺寸只写一次,其余全是表达式。 上面那个柜体的正确写法:
def cabinet_part(width=1500, depth=800, height=940, wall=50, lip=30, slot=20):
shell = s3d.extrude("shell", s3d.rect(width, depth), height, both=True)
shell = s3d.at(shell, z=height / 2)
well = height - 2 * slot - wall
inner = s3d.at(
s3d.extrude("inner_tool", s3d.rect(width - 2 * wall, depth - 2 * wall), well, both=True),
z=wall + well / 2,
)
改 height,内腔、开口、槽位一起跟着走。指南对这类改写给出的验收口径是形状相似度 F 1.000(对原稿),也就是说“可维护性变好”不必以“形状变差”为代价。
可删的细节用 attach 挂上去。 docs/examples/chair.py 是先写“计划”再挂细节:chair_frame 只搭座面与四条腿,发布 width、seat_h、back_y 等锚点;add_back、add_rails 各自挂在锚点上。删掉 add_back,椅子变成凳子,别的什么都不动。这比“在 head 里堆几何”更抗改:模型想删一个细节时,需要删的是一行调用,而不是在一段几何代码里做手术。
一个关节一个帧。 这是最容易实现、也最容易被破坏的约束:
f = s3d.local(body, 0, 0, 0)
spindle = s3d.at(spindle, on=f)
s3d.joint("body_to_spindle", spindle, f, kind="continuous", axis="+X")
同一个 f 既放零件、又当枢轴,模型就不可能只改一半。
在静止姿态下建模。 指南第 8 条最后一句是“Build at rest. Every joint at 0, no s3d.pose in the program.” 洗衣机程序把它执行得很彻底:washer() 只返回静止的装配,想展示打开状态要另调 washer_open()。这条纪律不只是为了好看——export 的行为是 GLB 导当前姿态、URDF 导静止姿态。程序里随手加一句 s3d.pose(machine, 92, joint="door_hinge") 去“演示一下”,GLB 就带着开门姿态,URDF 还是合着的,下游拿到两份对不上的资产,而程序本身零报错。
用 seat 而不是 cut 去做配合。 抽屉槽、旋钮座这类“零件占掉的体积”,用 s3d.seat(cab, drawer):它取的是静止姿态下的交集,零件本身不动、不被消耗,还能继续沿关节运动。tests/test_seat.py 里专门钉了这一点——即使先把抽屉 pose 到 150 mm,seat 切出来的仍是静止位置的腔体。如果模型用 cut(cab, drawer),抽屉会被布尔消耗掉,关节也就没东西可挂了。
五、防呆之二:让下一句就报错
光靠写法规矩不够,因为模型会“优化”掉看不懂的东西。sand3d 的做法是把常见误用变成在下一个动词处必定触发的错误,并且错误信息本身写成教学文本。核心在 src/sand3d/_guard.py:
对象被用掉了还说“再放一下”。 cut/join/intersect 会消耗工具。之后再用它:
at: 'lid' was used up by cut(box, ...) on line 3; a tool is consumed by the boolean.
To keep it, pass s3d.copy(lid) to cut instead.
同一个对象被传了四次。 模型很爱写这种“阵列”:
s3d.join(plate, *[s3d.at(rib, on=f) for f in s3d.ring(4, 20)])
at 移动对象、不复制对象,于是四个位置其实是同一个 rib。库直接拒绝:
join: 'rib' is passed 4 times; at moves an object, it does not copy it:
s3d.at(rib, on=s3d.ring(...)) places one copy per frame
at 的结果被扔掉。 s3d.at(p, x=100) 单独一行,CPython 在语句结束时释放返回值,__del__ 埋一个待抛错误,下一个动词引爆:
extrude: at() on line 2 placed a profile that nothing used; write p = s3d.at(p, ...)
这条设计挺讲究:错误不是立刻抛,而是挂到“下一次调用公共动词”时才炸,所以报错信息里能带上真正出错的那一行行号,也不会被 try/except 在无关位置吞掉。
装配层的约束检查更硬(src/sand3d/joints.py):
- 已经带关节的零件再
at:at: 'door' moves by its joint 'hinge': placing it would tear it off its pivot ... - 子件放在父件读出的帧上,之后父件或子件又动了:
... is no longer where its frame put it on 'cab' — 'cab' moved after the frame was read, or after 'knob' was placed: its pivot would follow 'cab' and 'knob' would not.判定的容差是平移 1e-3 mm、旋转 1e-6,微米级位移也会被抓到(见 tests/test_joints.py)。 - 贴在运动件上的贴纸没进组:
pose: 'sticker' was placed on a frame read on 'door', which this pose moves, and it is in no group that moves with it: it would stay behind — group it with 'door', or give it a joint of its own - 机制不在零位就声明新关节:
joint 'k': the mechanism is not at rest — 'hinge' on 'door' is posed at 10: declare joints at rest, every joint at 0 (pose them back to 0, or declare the joints first) - 行程区间不含 0:
range (20, 143) does not contain 0: everything is built at rest, every joint at 0 — build the part where it rests, and give the range from there - 用一个关节去
join掉:join: 'door' moves by its joint 'hinge': join would use it up, and the joint with it (a copy carries its joints too) — make the tool from a part that does not move; s3d.seat(host, part) cuts the cavity and leaves the part as it is
这些信息有个共同结构:说明发生了什么、为什么、以及应该改成什么。对模型来说,这等于把“几何约束”翻译回了它擅长的文本形式。一个 axis="+Z" 的符号错误不会在运行时被抓到(它合法),但“pivot 和零件不同源”“对象被消耗”“贴纸没进组”这些上游错误会被拦住——而它们恰恰是符号错误最常见的伴生错误。
顺带一提,1.0 移除的关键字也都保留成了带迁移指引的报错(at: mirror= is gone in 1.0 — ...、hole: at= is on= in 1.0、loft: closed= is loop= in 1.0)。这不是兼容性洁癖:旧脚本被模型改一半、新老写法混用,是另一种“能跑但语义变了”的来源。
六、防呆之三:改动前后对比与关键尺寸断言
库能做的到此为止;剩下的必须在程序外面做。三个层次。
第一层:把几何状态打印成可 diff 的结构。 用公共 API 就够,不用碰内部函数:
import json
import sand3d as s3d
def extents(part):
lo = [s3d.bbox(part, side).origin[k] for k, side in enumerate(("-X", "-Y", "-Z"))]
hi = [s3d.bbox(part, side).origin[k] for k, side in enumerate(("+X", "+Y", "+Z"))]
return [round(v, 6) for v in lo + hi]
def joints(part):
root = part.root if isinstance(part, s3d.Handle) else part
out = []
for ob in [root, *root.children_recursive]:
for j in json.loads(ob.get("s3d~joints", "[]")):
out.append({"name": j["name"], "on": ob.get("s3d_name", ob.name),
"kind": j["kind"], "range": j["range"], "value": j["value"]})
return out
def audit(part):
return {"box": extents(part), "joints": joints(part)}
导出成 JSON,改动前跑一次、改动后跑一次,逐字段比。包围盒能抓到“零件掉在原地”“门反着开”“抽屉多滑了 20”,关节表能抓到“关节少了一个”“range 被悄悄改了”“静止姿态不再是 0”。注意 bbox 是读当前摆放的,所以脚本要在 empty_scene() 之后从零构建,别复用上一次的场景。
第二层:写几何断言,而不是写“跑通了”。 把“门必须开到箱体外面”变成一条可执行的话:
def check_door(machine, door, cab=300.0):
closed = s3d.bbox(door, "+X").origin.x
s3d.pose(machine, 143, joint="door_hinge")
opened = s3d.bbox(door, "+X").origin.x
s3d.pose(machine, 0, joint="door_hinge")
assert opened > closed + 100, f"door swings inward: {closed:.1f} -> {opened:.1f}"
assert closed <= cab + 50, f"door does not sit on the cabinet front: {closed:.1f}"
这就是把指南里“8 个草稿只改符号”的那类事故,变成一条会在 CI 里红的断言。同理:face("top").origin.z 可以用来断言两个件贴平(仓库里就是这么钉“用 anchor="bottom" 站上去的垫片浮了 9.5e-6 mm,join 出两个壳”这个修复的);hole/pocket 之后的孔数、seat 之后的体积,都可以直接查。
第三层:用摘要兜住“看不见的移动”。 仓库自己用的是黄金摘要:每个用例的网格、摆放、命名属性、关节一起哈希,和记录值逐位比较。一般人不需要这么重,但可以借它的思想:把“改动的合理性”定义成“可见差异最小”——一次编辑只应该移动它声称要移动的那几块。指南在给出每一处重写时都附了 F 1.000,就是这个意思:结构改得更好了,形状一点没动。
七、给模型的系统提示,应该摆什么
三份文件分工很清楚:
- docs/api.md:词汇表本身,约 3 600 tokens,覆盖规则、全部签名和可运行例子;
- llms.txt:把模型指向上面的文件;
- docs/guidelines.md:装配程序的八条写法。
如果只给 API,模型会写出“能跑的程序”;要它写出“改得动的程序”,必须把顺序也写进去:先计划、再细节、最后零件;每个零件一个函数、在自己的原点建模;一个关节一个帧;每个关节在 0;可删的细节用 attach。
还有一条隐含要求:别让模型在没人看的情况下“顺手优化”。上面那些失败模式里,没有一个是模型故意写错的——它是在做它认为正确的整理:把表达式算成常数(“更快”)、把重复代码抽成两个函数(“更清晰”)、把轴改成它以为的正确方向(“门当然向外开”)、把 pose 加进主函数(“演示效果更好”)。库能做的,是在这些整理越过几何边界时立刻说话;工程上能做的,是在它说话之前就把断言摆好。
一句话收束:让大模型改建模脚本,真正要守住的不是语法,而是那些只在几何里成立的约束——而它们唯一的表达方式,是“一个尺寸只写一次”“一个关节一个帧”“改完必须量一遍”。
