进阶 pydantic.dev 2026-11-20 05:57:40 · 5 阅读

第23章 Jev 结合 Pydantic AI 与 Logfire 实现结构化 Agent 追踪

生产环境里很多 agent 其实不生成任何内容。它们读一张工单,判断该归谁处理;看一条 shell 命令,判断能不能安全执行。输出不过是一个 bool、一个 Literal、一个分数。可我们依然把这些任务丢给前沿大模型,等上一两秒,还得为它"推理"出四个词中的一个买单。 TypeSafe 推出的 Jev 就是为这类任务而生。你给它一段文本和一组带类型的问题,它为每个问题选出答案,并附上概率。没有需要解析的生成文本。Pydantic AI 2.50.0 已经可以在它上面跑 agent,Pydantic Logfire 也能展示它做出的判断。

你的输出类型就是问题列表

使用 TypeSafeModel 时,agent 的 output_type 中的每个字段都会变成一个问题:字段描述就是问题内容,prompt 是待判断的素材。所有字段会打包进同一次请求。 from typing import Literal import logfire from pydantic import BaseModel, Field from pydantic_ai import Agent logfire.configure() logfire.instrument_pydantic_ai() class Ticket(BaseModel): """Triage a support ticket.""" urgent: bool = Field(description='Does this need a reply within the hour?') area: Literal['billing', 'bug', 'account', 'other'] = Field(description='Which team owns it?') agent = Agent('typesafe:jev-latest', output_type=Ticket) result = agent.run_sync( 'You have charged me twice and my account is now overdrawn. I need this reversed today.' ) print(result.output) #> urgent=True area='billing' 安装时带上 typesafe 和 logfire extras,并设置 TYPESAFE_API_KEY 和 LOGFIRE_TOKEN: uv add "pydantic-ai-slim[typesafe,logfire]" 把 'typesafe:jev-latest' 换成任意语言模型,同一个 agent 就能跑在上面。不用改任何代码,就能在自己的数据上对比两者。 bool 就是非此即彼的选择题;Literal 或 Enum 是单选题;带 ge=0、le=1 的 float 直接就是概率本身;混入 UseEnumMemberDocstrings 且每个级别都有 docstring 的 IntEnum 则是一份评分标准;union 输出类型会先选出用哪个成员,再填充它的字段。Jev 答不了的字段(比如自由格式的 str)会在发送请求前抛出 UserError。例外是包含这类字段的 union 成员:Jev 仍可选中它,再由 FallbackModel 把这一步交给语言模型。完整清单见 TypeSafe 文档页。
光有 chat span 还不够
当分类器返回 area='billing' 但判断错了,你想知道它的把握有多大、差点选了哪个、走了哪条路径。但 chat span 只记录最终输出,这些信息全都丢了。 Douwe Maan 在两个 Pydantic AI PR 中修复了这个问题,都包含在 2.50.0 版本里: pydantic/pydantic-ai#8696 新增了 DecisionModel——任何遵循 Decisions 协议的模型都可继承的基类。TypeSafeModel 成了它之上的一个薄适配层。 pydantic/pydantic-ai#8698 为 DecisionModel 发出的每个请求,在 chat span 下新增一个 decide span,记录问题、带概率的答案、应用的阈值,以及正在填充的是哪条路径。 这些答案和其他 Pydantic AI span 一样,遵循 include_content 设置。关闭 content 后,你仍能看到问题类型和路径,但看不到文本和答案内容。

在 Live view 里查看

Logfire 这部分由 Petyo Ivanov 完成。在 Live view 中选中一次 agent 运行、一次模型运行或一个 decide span,Agent Run 标签页会出现 Classifier output 面板。 下面是一个支持工单分诊 agent 针对一张虚构工单提出 15 个问题的例子,这里展示前五个。是非题会显示概率;单选题显示所选选项,展开后还能看到备选项;严重程度评分标准展开后显示每个级别的概率——比如 1.6 分其实是 65% "无法工作"、30% "工作不顺畅"、5% "让人恼火"。类型化输出显示在下方: union 输出类型分两步走:Jev 先判断这段文本对应 union 中的哪个成员,再填充该成员的字段。面板会展示这两步以及同一输入,最终输出显示在下方: View decision span 可以跳到每一步对应的 decide span,Raw Data 仍保留所有原始属性。如果某次运行没有决策遥测数据,你看到的还是熟悉的对话视图。

Jev 还能用在哪里

  • Evals:你早已能在 Pydantic Evals 中把 Jev 当作 judge 使用,David Montague 还写了如何在高吞吐场景下用它打分。
  • Gateway:你也可以用自己的 TypeSafe key 通过 Pydantic AI Gateway 调用 Jev。
  • 其他后端:借助 DecisionModel,接入一个新的 Decisions 后端只需翻译它的传输层,decide span 和面板也随之而来。
如果你的 agent 的职责是做判断,不妨试试。换个模型名,用同一份数据跑一遍两种后端,看看概率差异。如果有你认为应该支持的用法被拒绝了,欢迎提交 issue。

评论 (0)