Pydantic AI 2.61.0：引用结构化与新模型名入库

Python 智能体框架 Pydantic AI 于 2026 年 10 月 24 日发布 2.61.0：把引用做成结构化数据并统一多个云厂商的返回格式、能按原始产出方回放引用，新增 kimi-k3.1-pro 与 kimi-k3.1-pro-highspeed 两个模型名，同时把持久化引擎的扩展接口转为公开，并收紧了输入护栏的默认行为。

这次发布的是什么

Python 智能体框架 Pydantic AI 在 2026 年 10 月 24 日发布 2.61.0。按官方发布正文的结构，这一版由一组新增能力、一批兼容性说明与大量缺陷修复组成，其中值得单独说的是三条：引用（citation）被做成结构化的数据、新增了 kimi-k3.1-pro 与 kimi-k3.1-pro-highspeed 两个模型名、持久化引擎的扩展接口转为公开。

引用这条线是这个版本比较有价值的部分。过去不同云厂商返回的引用格式各不相同，要用就得自己写适配；本版在文本片段上加了结构化的引用字段，并把 Bedrock、OpenRouter、xAI 三家返回的引用统一到同一个形状，在 Vercel AI 适配器中也保留下来。更实用的是「按产出方回放」：一串消息历史里本来就有引用，再发回给模型时，会按当初产出它的那家厂商的格式回填，避免跨厂商来回倒时丢失。

另外一个容易被忽略的变化是护栏：输入护栏现在会对用户自己的提示词做脱敏处理，并把失效即放行的分支补上。这是偏安全方向的收紧，升级后行为可能与旧版不同，需要在自己的流程里确认。

可用性与限制

• 语言与环境：这是 Python 包，发布在 PyPI 上，写作时的当前版本是 2.61.0；运行所需的 Python 版本与可选依赖以官方说明为准。
• 模型侧另行准备：框架本身不含模型，kimi 系列模型名只是名称常量，调用仍需你有对应厂商的访问途径，费用以官网为准。
• 兼容性 notes 要看：本版对 thinking 相关的行为做了调整——更宽作用域里的厂商专有设置在覆盖 thinking 时会给出告警，对不能关闭思考的模型会发送它接受的最小思考量。
• 废弃项：GoogleRealtimeModel 上的多说话人开关已被标注为废弃，因为当前没有 Gemini Live 模型支持它。
• 引用覆盖有限：所谓「统一引用格式」当前明确点名的三家是 Bedrock、OpenRouter 与 xAI，其余厂商的引用形状是否一致要按当前版本实测确认。

主要功能

• 给文本片段带上结构化引用
• 统一三家云厂商的引用格式
• 按原始产出方回放历史引用
• 在 Vercel AI 适配器中保留引用
• 新增两个 kimi 模型名常量
• 公开持久化引擎的扩展接口
• 给 Shell 日志加上体积上限
• 让输入护栏脱敏并补齐失效分支

技术原理

引用这件事落地时的难点有两个：一是各家返回的形状不同，二是同一个形状未必能被塞回同一家。本版的做法是在框架内部的文本片段上加一个引用结构，再在每家厂商的适配层做双向转换：读的时候从厂商格式转成框架格式，写回去的时候再按会话里这条引用当初来自哪家，转回那家的格式——这就是官方描述里说的「把 citations 回放给产出它的 provider」。同时，Vercel AI 适配器这一条链路要把引用留下来，否则经过一次适配就掉一层。

持久化引擎接口公开是另一类改动。过去这套扩展只在内部用，本版把操作类型、参数传输描述、运行上下文与运行身份钩子这些类型放到公开 API，意味着外部实现可以自己接进来，而不用依赖内部路径。与之配套的是对大量边界情况的处理：并发运行各自绑定自己的执行环境、失败重制作时保留上一份有效成果、共享 lock 的粒度改到目录级等等，这些改动主要影响自定义运行时的可靠性。

护栏那一条补的是「fail open」这一类问题。护栏本来的目的是在输入进来之前拦住不该进来的内容，但如果它自身出错就放行，防线等于没有；本版改为在护栏自身出错时不再默认放行，并对用户自己的提示词做脱敏，避免把原始输入直接写进日志与后续消息链。

实际体验

可以按下面顺序自查这一版与自己项目的关系：

第一步，确认能不能升。先在隔离环境里装到 2.61.0，跑一遍现有的单元测试；本版的兼容性说明集中在 thinking 相关行为与Google 实时模型的多说话人开关上，正好命中这些用法的，先看说明再决定。

第二步，验证引用是否真的打通。挑一个支持引用返回的接入方，发一个会带引用的请求，检查返回的消息里除了文本之外有没有额外的引用结构；然后把这串历史再发一遍，观察引用是否被按原本的格式回填，而不是被丢成纯文本。

第三步，验证新模型名。在代码里使用新增的 kimi 模型名常量，确认能被正常解析为对应的模型标识；如果厂商侧还没有给你开放这个模型，这一步会失败在高权限层面，而不是框架层面，属于预期情况。

第四步，复核护栏行为。如果你用了输入护栏，构造一个触发脱敏的输入，看日志与后续消息里是否不再出现原文；同时确认护栏自身出错时不再默认放行，这个行为变化最容易在产品环境里才暴露出来。

项目地址与获取方式

源码仓库在 GitHub 的 pydantic/pydantic-ai，发布页是 2026-10-24 的 v2.61.0 条目，正文中每一条改动都挂了对应的合并请求链接，GitHub 生成的发布说明按「兼容性说明 / 新增 / 缺陷修复 / 文档 / 内部项」分组。安装包发布在 PyPI 上，请通过官方渠道获取，避免安装来源不明的镜像版本。

适合谁用

• 要向用户展示「答案来自哪里」的产品：引用结构化这条线直接省掉一层自研适配。
• 跨多家厂商拼同一套代码的人：按产出方回放引用，减少了跨厂商来回切换时的信息丢失。
• 用 kimi 系列的开发者：两个模型名常量已经入库，不用再手动写字符串。
• 自建持久化运行时的团队：扩展接口公开后不必依赖内部路径。
• 只跑单模型同步请求的轻量脚本：本版大部分改动与你无关，可以不急着升。

常见问题

这次有没有破坏性变更？

官方把这一版的相关变化放在「兼容性说明」一节而不是「破坏性变更」标题下，多数还保留了旧行为并给出告警，例如厂商专有的思考设置覆盖更宽的 thinking 时会告警而不是报错、多说话人开关标为废弃而非删除。不过行为确有调整，建议按上面的步骤先在隔离环境跑一遍。

引用结构化之后，所有厂商的返回都能统一吗？

发布正文明确点名的是 Bedrock、OpenRouter 与 xAI 三家。其余接入方是否也被归一化，要看当前版本里各自的适配实现，按第二条步骤自己验证一次比较稳妥，不要默认全线支持。

新增的 kimi 模型名能用起来吗？

模型名只是框架里的一个名称常量，作用是让你不必手写模型字符串。能不能真的发起请求，取决于你在对应厂商处的访问方式与模型是否对你开放，这部分要按厂商的官方渠道确认，费用以官网为准。

输入护栏这次改了什么？

两条：一是护栏会对用户自己的提示词做脱敏处理；二是把过去出错即放行的分支补上。如果你的流程依赖护栏失败时继续往下走（比如为了可用性优先），升级后需要重新评估，因为这个行为被明确改掉了。

相关工具与内容

• Pydantic AI 2.57.0 版本说明
• Claude API 版本升级要点
• 模型接入渠道怎么选
• Claude Code 工具页
• Cursor 工具页
• AI 编程
• AI 智能体