推理优化知识库设计:让 agent 之间传承优化经验
不同 agent 在不同模型、不同硬件上做推理优化,踩过的坑和找到的技巧,怎样沉淀下来、去伪存真、及时淘汰过时内容,并让下一个 agent 会话直接继承。
1. 结论
适用条件包括硬件、软件版本、模型和精度。这样设计是因为推理优化的知识主要因为版本变化而过时:「某技巧在 TensorRT 10.x + Thor 上有效」,换到 11.x 可能就不成立了。所以过时检测主要盯版本漂移,不能只看写入时间。
它和 agent 工程规范仓库分工明确:规范仓库管「agent 该怎么干活」,知识库管「这个领域里什么是对的」。agent 通过同一个命令行工具查询和提交知识,不管是 Claude、Codex 还是 Cursor,用法都一样。人看的 Wiki 和 HTML 索引页由同一批卡片自动生成,不需要另外维护。
flowchart LR ST["agent 开始任务"] -->|"kb query
按硬件 / 模型 / 技巧"| KBS[("知识库
active 卡片")] ST --> WK["优化工作
边做边记证据"] WK -->|"kb propose
附证据"| INB["inbox 候选"] INB --> GATE{"质量门禁
自动检查 + 评审 agent + 人"} GATE -->|"通过 / 合并"| KBS GATE -->|"拒绝"| DROP["丢弃"] ST -->|"kb feedback
有效 / 无效"| KBS KBS --> GOV["治理任务
版本漂移 / TTL / 冲突 / 负反馈"] GOV -->|"needs-review / 复验"| KBS KBS -->|"kb build"| PUB["Wiki · HTML 索引 · agent 索引"]
2. 存什么、不存什么
| 存 | 不存 |
|---|---|
| 实测过的结论:「FP8 ViT 在 Thor 上比 FP16 快 1.7×,精度掉 0.3%」 | 没验证过的猜测(最多作为草稿留在 inbox) |
| 踩坑记录:现象 → 根因 → 正确做法 | 某一个仓库里的实现细节 |
| 硬件事实与限制:SM 数、带宽、某指令是否支持 | 大段源码、权重、engine 产物 |
| 验证过的流程:某类模型的优化步骤 | 对话记录原文 |
| 选型决定及理由 | 只适用于一次性环境的临时绕过办法 |
3. 仓库结构
AiInfraKB/
kb.toml # TTL 策略、发布配置
schema/card.schema.json # 卡片 frontmatter 的校验规则
vocab/ # 受控词表,保证不同 agent 用同一套名字
hardware.yaml # thor / orin / b200 / h100 …(含架构等属性)
software.yaml # tensorrt / cuda / tvm / vllm …及「当前版本」
models.yaml # pi05 / qwen / llama …
techniques.yaml # fp8-quant / kv-cache / cuda-graph / kernel-fusion …
cards/
facts/ # 硬件、软件的客观事实
lessons/ # 踩坑:现象 → 根因 → 做法
techniques/ # 优化技巧与最佳实践
benchmarks/ # 实测数据(带完整环境)
decisions/ # 选型决定与理由
playbooks/ # 多步流程,串起多张卡(如「在 Thor 上优化 VLA」)
evidence/ # 证据:ncu / nsys 摘要、bench 输出、复验脚本
inbox/ # agent 提交的候选,等审核
archive/ # 已废弃或被取代的卡(保留历史,默认不返回给 agent)
templates/ # 5 类卡片模板
tools/kb.py # CLI:lint / build,后续加 query / propose / feedback / govern
tests/
受控词表很关键。一个 agent 写 Jetson Thor、另一个写 thor,就检索不到同一条知识。kb lint 会拒绝词表里没有的名字,新名字必须先进词表。
4. 知识卡格式
---
id: kb-0142
type: lesson # fact | lesson | technique | benchmark | decision
title: Thor 上 SigLIP ViT 用 FP8 时 LayerNorm 必须留 FP16
status: active # draft | active | needs-review | deprecated | superseded
claim: 整体量化为 FP8 使动作误差升高 4 倍;LayerNorm 保持 FP16 后误差回到基线,延迟只多 3%。
applies_to:
hardware: [thor]
software: {tensorrt: ">=10.8,<11", cuda: ">=13.0"}
models: [pi05]
techniques: [fp8-quant]
precision: [fp8]
not_applies_to: INT8 量化路径未测
evidence:
- kind: benchmark # benchmark | profile | experiment | source | doc
ref: evidence/kb-0142/vit-fp8.md
env: {gpu: thor, clocks: locked, repo_commit: abc1234}
result: {latency_ms: 11.2, baseline_ms: 10.9, action_mse_ratio: 1.02}
verify: python bench/vit_fp8.py --ln-fp16 --check # 可重跑的复验命令
confidence: measured # inferred | measured | reproduced(两次独立复现)
authors: ["agent:claude", "human:xiaoan"]
created: 2026-10-12
last_verified: 2026-10-12
review_by: 2027-04-10 # last_verified + 该类型的 TTL
visibility: private # 只有 public 的卡片会发布出去
related: [kb-0098]
---
## 结论
## 适用条件
## 证据
## 复现
几条硬性要求:
claim必须是一句可证伪的话,带数字或明确条件。「FP8 很好用」这种写法会被拒。applies_to必填,并且只能用词表里的名字。正是它让卡片能被检索到,也能被判断是否过时。- 证据必须带环境指纹:硬件、频率是否锁定、驱动版本、代码 commit。不知道在什么环境下测的数字,没法复验。
- 一张卡只讲一个问题。新证据追加到已有卡片里,不另开新卡。
5. agent 工作流
5.1 开工前:先查
kb query --hardware thor --model pi05 --technique fp8-quant kb query --text "attention 融合 精度下降" kb show kb-0142
- 默认只返回
active卡片,按「条件匹配度 × 置信度 × 是否最近验证过」排序;needs-review的卡片附带警告。 - 返回精简版(结论 + 适用条件 + id),需要细节再
kb show,避免一次占满上下文。 - 第一版用结构化过滤加全文检索(SQLite FTS)就够了,卡片上千后再考虑向量检索。
5.2 工作中:边做边留证据
每做一次有意义的实验,就把命令、环境、结果写进 evidence/。证据要在当时就记下来,事后很难补全。
5.3 收尾:提交候选和反馈
kb propose --type lesson --from-template kb feedback kb-0142 --worked --env thor/trt10.9 # 查到的卡这次有没有用
propose 强制填写 claim、适用条件和至少一条证据,结果写进 inbox/。触发方式沿用规范仓库的思路:加一条规范和一个 kb-usage 技能,规定「优化任务开始先查、结束必须提交和反馈」,再同步到各仓库,每个新会话都会自动带上这套流程。
6. 质量门禁:筛出真正有用的知识
| 关卡 | 检查什么 | 谁来做 |
|---|---|---|
| 1. 格式 | 字段齐全、名字都在词表里、claim 里有数字或明确条件、证据文件存在 | kb lint(自动) |
| 2. 去重 | 已有卡片的 claim 和适用条件高度相似 → 改成给旧卡追加证据 | kb review(自动建议) |
| 3. 冲突 | 和已有卡片在相同条件下结论相反 → 两张都标 needs-review | 自动检测 |
| 4. 价值 | 能否跨模型或跨仓库复用;是否比基线有可观提升,或者是代价很高的坑 | 评审 agent |
| 5. 对抗审查 | 换一个模型的 agent,专门找证据不足、条件写宽了、有反例的地方 | 评审 agent |
| 6. 合入 | 有实测证据、无冲突可以先进 draft;变成 active 需要人批准 | 人 |
被第二次独立复现的卡片,置信度从 measured 升到 reproduced,检索时排得更靠前。
7. 知识治理:防止过时
7.1 生命周期
stateDiagram-v2
[*] --> draft: propose 通过格式检查
draft --> active: 人工批准
active --> needs_review: 版本漂移 / TTL / 负反馈 / 冲突
needs_review --> active: 复验通过
needs_review --> deprecated: 复验失败
active --> superseded: 新卡取代
deprecated --> [*]: 移入 archive
superseded --> [*]: 移入 archive
7.2 什么会触发复审
| 触发 | 规则 | 例子 |
|---|---|---|
| 版本漂移(最重要) | 词表登记各软件的当前版本;当前版本落到卡片 applies_to 范围之外 → needs-review | TensorRT 升到 11.0,所有写着 <11 的卡片进入复审 |
| TTL 到期 | 按类型设有效期:硬件事实 2 年,benchmark 和踩坑 6 个月,技巧 3 个月 | 超过 review_by |
| 负反馈 | 有 agent 反馈「按这张卡做了,没效果」 | 累计 1–2 次就复审 |
| 冲突 | 新卡和旧卡在相同条件下结论相反 | 同时复审两张 |
| 证据失效 | 引用的链接、commit、文件找不到了 | 定期检查 |
7.3 怎么复验
- 有
verify命令的卡片:定时治理任务在对应硬件上重跑,结果一致就更新last_verified。 - 没有的:治理 agent 对照新版本的文档和发布说明判断,写明「推断复验」,置信度降一级。
- 只做「取代」,不做「删除」。旧卡移进
archive/并保留指向新卡的链接,因为「为什么以前这样做、后来改了」本身也是知识。
7.4 冲突怎么裁决
- 条件更具体的优先(
thor + trt10.9优先于thor)。 - 条件相同时:实测优先于推断,复现过的优先于单次测量,较新的优先于较旧的。
- 如果真正的差别在条件上,就把一张卡拆成两张,各自写清楚适用范围。
7.5 健康指标
kb govern --report 输出:active 卡片数、处于 needs-review 的比例、30 天内被查询次数、查询后反馈「有效」的比例、候选从提交到审核的平均时长。有效率是最终衡量指标:沉淀的知识有没有真的帮到后来的 agent。
8. 发布:Wiki 和 HTML 索引
kb build 先跑 kb lint,零错误才构建,从同一批卡片生成三份产物:
| 产物 | 给谁看 | 内容 |
|---|---|---|
| MkDocs Wiki 源文件 | 人 | 每张卡一页,顶部显示状态、置信度、最后验证日期;非 active 的卡片加醒目横幅;按硬件、模型、技巧生成索引页 |
| HTML 索引页 | 人 | 单页表格,可按关键字和状态过滤;index.json 沿用本站门户的数据格式,可以直接挂成一个主题 |
INDEX.md | agent | 只列 active 卡片的精简目录,供不能调用 CLI 的 agent 渐进式读取 |
visibility: public 才会进入 kb build --public-only 的产物,再发布到站点。
9. 知识在不同 agent 之间迁移
- 内容与工具无关:卡片是纯 Markdown + YAML,不绑定任何一家 agent。
- 接口统一:所有 agent 都通过
kb命令行工具读写,后期再包一层 MCP server。 - 流程统一:「先查、留证据、提交、反馈」写在规范仓库里,通过同步分发,新会话一开就带着。
- 记录来源:
authors记下是哪个 agent、哪个模型写的,方便以后判断哪类来源的知识更可靠。
10. 实施分期
| 阶段 | 内容 | 验收 |
|---|---|---|
| P0 | 仓库框架:schema、词表、5 类卡片模板;kb lint、kb build(Wiki + HTML + agent 索引) | lint 能拒掉不合格的卡片;能看到生成的 Wiki 页和索引页 |
| P1 | kb query / show / propose / feedback;规范仓库加 kb-usage 技能,同步到 1 个仓库 | 新会话在优化任务里能查到卡片,结束时提交了候选 |
| P2 | 治理:版本漂移扫描、TTL、冲突检测、负反馈触发;kb review 评审 agent;定时治理任务 | 把 TensorRT 当前版本改高,相关卡片自动进入 needs-review |
| P3 | verify 自动复验、MCP server、向量检索、健康指标看板 | 有 verify 命令的卡片能定时自动复验 |
每个阶段都先给数据流图、类图和测试,review 通过后再写实现。