[RFC] 优化模型推理知识的分类、结构和检索范围

状态： Draft
RFC 类型： 知识库结构、治理和检索能力调整
目标仓库： cannbot-knowledge
编制日期： 2026-10-12
关联范围： knowledge/model/inference/**、推理知识的 Schema/Registry/Contract、Query/Lint 和 retrieval eval

1. 摘要

当前 cannbot-knowledge 已经形成了较完整的模型推理知识树，覆盖模型、模块、Kernel、框架、并行、平台、量化、优化、性能和故障诊断。

本 RFC 不推翻现有 OKF Bundle、domain/route/Profile 体系，而是对模型推理领域做一次增量重构：

1. 明确 Concept、Guide、Optimization、Runbook、Case 和 Benchmark Observation 的职责边界；
2. 取消 experience 作为模糊的中间分类层；
3. 增加模型推理场景的结构化范围信息，支持按 Prefill/Decode、高吞吐/低时延、模型结构、执行模式和服务形态检索；
4. 统一规则、案例、反模式、benchmark 和 Runbook 的正文模板；
5. 补齐 status、verified 和证据强度的实际使用；
6. 建立模型推理知识的迁移、去重、废弃和检索回归流程。

目标是让知识库能够回答以下问题，而不依赖 Agent 阅读大量无关卡片：

• 这个优化适用于哪个模型结构、哪个阶段和哪个硬件？
• 它面向高吞吐还是低时延？
• 它是通用规则、单模型案例还是一次 benchmark 观测？
• 结论来自官方文档、固定版本源码、运行时观测还是仓库自报数据？
• 当前 CANN/torch_npu/框架版本是否仍然适用？

2. 当前问题与修改必要性

2.1 当前内容规模较大，但知识类型和主题维度混杂

截至本 RFC 评审基线，knowledge/model/inference 约有 343 个 Markdown 文件，包含约 91 个 Concept、22 个 Guide、110 个 Optimization 和 94 个 Runbook。

现有目录整体可用，但存在以下结构问题：

concepts/techniques/
optimizations/experience/rules/
optimizations/experience/cases/
optimizations/experience/anti_patterns/
optimizations/experience/benchmark_observations/
guides/experience/interventions/

其中 experience、interventions 等目录名没有明确的机器语义，导致新知识的归档选择依赖个人判断。相同技术可能同时出现在 concepts/techniques、optimizations/rules、optimizations/cases 和 guides/experience 中，但没有稳定的选择规则。

具体示例：

• Multi-stream 同时有机制概念 concepts/techniques/multi_stream.md、优化规则 optimizations/experience/rules/decode_multi_stream_overlap_core_balance.md、模型案例 optimizations/experience/cases/moe_multi_stream_limit_core_num.md 和任务型 Guide guides/experience/interventions/prefill_micro_batch_dual_stream_moe_overlap.md。
• 图模式 同时有图模式概念、图模式启用决策规则、Graph Break 处理 Guide，以及图模式重编译/运行时 Runbook。
• MTP 同时有 MTP 机制概念、MTP 时延规则、单模型 MTP 案例和 MTP 接入 Guide。

这些位置并不一定都是错误的重复：它们可能分别表达机制、规则、案例和流程。当前真正的问题是没有定义“哪个文件拥有规范性结论、其他文件只能引用还是可以复制正文”的规则，导致同一条结论容易在多个位置各自维护。

2.2 推理场景维度没有结构化

模型推理优化知识实际需要按以下维度筛选：

• Prefill / Decode；
• 高吞吐 / 低时延 / 显存 / TTFT / TPOT；
• 单用户 / 小 batch / 大 batch / 高并发；
• Dense / MoE / MLA / DSA / DiT / 多模态；
• eager / GE Graph / npugraph_ex；
• offline / online / PD；
• BF16 / W8A8 / FP8 / MXFP4；
• A2 / A3 / Ascend 950。

当前主要依赖标题、description、正文和 tags 表达这些信息。tags 的治理职责是 task/topic，无法稳定承载完整的推理场景过滤。

2.3 生命周期和证据状态没有充分发挥作用

当前推理知识卡片基本都处于 stable 状态。静态审查发现，推理知识中没有实际使用 Frontmatter verified 事件。这个问题说明机器可检索的以下信息不完整：

• 是否在真实硬件上复核过；
• 是否有人审阅过；
• 结论是官方事实、源码事实、单次观测还是迁移推断。

本 RFC 不新增、不推广 cann_versions 字段，也不把版本字段作为本次迁移或验收要求。版本边界继续沿用现有治理规范；需要版本信息的卡片可以在正文和固定 commit 来源中说明，是否单独使用 cann_versions 留待后续独立变更评估。

模型推理知识尤其容易受到硬件代际、算子版本、图后端和量化格式变化影响，需要更严格的范围和生命周期表达。

2.4 Benchmark 观测和可复用规则边界不清

benchmark_observations 当前位于 optimizations 下，并使用 Optimization 类型。一次特定 batch、卡数和模型配置下的性能观测，容易被检索为普遍可迁移的优化规则。

需要明确区分：

• 观察到的一个结果；
• 可迁移的优化方法；
• 经过多次验证的经验规则；
• 仍未复现的仓库自报数据。

3. 目标与非目标

3.1 目标

• 保留当前 knowledge/model/inference 的 domain/route/Profile 主体结构；
• 明确知识卡职责和归档决策；
• 让推理知识可以按场景和平台稳定检索；
• 让 Agent 能区分事实、规则、案例、观测和诊断流程；
• 降低重复建卡、错放路径和错误泛化；
• 支持未来将 cann-recipes-infer/.agents 作为执行层接入本知识仓；
• 保持现有 Query、Lint、OKF Bundle 和导航契约兼容，采用渐进式迁移。

3.2 非目标

• 本 RFC 不重建整个 cannbot-knowledge 仓库；
• 不新增训练知识、算子源码知识或通用 CANN API 知识的分类；
• 不把模型代码、profiling 原始文件或权重提交进知识正文；
• 不在第一阶段新增大量新的 OKF Profile；
• 不把所有已有卡片一次性自动改写成新结构；
• 不改变默认 Query 的安全和权限边界。

4. 设计方案

4.1 保留当前顶层分类

保留以下主结构：

knowledge/model/inference/
├── concepts/
├── guides/
├── optimizations/
├── runbooks/
└── index.md

concepts 继续按知识对象分类：

concepts/
├── frameworks/
├── kernels/
├── models/
├── modules/
├── parallelism/
├── platforms/
├── quantization/
└── techniques/

这部分已经能够覆盖模型推理的主要主题，不在本 RFC 中大范围重命名。

4.2 优化经验目录调整

将当前经验目录逐步归并为：

guides/
├── bringup/
├── deployment/
├── integration/
├── models/
└── optimization/

optimizations/
├── rules/
├── cases/
├── anti_patterns/
└── benchmark_observations/

runbooks/
├── compilation/
├── performance/
├── precision/
├── runtime/
└── validations/

第一阶段可以保留原路径兼容已有链接，新增知识不再使用 experience 作为新入口。第二阶段再通过 merge、split、deprecate 和 replaced_by 逐步迁移旧卡片。

路径变化会改变 Concept ID。所有移动必须同步：

• 正文内部链接；
• 各级 index.md；
• replaced_by；
• retrieval eval 中的期望路径；
• 相关 Issue、PR 和日志。

4.3 知识类型职责定义

这些类型不是互斥的“内容主题”，而是同一主题的不同知识视图。允许多个类型围绕同一技术存在，但必须指定一个规范性来源，其他卡片只能补充上下文、证据或操作入口，不能复制并维护同一条规则。

类型	负责内容	不负责内容
Concept	定义、机制、职责边界、稳定事实	单次故障处置、单次 benchmark
Guide	围绕一个目标任务串联多个知识卡的完整流程、输入、步骤和验收	独占某条技术规则，或复制多个规则的完整正文
Optimization	可复用的触发条件、决策、优化方法、收益来源、代价和失效边界	未归因的单次性能数据、某一次任务的完整过程
Runbook	症状、探针、诊断路径、修复、验证和回退	只有背景介绍的概念说明
Case	特定模型/硬件/版本/commit 下对一个或多个 Optimization 的实施证据、差异和结果	重新定义通用规则，或只复制规则正文
Benchmark Observation	固定 workload 下的可复核观测和指标	跨场景泛化的结论
Anti-pattern	已知会导致错误、性能失真或无效优化的做法、信号和影响	完整的诊断步骤或修复流程

具体规则：

• 一个完整流程可以同时是 Guide 的候选，但只有当它面向一个任务、串联多个知识卡并提供统一验收时，才建立 Guide；单个优化点即使有实施步骤，仍优先使用 Optimization。
• Case 不是第二种 Optimization。Case 必须引用适用的 Optimization/Runbook，只记录当前模型的条件、改动差异、证据和结果；如果 Case 中发现了可跨模型复用的结论，再单独提炼为 Optimization。
• Anti-pattern 可以由轨迹、失败日志或 benchmark 失真中发现。如果它包含完整的“症状 → 探针 → 修复 → 验证”，规范流程应落为 Runbook；Anti-pattern 只保留错误模式、影响、快速识别信号和到 Runbook 的链接。
• Guide、Case、Anti-pattern 和 Runbook 都允许引用同一个规范 Optimization，但不复制其规则正文。

Guide 的预期示例包括：

• 一个模型从迁移、配置、并行、KVCache、图模式到验收的完整部署流程；
• MTP/投机解码接入流程；
• 多机 DP+EP MoE 的阶段对齐、通信改造和验证流程。

这些 Guide 的价值在于串联多个 Concept、Optimization 和 Runbook，并定义输入、步骤和最终验收；其中的单个优化点仍由被引用的 Optimization 负责。

第一阶段不新增 Case 和 Benchmark Observation 的新 OKF Profile。它们先分别作为 optimizations/cases 和 optimizations/benchmark_observations 下的受控内容类型，待 Query 真实需要按类型过滤时再评估新增 Profile。

4.3.1 知识提取前的去重门禁

知识生产不能直接按标题新建卡片。knowledge-ingest 在 create 前必须执行：

1. 按规范化主题、别名、路径、tags 和正文关键词查询候选卡；
2. 判断是 create、update、merge、split、deprecate 还是 defer；
3. 生成候选卡时标记规范性来源、引用卡和新增事实；
4. 禁止通过复制已有规则正文来“形成新案例”或“补充新 Guide”；
5. 对存在冲突的卡片保留冲突并提交人工决策，不自动合并。

去重采用“候选检索 + Agent/人工裁决”，不采用仅凭标题或向量相似度的自动合并。去重决策写入 ingest 的可重建产物和评审材料，不新增临时 Frontmatter 字段。

4.4 增加推理场景范围信息

本 RFC 建议增加一个受治理的可选字段 scope，而不是为模型推理单独设计一套不可复用的字段。scope 使用通用的逻辑表达式，具体维度和值由各 domain 的 Registry 注册。该字段必须先进入 Schema、Registry、Contract 和 Query 回归，不能由单张卡自行添加。

模型推理的第一版 scope 需要覆盖：

• 阶段：prefill、decode；
• 目标：throughput、latency、ttft、tpot、memory、bringup；
• 序列/负载：short_context、long_context、ultra_long_context、single_request、small_batch、large_batch、high_concurrency；
• 模型特征：dense、moe、mla、dsa、dit、multimodal；
• 执行模式：eager、ge_graph、npugraph_ex；
• 量化：bf16、w8a8、w8a8c8、fp8、mxfp4；
• 并行/部署：tp、ep、dp、cp、kvp、afd、offline、online、pd_disaggregated、pd_hybrid；
• 框架：cann_executor、sglang、vllm。

硬件继续使用已有的 platforms 字段，不复制到 scope；版本字段不属于本 RFC 的实施范围。

4.4.1 Scope 的表达和匹配语义

为避免多个独立数组丢失条件关联，scope 使用“多个候选 profile 的 OR + 单个 profile 内条件的 AND”语义：

scope:
  schema: model.inference.v1
  any_of:
    - all_of:
        phase: [prefill]
        objective: [ttft]
        load: [long_context]
        execution_mode: [ge_graph]
        model_features:
          all_of: [moe, mla]
        deployment: [offline]
    - all_of:
        phase: [decode]
        objective: [latency]
        load: [single_request]
        execution_mode: [eager]
        model_features:
          all_of: [moe, mla]
        deployment: [offline]

单份 Scope 的表达规则：

• scope.any_of 中的多个 profile 是 OR；命中任一 profile 即命中该卡片；
• profile 内不同维度是 AND；必须同时满足；
• 同一维度的多个普通值默认是 OR，例如 phase: [prefill, decode]；
• 模型特征不是互斥枚举，卡片的 model_features.all_of: [moe, mla] 表示结论要求同时具有 MoE 和 MLA，不是对模型全部特征的穷举；
• any_of 必须至少包含一个场景分支，每个分支的 all_of 必须至少包含一个条件；
• scope 中禁止使用空数组表达语义；
• 缺少字段表示“该维度未声明/未知”，不能自动解释为“普遍适用”；
• 枚举维度可使用独占的 [any]，表示有依据确认结论不受该维度限制；不能与具体值混用，不能用来代替未核实或未标注；集合维度是否支持通配表达由 Registry 另行定义，不把 model_features.all_of: [any] 解释为特征无关；
• 不能把两个 profile 的维度拆成独立数组，否则会丢失组合关系。

例如“Prefill + GE”和“Decode + eager”必须写成两个 any_of profile，不能写成：

phase: [prefill, decode]
execution_mode: [ge_graph, eager]

后者会被错误解释为四种组合都适用。

查询 Scope 与卡片 Scope 的匹配决策

查询 Scope 只包含用户明确提供、配置已确定或经确认的条件；推断但未确认的条件不参与冲突判断。以下匹配在现有 domain、route、Profile、platform 和 status 等过滤之内进行，不放宽原有边界。

比较结果分为三类：

• match（条件匹配）：本次比较的条件均有明确支持，可作为适用候选；它不替代正文、来源和版本边界核对，也不代表性能收益已验证；
• conflict（条件冲突）：至少一个条件有明确反证；
• unknown（适用性未知）：没有明确冲突，但卡片或查询缺少必要信息，或者两者使用不同的已注册 schema，无法直接比较。

只比较查询明确指定的维度和卡片声明的前置条件；双方均未涉及的维度不参与判断。普通枚举值存在交集时，该维度在交集范围内匹配；无交集时冲突。卡片要求的模型特征集合被查询已确认的特征集合包含时，该维度匹配；缺少某个必需特征的信息时为未知，只有明确不具备该特征或 Registry 存在确定的互斥关系时才判冲突。不能把“未提及 MLA”当成“不具备 MLA”。

查询已确认条件	卡片声明	结果	第一阶段处理与提示
Prefill + GE	Prefill + GE	match	保留，回显命中的场景分支
Prefill + GE	Prefill，未声明 execution_mode	unknown	保留，提示卡片未声明 GE 适用性
仅 Prefill	仅适用于 Prefill + GE	unknown	保留，提示还需确认 GE 前提
Prefill + GE	Prefill + execution_mode: [any]	match	保留；any 必须有不受执行模式限制的依据
phase: [any]，未确定实际阶段	仅适用于 Prefill	unknown	保留并提示 Prefill 前提，不能声称卡片覆盖全部阶段
Prefill + GE	Prefill + eager	conflict	排除，记录执行模式冲突
Prefill	Decode	conflict	排除，记录阶段冲突
已确认 MoE + MLA	model_features.all_of: [moe]	match	必需特征已满足，额外的 MLA 不构成冲突
只确认 MoE，MLA 未知	model_features.all_of: [moe, mla]	unknown	保留，提示 MLA 前提待确认
MoE，且明确不具备 MLA	model_features.all_of: [moe, mla]	conflict	排除，记录必需特征不满足
显式 model.inference.v1	未标注 scope 的旧卡片	unknown	在原过滤与文本召回范围内保留，提示缺少 Scope 声明
显式 model.inference.v1	使用其他已注册 scope.schema	unknown	不跨 schema 猜测或转换；文本相关且符合原过滤时保留，提示不可直接比较
非法或未注册的查询 schema、维度或值	任意卡片	参数错误	拒绝请求，不能降级为宽召回或 unknown

表中未列出的比较项假定已确认匹配。卡片自身的非法 Scope 由 Lint/索引准备拒绝，不作为合法旧卡片或未知适用性处理。查询中的 [any] 表示本次不限定该维度，不要求每张卡覆盖该维度的所有值，也不能据此确认卡片的具体前置条件。

单个场景分支内，任一条件冲突则该分支为 conflict；无冲突但存在未知条件则为 unknown；全部比较项匹配才为 match。多个分支之间，任一分支匹配则整体匹配；没有匹配但存在未知分支则整体未知；全部分支冲突才排除。查询含多个分支时逐对比较并保留组合关系，命中任一查询场景即可召回，不表示覆盖全部查询场景。

召回、排序与适用性提示

第一阶段仅在调用方显式提交已确认的 Scope 时启用以上判断：排除 conflict，保留 match 和 unknown。先在文本候选中判定和排除冲突，再排序并截取前 k 条，不在已截取的前 k 条内过滤后直接返回不足的结果。

保留项沿用现有相关性评分，不因 Scope 填写完整就加分；同分时 match 排在 unknown 前，再按原有路径顺序打破平局。未知项不被统一压到所有匹配项之后，避免无 Scope 的高相关旧卡片被低相关卡片挤出。

查询输出和审计记录需区分“检索相关”与“适用条件匹配”：回显实际使用的查询 Scope、scope_match、命中或待确认的场景分支，以及缺失条件、schema 不同或冲突原因。被保留的未知项明确提示“适用性待确认”，Agent 不得仅凭召回结果将其表述为已确认适用。过滤计数和原因进入审计，匹配结果不回写卡片。

决策表各行均需形成确定性回归用例，另补充以下组合正反案例：

1. 卡片包含“Prefill + GE”和“Decode + eager”两个分支：查询 Prefill + GE 或 Decode + eager 时命中对应分支；查询 Prefill + eager 或 Decode + GE 时均冲突，不能把两个分支拼接匹配。
2. 同一卡片同时包含 Prefill 和 Decode 优化时，输出命中分支，正文分别说明各阶段的规则和证据；命中 Prefill 分支不能把 Decode 的配置或收益推广给 Prefill。查询只提供 Prefill、卡片还要求 GE 时为未知，保留并提示 GE 前提。
3. 对同一查询与索引，无显式 Scope 时结果及排序与原 Query 一致；显式使用模型推理 Scope 后，相关旧卡片和其他已注册 schema 的相关卡片仍可作为未知项召回；未注册 schema 则必须报错。

4.4.2 自然语言到 Scope 的解析

用户只给自然语言时，不能直接让模型自由生成过滤条件。解析流程为：

1. 使用 Registry 中的别名和同义词表做确定性归一化；
2. Agent 提取候选 scope，同时标出来源词、置信度和未确定维度；
3. 用户已明确提供或配置已确定的条件无需重复确认；对平台、阶段、执行模式、量化、部署拓扑等高影响推断，不确定时先确认，或仅作为宽召回线索；现有平台必选与识别规则不因此放宽；
4. 调用方显式提交确认后的结构化 Scope 时，Query 按 §4.4.1 排除明确冲突项并保留未知项；未确认的条件不得混入该 Scope，也不能把模型置信度当成确认；
5. 没有显式提交 Scope，或只有自然语言推断但未确认时，沿用原查询范围和排序，线索只用于文本宽召回；
6. 查询结果中回显最终使用的 Scope 及本次是否启用过滤，便于审计和复现；未启用时不得宣称已执行 Scope 适用性检查。

4.4.3 Scope 的跨领域扩展

scope.schema 是全局扩展点，例如：

model.inference.v1
ops.operator.v1
training.distributed.v1
runtime.service.v1

通用逻辑结构、缺省语义、OR/AND 组合和空值规则由全局 Scope Contract 统一定义；具体维度、枚举、别名和解析器由 domain Registry 注册。后续其他领域不能自行创造一套不兼容的 scope 语法。

不能把模型名称作为唯一适用范围。模型名称只作为 Model Concept 或正文中的案例标识，规则卡必须优先按结构和执行条件表达。

4.5 正文模板

Optimization 卡

## 适用场景
## 问题信号
## 优化规则
## 机制
## 实施要点
## 收益
## 代价和风险
## 回退方式
## 验证方法
## 适用边界
## 相关经验
## Evidence

Runbook 卡

## 症状
## 快速检查
## 诊断路径
## 根因
## 修复
## 验证
## 回退和残留风险
## Evidence

Benchmark Observation 卡

## Workload
## Hardware
## Software
## Baseline
## Variant
## Metric Definition
## Repetition and Variance
## Result
## Limitations
## Evidence

性能数字必须写清：

• batch、序列长度、并发数；
• 卡数、die 数和并行配置；
• CANN、PyTorch、torch_npu 版本；
• warmup 和重复次数；
• 指标定义；
• 是否受控对比；
• 是否独立复现；
• 是否只代表单模型和单硬件。

4.6 生命周期和证据规则

推理知识使用以下状态：

状态	使用条件
draft	来源或范围不足，暂不进入默认 Query
stable	结论、来源、适用范围和验证方式完整
deprecated	已知过时或被新卡替代，但保留历史解释

verified 记录真实复核事件，不因为 Lint 通过或来源固定而自动填写。

对稳定的 Optimization、Guide、Runbook，至少要求正文存在：

• 适用范围；
• 失效边界；
• 验证信号；
• 必要的固定来源。

版本字段不属于本 RFC 的实施范围。涉及版本差异时，卡片正文应说明已确认的范围或待验证边界，并保留固定 commit 来源；不要在本次迁移中批量补写 cann_versions。

对于仓库自报 benchmark，没有独立复测时必须明确标记为仓自报，不能写成通用性能保证。

5. 迁移方案

阶段 0：规范和试点

范围只选择模型推理中的高价值主题：

• 并行策略；
• KVCache/FA；
• 图模式；
• 多流；
• 量化；
• MTP；
• A3/950 平台。

工作内容：

1. 增加推理分类规范和模板；
2. 补充 scope 通用逻辑契约和模型推理 Registry 值；
3. 选择 20～30 张推理卡片做人工归类试点；
4. 同时选择 5～10 张算子/算子框架知识卡做跨 domain 兼容试点；
5. 不立即移动原文件，先生成迁移和去重清单；
6. 统计重复、边界冲突、scope 组合错误和缺证据情况；
7. 选取至少一个 Operator 查询、一个 Operator 知识摄入和一个 Trace→Runbook 任务验证全库结构没有回归。

阶段 1：规则、案例和 Runbook 归并

优先处理：

• dp_attention_tp_oproj_mlp_hybrid；
• afd_attn_ffn_disaggregation；
• long_seq_prefill_context_parallel；
• kvp_longseq_decode；
• graph_mode_enable_decision_profiling；
• decode_multi_stream_overlap_core_balance；
• decode_weight_prefetch_ordering；
• superkernel_decode_ge_graph_fusion_scope；
• prefill_decode_cluster_scale_mismatch；
• A3/950 量化和平台卡片；
• 性能测量反模式和 profile_run OOM Runbook。

每张卡明确采用 update、merge、split、deprecate 或 defer 处理方式，不做无理由复制。所有新卡必须经过知识查询去重门禁。

阶段 2：Query 和评测接入

新增推理检索用例，至少覆盖：

MLA + Decode + low latency + A3
MoE + Decode + high throughput + EP
Long context + Prefill + CP
A3/950 + FP8/MXFP4
PD + DP/EP + multi-machine
Graph mode + host gap
Multi-stream + fake overlap
KVCache + FA + precision failure

Query 评测需要同时检查：

• 目标卡片是否召回；
• 是否召回错误平台或错误阶段的卡片；
• 是否把 benchmark observation 当成通用规则；
• 是否能区分 stable、draft 和 deprecated；
• scope 的组合关系是否保持；
• §4.4.1 决策表及组合正反案例是否通过，未知项是否保留并提示待确认条件；
• 无显式 Scope 或只有未确认推断时，是否保持原查询范围和排序；
• 规则、案例、Runbook 和 Operator 卡片是否被正确区分。

同时增加跨领域回归用例：

• AscendC Operator 查询仍命中原有 Operator 卡；
• TileLang/PyPTO 互操作查询仍能区分 DSL 专属知识；
• Trace→Runbook 摄入不会把 Runbook 错放为 Optimization；
• 算子知识的 domain/route/Profile 和模型推理知识互不串召回；
• 去重查询能够阻止同一主题重复建卡。

阶段 3：旧路径迁移和清理

试点验证后再处理：

• 删除或归并 experience 中重复的层级；
• 更新 index 和所有内部链接；
• 为旧卡片设置 deprecated/replaced_by；
• 补充 verified，不在本次迁移中批量补写版本字段；
• 更新模型推理知识导航和贡献文档。

6. 兼容性、迁移和回退

6.1 兼容性

• 保留现有四个主要 Profile：Concept、Guide、Optimization、Runbook；
• 第一阶段不新增 Observation Profile；
• 现有卡片不要求一次性移动；
• 第一阶段无显式查询 Scope 时，Query 继续按原过滤条件、标题、description、tags 和正文召回，保持原有结果范围与排序；卡片新增 Scope 不自动启用过滤；
• 调用方显式提交已确认的查询 Scope 时，按 §4.4.1 排除明确冲突项，保留条件匹配项与适用性未知项，并回显实际使用的条件、命中分支和待确认前提；
• 只有自然语言推断且未确认时，仅将线索用于文本宽召回，不启用 Scope 过滤，不放宽原有平台等前置条件；
• 未标 Scope 的旧卡片和其他已注册 schema 的卡片，在原过滤与文本召回范围内保留为未知项；没有跨 schema 转换或“未知即排除”的默认行为；
• 第一阶段不启用全局默认 Scope 过滤，也不要求只返回 match；以后若改变默认行为或排除未知项，需另行评审并验证召回影响。

6.2 迁移

• 先生成清单，再移动文件；
• 任何移动都同步 Concept ID、链接、索引和 replaced_by；
• 以固定 commit 和原始来源为基线，不凭标题自动合并；
• 使用 knowledge-ingest 和 knowledge-lint 完成新卡生产和校验；
• 每轮迁移记录当天日志。

6.3 回退

如果新路径、字段或 Query 过滤导致召回下降：

1. 恢复受影响的卡片、路径、导航和链接到同一迁移前版本，并使用与恢复内容及治理规则一致的索引；不能只恢复旧索引而保留已迁移的内容；
2. 停用本轮新增的显式 Scope 冲突过滤、同分排序和适用性判断，恢复旧 Query 行为；第一阶段不存在需要关闭的全局默认 Scope 过滤；
3. 回显本次未执行 Scope 过滤，调用方恢复原查询路径，不能静默忽略显式条件后仍声称已完成适用性检查；Scope 声明可保留在支持该字段的版本中，若回退到尚不支持该字段的版本，须连同 Schema、Contract、卡片和索引一致回退；
4. 保留已经生成的 draft 卡，不将其标记为 stable；
5. 根据失败用例修正 Schema、Registry、Contract 或卡片内容。

7. 替代方案

方案 A：维持现状

优点是没有迁移成本。

缺点是：

• 新知识继续依赖个人判断归档；
• experience 和 interventions 继续扩大；
• 规则、案例、benchmark 和 Runbook 继续混淆；
• 推理场景难以精确检索；
• Agent 容易把单次经验泛化为通用结论。

不建议采用。

方案 B：完全重建新 Profile

为 Case、Benchmark、Anti-pattern、Scenario 分别新增 OKF Profile。

优点是语义更精确，缺点是需要同步修改大量 Schema、Registry、Contract、Query、Lint、索引和现有卡片，迁移风险较高。

不作为第一阶段方案。只有当现有 Optimization Profile 无法满足实际 Query 和治理需求时，再单独提交后续 RFC。

方案 C：本 RFC 的渐进方案

保留现有 Profile，先治理路径、模板、场景字段、证据和检索回归，再根据真实消费需求决定是否新增 Profile。

本 RFC 推荐方案 C。

8. A/B 实验计划

8.1 实验目标

验证新结构是否改善模型推理知识的：

• 查询召回；
• 平台和阶段命中准确性；
• 规则/案例/benchmark 区分能力；
• Agent 选择正确知识卡的成功率；
• 重复建卡和错误归档率。

8.2 A/B 版本

版本	内容
A	当前路径、Frontmatter、Query 和索引
B	新分类模板、scope、场景检索和迁移试点卡片

控制变量包括：

• 同一冻结的知识仓基线 commit，分别记录 A/B 的变更与索引指纹；
• 同一 Query 模型和参数；
• 同一查询问题；
• 同一平台过滤和已确认的查询 Scope；A 沿用原 Query，B 按 §4.4.1 处理显式 Scope；无 Scope 的兼容用例单独比较原结果与排序。版本边界由正文核对，不引入现有 Query 尚未提供的版本过滤；
• 同一评测用例顺序。

8.3 评测集

至少准备 30 个推理任务查询，覆盖：

• 高吞吐；
• 低时延；
• Prefill；
• Decode；
• MoE；
• MLA/DSA；
• KVCache/FA；
• 图模式；
• 多流；
• 量化；
• A3/950；
• 在线/PD；
• 性能反模式；
• 精度和运行时故障。

每个用例包含：

• 查询问题；
• 平台和版本；
• 期望召回卡片；
• 不应召回的干扰卡片；
• 已确认的查询 Scope、未确认的自然语言线索，以及期望的匹配分支和待确认条件；
• 期望答案要点；
• 人工核对结果。

8.4 预注册指标和通过标准

Scope 指标只在具有显式、已确认查询 Scope 的评测用例上计算。A/B 使用同一份冻结的查询条件、标准答案和判定依据，由人工结合正文、来源及查询前提判定前 5 个结果；不能直接用 Query 自报的 scope_match 代替正确性判定。机器标为未知的旧卡片，如果正文和来源足以支持人工核对，可以在人工评测中判为匹配；证据不足或查询缺少前提的结果仍为未知，不能强行算作匹配或冲突。

对每个用例 q，令 T_q 为实际返回的前 5 个结果数，M_q、C_q、U_q 分别为人工判定的条件匹配、明确冲突、适用性未知数量，满足 T_q = M_q + C_q + U_q。平台、阶段、目标、执行模式、模型特征等的判定以该用例冻结的已确认条件为准。仅某个分支适用时按命中分支核对，不能用卡片其他分支的内容补足条件或收益证据。

指标	计算口径	改善方向
Recall@5	对有期望卡片的用例，计算前 5 中命中的期望卡片数 / 期望卡片总数，再对用例等权平均；迁移前后的等价卡片使用预先冻结的映射比对	越高越好
Scope precision@5	sum(M_q) / sum(T_q)，按实际返回项微平均；未知项不算已确认匹配	越高越好
Conflict rate@5	sum(C_q) / sum(T_q)，即前 5 中明确违反查询条件的比例	越低越好
Unknown rate@5	sum(U_q) / sum(T_q)，单列适用性尚不能确认的比例，不将其算作明确冲突	单独报告，不通过删除未知项追求下降
非空召回率	有期望卡片的用例中，实际返回至少一项的用例数 / 此类用例总数；同时报告每个用例实际返回数	不低于基线，防止少返回或空返回美化精度
Decision accuracy	Agent 最终选择的规则在该用例条件下适用的任务数 / 有最终决策的任务数；未完成决策的数量另报	越高越好
Duplicate rate	人工核定为同一主题重复建卡的新增卡片数 / 评测任务新增卡片总数	越低越好
Evidence completeness	来源、适用范围、验证和边界均完整的稳定卡片数 / 试点稳定卡片总数	越高越好

例如前 5 中有 2 项匹配、1 项冲突、2 项未知，则 Scope precision@5 为 40%，Conflict rate@5 为 20%，Unknown rate@5 为 40%。原定义中的“不匹配比例”不再使用 Scope precision 命名。

不足 5 项时按实际返回项计算，并报告返回数；零返回用例不伪造分母 5，也不记作精度 100%。若某项指标分母为零则记为 N/A，并报告原因；显式 Scope 评测整体零返回或无法计算精度时不能通过验收。无 Scope 的查询只参与召回、决策和兼容性评测，不混入 Scope 指标分母。Duplicate rate 等其他比率同样不在零分母时虚报改善。

通过标准在实验开始前固定，建议至少满足：

• Recall@5 和非空召回率不低于当前基线，已确认适用的期望卡片不得被 Scope 错误排除；
• Scope precision@5 相对基线提升，Conflict rate@5 不高于基线；同时报告 Unknown rate@5 和实际返回数，不把未知直接当成冲突或用减少返回掩盖召回损失；
• §4.4.1 决策表和组合正反案例全部通过，未知项正确提示，跨分支拼接匹配和非法 schema 静默降级均为零；
• 无显式 Scope 的兼容用例保持原过滤与排序；已确认 Scope 的用例中，高吞吐/低时延和 Prefill/Decode 的冲突由上述指标与冻结的正反案例判定，不再仅以“无明显串召回”描述；
• 原有 Query 场景无阻断性回归；
• knowledge-lint、检索索引和 bash check.sh 全部通过。

9. 实现影响

可能涉及的机器事实源和消费者：

变化	需要同步
scope 字段	frontmatter.schema.json、profiles.yaml、Registry、Contract、Query、Lint、测试
新目录布局	paths Spec、索引、路径 Contract、迁移脚本和 retrieval eval
新正文模板	knowledge-ingest、贡献文档、样板和内容检查
生命周期审计	Frontmatter、Lint、Query 默认过滤和迁移清单
检索过滤	knowledge-query、显式 Scope 的冲突过滤与未知项提示、同分排序、审计回显和范围回归

本 RFC 不改变：

• OKF Bundle root；
• 现有 domain/route 主体；
• 默认知识查询的安全和权限边界；
• 原有 Profile 的基本职责；
• 生产知识必须可追溯、可验证和经 committer 检视的贡献流程。

10. 风险与缓解

风险	缓解方式
移动卡片导致 Concept ID 变化	分阶段迁移，统一更新链接和 replaced_by
新字段增加维护成本	先做可选字段，限定受控值和最小范围
过度细化目录导致检索变差	不新增过多 Profile，优先使用现有 Profile 和正文模板
把单次 benchmark 泛化成规则	强制 Benchmark Observation 模板和 Evidence/Limitations
版本边界表达不清	在正文中说明已确认范围或待验证边界，保留固定 commit 来源；不在本 RFC 中新增版本字段要求
旧查询召回下降	无显式 Scope 时保持原查询行为；有显式 Scope 时保留未知项；异常时停用新增 Scope 处理，并按 §6.3 一致回退内容、规则与索引
迁移过程产生大量重复卡	迁移前强制 Query，明确 create/update/merge/split/deprecate/defer

11. 验收标准

本 RFC 实施完成后，至少应满足：

• 模型推理知识有明确的 Concept/Guide/Optimization/Runbook 边界；
• 新增知识不再使用无明确语义的 experience 作为归档依据；
• 高吞吐、低时延、Prefill、Decode、长序列、模型结构和执行模式可查询；
• 稳定卡片能够表达平台、scope、验证状态和证据；
• Benchmark 观测不会被默认表述成通用规则；
• 至少 30 个推理检索用例通过；
• Scope 决策表及组合正反案例通过，匹配、冲突和未知的召回、排序及提示行为一致，指标方向与分母按 §8.4 执行；
• 原有 Query 关键路径无阻断性回归；
• 迁移卡片的链接、导航和 Concept ID 关系完整；
• knowledge-lint 和 bash check.sh 通过；
• RFC 实验结果已回填，并形成关联 PR 的评审材料。

12. 待评审问题

1. 通用 scope 是否采用当前 RFC 的 schema + any_of/all_of 结构？
2. benchmark_observations 是否继续使用 Optimization Profile，还是在后续 RFC 中新增 Observation Profile？
3. 是否需要为 Case 建立独立 Profile，还是保持在 optimizations/cases？
4. 是否在本 RFC 中直接迁移所有 experience 路径，还是先只约束新增内容？
5. 第一阶段按 §6.1 固定为“无显式 Scope 沿用原查询；显式已确认 Scope 排除冲突、保留未知；未确认推断只做文本宽召回”。请评审 §4.4.1 的决策表和同分排序是否满足场景需求；全局默认过滤或排除未知项作为后续独立评审，不作为本阶段的未定开关。
6. A5/Ascend 950 相关知识是否单独建立平台 scope，还是继续复用当前 platforms: ['950'] 注册值？

13. 结论

本 RFC 推荐采用渐进式治理：保留当前 OKF/Profile 基础，先统一模型推理知识的职责边界、路径命名、场景范围、证据模板和检索评测，再根据实际消费结果决定是否引入新的 Observation 或 Case Profile。

这样可以避免一次性重建知识仓，同时解决当前最主要的三个问题：

1. 同一优化主题在多个路径之间重复或职责不清；
2. 高吞吐、低时延、Prefill、Decode、平台和模型结构信息难以机器过滤；
3. stable、benchmark、源码事实和实验推断没有被清楚区分。