Harness Times

一组被排成 N 维网格的数。它不是什么高深的对象，只是「数 + 排列方式」。

出现场景 凡是讲模型计算的地方都会出现：输入是张量，权重是张量，中间结果也是张量。

张量每一维的大小，写作 [n, d] 这样的列表。

出现场景 读论文、调代码、排查报错时最先看的东西——绝大多数形状错误都会在训练时直接抛出。

一串有序的数。在模型里，它代表「某个东西被表示成的一条坐标」。

出现场景 每个 token 被变成一个向量；每个词的 Embedding 也是一个向量。

两个等长向量逐项相乘再求和，得到一个数：它衡量两个向量「方向有多一致」。

出现场景 注意力里所有「谁该关注谁」的分数，都是点积算出来的。

描述「输入变大时，计算量按什么速度增长」的记号，只看增长趋势、忽略常数。

出现场景 凡是讨论「上下文变长会怎样」「这个方案能不能扛住」的地方，说的都是它。

把任意一串数变成「都为正、且加起来等于 1」的一串数，可当作比例或概率来读。

出现场景 打分之后必需的一步：把原始分数变成权重。也出现在采样、分类等很多地方。

打分结果除以 √d 再送进 softmax，防止数值过大导致 softmax 退化。

出现场景 注意力公式里那个最容易被忽略、却又不能省的除法。

两个互不包含、可分别独立判断的评测维度。

出现场景 拆评测维度时；判定「再拆一层有没有意义」时。

指标计算中作为基数与比较基准的样本集合。

出现场景 报任何百分比前都要先问分母是什么。

观测到的差异是否超出随机波动的统计判断。

出现场景 比较两个版本得分、下「变好了」结论之前。

同一配置多次运行得分的离散程度，用于界定噪声。

出现场景 跑评测设 repeats>1 时；解读不稳定指标时。

只看两向量夹角、忽略长度，是文本检索默认度量。

出现场景 比较两个文本向量「多像」时，默认就是它。

高维空间中的直线距离，归一化后与余弦单调对应。

出现场景 嵌入模型用欧氏训练、或你想直观看「空间距离」时，用它。

把向量缩放到单位长度，使余弦与点积等价。

出现场景 嵌入产出后、做相似度或建 ANN 索引前，默认先归一。

用一个可学习的权重矩阵做乘法，把向量从一组坐标换算到另一组坐标。

出现场景 注意力里生成 Q/K/V 的那一步；FFN 里也有两处。

接在注意力之后、对每个位置独立做一次的两层全连接变换。

出现场景 Transformer 每一层的第二个子层。它往往占模型参数的大头。

softmax 之前、长度等于词表大小的原始分数向量。

出现场景 看模型最后一层输出、理解温度 / top-p 在改什么、做约束解码时。

模型处理文本的最小单位。它既不是字也不是词，而是分词器切出来的一个片段。

出现场景 上下文长度、计费、截断策略——所有这些「按 token 算」的东西。

把离散的编号（如 token id）映射成一个稠密向量的过程或那张表。

出现场景 模型最开头第一步：token 编号 → d 维向量。

每个位置用来表示信息的向量长度，例如 4096。

出现场景 所有形状标注里的那个 d；显存估算、参数量估算都从它出发。

把「这是第几个位置」的信息注入到表示里的机制。

出现场景 不加它，模型无法区分语序；加了它，也带来「能不能外推到更长上下文」的问题。

把输入喂进模型、一路算到输出，这一次计算叫一次前向计算；它不更新任何参数。

出现场景 算推理成本、算首 token 延迟、估显存占用时，量的都是「一次前向」。训练时则是前向与反向成对出现。

序列里每个位置都去看一遍所有位置（包括自己），按相关度加权收集信息。

出现场景 Transformer 的主体。所有「上下文越长越贵」的结论都从这里长出来。

同一份输入经三组不同投影得到的三种角色：我要找什么、我能被什么找到、我实际携带什么。

出现场景 注意力的核心变量。K 与 V 也正是后续会被 KV Cache 缓存起来的对象。

用 Q 和 K 的点积算出「两个位置之间相关度」的那一步，结果是一张 [n, n] 的表。

出现场景 注意力三步走的第二步，也是 n² 复杂度真正产生的地方。

用 softmax 得到的权重，把各个位置的 V 按比例混合起来，得到当前位置的输出。

出现场景 注意力三步走的最后一步；输出形状回到 [n, d]。

形状为 [n, n] 的权重表，每行加起来等于 1，表示「每个位置把注意力分给了谁」。

出现场景 复杂度、显存、可解释性三条线索都指向它。

把表示空间切成若干子空间，并行做多组注意力，最后拼接——让模型同时维持多种关注方式。

出现场景 所有现代 Transformer 的实际形态。看到「头数 h」就是指它。

把注意力矩阵右上角置为无效，使位置 i 只能看到 i 及之前的位置。

出现场景 decoder-only 模型（也就是现在几乎所有大模型）的必备步骤。

计算量随序列长度 n 的平方增长——n 翻倍，代价变 4 倍。

出现场景 「上下文很贵」的唯一物理来源。第 1 章的主角。

推理的两个阶段：一次性处理整段输入（prefill）与逐个生成新 token（decode）。

出现场景 分析延迟、成本、吞吐时的基本切分；「首 token 慢」和「吐字慢」是两件事。

把已经算过的 K 和 V 存下来，生成下一个 token 时直接复用，不重算前缀。

出现场景 第 2 章的主题；也是多轮对话成本与显存的主要变量。

模型一次能接收的 token 总数上限；它同时是能力边界、成本边界和显存边界。

出现场景 凡是「塞不塞得下」「要不要裁剪」的判断，说的都是它。

生成第 t 个 token 时，必须用到前面所有 token 的信息。

出现场景 凡是讲 Transformer 逐 token 生成的地方都默认它成立；KV Cache 正是它的直接推论。

相邻两轮请求共享尽量长的字节前缀，以命中缓存、避免重算。

出现场景 写多轮 Agent、拼 system prompt、序列化工具列表时，你就在和它的破坏点打交道。

多个查询头共享一组 K/V 头，显著缩小 KV Cache 显存。

出现场景 几乎所有长上下文模型都用它；看模型配置里的 n_kv_heads 时就是在看它。

GQA 的极端形式，所有查询头共享同一组 K/V 头。

出现场景 追求极致缓存压缩、或显存极度紧张时的选型；是 GQA 的特例。

K/V 这一侧注意力头的个数，是 KV Cache 体积的关键因子。

出现场景 估算显存、读模型配置、解释为什么长上下文模型要用 GQA 时。

每个注意力头内部向量的维度（长度）。

出现场景 算显存、调注意力超参、看模型配置 head_dim 字段时。

服务端按策略回收显存中的 KV Cache 块，命中率不受你完全控制。

出现场景 高并发、长上下文、缓存驻留时间长的线上服务里。

前缀被复用而非重算的 token 占本应可复用 token 的比例。

出现场景 衡量多轮 Agent 成本、对比不同请求拼接方式时。

KV Cache 占用的显存，随序列长度线性增长，需单独估算。

出现场景 规划长上下文并发数、算单卡能扛多少请求时。

对工具定义与历史取哈希，验证相邻两轮是否共享同一前缀。

出现场景 在 Harness 里做日常前缀稳定性检查、CI 守门时。

一层内多个前馈子网络，每个 token 只激活其中几个。

出现场景 解释为什么 671B 模型成本和几十 B 模型接近；看模型参数量与激活量两个数字时。

路由可选中的子网络，通常就是一个前馈层（FFN）。

出现场景 读 MoE 结构图、看专家利用率、理解路由坍缩时。

给每个 token 算各专家权重并取 top-k 的小网络。

出现场景 读 MoE 图、写路由代码、解释 top-k 怎么来时。

每个 token 只走 top-k 个专家，其余专家不参与本次计算。

出现场景 解释 MoE 为什么省算力、区分它与稀疏注意力时。

模型中全部参数的总和，决定显存占用的下限。

出现场景 比较模型大小、算部署显存下限、解释 MoE 容量时。

每生成一个 token 实际参与计算的参数量。

出现场景 估算单 token 算力、比较 MoE 与稠密模型单价时。

门控反复选少数专家，其余专家几乎不被训练、容量被浪费。

出现场景 训练 MoE、看专家利用率分布、解释为什么加负载均衡损失时。

惩罚过度使用的专家、强制使用率均匀的训练辅助项。

出现场景 训练 MoE、调路由坍缩、读模型训练配置时。

专家分布在不同设备时，每次路由都需跨设备搬运 token 的通信模式。

出现场景 部署 MoE、评估延迟与通信开销、解释为什么 MoE 难本地化时。

把 MoE 的不同专家分布到不同设备上的并行策略。

出现场景 部署超大 MoE 模型、算「为什么显存门槛高、通信为什么贵」时。

总参数量与激活参数量相等的常规模型，每次推理所有参数都参与。

出现场景 作为 MoE 的对照基准、比较两类模型的成本结构时。

在 softmax 前给 logits 除以 T，改变分布陡峭程度。

出现场景 调采样随机性、决定 Agent 哪些调用要确定性时。

按累计概率截断候选集，只保留到 p 为止的 token。

出现场景 和温度配合调采样、需要动态候选集大小时。

固定只保留概率最高的 k 个 token 作为候选。

出现场景 调采样候选数、和 top-p 二选一或叠加使用时。

对已出现过的 token 降低分数，以缓解复读。

出现场景 模型开始车轱辘话、循环输出时调它。

每一步都取概率最高的 token，即温度设为 0 的解码。

出现场景 需要确定性输出、temperature=0 时的底层行为。

批处理中累加顺序等差异导致结果出现细微翻转。

出现场景 排查「同样请求两次结果不同」、解释 temperature=0 也不完全确定时。

解码时限制每个位置只能取合法 token，而非生成后再校验。

出现场景 要求 JSON / 特定格式、工具调用参数必须合法时。

固定采样所用的随机序列，但只在同后端同版本下才可复现。

出现场景 想复现某次输出、做对照实验、排查不确定性来源时。

从模型给出的概率分布里挑选 token 的一整套规则。

出现场景 讨论「同一个问题两次答案不同」是否正常、该怎么控制时。

把权重与缓存从 fp16 降到 fp8 / int8 / int4，减小体积与搬运量。

出现场景 模型装不下、显存不够、要降 decode 搬运量时。

把 KV Cache 切成固定块按需分配，消除显存碎片。

出现场景 并发上不去、显存碎片严重、读 vLLM 等框架时。

某请求一结束就立刻补入新请求，不等整批做完。

出现场景 提升吞吐、降低 GPU 空转、读现代推理框架默认能力时。

小模型起草多个 token，大模型一次前向并行验证采纳。

出现场景 单请求延迟高、输出长、想在不损质量前提速时。

缓存压缩后的潜在向量再投影回 K/V，缩小缓存系数。

出现场景 读 DeepSeek 类模型、解释怎么在同样显存撑更长上下文时。

从请求到产出第一个 token 的时间，prefill 阶段的主要指标。

出现场景 衡量「用户等多久才看到第一个字」、优化 prefill 瓶颈时。

decode 阶段把权重从显存搬到计算单元的速度上限，是真正瓶颈。

出现场景 解释 decode 为何 GPU 利用率低、选 decode 优化手段时。

投机解码中，小模型草稿被大模型采纳的比例。

出现场景 评估投机解码是否值得上、调到什么草稿长度时。

长度不定导致按最大长度预留、空间被浪费成空洞。

出现场景 并发上不去、显存看着够却分配不出、理解 PagedAttention 动机时。

通过分块与算子融合减少注意力显存访问次数的算法。

出现场景 优化 prefill 算力与显存访问、读现代推理框架必装项时。

把多个小算子合并成一个，减少显存读写次数。

出现场景 优化 prefill 阶段、理解为什么框架要把层「 fuse 」在一起时。

把概率性文本生成器包装成可交付执行系统的全部工程。

出现场景 讨论「模型之外还有什么」、面试答「什么是 Harness」时。

把 Harness 拆成六层的结构，每层都可能成为效果瓶颈。

出现场景 读第一章、定位某层是瓶颈、向同事解释 Harness 全貌时。

工具的完整说明：名称、用途、参数、返回、幂等、副作用、成本。

出现场景 设计任何工具、排查调用失败、面试讲工具层时。

把工具报错分类后写回上下文，让模型换参数重试。

出现场景 工具执行失败、循环没终止、任务完成率上不去时。

工具执行对外部世界造成的、不能自动撤销的改动。

出现场景 设计工具权限、决定要不要确认、划分副作用等级时。

只给完成任务所需的能力，让越权在能力层面不可达。

出现场景 配置工具权限、设计沙箱、审计越权风险时。

每一步调用与状态都可查、可回放。

出现场景 线上出问题定位、设计 trace、写最小可用 Harness 时。

用户最终拿到的产物形态：报告、表格、代码、网页。

出现场景 设计产物形态、处理版本回滚、谈「用户拿到什么」时。

任务分解、派生、并行串行、结果汇总与人工介入点。

出现场景 设计长任务、拆子任务、决定在哪暂停问人时。

同一操作重复执行与执行一次的结果相同。

出现场景 设计可重试工具、处理超时重试、防重复副作用时。

反复执行想一步、做一步、看一眼结果，直到满足终止条件。

出现场景 所有 Agent 系统的主循环；讨论「它为什么停不下来」时。

循环的三步骨架：决定动作、执行工具、把结果回喂。

出现场景 讲循环结构、设计回喂逻辑、排查下一轮跑偏时。

退出循环的五类判据：完成、预算、无进展、需人工、系统异常。

出现场景 设计循环、防无限循环、面试问「什么时候该停」时。

连续多轮状态未发生实质变化即判定停滞并退出。

出现场景 循环空转、预算无声耗尽、设计停滞判据时。

工具名加规范化参数，用于统计重复调用。

出现场景 做无进展检测、判重、设计重复上限时。

对工作区文件列表与哈希取值，判断是否真有产出变化。

出现场景 有文件系统产出的任务、判停滞、设计指纹时。

每轮 token 消耗持续上升而产出不变，作为提前预警信号。

出现场景 上下文膨胀预警、辅助判停滞、设提前量时。

在越权或不可逆操作前暂停，交给用户决策。

出现场景 不可逆操作前、信息缺失、需要人拍板时。

轮数、token、时间、金额任一触顶后退出并返回部分结果。

出现场景 循环退出、防烧钱、设计上限、面试问刹车时。

暂停后完整状态被持久化，用户回来能从中断点继续。

出现场景 设计人工介入、长任务检查点、断点续跑时。

描述工具参数的类型、必填、枚举、范围与格式范例。

出现场景 写工具定义、约束参数、防非法输入时。

写给模型看的说明：做什么、何时用、参数怎么填、返回什么。

出现场景 写任何工具、提升调用成功率、面试讲工具层时。

把工具错误分成因不同处理策略的几类。

出现场景 设计错误回喂、决定重试策略、写 Handler 时。

查询成功但没有数据，属于成功而非失败。

出现场景 工具返回无数据、模型反复重试、防空转时。

由调用方按操作意图生成的稳定标识，重试时键不变。

出现场景 设计可重试写操作、防重复发送、面试讲幂等时。

工具供给的标准化协议，让工具可跨产品复用。

出现场景 决定工具要不要走标准协议、接第三方生态时。

强制模型按 schema 产出可解析的 JSON 等结构。

出现场景 让模型输出可解析结果、保证符合 schema、接工具时。

在 Handler 入口再校验一遍参数，不信任任何上游。

出现场景 写工具 Handler、防脏参数、兜底校验时。

工具按只读、可逆写、不可逆分级，决定是否需确认。

出现场景 设计工具权限、定确认策略、配最小权限时。

在契约里标注工具是否昂贵、是否慢、是否有配额。

出现场景 设计工具契约、防成本失控、标昂贵接口时。

决定模型每一轮看到什么：预算分配、注入、压缩与排序。

出现场景 谈效果上限、设计上下文、和提示工程对比时。

把窗口容量按指令、能力、知识、状态四类成分分配。

出现场景 设计上下文、定各成分占比、防撑爆窗口时。

上下文中真实判断依据的占比，占比下降即越跑越笨。

出现场景 解释效果下降、设计压缩、谈「越跑越笨」时。

只保留最近 N 轮，更早历史直接丢弃。

出现场景 设计短任务压缩、控制上下文长度、快速降本时。

把已完成段落压成固定字段的结构化摘要。

出现场景 中长任务压缩、固化结论、防历史膨胀时。

中间产物写入文件，上下文只留指针与目录清单。

出现场景 长任务、大产出物、控上下文增长时。

超长结果保留头尾、中间省略，并标注省略多少字符。

出现场景 单条工具返回超长、防挤爆窗口、做即时裁剪时。

给每段知识标注是事实、推断还是观点。

出现场景 注入检索知识、标可信度、防幻觉、给引用时。

复用相同前缀的计算结果以省成本，靠字节稳定命中。

出现场景 排上下文顺序、省推理成本、设计稳定头部时。

用量到 60%、单条超 10%、阶段边界三个提前量信号。

出现场景 设计压缩时机、防来不及压、定阈值时。

当前任务的上下文、中间结果与待办，任务结束即释放。

出现场景 所有 Agent 跑任务时都在用它；讨论「上下文怎么管理」说的就是它。

发生过什么：任务历史、结论、失败原因。

出现场景 需要回顾之前做过什么、为什么失败时；做事后复盘与追溯时。

长期稳定的事实与偏好，如用户是谁、习惯什么口径。

出现场景 需要「这个用户长期是怎样的」「团队默认口径是什么」时命中。

两条记忆矛盾时按四类原则决定信谁或暴露冲突。

出现场景 召回或写入时发现同一 key 下出现互相矛盾的信息时。

新事实取代旧事实，旧值保留为历史版本并标记失效。

出现场景 同一归属实体先后写入了不同的事实值时。

只标记失效时间而不物理删除，以保留可解释性。

出现场景 记忆被新版本取代、或用户行使删除权之前，需要保留历史时。

按 key 取回当前有效版本，上限五条并带写入时间。

出现场景 Agent 需要把相关记忆注入上下文时；讨论「召回质量」时。

对记忆内容取哈希，用于跨库去重。

出现场景 写入前判断「这条和已有的是不是重复」时；跨存储去重时。

触发写入的三类事件：显式指令、任务固化、自动抽取。

出现场景 决定「这条信息该不该写进记忆」的任何时刻。

任何时候都能回答系统为什么曾这么认为。

出现场景 用户质疑「你为什么觉得 X」时；做合规审计与复盘时。

把任务拆给多个 Agent，需满足隔离、并行或权限收益。

出现场景 任务复杂到一定程度，考虑「要不要多开 Agent」时。

由父 Agent 派生、只把结论回传的执行单元。

出现场景 需要把海量中间材料隔离出去、只回传结论时。

子任务海量中间材料用完即弃，父上下文只装结论。

出现场景 讨论「为什么用 Subagent 而不是长上下文单 Agent」时。

父 Agent 分解任务、派生、汇总的编排形态。

出现场景 任务分解清晰、子任务同质，需要一棵调度树时。

A 的输出交给 B、B 交给 C 的串行加工形态。

出现场景 阶段界限清晰的加工流程，如「抽取→清洗→生成」。

生成者与评审者交替循环，直到达标或触发上限。

出现场景 质量要求高、产出可验证，需要反复打磨时。

归并多个子结论，冲突显式暴露、低置信度降为参考。

出现场景 多个子 Agent 返回结论，需要合成为最终产物时。

读数据与写生产库的操作由不同 Agent 持有工具集。

出现场景 某些操作需要更高权限或更强沙箱约束时。

子结论矛盾时不静默选边，交由父 Agent 或用户裁决。

出现场景 汇总时发现两个子 Agent 给出相反结论时。

子 Agent 回传的唯一定式结构，含结论、证据、来源、置信度。

出现场景 设计多 Agent 系统时，定义子 Agent 返回格式时。

攻击者在模型会读到的地方放文字，冒充指令改变系统行为。

出现场景 系统会读取外部内容（网页、文档、文件名）并喂给模型时。

先列清攻击面与攻击者能力，再谈防御。

出现场景 设计任何 Agent 安全方案前，先画威胁模型时。

一切来自外部、只能当数据不能当指令的内容。

出现场景 任何外部输入进入模型上下文之前，先标记为不可信。

按任务下发最小工具集，权限在工具内部强制执行。

出现场景 设计 Agent 工具权限、划分子 Agent 能力边界时。

让代码执行被限制在可回收容器里的隔离环境。

出现场景 需要跑模型生成的代码、又怕它乱动系统时。

不可逆操作强制人工确认，是不依赖模型判断的确定性代码。

出现场景 系统要执行删除、发送、发布、付费等不可逆动作前。

记录每次调用的输入、输出、上下文与最终授权人。

出现场景 出事后要能回答「谁、在什么上下文下、做了什么」时。

一次被攻破后，副作用能波及的范围。

出现场景 评估「如果这一步被攻破，最坏能坏到哪」时。

剥离伪指令、隐藏字符与异常重复，并记录发现。

出现场景 所有外部内容进入上下文之前的统一入口。

只看工具名与参数、不调用模型的判定代码。

出现场景 需要「无论模型是否被说服都必须执行」的硬性判定的地方。

跨越很多轮、很多步骤、可能跨进程生命周期的任务。

出现场景 任务要跑很久、跨多次调用甚至跨重启时。

流式响应长时间不吐字、无结束标记或连接假活。

出现场景 调大模型流式接口、长时间没拿到完整结果时。

相邻两个数据块之间超过阈值无新数据即判定卡死。

出现场景 流式响应进行中，需要检测「中途停住」时。

从请求发出到收到第一个字节的时间。

出现场景 诊断「请求是不是根本没被接住」时，作为第一道心跳。

IDLE→STREAMING→…→DONE 的显式状态迁移。

出现场景 需要把流式响应的生命周期管清楚、可恢复时。

每步完成后持久化的状态快照，用于中断后恢复。

出现场景 长任务要能跨进程重启、用户关窗口后接上时。

单条裁剪、旧步骤摘要、结论钉住三步自动执行。

出现场景 长任务上下文接近窗口上限，需要自动瘦身时。

把关键结论固化为不可压缩区，防止被后续压缩丢掉。

出现场景 自动压缩开启后，怕关键约束被压掉时。

软超时触发降级，硬超时才判定任务失败。

出现场景 需要区分「再等等还能出结果」与「彻底没救了」时。

容忍代码块包裹、尾随逗号等变体的输出解析。

出现场景 解析模型返回的 JSON / 工具参数，怕它格式不标准就崩时。

把模型调用收敛到一处，换供应商只改一层。

出现场景 系统要支持多家模型供应商、或随时切换兜底模型时。

指标的分子、分母与边界情况合在一起的可复现定义。

出现场景 写评测代码前；对比两个版本时口径必须保持一致。

按样本标签分组分别统计的指标，用于发现局部退化。

出现场景 看总指标提升时；排查「整体好但某层坏」时。

跌幅小于历史波动区间的差异，不当作回归去修。

出现场景 看到指标下降、要决定「是否算回退」时。

必须保留并归因的未通过样本列表，是改动的依据。

出现场景 评测跑完之后；要排下一轮迭代清单时。

别人按同一口径能算出同一个指标的属性。

出现场景 接手同事的评测、或跨版本对比数字时。

警惕整体指标提升掩盖某个分层指标退化的机制。

出现场景 看对比报告、总指标上升时；设计门禁时。

10-20 条最低限度样本，每次提交必跑且必须全过。

出现场景 PR 创建后接入门禁；判断系统还能不能跑通。

100-300 条曾真实发生的问题，钉住不许退步的样本集。

出现场景 每次发版前；验证修过的 bug 没再出现。

极端输入（超长、空值、多语言、歧义）下是否崩溃的样本集。

出现场景 每次发版；评估系统的鲁棒性下限。

恶意输入、提示注入、诱导越权的攻击样本集。

出现场景 定期（月度）；发布前作为安全底线。

约 20% 不能看单条、不能针对性优化的无偏样本池。

出现场景 发版前/对外汇报；判断有没有过拟合时。

约 80% 可反复跑、可针对失败样本定向优化的样本池。

出现场景 日常迭代；指导改进方向（不作对外结论）。

只提升在特定样本上的分数，而没有泛化到新输入。

出现场景 调试池与保留池差距扩大时；评测集分数长期不动时。

线上问题经定性、脱敏、标注后沉淀为回归样本的机制。

出现场景 评测集生长；发现新的线上问题要固化时。

样本能否被自动化判定通过或不通过的性质。

出现场景 决定一条样本能不能进回归集时。

标注应该调用哪个工具、传什么参数、是否应拒绝或澄清。

出现场景 给回归集写标注；区分 badcase 该进集还是该重写时。

模型输出能被解析、被引擎接受且结果正确的比例。

出现场景 报办事型 Agent 的核心指标时；跨团队对比时。

工具调用参数与人工标注期望值的匹配比例。

出现场景 评测办事型 Agent 调参对不对时。

任务按期望行为完成的样本占比，判定方式分三档。

出现场景 衡量一个任务最终有没有被办成时。

信息不足、不该硬答，应拒绝或澄清的样本。

出现场景 评测集里混入模糊/缺信息请求时；算分层指标时。

以全部样本为分母的完成率，最能反映真实体验。

出现场景 对外汇报；衡量用户真正感受到的完成水平时。

规范化后判定两个不同写法表达同一含义。

出现场景 字段级比对误杀等价表达时；算语义等价级准确率时。

统一大小写、单位与同义词后再比对参数的处理。

出现场景 算语义等价级参数准确率前；维护比对规则时。

参数比对的四种严格程度：结构/字段/语义/结果级。

出现场景 定参数准确率口径前；选生产环境评估档时。

规范化规则纳入版本管理，变更时口径必须标注更新。

出现场景 改 RULES 同义词表时；复盘指标突升突降时。

不可解样本上正确拒绝或澄清的比例。

出现场景 评测系统会不会硬猜时；分层报告的第三层。

把评分拆成每维 5/3/1 分且能回答是否的具体描述。

出现场景 做洞察型评分、写机器打分提示词时。

用模型给输出打分以降低人工成本的手段。

出现场景 洞察型输出要批量评分、人工成本太高时。

两两对比时评审模型偏向先出现的那一个。

出现场景 做两两对比、判 A 与 B 谁更好时。

评审模型给更长更啰嗦的输出更高分。

出现场景 评长文/报告类输出、担心「写多得分高」时。

评审模型偏袒与自身风格相似的输出。

出现场景 选评审模型、避免同源自证时。

结构化、带小标题、带 emoji 的输出得分更高。

出现场景 评带 Markdown 排版的洞察输出时。

某一维低于阈值直接判不合格，不参与平均。

出现场景 合成多维评分、避免短板被平均分掩盖时。

输出是否回答了用户真正关心的问题，权重最高。

出现场景 评洞察型输出第一维；合成加权时。

每条结论是否有可核验的依据与量级。

出现场景 评洞察型输出第二维；揪出「显著」「大幅」等空话时。

用户看完能否据此排期行动。

出现场景 评洞察型输出第三维；合成时触发否决。

判断 A 与 B 谁更好，必须交换顺序各跑一次。

出现场景 选两个版本/两份输出择优时；机器评委做对比时。

用同源模型既生成又评审，分数自证的陷阱。

出现场景 搭评审管线、选评审模型时；识别「虚假高分」时。

一次请求的完整记录，要求能本地重放。

出现场景 出问题查原因、要做复盘与归因时。

用当时的请求体重跑，对比改动前后结果。

出现场景 验证一次代码改动是否真改善时；做 A/B 对照时。

把失败定位到具体环节，产出分布而非单一失败率。

出现场景 评测跑出失败、要排改动清单时。

把评测接进 CI，不达基线则阻塞合并或发布的关卡。

出现场景 PR/发版流程；让评测有约束力时。

按 1%→5%→20%→全量逐步放量验证真实分布。

出现场景 发版后上线；用真实流量验证改动时。

用户主动重试的比例，是最接近真相的质量信号。

出现场景 衡量真实体验、挖掘 badcase 时；与完成率并列观察。

事先写死触发回滚的指标阈值，不允许临时决定。

出现场景 灰度发布前；定义什么情况必须撤。

按环节统计失败原因的分布，比失败率有用得多。

出现场景 周会排期、决定这轮改哪一层时。

用户主动中止任务的比例，与重试率并列观察。

出现场景 衡量真实体验、监控线上质量时。

可锚定的对象及其别名与层级，解决说的是不是同一个东西。

出现场景 知识建模第一层；用户说法与库里标准名对不齐、检索漏召回时，先查这里。

可溯源的关系与数值，是唯一可直接作为结论依据的层。

出现场景 回答「是什么」时引用的就是它；看到「来源+口径+时间」三件套就在这层。

带依据链的衍生结论，只能提供视角，不能当事实。

出现场景 给出「分析/建议/预测」时说的就是它；看到「据某数据推测」要想到这层。

推断所依赖的事实 id 列表，缺了就不许入库。

出现场景 判断一条「分析结论」能不能信、能不能入库时，先看它的依据链。

每个数值被计算时所依据的定义版本。

出现场景 比较两个时期的同一指标前，必须先确认口径版本是否一致。

把华东、东区、East China 映射到同一实体 id。

出现场景 用户说法和库里标准名对不上、检索漏召回时，第一步就是别名归一。

组织架构、元数据等权威基础数据。

出现场景 搭建实体层时，主数据是标准名、别名、层级的主要来源。

把自然语言需求转成可执行查询语句的过程。

出现场景 办事型 Agent 要把「华东区上季转化率」变成可取数的调用时，就是它。

据上下文判断转化率具体指哪条业务线的指标。

出现场景 同一个词在不同业务线含义不同、必须先定位时，靠它。

每条事实能回溯到产生它的源系统。

出现场景 判断一条数据能不能信、能不能比对时，先看它有没有源系统。

把检索到的材料注入上下文再生成回答的完整链路。

出现场景 凡是「基于资料回答、附引用」的系统，背后都是这条六环节链路。

把用户口语转成检索意图：别名归一、指代消解、改写。

出现场景 拿到用户原始提问、还没去检索之前，先过这一环。

把文档切成可检索的单元。

出现场景 建索引前必须把长文档切成块；回答不准先怀疑切分切坏了。

向量化并建立可快速近邻查找的结构。

出现场景 切分完成后建索引；检索变慢或全错，先查索引是否与模型版本一致。

从索引里取回一批候选的动作。

出现场景 RAG 第四环；讨论「取回多少条候选、怎么过滤」时就是它。

对候选做精排并截断到 N 条。

出现场景 召回之后、组装之前；回答相关但排序不对时查这一环。

小块用于检索，命中后返回其所属的大块。

出现场景 既要检索准、又要上下文足时，默认选它。

相邻块保留 10%-20% 重叠，降低答案被切断的概率。

出现场景 切分长文档时；答案被切在两块中间、两边都不全，就是重叠不够。

把版本、语言等条件在召回阶段就下推过滤。

出现场景 只要搜「某版本/某语言/某时间」的文档，就必须用它在召回层过滤。

召回阶段返回的候选条数。

出现场景 配召回参数、排查「该命中却没命中」时，先调 top-k 看。

嵌入实际编码的是主题语义，而非精确信息。

出现场景 解释「向量为什么找错、为什么擅长同义」时，回到语义场。

支持与不支持、同比增与降在向量空间里几乎重合。

出现场景 用户问「不支持/下降」却召回一堆「支持/上升」时，就是它。

订单号、错误码、函数名等差一字符即另一对象的信息。

出现场景 查编号、型号、函数名这类「一字不差」的查询，必须走精确路。

否定词在向量空间几乎不产生位移，导致召回相反内容。

出现场景 带「不/未/无/非」的查询召回到反义文档时，就是它。

把向量分与关键词分归一化后加权求和。

出现场景 想把两路信号合成一个分数来排序时，会先想到它。

用哪个度量取决于嵌入模型训练时的选择，而非直觉。

出现场景 新接一个嵌入模型、决定用余弦还是点积时，先看模型卡。

亲手验证支持与不支持、ERR_45004 这类该远却近的相似度。

出现场景 上线前想确认「哪些查询向量搞不定」时，必做它。

关键词与向量两路并行召回再融合。

出现场景 纯向量总漏精确串或极性、纯关键词总漏同义时，上混合。

基于词频与逆文档频率的关键词检索打分算法。

出现场景 混合检索里负责精确串、否定词、编号的那一路，就是它。

只看排名不看分数，按 1/(k+rank) 求和后再排序。

出现场景 两路检索结果要合并、又懒得调归一化权重时，用 RRF。

把查询与候选拼成一段一起过模型，捕捉细粒度交互。

出现场景 召回后要精排、且 candidate 只有几十条时，用它。

两路分数各自归一化后按权重相加的融合方式。

出现场景 你想显式控制向量路与关键词路占比时，用这种融合。

回答里标注了证据清单中不存在的编号。

出现场景 模型在结论后写了编号、但清单里查无此号，就是它。

引用可信度的四个等级，从无引用到可点开验证。

出现场景 评估一个系统「引用到底能不能信」时，按这四级打分。

附在产物末尾、可逐条点开核对的依据列表。

出现场景 报告末尾那张带链接、可逐条核对的列表，就是它。

生成后检查引用 id 是否真实存在并按结果降级。

出现场景 回答生成完、交付前，跑一遍它就是这道闸。

给知识标注有效时长，到期即视为待验证。

出现场景 价格、汇率、排期这类「会随时间失效」的事实型知识入库时。

只更新变化的部分，而非整体重建。

出现场景 上游数据源局部变化时；知识库体量大、全量重建太贵时。

把知识恢复到某个历史版本。

出现场景 新版本引入错误结论、需要撤销时。

衡量知识是否过时的可计算特征。

出现场景 召回多条知识后决定优先信哪条时；做新鲜度排序时。