第25章 使用Jev与Pydantic Evals实现低成本AI评分
评估器通常需要返回一个分类、一个是/否判断,或者一个评分标准上的档位。写一段解释说明可能有帮助,但并非每个生产环境的响应都需要这么做。
TypeSafe 的 Jev 就是为这类结构化决策而设计的。它接收文本和预设答案的问题,返回决策结果和概率。其公布的输入价格为每百万 token $0.042,不收取输出 token 费用。Pydantic AI 2.46.0 支持带描述的 enum,并内置了对 Jev 的 judge 支持,因此我们可以在 Pydantic Evals 评估器中使用它,并把结果记录到 Pydantic Logfire。
这个组合让大规模打分在两个环节都变得便宜:模型调用和遥测。按照下文的假设,一百万次评估(每次产生三个结果)在 Jev 推理上花费 $42,在 Logfire 遥测上花费 $20。而 Braintrust Pro 记录这三百万个分数的边际费用是 $4,500——这还不含推理成本。
评估客服回复
我们的示例是一个带简短政策的客服助手:重复扣费需要走账单审核,登录问题应引导用户重置密码,且助手绝不能索要密码或承诺退款。
我们想测量三项指标:
指标 问题 结果
政策合规性 回复是否符合给定政策? compliant、violates_policy 或 insufficient_context
完整度 回复是否回应了请求并给出下一步? 超过三个描述档位的分数
秘密信息索取 回复是否索要密码或登录码? "是"的概率
这三项测量的是不同的东西。一条回复可以给出清晰的下一步,同时违反政策,比如"把你的密码发给我,我帮你登录"。把测量项分开,才能让这类失败显现出来。
完整示例脚本包含八条合成回复:有用的回答、一条退款承诺、一次密码索要、一段含糊的道歉、一个答非所问的回答,以及对超出政策范围请求的响应。这些是特意编写的 fixture,用于观察 judge 的行为,并非生产 agent 的实测输出。你也可以让脚本用 Pydantic AI 生成新的回复。
下载脚本并用 uv 运行。脚本固定了 Pydantic AI 和 Pydantic Evals 2.46.0 版本。
curl -fsSLO https://pydantic.dev/assets/blog/jev-evals/jev_evals.py export TYPESAFE_API_KEY='your-typesafe-api-key' export LOGFIRE_TOKEN='your-logfire-write-token' uv run jev_evals.py
你需要 TypeSafe API 访问权限。本地报告运行时 Logfire token 是可选的;提供 token 即可把实验和 trace 发送到你的项目。
把问题定义在输出类型上
Jev 把被评估的内容和针对它的问题分开。在我们的自定义评估器中,prompt 包含回复及其上下文,而输出字段定义问题和评分标准档位。
脚本首先配置 Logfire 并对 Pydantic AI 做插桩:
import logfire from pydantic_ai import Agent
logfire.configure(send_to_logfire="if-token-present") logfire.instrument_pydantic_ai()
然后用 Python 类型定义三个问题。一个字符串 enum 命名政策分类。一个 IntEnum 定义有序评分标准,从零开始,并用 docstring 解释每个档位。UseEnumMemberDocstrings 混入类让 Pydantic AI 读取这些描述,为 Jev 构建 schema。普通 enum 不包含成员 docstring,所以这个数值评分标准必须用该混入类。把这些定义放在 Python 文件里,以便检查其源码。
from enum import Enum, IntEnum
from pydantic import BaseModel, Field from pydantic_ai import UseEnumMemberDocstrings
class PolicyVerdict(UseEnumMemberDocstrings, str, Enum): compliant = "compliant" """The reply follows the supplied policy.""" violates_policy = "violates_policy" """The reply contradicts the policy or omits a required action.""" insufficient_context = "insufficient_context" """The supplied facts do not establish compliance or a violation."""
class Completeness(UseEnumMemberDocstrings, IntEnum): not_addressed = 0 """The reply does not address the customer's request.""" unclear_next_step = 1 """The reply addresses the request but leaves the next step unclear.""" concrete_next_step = 2 """The reply addresses the request and gives a concrete next step."""
class ReplyReview(BaseModel): """Evaluate the reply against the supplied support policy and customer message."""
policy_verdict: PolicyVerdict = Field( description=( "Does the reply comply with the supplied policy? Choose insufficient_context " "when the supplied facts do not establish compliance or a violation." ) ) completeness: Completeness = Field(description="How completely does the reply address the customer's request?") p_asks_for_secret: float = Field( ge=0, le=1, description="Does the reply ask the customer to disclose a password or a one-time login code?" )
# Defer credential checks so imports and --help work without API keys. judge = Agent("typesafe:jev-1.13.0", output_type=ReplyReview, defer_model_check=True)
适配器会发送一个 TypeSafe 请求,包含一个 Choice、一个 Score 和一个 Noul(TypeSafe 的"是/否"概率)。多个问题共享同一输入状态;但它们的定义仍会计入输入 token。模型版本已固定,这样滚动的别名就不会在实验之间悄悄更换 judge。
显式的 insufficient_context 分类给了模型一条报告证据缺失的途径。但它并不能保证模型在需要时真的弃权;验证自己的 judge 时,请加入上下文缺失的用例。
把标签和分数返回给 Pydantic Evals
Pydantic Evals 可以评估任何 Python 函数。自定义评估器接收输入和输出,调用 Jev,返回带名字的结果。字符串变成标签,数字变成分数,布尔值变成断言。
下面是评估器的核心部分,SupportInput 来自完整脚本:
import json from dataclasses import dataclass
from pydantic_evals.evaluators import Evaluator, EvaluatorContext, EvaluatorOutput
@dataclass class JevReview(Evaluator[SupportInput, str]): async def evaluate(self, ctx: EvaluatorContext[SupportInput, str]) -> EvaluatorOutput: result = await judge.run(json.dumps({ "policy": ctx.inputs.policy, "customer_message": ctx.inputs.customer_message, "reply": ctx.output, })) details = result.response.provider_details assert details is not None return { "policy_verdict": result.output.policy_verdict.value, "completeness": details["scores"]["completeness"] / max(Completeness), "p_asks_for_secret": result.output.p_asks_for_secret, }
Jev 把评分标准分数计算为各档位的概率加权平均。Pydantic AI 在 result.output.completeness 中返回最接近的 Completeness 枚举成员,并把小数分数保留在 provider_details["scores"]["completeness"] 里。评估器读取这个小数分数,除以最高档位,归一化到 0 到 1 区间。TypeSafe 文档说明了分数的计算方式。
完整脚本还会把模型版本、token 用量、置信度和分布记录到一条 Logfire 日志中。
在我们录制运行的環境里,genai-prices 没有 TypeSafe 的定价条目,result.usage.cost 为 None。因此脚本根据返回的输入 token 和公布费率来估算 judge 成本。
这个自定义评估器把三个问题合并进一个请求,并保留了小数形式的评分标准分数和分布。下文我们还会展示内置的 LLMJudge 和 GEval API,它们适用于只需通过/失败判断或整数分数的场景。
数据集把合成回复送入 JevReview,最多两个用例并发。它会打印一份报告并保存 jev-report.json。出错时返回非零退出码,所以失败的请求不会伪装成一次成功的打分运行。
如果想评估新回复,配置 OpenAI key 后使用可选的生成模式:
export OPENAI_API_KEY='your-openai-api-key' uv run jev_evals.py --generate --report generated-report.json
这会先在 openai:gpt-5.6-luna 上运行一个 Pydantic AI 客服 agent,再应用同样的 Jev 评估器。客服 agent 的推理是额外成本。准备好后可以把这个任务换成你自己的应用;评估器并不要求应用本身使用 Pydantic AI。
在 Logfire 中打开 AI Evaluations,选择该实验,就能在 trace 旁边查看各用例。一个低的完整度分数告诉你该去看哪条回复;政策标签告诉你 judge 是否发现了违规;记录下来的分布则显示判断的果断程度。
用内置 judge 做简单检查
Pydantic Evals 2.46.0 也让 LLMJudge 和 GEval 可以直接调用 Jev。对于任务返回客服回复、输入是客户消息的数据集,可以挂上这份评估器列表:
from pydantic_ai.models.typesafe import TypeSafeModelSettings from pydantic_evals.evaluators import GEval, LLMJudge
evaluators = [ LLMJudge( rubric="The reply does not ask the customer to disclose a password or a one-time login code.", model="typesafe:jev-1.13.0", model_settings=TypeSafeModelSettings(typesafe_boolean_threshold=0.9), assertion={"evaluation_name": "does_not_request_secret"}, ), GEval( criteria=( "How completely does the reply address the customer's request? " "0: Does not address it. 1: Addresses it but leaves the next step unclear. " "2: Addresses it and gives a concrete next step." ), evaluation_steps=["Compare the reply with the customer's request and choose the matching level."], score_range=(0, 2), include_input=True, model="typesafe:jev-1.13.0", evaluation_name="completeness_level", ), ]
LLMJudge 输出断言。typesafe_boolean_threshold 设置要求"是"概率至少达到 0.9 才算断言通过,而非默认的 0.5。布尔置信度是相对于这个阈值度量的,所以调整阈值也会改变报告的置信度。我们主示例中的有界 float 则直接返回概率本身,没有单独的置信度条目。Pydantic AI 文档解释了置信度的计算方式。
GEval 输出 0 到 2 的整数。它把评估标准和评估步骤放进输入状态,然后提出一个引用这些内容的结构化分数问题。它的分数档位使用泛化的 worst、intermediate、best 描述;而上面的自定义 enum 为每个档位提供了具体描述。两个评估器都不要求 Jev 生成解释。它们各自发起一次模型调用,所以这两项检查对每条回复要用两个请求。如果你想在一次请求里问多个问题、拿到分类标签或小数评分标准分数,就用上面的自定义评估器。
内置 judge 示例用同样的 Logfire 配置,在两条合成回复上运行这两者:
curl -fsSLO https://pydantic.dev/assets/blog/jev-evals/jev_builtin_judges.py uv run jev_builtin_judges.py
在我们的实际运行中,密码重置回复通过了断言,索要密码的回复未通过。两者的完整度都是 2 级:给出具体下一步的回复仍可能不安全,这正是这些检查需要分开的原因。
对于运行时才加载的分类,2.46.0 还新增了 Choices,无需声明 enum 类即可构建一组带描述的选项。我们固定的政策评分标准适合用 enum。提议中的 Classifier 评估器尚未落地;这些示例都不依赖它。
示例运行结果
我们于 2026 年 9 月 19 日在 Pydantic AI 2.46.0 上用 jev-1.13.0 跑了这八条合成回复。八次评估全部完成,结果如下:
用例 政策判定 完整度(0 到 1) 索要秘密的概率
有用的重复扣费回复 compliant 1.000 0.01
保证退款 violates_policy 0.510 0.01
含糊道歉 violates_policy 0.325 0.01
有用的登录回复 compliant 1.000 0.02
索要密码和登录码 violates_policy 0.490 0.99
答非所问 violates_policy 0.000 0.01
转人工支持 compliant 0.985 0.01
虚构的免费一年政策 violates_policy 0.560 0.01
这八个请求共用了 5,444 个输入 token,平均每条回复 680.5 个。按公布费率,24 个评估结果共 $0.000228648。记录结果中包含 fixture 文本和包版本。本次运行的遥测是本地采集的,上述金额只涵盖 Jev 推理。
含糊道歉那条值得细看。政策要求索取交易 ID,而道歉回复没有这么做。enum 描述中明确包含"遗漏必需动作",Jev 以 0.91 的置信度选择了 violates_policy。这种遗漏是否算违规,是应由你和客服团队共同敲定的评分标准决策。
我们还运行了可选的生成模式:OpenAI 生成八条回复,Jev 全部评估成功,每条都标记为 compliant。该运行用了 5,564 个 Jev 输入 token,折算 judge 推理成本 $0.000233688,另加独立的生成成本。其记录的输出和判定结果与 fixture 一起可用。
如何理解置信度
Jev 在返回分类和评分标准判定时,还会附带置信度数值和答案分布。我们的评估器把这些记录到 Logfire,方便你观察 Jev 选择答案的果断程度。置信度描述的是分布的集中程度;置信度低时,可以查看完整分布,看 Jev 在权衡哪些答案。
对于索要密码那条回复,Jev 在三个完整度档位上给出的概率分别是 0.38、0.26 和 0.36,归一化得分为 0.490,置信度 0.0。中间分数来自档位之间的分歧,档位 0 的权重略高于档位 2。在 Logfire 里把这条分布和回复对照查看,就能在打磨评分标准时拿它与人判结果做比较。
但这到底要花多少钱?
Logfire 的 Team 和 Growth 套餐在超出包含额度后,按每百万条遥测记录 $2 计费,分数本身不另收费。span、日志和评估结果都计入遥测用量。一次评估可能产生多条记录,所以"每百万 span $2"并不等于"每百万完整评估 $2"。
下面是一个基于 2026 年 9 月 21 日核实的公布价格的边际成本模型:
评估一百万条回复,每条产生三个记录结果。
每条回复平均 1,000 个计费 Jev 输入 token,包括状态和全部问题。
每条回复预留 10 条 Logfire 记录,涵盖任务与 judge 的 span、诊断日志和评估结果。
包含的月度额度和模型额度已用尽。订阅费和应用自身推理不计算在内。
十条记录这个数字是规划假设,不是对脚本的实测。插桩方式、重试、额外日志和任务复杂度都会改变实际数量。token 数同样是假设;脚本会记录 Jev 上报的用量,你可以换成自己的数字。
1M 条回复的边际成本 Jev + Logfire Growth Jev + Braintrust Pro
Jev 推理:1B 输入 token $42 $42
Logfire 遥测:10M 条记录 $20 N/A
Braintrust 3M 分数费用 N/A $4,500
小计 $62 $4,542,另加数据处理费和任何留存费用
推理的计算是 1,000,000 * 1,000 / 1,000,000 * $0.042 = $42。Braintrust Pro 公布的分数超额价格是每千个 $1.50,所以三百万个分数加 $4,500。其计费 FAQ 把每个记录的分数都计入用量;定价页还包含自定义代码评分器。这个对比假设你把三个判定全部作为分数记录到 Braintrust,政策判定映射为数值结果,其分类保留为元数据。
在这些假设下,Logfire 加 Jev 的成本约为 Braintrust 加 Jev 小计的 1.4%,便宜约 73 倍。
输入变长会等比例推高两边的推理总额。每条回复 4,000 token 时,对比变成 $188 对 $4,668——这还没算 Braintrust 的数据费用。遥测增多会推高 Logfire 的总额:每条回复 50 条记录、token 数不变时是 $142。但两种变化都不会引入针对分数本身的费用。
我们之前的文章 Score freely 和 Focus on evals with Logfire 解释过为什么这项费用对评估覆盖率很重要。当 Jev 推理成本这么低时,Braintrust 这类平台的按分数计费反而可能成为账单的大头。
从八用例示例开始,检查各项判定,再把 fixture 换成你应用中带标注的真实样例。一旦 judge 对你的评分标准的判断足够可靠、能用于目标场景,就把它铺到更多流量上,把人工审核或更贵的 judge 留给真正需要的用例。
对于布尔检查,低置信度回退示例使用 FallbackModel 配合一个响应处理器,读取 provider_details["confidence"],把不确定的用例转给另一个模型。记得测量回退发生的频率:这些用例会产生两次模型调用。