Confidence 置信度：模型说「我不确定」时怎么办

前四课的答案你都已经见过 confidence：Choice 的工单在 returns 和 billing 之间分裂时它是 0.42，Score 的 bug 报告在两级之间摇摆时它是 0.35，Noul 压根不给它。这个数从哪来、怎么用、什么时候不用听它的——这节课把 Jev confidence 一次讲清，全程 12 分钟。

先给结论：confidence 是答案自己的概率分布算出来的一个数，不是模型的自我表白。你在代码里拿它做一件事——决定这个答案要不要自动执行。

学完你能做什么

• 用官方公式从 probabilities 手工验算任何一个 confidence：Choice 和 Score 各有一套，都能在 Python 里复现
• 用三档用法写代码：高置信自动执行、中置信标记复核、低置信转人工
• 按风险缩放阈值：0.5 兜底，approve_transfer 这类高危操作要求 > 0.9 才无人值守
• 说清 Noul 为什么没有 confidence、想统一门槛时怎么自算 |2p − 1|
• 该用 probabilities 时不硬用 confidence：top 概率和 top-to-second 比这两个替代指标什么场合更合适

你现在的困境

• 自动化跑得好好的，突然一条输入走出离谱分支——事后看，模型当时其实「不确定」，但你的代码没处知道
• 问 GPT「你确定吗」，它回一段「我相当有把握，但也不排除……」的散文，if 写不出来
• 也想过自己从概率分布里造个「确定度」，但每个题型分布形状不一样，公式定不下来，阈值更没法统一

什么时候用这一招

当你需要：

• 在「自动执行 / 转人工」之间做门控：答案告诉你是什么，confidence 告诉你要不要做
• 同一套 0 到 1 的标尺处理所有 Choice / Score 答案，从第一个请求就能设阈值
• 中文等非英语材料上线前的体检：官方明说 CJK 准确度较低，路由时要盯紧 confidence

而且不想：

• 到处设阈值——只关心挑最优时直接取最高概率选项就行（见踩坑提醒第 4 条）
• 为「模型有多确定」再发一次请求、再调一个模型
• 在模型自己都没把握时硬让它自动执行

🎒 开始前的准备

• 完成了 Score 打分题：手上有能跑的 score_bug.py，见过 1.43 / 0.35 那个答案
• 看过 Choice 选择题：知道 probabilities 是所有选项的分布、总和约为 1
• 跑通过第一个请求：.venv 里装好了 typesafe-sdk，TYPESAFE_API_KEY 已在环境变量里

核心思路

confidence 是分布形状的单一数字摘要。 每个 Choice / Score 答案都自带 probabilities——概率怎么铺开，就是模型确定程度的全部信息：全押一个结果 = 很确定，均匀摊开 = 不确定。confidence 只是把这件事压成一个 0 到 1 的数，让你不用自己做数学。

分布形状	confidence	模型的意思
全在一个结果上	1	「就是它」
集中但分裂	0.4 上下	「大概率是它，但有备选」
均匀摊开	0	「我说不好」

两个关键认识，先立在这里：

• 它不是「答案正确」的保证。 confidence 1.0 描述的是「分布全押一个结果」这件事，不保证那个结果对——题目写得含糊时，模型可以很自信地押错
• 它不需要你额外出钱。 TypeSafe 在每个 Choice / Score 答案上直接返回它，常见用法零额外工作

为什么值得专门用一个数？官方文档的原话：一个智能系统——不管人还是机器——如果不能表达诚实的不确定，就不值得信任。confidence 就是模型说「这条我不确定」的内置机制——你的代码由此能对不同确定度做不同的事。这是搭建「真正可靠」的系统的基础。

三种题型和 confidence 的关系一张表说清：

题型	有没有 confidence	为什么
Choice	✅	概率铺在 n 个选项上，需要概括
Score	✅	概率铺在有序等级上，需要概括
Noul	❌	只有是/否两种结果，一个概率 noul 已经把分布说完了
Box	✅	图像定位也带一个 0–1 的数

跟我做

第 1 步：把 Score 工单答案的 confidence 手工验算出来

为什么：不信公式就没法信阈值。拿 Score 课跑过的、官方录制过的真实答案验算一遍——算得出 0.35，后面所有的阈值才立得住。

Score 课 score_bug.py 的完整答案（官方示例，bug_severity）：

{
  "type": "score",
  "score": 1.43,
  "confidence": 0.35,
  "probabilities": {
    "0": 0.0,
    "1": 0.57,
    "2": 0.43
  }
}

分数 1.43 怎么来的你已经会了（等级号 × 概率加权）。confidence 0.35 呢？官方 Python 函数，逐字可用：

def score_confidence(probabilities: list[float]) -> float:
    n = len(probabilities)
    m = probabilities.index(max(probabilities))
    spread = sum(p * abs(i - m) for i, p in enumerate(probabilities))
    even_spread = sum(abs(i - (n - 1) / 2) for i in range(n)) / n
    return max(0.0, 1 - spread / even_spread)


levels = sorted(answer.probabilities)
score_confidence([answer.probabilities[level] for level in levels])

在 score_bug.py 末尾补上这几行（answer = response.answers["bug_severity"]），再跑：

.venv/bin/python score_bug.py

你应该看到：函数返回 0.355——和 API 返回的 0.35 一致（0.355 四舍五入到两位小数就是 0.35）。官方文档对同一分布的验算：最可能级是 1，spread 是 0.43，三档的均匀分布平均距离是 2/3，所以 1 − 0.43 ÷ (2/3) ≈ 0.35。

现在你知道了一件重要的事：confidence 不是黑盒评分，是纯函数——任何时候都可以从答案自己的 probabilities 复算出来。公式的直觉在 Score 和 Choice 里略有不同，接下来两步分别看。

• 我跑出了 0.355，知道它和 API 返回的 0.35 是同一个数

第 2 步：验算 Choice 的 confidence 公式：只看最高概率

为什么：Choice 是你日常用得最多的门控信号（智能路由就建立在它上面），它的公式比 Score 简单得多，一行就能心算。

对 n 个选项、最高概率为 p_max 的 Choice：

confidence = (p_max − 1/n) / (1 − 1/n)

读法：衡量最高概率超出「均分线」（每个选项 1/n）多远——均分 = 0，全押 = 1。三选项代入，就是 Choice 课你见过的那个形式：

confidence = (3 × 最大概率 − 1) / 2

用官方函数验算。它只看 top 概率——(0.6, 0.3, 0.1) 和 (0.6, 0.2, 0.2) 的 confidence 都是 0.4：

def choice_confidence(probabilities: list[float]) -> float:
    n = len(probabilities)
    return (max(probabilities) - 1 / n) / (1 - 1 / n)


choice_confidence(list(answer.probabilities.values()))

你应该看到：

choice_confidence([0.6, 0.3, 0.1])  # 0.4
choice_confidence([0.6, 0.2, 0.2])  # 0.4

自己动手算 Choice 课那条含糊工单的 department（returns 0.61、billing 0.35、shipping 0.04）：(0.61 − 1/3) / (2/3) ≈ 0.42——正是官方当时返回的 0.42。

这个公式的性格你要记住：Choice 的 confidence 装瞎——只看第一名，不管第二三五名怎么分。这是 Choice（选项无顺序）和 Score（等级有顺序）的分野，也是下一步的内容。

• 我能心算三选项的 confidence：(3 × 最大概率 − 1) / 2

第 3 步：理解 Score 公式为什么算「距离」

为什么：Score 的等级有先后顺序——「有点严重」和「很严重」是邻居，「不要紧」和「致命」是两端。同样分裂在两档上，分裂的位置不同，确定度应该不同。Choice 公式做不到这一点。

官方的对照，值得盯着看十秒：

三级量表上的概率	confidence	模型的状态
(0, 0.5, 0.5)	0.25	在相邻两级之间纠结
(0.5, 0, 0.5)	0	在光谱两端之间撕裂
(0.6, 0.2, 0.2)（当 Choice 算）	0.4	只看第一名

Choice 公式给前两个分布算出的都是 0.25——它看不见「距离」。Score 公式看得见：

confidence = max(0, 1 − 概率加权·离最可能级的平均距离 ÷ 均匀分布的平均距离)

第 1 步代码里的 spread 就是那个「概率加权的平均距离」，even_spread 是均匀分布的参照距离，分布比均匀还散时下限取 0。效果一句话：概率落在邻近级扣得少，落在远端扣得多。

什么时候该联想到这组对照？看到低 confidence 官方给了三种解释：等级对这个输入重叠、问题测了不止一件事、state 信息不够。逐条排查：改等级描述、拆题、补材料——Score 课的踩坑提醒展开过做法。

你应该看到：用第 1 步的函数验算 score_confidence([0, 0.5, 0.5]) 得 0.25、score_confidence([0.5, 0, 0.5]) 得 0.0——和官方文档的数字一致。

• 我能说出 (0, 0.5, 0.5) 和 (0.5, 0, 0.5) 的 confidence 分别是多少、为什么不同

第 4 步：用三档用法把 Jev confidence 变成代码行为

为什么：验算完公式，回到最实际的问题——拿到一个 0 到 1 的数，if 怎么写。官方给的起点模式：切成三档，每档一种行为。

档位	代码行为	官方原话的意思
高	自动执行	模型看得清楚，不需要人介入
中	谨慎行事——让用户确认、标记复核、先补信息再动	答案合理，但模型不肯定
低	不执行——转人工、要求澄清、回退到其他系统	模型在说：信息不够，或这题不合适

把它套回熟悉的面孔（Choice 课第 3 步的五道题，官方示例值）：

问题	confidence	三档怎么落
return_reason（wrong_size 1.0）	1.0	高：直接采用
tone（frustrated 0.84）	0.76	高 / 中边界：自动可用
shipping_issue（delayed 0.74）	0.67	中：反正部门不是 shipping，代码直接忽略
department（returns 0.61）	0.42	中：按 returns 走，但 billing 抄送一份
requested_resolution（refund 0.40）	0.2	低：去问客户，别猜

你应该看到：同一批答案按 confidence 落进三档，每档对应一种明确的代码行为——而不是只有「执行 / 不执行」一个开关。

分档的边界画在哪？官方下一句就是答案——取决于风险，也就是下一步。

• 我能对任何一个 confidence 说出它落在哪一档、那一档该做什么

第 5 步：让置信度阈值随风险缩放（官方完整代码）

为什么：三档的边界不是三个全局常数。官方一句话点破：同一个系统里，不同动作该按「做错的后果」设不同的门槛。这就是置信度阈值（confidence threshold）和普通魔法数字的区别。

官方完整示例——语音银行助手的意图判断，三种意图风险悬殊：

response = client.system_one(
    state=user_message,
    questions={
        "action": Choice(
            instructions="What is the user trying to do?",
            criteria={
                "check_balance": "View account balance",
                "approve_transfer": "Approve the pending withdrawal request",
                "support": "Get help with an issue",
            },
        ),
    },
)

action = response.answers["action"]
confidence = action.confidence

if confidence < 0.5:
    # Model is genuinely unsure. Don't guess.
    route_to_human(user_message)

elif action.choice == "check_balance":
    # Low stakes. Showing the wrong screen is recoverable.
    show_balance(account_id)

elif action.choice == "approve_transfer":
    if confidence > 0.9:
        # High stakes, high confidence. Proceed with confirmation.
        confirm_then_execute(account_id)
    else:
        # High stakes, moderate confidence. Verify first.
        ask_user_to_confirm(account_id)

逐个门控拆开（全部来自官方代码）：

门控	值	逻辑
兜底 floor	0.5	先接住「模型说拿不准」的一切——不许猜
check_balance	0.5 以上即可	低危：大不了示错屏，可恢复
approve_transfer	> 0.9 才直接执行	高危：批量转账做错了不可逆，先确认

风险编码在你的代码里，不在模型里——这是官方反复强调的立场。配套两条实操建议：

• 从保守起步：阈值先设高，用自己的数据测，看到真实表现再调——官方 NOTE 原话：正确的阈值取决于你的领域和模型在你的用例上的表现
• 改阈值不用改 prompt：阈值是代码常数。官方 Agent Skill 建议把问题和阈值常量集中在一个文件里，人审起来不用到处翻

你应该看到：一段路由代码，先有 0.5 兜底、再按动作类型分层——而不是一个全局阈值切到底。

顺带回答上一课留的问题：route_to_human / show_balance 这些是示意函数名，换成你自己的处理逻辑。

• 我的门控代码有一个兜底 floor，高危动作的阈值比低危的高

💡 Noul 想进同一套门槛怎么办

Noul 课的进阶技巧给过公式：confidence = |2p − 1|——p 为 0.99 算出 0.98，p 为 0.5 算出 0。官方说明它就是把 Choice 公式套在「是/否」两个选项上，所以和 Choice 的 confidence 同标尺，可以进同一套门控代码。

检查点 ✅

• 我手工验算过至少一个 confidence（Score 的 0.35 或 Choice 的 0.42），知道它是 probabilities 的纯函数
• 我知道 Choice 公式只看最高概率，(0.6, 0.3, 0.1) 和 (0.6, 0.2, 0.2) 都是 0.4
• 我能说出 (0, 0.5, 0.5) 是 0.25、(0.5, 0, 0.5) 是 0，以及为什么 Score 公式要算距离
• 我的代码是三档用法：高自动执行、中确认或标记、低转人工；阈值随风险缩放（0.5 兜底、高危 > 0.9）
• 我知道 confidence 是「分布形状」不是「答案正确」的保证，题含糊时模型会自信地押错

踩坑提醒

❌ 把 confidence 当「答案正确」的保证

现象：confidence 1.0 的答案出了错，开始怀疑模型「装嘴硬」。

为什么错：confidence 1.0 只描述「这一题的分布全押一个结果」，说的是模型这个答案内部的一致，不背书它对了。等级描述含糊、state 缺信息时，模型可以很自信地押在错误选项上——Score 课的量表实验里，confidence 照样给得出 1.0 级别的数。

正确做法：把 confidence 当「要不要自动执行」的门控，题目的质量另测——官方 NOTE 原话：用你自己的数据、按观察到的表现调整。低 confidence 排查三方向（等级重叠 / 问题测多件事 / state 信息不够）才是去病因的路。自一致性场景页展示的是另一条路：跨多次运行量稳定性。

❌ 阈值一刀切，高危低危共用一个数

现象：给所有动作设同一个置信度阈值（比如全站 0.6），上线后低危动作疯狂转人工、高危动作偶尔溜过去。

为什么错：官方明说不同动作做错的后果不同——check_balance 错了可恢复，approve_transfer 错了不可逆。同一个阈值不可能同时满足两种风险。

正确做法：0.5 兜底 + 按动作分层（第 5 步的官方代码）；另外别用 X-Y 常数做全局门槛，把阈值写成熟知的具名常数和注释，和问题定义放一个文件里方便人审。

❌ 用 confidence 做分布分析

现象：想算「第二名比第一名差多少」「概率的熵是多少」，伸手去拿 confidence。

为什么错：confidence 是把分布压扁后的单一摘要，压扁即丢信息。官方 Agent Skill 常见问题清单点名了：有具体统计算法需求时，该用的是 probabilities 不是 confidence。

正确做法：做分析拿 probabilities（它每次都完整返回，官方明说「你可以自己算任何重要的指标」）；做门控拿 confidence。两个需求经常并存——那就在答案里各取各的，见进阶技巧。

❌ 到处设 confidence 阈值

现象：每个答案、每条分支都放一个阈值，越设越多，调不过来。

为什么错：官方 Agent Skill 常见问题清单：只关心挑出最优选项时，直接取概率最高的那个（即返回的 choice）就行，不必到处设 confidence 阈值。

正确做法：只在「不确定这个答案能不能自动执行」的关键门控上设阈值（第 5 步的三处就是典型）；挑最优直接取 choice / 最高概率。这也是官方说的「到处都是阈值」症状的解药。

❌ Noul 答案上找 confidence 字段

现象：response.answers["is_urgent"].confidence——报 AttributeError。

为什么错：Noul 的分布只有两种结果，一个概率值已经完整描述了它，没有要概括的东西，官方在 Noul 页和 Confidence 页各强调过一遍。接近 0.5 本身就是它的不确定信号。

正确做法：直接用 Noul 课的起步阈值 yes ≥ 0.7、no ≤ 0.3，中间值转人；需要同标尺时自算 |2p − 1|（第 5 步的 tip）。

进阶技巧（可选）

🔧 不想用官方 confidence？两个替代指标。 官方明说 confidence 只是「一种合理的概括，不是唯一的」——以下两个从同一份 probabilities 算出，实践中常常同样有效，值得和 confidence 并排试：

指标	定义	什么场合顺手	官方提醒
top 概率 p_max	第一名的概率，直接读作「选中项的可能性」	阈值好推理	含义随选项数变——0.5 在两选项里是弱答案、十个选项里是强答案，每题单独设阈值
top-to-second 比 p_max / p_second	第一名比第二名清晰多少	真实决策常就看前两名	无视其余选项的分布

因为公式是精确的、probabilities 每次都完整返回，你的应用需要什么统计量就可以自己算什么——官方返回一个固定值只是让你「从第一个请求起就有个合理的默认」。

🔧 中文材料的 confidence 体检。 官方在语言支持页明说：包括 CJK 在内的其他语言能用但准确度较低，非英语负载「路由时要盯紧 confidence」。中文内容上线前：拿自己的数据跑一批，统计 confidence 分布和落进不确定带的答案比例，再定阈值——这也是本栏目反复强调的第一步。

🔧 不写代码先感受公式。 第一个请求课的 Playground（console.typesafe.ai/playground）里贴 state、加 Choice 题，观察滑一个选项概率时 confidence 怎么变——官方文档页首的交互演示就是这个原理（三选项，(3 × 最大概率 − 1) / 2）。

本课小结

✅ Jev confidence 是答案自己的 probabilities 算出来的统计量：全押一个结果 = 1，均匀摊开 = 0；每个 Choice / Score 答案自带，Noul 没有。

✅ 公式可验算：Choice 是 (p_max − 1/n) / (1 − 1/n)（只看最高概率）；Score 按概率加权的离最可能级距离对比均匀分布，邻近级扣得少、远端扣得多。

✅ 三档用法：高自动执行、中确认或标记、低转人工；阈值随风险缩放——0.5 兜底，approve_transfer 高危要 > 0.9。

✅ 两件不要做：不把 confidence 当正确保证（它描述分布）；不做统计分析（分析用 probabilities，挑最优直接取最高概率）。

关键配置字段回顾：

字段 / 常数	推荐值	说明
confidence	0–1，直接读	Choice / Score / Box 答案自带；Noul 无
兜底 floor	0.5	官方示例的起点；低于它一律不自动执行
高危动作阈值	> 0.9	不可逆操作（转账、删除）的无人值守线
Noul 统一门槛	abs(2 * p - 1)	和 Choice confidence 同标尺
阈值存放	与问题定义同一个文件	官方建议：方便人审

confidence 用到真实系统的三个去处：智能路由（意图分类 + 置信度门控做成完整分流系统）；75 类行业分类（confidence ≥ 0.9 报小类、低于它报大类——60 份 SEC 年报实测：有把握的一半 90% 对，没把握的一半报大类后从 40% 提到 70% 可用）；自一致性（跨多次运行量答案稳定性）。

下一课预告

文本之外的判断怎么做？下一课：Box 与图像：让 Jev 在图里找东西。

你会学到：

• 图像放进 state 和问题里的两种方式，以及 Danger Zone 请求头怎么开
• Box 答案的四条边（top / bottom / left / right，各 0–1）怎么换算回像素坐标
• Box 答案自带的 confidence 怎么用：低于阈值时放大裁剪框或换更好的图再问
• 为什么官方称 Images / Box 尚未达到生产标准、格式可能随版本变化