以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。
选模型时,团队通常拿到一张参数表:上下文 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,所以非法卡不会被误判为“通过阈值”。这个顺序很重要:先保证数据合法,再谈是否达标。
这个实验只演示结构校验,不判断数字是否真实。一张卡可以字段齐全、取值合法,但数字来自有偏的评测集;结构校验能挡住明显的错误,挡不住测量方法的问题。
能力卡与参数表的区别
| 维度 | 参数表 | 能力卡 |
|---|---|---|
| 目的 | 展示规格 | 支持选型 |
| 指标 | 上限、价格 | 分布、成功率、边界 |
| 条件 | 通常省略 | 明确记录 |
| 可复验 | 难 | 可重跑 |
| 更新 | 随版本发布 | 随评测更新 |
参数表回答“最大能放多少”,能力卡回答“在什么条件下、多可靠地完成什么”。前者是规格,后者是证据。选型需要证据。
能力卡怎么写才可比较
可比较的能力卡有三个特征:
- 字段固定:所有候选模型用同一套字段,缺项写“未测”,而不是省略。
- 单位固定:延迟用秒、成本用同一货币、比例用 0–1。
- 条件固定:同一评测集、同一提示模板、同一采样参数。
缺项写“未测”很重要。省略会让读者误以为“没有这项要求”,而“未测”明确表示“不知道”。选型时,未知项应该被当作风险,而不是零成本。
尾延迟与分布
能力卡里的延迟应该用分位数,而不是平均值。Agent 的体验由尾延迟决定:平均 0.5 秒、p95 3 秒的系统,用户会记住那 5% 的卡顿。
| 指标 | 含义 | 用途 |
|---|---|---|
| p50 | 中位延迟 | 典型体验 |
| p95 | 95 分位 | 尾延迟预算 |
| p99 | 99 分位 | 极端情况 |
同样,工具成功率和接地率也应该给出样本量和置信区间。一个 0.94 的成功率,如果只测了 50 次,区间可能很宽;能力卡不写样本量,读者无法判断精度。
能力卡的边界
能力卡不能替代完整评测:
- 它只覆盖选型最关心的字段,不覆盖所有任务;
- 它是某个时间点的快照,模型更新后会过期;
- 它依赖评测集,评测集有偏则数字有偏;
- 它不告诉你“为什么失败”,只告诉你“失败多少”。
所以能力卡应该和失败分析、回归测试、线上监控一起使用。它是入口,不是结论。
架构含义
能力卡对架构有四个直接约束:
- 字段标准化。 所有候选模型用同一套字段和单位。
- 条件可追溯。 评测集、提示、参数、日期都要记录。
- 分布优先。 延迟用分位数,成功率带样本量。
- 缺项显式。 未测就写未测,不用省略掩盖未知。
第 4 条决定能力卡是否诚实。省略一个字段,读者会默认它不重要;写“未测”,读者会知道这是一个需要补测的风险。选型决策应该建立在“已知的未知”上,而不是“未知的未知”。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 字段齐全 | 8 个必填字段 | 只有上下文和价格 |
| 定义明确 | 每个字段有口径 | 同名不同义 |
| 条件记录 | 评测集/提示/参数/日期 | 只给数字 |
| 分布完整 | p50/p95 + 样本量 | 只给平均 |
| 缺项显式 | 未测标注 | 直接省略 |
这些判据里,“定义明确”是最容易出问题的一条。不同团队对“工具成功率”的理解可能完全不同:有人算格式合法,有人算参数正确,有人算目标达成。口径不统一,能力卡就失去了比较的意义。
一个选型的例子
假设要在两个模型之间选型。参数表显示:
| 模型 | 上下文 | 价格 |
|---|---|---|
| A | 32k | 低 |
| B | 128k | 高 |
只看参数,B 更强但更贵。能力卡补充:
| 指标 | A | B |
|---|---|---|
| 工具成功率 | 0.86 | 0.94 |
| 接地率 | 0.78 | 0.88 |
| 拒答率 | 0.91 | 0.95 |
| ttft p95 | 1.2s | 0.9s |
| 长上下文质量 | 未测 | 未测 |
如果任务是短上下文、工具调用为主,A 的成功率可能够用,成本更低;如果任务需要长文档综合,B 的 128k 有优势,但“长上下文质量未测”是一个必须补的风险项。能力卡让这个取舍显性化,而不是停留在“B 更强”。
如何维护能力卡
能力卡不是写一次就完了:
- 模型版本更新时重测;
- 评测集更新时标注版本;
- 线上监控发现偏差时回填;
- 每季度复核字段是否仍然 relevant;
- 保留历史版本,支持纵向比较。
维护成本不低,但比“每次选型都重新做一遍评测”低。能力卡的价值在于复用:一次测量,多处引用。
小结
- 能力卡用固定字段、单位和条件,把模型边界写成可比较的一页文档。
- 必填字段至少包括上下文、尾延迟、工具成功率、接地率、拒答率和成本。
- 测量条件(评测集、提示、参数、日期)与数字同样重要。
- 先做字段校验,再做阈值判定;非法数据不能被误判为达标。
- 延迟用分位数,成功率带样本量;缺项写“未测”,不要省略。
- 能力卡是选型入口,不替代失败分析和线上监控。
阅读导航:上一节:12.3 模型间差异的量化与 A/B · 下一节:13.2 选型矩阵:把场景、成本与风险放在一张表 。
常见错误与边界
- 把参数表当能力卡。 上下文和价格不能回答工具成功率、接地率和尾延迟。
- 字段同名不同义。 工具成功率的口径不统一,数字无法比较。
- 省略测量条件。 没有评测集、提示和参数,数字不可复验。
- 只给平均值。 Agent 体验由尾延迟决定,p95 比均值更有意义。
- 缺项直接省略。 会让读者误以为没有要求;应显式写“未测”。
- 把能力卡当完整评测。 它只覆盖选型字段,失败原因和线上表现仍需单独分析。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。