Kernel与Shader Agent Harness：构建可约束可复现的GPU代码生成框架

1. 从标题拆解：Kernel 与 Shader 的 Agent Harness 到底在解决什么问题

第一次看到 "Kernel & Shader agent harness" 这个组合，很多人会愣一下：Kernel 是操作系统或计算框架里的底层执行单元，Shader 是 GPU 上跑图形或通用计算的程序，Agent 是能自主决策的执行体，Harness 是"挽具、约束框架"。把这四个词拼在一起，它描述的其实是一件事——给"能自己写 Kernel 和 Shader 的智能体"套上一副可控、可测、可复现的挽具。

我接触这个方向是从 LuisaCompute 和 eDSL 这两个关键词开始的。LuisaCompute 是一套跨后端的并行计算框架，它用一套统一的 DSL 描述计算，然后编译到不同的后端（CUDA、Metal、DX 等）。eDSL 就是"embedded DSL"，把领域特定语言嵌进宿主语言里。当你让一个 Agent 去生成 Kernel 或 Shader 代码时，最大的痛点不是"它写不出来"，而是"它写出来的东西没法验证、没法约束、没法批量回归"。Harness 就是来解决这个的。

所以这篇东西适合谁看？三类人：一是做 GPU 计算、图形渲染，想把手写 Kernel/Shader 的重复劳动交给 Agent 的工程师；二是做 AI 代码生成、想让模型产出可执行并行代码的研究者；三是做编译器、DSL、运行时，想搭一套自动化测试与约束框架的人。哪怕你只是被"卡到 installing kernel"或者"kernel header files not in any"这类报错折磨过，理解 harness 的思路也能帮你把问题定位得更快。

核心价值一句话：Harness 把"Agent 生成 Kernel/Shader"从一次性的、靠运气的尝试，变成可约束、可度量、可迭代的工程流程。下面我按自己实际搭这套东西的顺序，把设计思路、关键细节、实操过程和踩坑记录完整拆开讲。

2. 整体设计与思路拆解：为什么是 Harness 而不是普通脚本

2.1 Harness 和 Agent 的区别，先把这个说清楚

热词里有个"harness和agent区别"，这问题问得特别到位，因为很多人把两者混为一谈。我的理解是：

• Agent 是"决策者"：它接收任务描述，决定生成什么 Kernel、用什么并行策略、怎么切分线程块。它是有"意图"的。
• Harness 是"约束与度量层"：它不关心 Agent 想干什么，它只负责给 Agent 提供受控的执行环境、把生成结果编译运行、收集正确性和性能数据、把失败原因结构化地反馈回去。

打个比方，Agent 是赛车手，Harness 是赛道加计时系统加安全护栏。赛车手可以很激进，但护栏保证他不会冲出赛道，计时系统保证每圈成绩可比较。没有 Harness 的 Agent 生成代码，就像在没有护栏的山路上飙车——偶尔能跑出好成绩，但你不敢让它连续跑一百次。

这个区分直接决定了架构：Agent 侧要尽量"薄"，Harness 侧要尽量"厚"。Agent 只输出结构化的代码和元数据，所有编译、执行、校验、统计的脏活都压在 Harness 里。这样换一个 Agent（换个模型、换个 prompt 策略）时，Harness 完全不用动。

2.2 为什么选 LuisaCompute + eDSL 这条路线

选型这块我纠结过很久。直接让 Agent 生成 CUDA C++ 行不行？行，但有几个硬伤：

第一，后端绑定太死。生成 CUDA 就只能跑在特定硬件上，换台机器就废了。LuisaCompute 的好处是它有一套统一 DSL，同一段计算描述能编译到多个后端，Harness 的测试矩阵一下子就能铺开。

第二，eDSL 天然适合做约束。因为计算是用宿主语言（比如 C++）里的 API 拼出来的，Agent 生成的其实是"调用序列"而不是"一整块自由文本"。调用序列可以被静态检查——参数类型对不对、维度匹配不匹配、有没有越界，这些在编译期就能拦下来。而自由文本的 CUDA 代码，你只能靠编译器和运行时报错，反馈链路长得多。

第三，可复现性。eDSL 生成的中间表示（IR）是确定的，同样的输入必然得到同样的 IR。这对 Harness 做回归测试太重要了——你可以把 IR 的哈希存下来，Agent 改一版就对比一次，任何非预期的变化都能立刻发现。

提示：如果你的场景强绑定某一家的硬件，直接用原生方案可能更省事。但只要你有"多后端"或"长期回归"的需求，eDSL 路线的收益会迅速超过前期投入。

2.3 Harness 的四个核心模块

我把 Harness 拆成四块，每块职责单一：

这四块串起来就是一个闭环：Agent 生成 → 约束层拦一道 → 执行层跑起来 → 校验层判对错 → 反馈层把结果喂回 Agent。Agent 下一轮就能带着"上次哪里错了"的信息继续改。这个闭环是整套东西的灵魂，缺了反馈层，Agent 就只是在盲猜。

3. 核心细节解析与实操要点：约束层和执行层怎么落地

3.1 约束层：把"能编译"和"能跑对"分开

新手最容易犯的错，是把所有检查都堆到运行之后。结果就是 Agent 生成一段代码，编译报错，你拿到一个几百行的模板报错，根本不知道从哪改。约束层的意义就是在编译之前，先把明显不合法的东西挡掉。

具体检查什么？我列一下自己实际用的清单：

• 维度一致性：Kernel 的线程块大小、共享内存大小、输入张量形状，三者必须自洽。比如你声明了block_size = 256，但共享内存按 128 个元素分配，这就是矛盾。
• 类型匹配：eDSL 里每个变量都有类型，Agent 经常把float和half混用。静态检查能在编译前抓到。
• 资源上限：每个后端对寄存器数、共享内存、线程数都有硬上限。超了要么编译失败，要么性能暴跌。约束层应该提前算一遍。
• 访问边界：数组下标、纹理坐标，这些越界访问在 GPU 上往往是静默错误（不报错但结果错），必须静态或动态插桩检查。

这里有个实操心得：约束层不要追求"全知全能"，要追求"快速失败 + 清晰原因"。我一开始想把所有规则都塞进去，结果约束层自己变成了一个几百行的怪物，维护成本比 Agent 还高。后来改成"只拦高频错误 + 每条规则独立可关"，清爽多了。

3.2 执行层：编译缓存是性能关键

执行层看着简单——编译、跑、收数据。但真跑起来，编译时间会吃掉你大部分预算。一个中等复杂度的 Kernel，从 eDSL 到后端二进制，编译可能要几秒到几十秒。如果 Agent 每轮都重新编译，迭代速度直接崩。

我的做法是两级缓存：

第一级是IR 缓存。eDSL 生成的 IR 做哈希，命中就直接复用，跳过前端。这一级能省掉大部分解析和类型检查时间。

第二级是二进制缓存。编译产物按"IR 哈希 + 后端 + 编译选项"做键存起来。同一段 Kernel 换个后端要重编，但同后端重复跑就直接加载。

实测下来，两级缓存能把平均迭代时间从十几秒压到一两秒。这个提升对 Agent 的迭代效率是决定性的——Agent 一轮快，你就能在同样时间里让它多试几十次。

注意：缓存键一定要包含编译选项。我踩过一次坑，改了优化等级但缓存没失效，结果拿旧二进制跑了一整天，数据全是错的。后来把编译选项的哈希也拼进键里才解决。

3.3 校验层：参考实现从哪来

校验层要判断 Agent 生成的 Kernel 对不对，就得有个"标准答案"。标准答案有三个来源，各有取舍：

• 手写参考实现：最可靠，但工作量大，而且手写实现本身可能有 bug。
• CPU 版本：把同样的计算用 CPU 跑一遍，作为基准。好处是容易写、容易调试；坏处是慢，而且浮点误差和 GPU 不完全一致。
• 高精度版本：用双精度或更高精度算一遍，作为"真值"，然后看 GPU 单精度结果落在误差范围内没有。

我一般用 CPU 版本做功能校验，用高精度版本做数值校验。功能校验看"结果对不对"，数值校验看"误差可接受吗"。两个都过才算通过。

误差阈值怎么定？这取决于你的计算类型。累加类操作（比如归约求和）误差会随规模增长，得用相对误差加绝对误差的组合判据。我通常设相对误差 1e-4、绝对误差 1e-5，超过就标记为可疑，人工看一眼。

3.4 反馈层：让 Agent 看得懂错误

反馈层是最容易被忽视、但价值最高的一块。Agent 拿到一个原始报错，和拿到一份结构化诊断，改代码的效率差好几倍。

我的反馈格式大概长这样：

{ "stage": "constraint", "rule": "dimension_mismatch", "location": "shared_memory_alloc", "expected": 256, "actual": 128, "hint": "共享内存元素数应等于 block_size，当前声明为 128 但 block_size 为 256" }

关键是那个hint字段——它把机器能理解的错误翻译成 Agent 能理解的建议。这个 hint 不用很智能，模板化就行，但一定要具体到"改哪个值、改成什么"。

4. 实操过程与核心环节实现：从零搭一个最小可用 Harness

4.1 环境准备与依赖梳理

先把环境说清楚。我用的组合是 LuisaCompute 作为计算框架，eDSL 层用它的 C++ 嵌入接口，Agent 侧接一个能输出结构化代码的模型接口。依赖上要注意几点：

• 编译器版本：eDSL 对宿主编译器版本敏感，太新太旧都可能出问题。我固定在某个 LTS 版本上，避免"昨天还能编今天就不行"。
• 后端 SDK：每个后端要装对应的驱动和工具链。这块最容易卡在"installing kernel"之类的环节——通常是驱动版本和工具链版本不匹配。
• Python 环境：如果 Harness 的调度部分用 Python 写，注意"不再支持与所选 kernel 关联的 python 版本"这类报错，本质是 Jupyter 或某个运行时绑定的解释器版本和当前环境不一致。解决办法是显式指定解释器路径，别依赖自动发现。

提示：环境这块我强烈建议用容器固化。Kernel/Shader 开发对工具链版本极其敏感，裸机环境迟早会乱。

4.2 约束层的代码骨架

约束层我用一个规则列表实现，每条规则是一个函数，输入是 Agent 生成的结构化描述，输出是通过或一条诊断。骨架大概这样：

class Constraint: def check(self, kernel_desc): raise NotImplementedError class DimensionConsistency(Constraint): def check(self, kernel_desc): block = kernel_desc["block_size"] smem = kernel_desc["shared_memory_elems"] if smem != block: return Fail( rule="dimension_mismatch", location="shared_memory_alloc", expected=block, actual=smem, hint=f"共享内存元素数应等于 block_size({block})，当前为 {smem}" ) return Pass() def run_constraints(desc, constraints): for c in constraints: r = c.check(desc) if isinstance(r, Fail): return r return Pass()

这个结构的好处是加规则就是加一个类，删规则就是删一个类，互不影响。我一开始用一个大函数写所有检查，后来规则一多就完全没法维护了。

4.3 执行层的编译与运行封装

执行层要处理的核心是"把 eDSL 描述变成能跑的东西，并收集数据"。流程是：

1. 从 Agent 输出解析出 Kernel 描述（结构化 JSON 或类似形式）。
2. 用 eDSL API 把描述翻译成实际的 Kernel 对象。
3. 查缓存，命中就加载，没命中就编译。
4. 准备输入数据，分配设备内存。
5. 启动 Kernel，同步等待完成。
6. 收集输出、耗时、资源占用。

第 5 步的同步等待有个坑：GPU 是异步的，如果你不等同步就取结果，拿到的可能是垃圾数据。我见过有人因为忘了同步，校验层一直报错，查了半天才发现是时序问题。所有性能计时和结果读取之前，必须显式同步。

计时也要注意：第一次运行往往包含初始化开销（比如上下文创建、内存分配），不能算进 Kernel 耗时。我的做法是预热跑几次，再正式计时取平均。这样数据才稳定可比。

4.4 校验层的对比逻辑

校验层的核心是对比。我一般这样组织：

def validate(gpu_result, cpu_result, rtol=1e-4, atol=1e-5): diff = abs(gpu_result - cpu_result) tol = atol + rtol * abs(cpu_result) bad = diff > tol if bad.any(): idx = bad.nonzero() return Fail( rule="numerical_mismatch", count=int(bad.sum()), max_rel_err=float((diff / (abs(cpu_result) + 1e-12)).max()), first_bad_index=idx[0] if len(idx) else None, hint="数值超出容差，检查归约顺序或精度类型" ) return Pass()

这里first_bad_index特别有用——它告诉你第一个出错的位置，往往能直接指向 bug 所在。比如第一个错的位置正好在某个边界，那大概率是边界处理有问题。

4.5 反馈层的组装与回灌

反馈层把前面各层的诊断汇总，按严重程度排序，然后拼成一段 Agent 能读的文本或 JSON。我一般按这个优先级排：

1. 约束层失败（最优先，因为根本没跑起来）
2. 编译失败
3. 运行崩溃
4. 数值校验失败
5. 性能不达标

Agent 拿到反馈后，下一轮就针对最高优先级的问题改。这个优先级顺序很重要——如果 Agent 同时看到"编译失败"和"性能不达标"，它应该先解决编译，因为性能数据在编译失败时根本没意义。

回灌的时候，我会把历史几轮的反馈也带上，让 Agent 知道"这个问题我改过几次了"。避免它在同一个坑里反复横跳。

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

5.1 编译类问题速查

"kernel header files not in any"这个报错我印象很深。它本质是构建系统找不到内核头文件目录。在 Linux 内核模块开发里，这通常意味着你没指定正确的内核源码路径。在 eDSL 场景里，类似的问题会表现为"找不到某个后端的内置头文件"。解决办法都是显式指定搜索路径，别依赖默认值。

5.2 运行类问题排查

运行阶段最烦的是"静默错误"——不崩溃，但结果不对。这类问题排查思路是二分定位：

先把输入规模缩到最小（比如 1 个元素），看结果对不对。如果小规模对、大规模错，那大概率是并行归约或同步的问题。如果小规模就错，那是基础逻辑问题。

然后逐步放大规模，找到第一个出错的规模。这个临界点往往能揭示问题——比如规模超过线程块大小时才错，那就是跨块同步没处理好。

注意：GPU 上的越界访问经常不报错，只是读到垃圾数据。所以校验层一定要覆盖边界情况，别只测"正常规模"。

5.3 性能类问题排查

性能不达标时，先别急着改代码，先确认测量方法对不对。我见过太多"性能问题"其实是测量问题：

• 没预热，第一次运行的初始化开销被算进去了。
• 没同步，计时器测的是"提交任务"的时间而不是"执行完成"的时间。
• 没排除数据传输，把主机到设备的内存拷贝时间也算进 Kernel 耗时了。

确认测量没问题后，再看 Kernel 本身。常见的性能瓶颈：线程块太小导致占用率低、共享内存 bank 冲突、全局内存访问不连续、分支发散。这些每个都能单独写一篇，这里不展开，但排查顺序建议是先看占用率，再看内存访问模式，最后看指令效率。

5.4 我踩过的三个坑

第一个坑：缓存键漏了编译选项。前面提过，改了优化等级但缓存没失效，白跑一天。教训是缓存键要包含所有影响产物的因素。

第二个坑：反馈信息太长。一开始我把完整报错原样喂给 Agent，结果它被几百行模板信息淹没，改不到点子上。后来改成只给结构化摘要加一句 hint，效果好太多。

第三个坑：约束层规则互相冲突。有两条规则对同一个字段提出了不同要求，导致合法代码被拒。后来我给规则加了优先级和互斥标记，冲突时按优先级裁决。

6. 扩展方向与个人经验

这套 Harness 搭起来之后，能扩展的地方很多。比如把性能数据也纳入反馈，让 Agent 不只追求"跑对"还追求"跑快"；比如把多个后端的测试结果横向对比，自动发现某个后端的特有问题；再比如把历史所有 Agent 的生成记录存下来，做失败模式分析，反过来优化约束层的规则。

我个人在实际操作中的体会是：Harness 的价值不在于它多智能，而在于它多稳定。Agent 可以很聪明，但如果 Harness 本身不稳定——今天能跑明天不能跑、同样的输入给不同的结果——那整个流程就没法信任。所以我在 Harness 上花的调试时间，比在 Agent 上多得多。这个投入是值得的，因为 Harness 一旦稳了，Agent 的迭代就是线性的、可预测的。

最后分享一个小技巧：给 Harness 加一个"最小复现"模式。当某个 Kernel 失败时，自动把它缩减到能复现问题的最小规模，然后把这个最小案例存下来。时间一长，你就有了一个失败案例库，既能用来回归测试，也能用来分析 Agent 的典型错误模式。这个库的价值，随着你跑的次数增加会越来越高。