《AI Agent 技术原理与架构·模型、推理与能力边界》13.1 一页能力卡

选模型时,厂商参数表往往只给上下文长度和价格,缺少工具成功率、接地率、拒答率和尾延迟。能力卡用固定字段和测量条件,把模型边界写成可比较、可复验的一页文档。本节用字段校验与阈值判定实验,演示一张能力卡如何被验证和拒绝,并说明缺项与尾延迟应该如何处理。

以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。

选模型时,团队通常拿到一张参数表:上下文 128k、价格每百万 token 多少、支持工具调用。这些数字有用,但不足以回答 Agent 最关心的问题:工具调用成功率多少、检索接地率多少、该拒答时会不会拒答、尾延迟多长、长上下文下质量掉多少。

能力卡(capability card)就是为解决这个问题设计的:用固定字段、固定单位和固定测量条件,把模型边界写成一页可比较的文档。它不是营销材料,也不是完整评测报告,而是“选型时需要的最小事实集”。

能力卡应该有哪些字段

字段含义单位
model模型标识与版本字符串
context有效上下文长度token
ttft_p95首 token 延迟 95 分位秒
tpot_p95每输出 token 时间 95 分位秒
tool_success工具调用成功率0–1
grounding答案有证据支持的比例0–1
refusal该拒答时正确拒答的比例0–1
cost_per_1k每千 token 综合成本货币

字段不多,但每个都要有明确定义。比如 context 是“窗口上限”还是“有效可用长度”,差别很大;tool_success 是“调用格式合法”还是“动作达成目标”,也完全不同。字段名相同、定义不同,能力卡就无法比较。

测量条件同样重要

一个数字离开测量条件就没有意义。能力卡至少要记录:

  • 评测集名称、规模、分层;
  • 提示模板与工具定义版本;
  • 采样参数(温度、top-p、最大输出);
  • 推理服务与硬件(如果影响延迟);
  • 测量日期;
  • 失败样本的处理方式(算错、剔除还是重试)。

没有这些,读者无法判断数字是否适用于自己的场景。一个在短提示上测出的 0.94 工具成功率,可能在长上下文、多工具的场景下降到 0.80;能力卡不写条件,就会被误用。

最小实验:字段校验与阈值判定

下面的实验定义 8 个必填字段,检查取值范围,并按最低上下文、最大首 token 延迟和最低工具成功率判断一张卡是否“可发布”。

# file: agp_lab/capability_card.py | write
# tier: 3
# verify: python3 -m unittest tests.test_capability_card
"""一页能力卡:必填字段、取值范围与可发布判定。"""
from __future__ import annotations

from dataclasses import dataclass

FIELDS = ("model", "context", "ttft_p95", "tpot_p95", "tool_success",
          "grounding", "refusal", "cost_per_1k")


@dataclass(frozen=True)
class Card:
    model: str
    context: int
    ttft_p95: float
    tpot_p95: float
    tool_success: float
    grounding: float
    refusal: float
    cost_per_1k: float


BASE = Card("base", 32_000, 1.2, 0.04, 0.86, 0.78, 0.91, 0.012)
STRONG = Card("strong", 128_000, 0.9, 0.03, 0.94, 0.88, 0.95, 0.030)


def validate(card: Card) -> list[str]:
    errors: list[str] = []
    if card.context <= 0:
        errors.append("context 必须为正")
    if card.ttft_p95 <= 0 or card.tpot_p95 <= 0:
        errors.append("延迟必须为正")
    for name in ("tool_success", "grounding", "refusal"):
        value = getattr(card, name)
        if not 0 <= value <= 1:
            errors.append(f"{name} 越界")
    if card.cost_per_1k < 0:
        errors.append("cost 不能为负")
    return errors


def passes(card: Card, min_context: int = 32_000,
           max_ttft: float = 1.5, min_tool: float = 0.85) -> bool:
    return (not validate(card)
            and card.context >= min_context
            and card.ttft_p95 <= max_ttft
            and card.tool_success >= min_tool)


if __name__ == "__main__":
    for card in (BASE, STRONG):
        print(f"{card.model:<8} valid={not validate(card)} passes={passes(card)}")
    broken = Card("broken", 0, 1.0, 0.04, 1.2, 0.8, 0.9, 0.01)
    print("broken_errors:", validate(broken))

运行:

cd private/labs/agp-lab
python3 -m agp_lab.capability_card

输出:

base     valid=True passes=True
strong   valid=True passes=True
broken_errors: ['context 必须为正', 'tool_success 越界']

base 和 strong 都通过校验:字段在合法范围内,且满足最低上下文 32000、首 token 延迟不超过 1.5 秒、工具成功率不低于 0.85。

broken 的 context 为 0、tool_success 为 1.2,校验返回两条错误。注意 passes 会先调用 validate,所以非法卡不会被误判为“通过阈值”。这个顺序很重要:先保证数据合法,再谈是否达标。

这个实验只演示结构校验,不判断数字是否真实。一张卡可以字段齐全、取值合法,但数字来自有偏的评测集;结构校验能挡住明显的错误,挡不住测量方法的问题。

能力卡与参数表的区别

维度参数表能力卡
目的展示规格支持选型
指标上限、价格分布、成功率、边界
条件通常省略明确记录
可复验难可重跑
更新随版本发布随评测更新

参数表回答“最大能放多少”,能力卡回答“在什么条件下、多可靠地完成什么”。前者是规格,后者是证据。选型需要证据。

能力卡怎么写才可比较

可比较的能力卡有三个特征:

  1. 字段固定:所有候选模型用同一套字段,缺项写“未测”,而不是省略。
  2. 单位固定:延迟用秒、成本用同一货币、比例用 0–1。
  3. 条件固定:同一评测集、同一提示模板、同一采样参数。

缺项写“未测”很重要。省略会让读者误以为“没有这项要求”,而“未测”明确表示“不知道”。选型时,未知项应该被当作风险,而不是零成本。

尾延迟与分布

能力卡里的延迟应该用分位数,而不是平均值。Agent 的体验由尾延迟决定:平均 0.5 秒、p95 3 秒的系统,用户会记住那 5% 的卡顿。

指标含义用途
p50中位延迟典型体验
p9595 分位尾延迟预算
p9999 分位极端情况

同样,工具成功率和接地率也应该给出样本量和置信区间。一个 0.94 的成功率,如果只测了 50 次,区间可能很宽;能力卡不写样本量,读者无法判断精度。

能力卡的边界

能力卡不能替代完整评测:

  • 它只覆盖选型最关心的字段,不覆盖所有任务;
  • 它是某个时间点的快照,模型更新后会过期;
  • 它依赖评测集,评测集有偏则数字有偏;
  • 它不告诉你“为什么失败”,只告诉你“失败多少”。

所以能力卡应该和失败分析、回归测试、线上监控一起使用。它是入口,不是结论。

架构含义

能力卡对架构有四个直接约束:

  1. 字段标准化。 所有候选模型用同一套字段和单位。
  2. 条件可追溯。 评测集、提示、参数、日期都要记录。
  3. 分布优先。 延迟用分位数,成功率带样本量。
  4. 缺项显式。 未测就写未测,不用省略掩盖未知。

第 4 条决定能力卡是否诚实。省略一个字段,读者会默认它不重要;写“未测”,读者会知道这是一个需要补测的风险。选型决策应该建立在“已知的未知”上,而不是“未知的未知”。

架构判据

判据合格的样子不合格的样子
字段齐全8 个必填字段只有上下文和价格
定义明确每个字段有口径同名不同义
条件记录评测集/提示/参数/日期只给数字
分布完整p50/p95 + 样本量只给平均
缺项显式未测标注直接省略

这些判据里,“定义明确”是最容易出问题的一条。不同团队对“工具成功率”的理解可能完全不同:有人算格式合法,有人算参数正确,有人算目标达成。口径不统一,能力卡就失去了比较的意义。

一个选型的例子

假设要在两个模型之间选型。参数表显示:

模型上下文价格
A32k低
B128k高

只看参数,B 更强但更贵。能力卡补充:

指标AB
工具成功率0.860.94
接地率0.780.88
拒答率0.910.95
ttft p951.2s0.9s
长上下文质量未测未测

如果任务是短上下文、工具调用为主,A 的成功率可能够用,成本更低;如果任务需要长文档综合,B 的 128k 有优势,但“长上下文质量未测”是一个必须补的风险项。能力卡让这个取舍显性化,而不是停留在“B 更强”。

如何维护能力卡

能力卡不是写一次就完了:

  • 模型版本更新时重测;
  • 评测集更新时标注版本;
  • 线上监控发现偏差时回填;
  • 每季度复核字段是否仍然 relevant;
  • 保留历史版本,支持纵向比较。

维护成本不低,但比“每次选型都重新做一遍评测”低。能力卡的价值在于复用:一次测量,多处引用。

小结

  • 能力卡用固定字段、单位和条件,把模型边界写成可比较的一页文档。
  • 必填字段至少包括上下文、尾延迟、工具成功率、接地率、拒答率和成本。
  • 测量条件(评测集、提示、参数、日期)与数字同样重要。
  • 先做字段校验,再做阈值判定;非法数据不能被误判为达标。
  • 延迟用分位数,成功率带样本量;缺项写“未测”,不要省略。
  • 能力卡是选型入口,不替代失败分析和线上监控。

阅读导航:上一节:12.3 模型间差异的量化与 A/B · 下一节:13.2 选型矩阵:把场景、成本与风险放在一张表 。

常见错误与边界

  1. 把参数表当能力卡。 上下文和价格不能回答工具成功率、接地率和尾延迟。
  2. 字段同名不同义。 工具成功率的口径不统一,数字无法比较。
  3. 省略测量条件。 没有评测集、提示和参数,数字不可复验。
  4. 只给平均值。 Agent 体验由尾延迟决定,p95 比均值更有意义。
  5. 缺项直接省略。 会让读者误以为没有要求;应显式写“未测”。
  6. 把能力卡当完整评测。 它只覆盖选型字段,失败原因和线上表现仍需单独分析。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图