1. 为什么我要用 Agent 来画一张 AI 芯片全栈软件地图
第一次听到“用 Agent 做一块 AI 芯片的全栈软件地图”这个说法，很多人会以为是在讲芯片设计自动化，其实不是。这里的“做”不是流片，而是用 Agent 把一颗 AI 芯片从驱动到框架、从运行时到算子库的整条软件栈梳理成一张可执行、可验证、可迭代的地图。我过去几年一直在做异构计算和芯片软件栈相关的工作，踩过不少坑，也见过太多团队在“软件栈到底包含哪些层、谁依赖谁、哪一层先跑通”这件事上反复扯皮。Agent 在这里的价值，不是替你写 Verilog，而是替你把散落在文档、代码仓库、issue 和口口相传里的软件栈知识，变成结构化的、可查询的、可自动补全的资产。
先说清楚这张“全栈软件地图”到底指什么。一颗 AI 芯片要真正跑起一个大模型推理任务，软件侧通常要经过这么几层：最底下是KMD（Kernel Mode Driver，内核态驱动），负责和硬件打交道、管理设备、处理中断和内存映射；往上是UMD（User Mode Driver，用户态驱动），负责命令提交、队列管理、内存分配策略；再往上是运行时（Runtime），比如各种推理引擎的 backend；然后是算子库和编译器，把高层算子 lowering 到芯片指令；最上面才是框架层，PyTorch、ONNX、TensorFlow 这些。每一层都有自己的接口、约束和调试手段，而“地图”要回答的核心问题是：一个算子从框架调用到最终在芯片上执行，中间经过了哪些模块、哪些数据结构、哪些同步点。
我之所以选择用 Agent 来做这件事，是因为传统方式做这张地图有三个绕不开的痛点。第一，信息源太分散：驱动代码在一个仓库，运行时在另一个仓库，算子库文档在内部 wiki，调试经验在老员工脑子里。第二，地图会过期：芯片迭代一版，UMD 的 ioctl 编号变了，KMD 的寄存器定义变了，地图如果靠人手维护，两周就废。第三，验证成本高：你画完一张调用链路图，怎么证明它是对的？只能靠人肉跑一遍，费时费力。Agent 恰好擅长这三件事：它能跨仓库检索和抽取信息，能按固定 schema 重新生成结构化输出，还能调用工具去实际验证某条链路是否走得通。
提示：这里说的 Agent 不是指某个特定产品，而是指“具备工具调用能力、能多步推理、能读写外部状态”的智能体。你可以用现成的 Agent 框架搭，也可以自己写编排逻辑，核心是让它围绕“软件栈地图”这个目标去干活。
适合看这篇内容的人，我大致分三类。第一类是刚接手 AI 芯片软件栈的工程师，你需要快速建立全局观，知道每一层大概长什么样、边界在哪。第二类是做 Agent 应用开发的同行，你想找一个真实、有深度、非玩具级的场景来练手，芯片软件栈这种“知识密集、结构性强、可验证”的领域非常合适。第三类是技术管理者或架构师，你在评估“用 Agent 管理复杂技术知识”到底靠不靠谱，这篇会给你一个可复现的参考路径。下面我会从整体设计、核心细节、实操过程到问题排查，完整讲一遍我是怎么做的。
2. 整体设计与思路拆解：地图的骨架怎么定
2.1 先定义地图的“坐标系”，再谈 Agent 怎么用
很多人一上来就让 Agent “帮我总结一下芯片软件栈”，结果得到一堆正确的废话。问题出在没有给地图定义坐标系。地图不是散文，它必须有固定的维度，否则每次生成的东西都对不齐。我最后定下来的坐标系是三个维度：层级（Layer）、实体（Entity）、关系（Relation）。
层级就是前面说的 KMD、UMD、Runtime、算子库、框架这几层，但我会再细一点，比如 UMD 里拆出“设备管理”“内存管理”“命令提交”三个子域。实体是每一层里的具体对象，比如 KMD 里的device_node、dma_buffer，UMD 里的command_queue、context。关系则是实体之间的依赖和调用，比如“UMD 的 command_queue 通过 ioctl 向 KMD 的 device_node 提交命令”。这三个维度定下来之后，Agent 的任务就变得非常明确：从代码和文档里抽取实体，判断它属于哪一层哪个子域，再抽取实体之间的关系。
为什么这么设计？因为我试过让 Agent 自由发挥，结果它会把“PyTorch 的 tensor”和“KMD 的 dma_buffer”混在一起讲，层级完全乱掉。有了坐标系之后，我可以在 Agent 的 prompt 里强制它输出 JSON，每个实体必须带layer、subdomain、name、source字段，每条关系必须带from、to、type、evidence字段。这样生成的地图才是机器可读、可对比、可增量更新的。这一点非常关键：地图的价值不在于好看，而在于能被程序消费，否则你没法做自动化验证。
2.2 为什么选“抽取-验证-回写”三段式，而不是一次性生成
我一开始的思路是让 Agent 读一遍所有仓库，直接吐出一张完整地图。实测下来问题很大：一是上下文塞不下，二是 Agent 会在长链路推理里“脑补”出不存在的调用关系，三是生成结果没法追溯。后来我改成三段式：抽取（Extract）、验证（Verify）、回写（Write-back）。
抽取阶段，Agent 只做一件事：针对某一个子域，从指定文件集合里抽出实体和关系，输出结构化 JSON。比如这一轮只处理“UMD 命令提交”，输入就是 UMD 仓库里cmd_submit.c、queue.c和对应的头文件。验证阶段，Agent 拿到抽取结果后，不是直接信，而是去代码里找证据：这条调用关系在哪个函数里、哪一行、有没有条件分支。如果找不到证据，这条关系就被标记为unverified。回写阶段，把验证过的实体和关系合并进主地图，冲突的地方打上conflict标记，留给人来裁决。
这个设计的核心考量是把 Agent 的“生成能力”和“验证能力”分开。生成的时候允许它发散，验证的时候强制它收敛。我踩过的坑是：如果让 Agent 一边生成一边自我验证，它很容易“自己说服自己”，把错的也验证成对的。分开之后，验证阶段我会换一个不同的 prompt，甚至换一个不同的模型，专门做“找茬”，准确率明显提升。
2.3 地图的存储格式：为什么最后选了图数据库而不是 Markdown
一开始我用 Markdown 存地图，人看着舒服，但一旦实体超过两百个，查询和更新就崩了。比如我想知道“所有依赖 dma_buffer 的 UMD 实体有哪些”，在 Markdown 里只能靠 grep，还容易漏。后来换成图数据库（我用的是 Neo4j，你也可以用 SQLite 加关系表，甚至用 JSON 文件加索引），实体是节点，关系是边，每个节点和边都带source、confidence、last_verified属性。
这么做的直接好处是：Agent 在验证阶段可以直接查图数据库，问“从 command_queue 到 device_node 是否已经存在一条路径”，避免重复抽取。另一个好处是增量更新变得可行：芯片迭代后，我只需要让 Agent 重新抽取变化的子域，然后做一次图 diff，就能知道哪些关系失效了。Markdown 做不到这一点，因为它是线性的，没有拓扑结构。当然，图数据库对小白有门槛，如果你只是想先跑通流程，用 JSON 文件加一个简单的查询脚本也够用，等实体规模上来了再迁移。
3. 核心细节解析与实操要点：每一层到底抽什么
3.1 KMD 层：从 ioctl 编号和寄存器定义入手
KMD 是整张地图的地基，也是最难抽的一层，因为它和硬件强相关，很多信息藏在寄存器手册和驱动代码的宏定义里。我的做法是以 ioctl 编号为锚点。KMD 通常会暴露一组 ioctl 给 UMD 调用，每个 ioctl 对应一个命令，比如ALLOC_BUFFER、SUBMIT_CMD、WAIT_FENCE。Agent 的任务是：从 KMD 头文件里抽出所有 ioctl 编号和对应的处理函数，再从处理函数里抽出它操作的硬件资源（寄存器、DMA 通道、中断号）。
这里有个细节：ioctl 编号在不同内核版本里可能变，所以 Agent 抽取时必须带上内核版本或 commit hash作为属性。我试过不带版本号，结果地图里同一个 ioctl 有两个编号，验证阶段直接冲突。另外，寄存器定义往往在单独的.h文件里，Agent 需要跨文件关联，这时候我会在 prompt 里明确告诉它“寄存器宏定义在regs/目录下，ioctl 处理函数在drivers/目录下，请建立映射”。如果不给这个提示，Agent 很容易只抽到函数名，抽不到寄存器。
注意：KMD 层抽取时，不要试图一次性抽完所有寄存器。寄存器动辄上千个，全抽进来地图会爆炸。我的经验是只抽被 ioctl 处理函数直接引用的寄存器，其余的先忽略。等地图主干稳定了，再按需扩展。
3.2 UMD 层：命令队列和内存管理是两条主线
UMD 是承上启下的一层，往上接运行时，往下接 KMD。我把它拆成两条主线来抽：命令队列和内存管理。命令队列这条线，Agent 要抽的是queue、command buffer、fence、event这些实体，以及它们之间的提交和同步关系。内存管理这条线，要抽的是buffer、heap、allocation、mapping这些实体，以及它们和 KMD 侧dma_buffer的对应关系。
为什么强调这两条线？因为实际调试中，百分之八十的问题出在命令提交和内存映射上。比如一个算子跑出错误结果，可能是命令队列的 fence 没等对，也可能是 buffer 的 cache 属性设错了。如果地图里这两条线是清晰的，排查时就能快速定位到“哦，这个 buffer 是从 UMD 的 heap 分配的，映射到 KMD 时用了 write-combine，但算子需要 coherent，所以数据不一致”。Agent 在抽取时，我会让它特别标注每个 buffer 的内存属性（coherent、cached、write-combine）和每个 fence 的同步语义（host-device、device-device）。
3.3 Runtime 与算子库：接口契约比实现更重要
到了 Runtime 和算子库这一层，代码量更大，但地图不需要抽到函数级。我的策略是只抽接口契约：Runtime 暴露给框架的 API 有哪些，每个 API 的输入输出是什么，它内部会调用 UMD 的哪些接口。算子库同理，只抽“算子名 -> 芯片指令序列”的映射关系，不抽指令的具体编码。
这么做的理由是：上层软件栈变化快，下层硬件相对稳定。如果地图抽到函数级，框架一升级，地图就得大改。只抽接口契约的话，框架升级通常只影响 API 签名，地图的改动量很小。Agent 在这一层的任务是：从 Runtime 的头文件里抽 API 列表，从实现文件里抽“这个 API 调用了哪些 UMD 接口”，然后建立跨层关系。我实测下来，这一层用 Agent 抽取的准确率最高，因为接口定义通常很规范，不像 KMD 那样充满宏和条件编译。
3.4 关系抽取的难点：如何区分“调用”和“依赖”
实体好抽，关系难抽。最难的是区分调用关系（call）和依赖关系（depend）。比如 UMD 的submit_command调用了 KMD 的ioctl，这是调用关系；但 UMD 的command_queue依赖 KMD 的device_node存在才能创建，这是依赖关系。两者在代码里可能都表现为函数调用，但语义完全不同。
我的解决办法是在 prompt 里给 Agent 明确的判定规则：如果 A 的函数体里直接出现了 B 的函数名，且 B 是跨层接口，判为 call；如果 A 的初始化或生命周期管理里需要 B 先存在，判为 depend。同时，我会让 Agent 输出evidence字段，把判定依据的代码片段贴出来。这样即使判错了，人工复核时也能快速纠正。这个规则不是完美的，但比让 Agent 自由发挥靠谱得多。踩过的坑是：有些关系既是 call 又是 depend，这时候我会让 Agent 输出两条边，分别标注类型，而不是强行合并。
4. 实操过程与核心环节实现：从零跑通一遍
4.1 环境准备与工具选型
先说环境。我用的是 Python 3.11，Agent 编排用的是 LangGraph（你也可以用别的，核心是支持多步和状态管理），图数据库用 Neo4j 5.x，代码检索用 ripgrep 加一个简单的 AST 解析器（Python 的ast模块对 C 代码不够用，我额外用了pycparser处理头文件）。模型方面，抽取阶段用了一个上下文窗口较大的模型，验证阶段换了一个推理能力更强的模型，具体名字不重要，你可以根据自己手头的资源选。
工具选型上，我强烈建议不要一上来就上重型框架。我最初用了一个功能很全的 Agent 平台，结果调试成本极高，一个 prompt 改动要等半天才能看到效果。后来换成 LangGraph 加自己写的工具函数，反而跑得更快。核心工具就四个：read_file（读代码）、search_code（正则或 AST 搜索）、query_graph（查图数据库）、write_graph（写图数据库）。Agent 的每一步推理，本质上就是在这四个工具之间切换。
提示：如果你只是想先验证思路，可以跳过图数据库，用 JSON 文件加一个
networkx内存图。等实体超过五百个再迁移到 Neo4j，迁移成本很低，因为节点和边的 schema 是一样的。
4.2 抽取阶段的完整流程与参数设置
抽取阶段我按子域分批跑，每个子域一个 Agent 任务。以“UMD 命令提交”为例，流程是这样的：第一步，Agent 调用search_code，在 UMD 仓库里搜索submit、queue、fence等关键词，拿到候选文件列表。第二步，Agent 对每个候选文件调用read_file，抽取实体和关系，输出 JSON。第三步，Agent 调用query_graph，检查抽到的实体是否已存在，避免重复。第四步，Agent 调用write_graph，把新实体和关系写入，标记confidence为medium，等待验证。
参数设置上，有几个关键点。上下文窗口：每个子域的输入代码量控制在模型窗口的百分之六十以内，留出空间给 prompt 和输出。温度：抽取阶段温度设 0.2，允许一点点发散；验证阶段设 0，强制确定性。重试次数：如果 Agent 输出的 JSON 解析失败，自动重试两次，第二次在 prompt 里附上解析错误信息。我实测下来，JSON 解析失败率大概在百分之五左右，主要是模型偶尔会加注释或尾逗号，重试基本能解决。
4.3 验证阶段：怎么让 Agent 自己找自己的茬
验证阶段是整个流程里最容易被忽视、但价值最高的环节。我的做法是：抽取阶段结束后，把生成的 JSON 喂给一个全新的 Agent 会话，prompt 里明确说“你的任务是找出这些实体和关系里的错误，每条关系都必须有代码证据，找不到证据的标记为 unverified”。这个 Agent 不允许修改实体，只能标记和补充证据。
具体验证逻辑分三层。第一层是存在性验证：实体名是否真的在代码里出现，关系两端的实体是否都存在。第二层是语义验证：这条关系是 call 还是 depend，类型标对了吗。第三层是一致性验证：同一个实体在不同子域里的属性是否冲突，比如command_queue在命令提交子域里标记为per-context，在内存管理子域里标记为global，这就是冲突，需要人工裁决。
我踩过的一个坑是：验证 Agent 有时候会“过度验证”，把一些正确的弱关系也标成 unverified，因为它找不到直接的代码证据。后来我在 prompt 里加了一条规则：“如果关系是通过数据结构成员间接建立的，允许标记为inferred，但必须说明推断路径”。这样既保留了弱关系，又不会让它们污染强关系。
4.4 回写与增量更新：地图怎么保持不过期
回写阶段的核心是冲突处理。新抽取的关系和已有关系冲突时，我不会让 Agent 自动覆盖，而是写入一个conflict队列，附上两边的证据，留给人来裁决。裁决之后，人工在数据库里更新，并记录裁决理由。这个理由很重要，因为下次 Agent 再抽到同样的冲突时，可以读取历史裁决，避免重复提问。
增量更新方面，我做了两件事。第一，给每个实体和关系加last_verified时间戳，超过一定时间（比如三个月）的标记为stale，下次抽取时优先重新验证。第二，监听代码仓库的 commit，如果某个子域的文件有变更，自动触发该子域的重新抽取。这样地图就能跟着代码走，而不是靠人记得去更新。实测下来，一个中等规模的芯片软件栈，全量抽取大概需要两到三小时，增量更新通常十分钟以内就能跑完。
5. 常见问题与排查技巧实录
5.1 Agent 抽取结果层级混乱怎么办
这是最常见的问题。表现是 Agent 把 UMD 的实体标成了 KMD，或者把 Runtime 的 API 标成了算子库。根本原因是层级边界在代码里不是显式标注的，Agent 只能靠目录结构和命名习惯猜。我的解决办法是在 prompt 里给一个层级判定表，明确列出每一层的目录特征和命名特征。比如“路径包含drivers/kernel/的判为 KMD，路径包含drivers/user/的判为 UMD，路径包含runtime/的判为 Runtime”。同时，我会让 Agent 在不确定时输出layer: unknown，而不是硬猜。unknown 的实体后续人工补标，比标错了再改成本低得多。
5.2 关系抽取漏掉间接调用怎么补
间接调用是关系抽取的老大难。比如 A 调用 B，B 调用 C，但 A 和 C 之间没有直接调用，地图里就缺了 A 到 C 的路径。我的做法是在验证阶段加一个“路径补全”步骤：Agent 查图数据库，找出所有长度为 2 的路径，然后去代码里验证这条路径是否真实存在（即 B 是否真的在 A 和 C 之间起桥梁作用）。如果存在，就补一条indirect_call关系。这个步骤能补出不少隐藏的依赖，尤其是跨层调用。注意，补全的关系要标记inferred，和直接抽取的关系区分开。
5.3 地图规模大了之后查询变慢怎么优化
实体超过一千个之后，图数据库的查询开始变慢，尤其是多跳查询。我做了三个优化。第一，给高频查询建索引，比如按layer和subdomain建复合索引。第二，预计算常用路径，比如“从框架 API 到 KMD ioctl 的所有路径”，存成物化视图，查询时直接读。第三，分层加载，Agent 查询时默认只加载当前子域和相邻子域，跨子域查询才加载全图。这三个优化下来，查询延迟从秒级降到毫秒级。如果你用的是 JSON 文件，优化手段类似，核心是别每次都全量加载。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查思路 | 解决办法 |
|---|---|---|---|
| 实体层级标错 | 目录特征不明显 | 检查实体所在文件路径 | 补充层级判定表，允许 unknown |
| 关系类型混淆 | call 和 depend 判定规则不清 | 查看 evidence 字段 | 明确判定规则，输出两条边 |
| JSON 解析失败 | 模型输出格式不稳 | 检查原始输出 | 降低温度，加重试，附错误信息 |
| 验证过度标记 | 弱关系找不到直接证据 | 查看 inferred 规则 | 允许 inferred，说明推断路径 |
| 地图更新滞后 | 没有监听代码变更 | 检查 last_verified | 加 commit 监听，自动触发重抽 |
| 查询变慢 | 全量加载，无索引 | 看查询计划 | 建索引，预计算路径，分层加载 |
5.5 几个我踩过的坑和独家技巧
第一个坑是过早追求全自动化。我一开始想让 Agent 从抽取到验证到回写全自动跑，结果错误累积，地图越跑越乱。后来改成“抽取自动、验证半自动、回写人工确认”，准确率大幅提升。第二个坑是忽略代码版本。有一次芯片迭代，KMD 的 ioctl 编号变了，但地图没更新，导致排查问题时对着旧地图找，浪费了半天。后来强制每个实体带版本号，问题就解决了。
独家技巧方面，分享两个。第一，用“反例”训练 Agent。我会在 prompt 里放几个典型的错误抽取案例，告诉 Agent“这种是错的，不要这么抽”。这比只给正例效果好得多。第二，让 Agent 输出“不确定”。很多 Agent 应用追求“什么都能答”，但在软件栈地图这个场景里，承认不确定比瞎猜更有价值。我会在 prompt 里明确说“如果你不确定，输出 unknown，不要编造”。实测下来，unknown 的比例大概在百分之十左右，这百分之十人工补标的成本，远低于纠正错误抽取的成本。
6. 地图做出来之后能干什么
地图跑通之后，最直接的用途是新人 onboarding。以前新人要花两周才能搞清楚软件栈的调用链路，现在对着地图查，两天就能上手。第二个用途是故障排查。线上出问题时，从报错的 API 出发，沿着地图往下查，能快速定位到是 UMD 的队列问题还是 KMD 的内存问题。第三个用途是变更影响分析。要改 UMD 的某个接口时，先查地图，看哪些 Runtime API 依赖它，评估影响范围。
再往远一点，这张地图还能喂给 Agent 做自动问答。比如工程师问“我想加一个新的算子，需要改哪些层”，Agent 查地图就能给出从算子库到 KMD 的完整改动清单。这个场景我还在打磨，目前的准确率大概在百分之七十左右，主要卡在算子库到指令序列的映射还不够细。但方向是清楚的：地图是知识的骨架，Agent 是骨架上的肌肉，两者结合，才能让芯片软件栈这种复杂系统变得可理解、可维护、可演进。
最后分享一个我在实际操作中的体会：做这张地图最大的阻力不是技术，而是信息源的碎片化。很多关键信息不在代码里，而在邮件、聊天记录和口头约定里。Agent 能处理代码和文档，但处理不了“老张说这个 fence 要等两拍”这种隐性知识。所以我的建议是，先把代码和文档里的显性知识抽干净，再用人来补隐性知识，不要指望 Agent 一步到位。地图的价值不在于一次做完美，而在于它能持续迭代，每次迭代都比上一版更接近真相。
