首页 / AI Native / Agent Kernel / 推理优化知识库

推理优化知识库设计:让 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 产物
验证过的流程:某类模型的优化步骤对话记录原文
选型决定及理由只适用于一次性环境的临时绕过办法
判断标准:换一个 agent、换一个模型来做事,这条知识还能帮它少走弯路,就值得存。

3. 仓库结构

AiInfraKB/
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. 知识卡格式

cards/lessons/kb-0142.md
---
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]
---

## 结论
## 适用条件
## 证据
## 复现

几条硬性要求:

5. agent 工作流

5.1 开工前:先查

shell
kb query --hardware thor --model pi05 --technique fp8-quant
kb query --text "attention 融合 精度下降"
kb show kb-0142

5.2 工作中:边做边留证据

每做一次有意义的实验,就把命令、环境、结果写进 evidence/。证据要在当时就记下来,事后很难补全。

5.3 收尾:提交候选和反馈

shell
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-reviewTensorRT 升到 11.0,所有写着 <11 的卡片进入复审
TTL 到期按类型设有效期:硬件事实 2 年,benchmark 和踩坑 6 个月,技巧 3 个月超过 review_by
负反馈有 agent 反馈「按这张卡做了,没效果」累计 1–2 次就复审
冲突新卡和旧卡在相同条件下结论相反同时复审两张
证据失效引用的链接、commit、文件找不到了定期检查

7.3 怎么复验

7.4 冲突怎么裁决

  1. 条件更具体的优先(thor + trt10.9 优先于 thor)。
  2. 条件相同时:实测优先于推断,复现过的优先于单次测量,较新的优先于较旧的。
  3. 如果真正的差别在条件上,就把一张卡拆成两张,各自写清楚适用范围。

7.5 健康指标

kb govern --report 输出:active 卡片数、处于 needs-review 的比例、30 天内被查询次数、查询后反馈「有效」的比例、候选从提交到审核的平均时长。有效率是最终衡量指标:沉淀的知识有没有真的帮到后来的 agent。

8. 发布:Wiki 和 HTML 索引

kb build 先跑 kb lint,零错误才构建,从同一批卡片生成三份产物:

产物给谁看内容
MkDocs Wiki 源文件人每张卡一页,顶部显示状态、置信度、最后验证日期;非 active 的卡片加醒目横幅;按硬件、模型、技巧生成索引页
HTML 索引页人单页表格,可按关键字和状态过滤;index.json 沿用本站门户的数据格式,可以直接挂成一个主题
INDEX.mdagent只列 active 卡片的精简目录,供不能调用 CLI 的 agent 渐进式读取
公开范围:默认只在本地构建。卡片标了 visibility: public 才会进入 kb build --public-only 的产物,再发布到站点。

9. 知识在不同 agent 之间迁移

10. 实施分期

阶段内容验收
P0仓库框架:schema、词表、5 类卡片模板;kb lint、kb build(Wiki + HTML + agent 索引)lint 能拒掉不合格的卡片;能看到生成的 Wiki 页和索引页
P1kb query / show / propose / feedback;规范仓库加 kb-usage 技能,同步到 1 个仓库新会话在优化任务里能查到卡片,结束时提交了候选
P2治理:版本漂移扫描、TTL、冲突检测、负反馈触发;kb review 评审 agent;定时治理任务把 TensorRT 当前版本改高,相关卡片自动进入 needs-review
P3verify 自动复验、MCP server、向量检索、健康指标看板有 verify 命令的卡片能定时自动复验

每个阶段都先给数据流图、类图和测试,review 通过后再写实现。