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

第27章 使用 Pydantic AI 生成图像

先说重点:现在可以通过 Pydantic AI 使用专门的图像生成模型了!之前的图像生成支持依赖自带图像生成能力的对话式模型。新的 ImageGenerator 提供了直接调用的 API,无需经过 agent 运行。 同一套接口支持 OpenAI GPT Image、Google Gemini 和 xAI Grok Imagine。Google 同时支持 Gemini Developer API 和 Vertex AI。你也可以通过 ImageGeneration capability 让 agent 访问专门的图像模型。 如果你在公司自建 agent 框架或使用 Pydantic AI,欢迎到 Slack 上和我们聊聊——这个功能正是在与用户的交流中催生的。详见下文。 生成一张图片 安装 OpenAI extra 并设置 API key:

uv add 'pydantic-ai-slim[openai]>=2.41.0' export OPENAI_API_KEY='your-api-key'

然后为一家咖啡馆的原声音乐之夜生成一张插图:

from pathlib import Path from pydantic_ai import ImageGenerator images = ImageGenerator('openai:gpt-image-2') result = images.generate_sync( 'A warm, painterly illustration of acoustic live music at a cafe. ' 'No lettering or logos.' ) Path('cafe.png').write_bytes(result.image.data)

result.image 是一个 BinaryImage,字节内容和媒体类型都可以直接访问。异步代码用 await images.generate(...)。还可以通过 images= 传入参考图片进行编辑或转换。 图像生成指南涵盖了各家 provider 的配置、图片编辑、输出格式和设置。Google 使用 gemini: 前缀(Gemini Developer API)或 google-cloud: 前缀(Vertex AI);xAI 使用 xai:。每个 provider 需要各自的 optional dependency 和凭证。 让 agent 来生成图片 直接调用 API 意味着由你的应用决定何时生成图片。而通过 ImageGeneration capability,决定权交给 agent,图片会随运行消息返回。 下面的例子定义了一个图像生成器,并将其作为 capability 的本地实现传入:

from pathlib import Path from pydantic_ai import Agent, ImageGenerator from pydantic_ai.capabilities import ImageGeneration from pydantic_ai.messages import BinaryImage, ToolReturnPart images = ImageGenerator('openai:gpt-image-2') agent = Agent( 'openai:gpt-5-mini', capabilities=[ImageGeneration(native=False, local=images)], ) result = agent.run_sync( 'Generate an illustration of acoustic live music at a cafe.' ) generated = [ file for message in result.all_messages() for part in message.parts if isinstance(part, ToolReturnPart) for file in part.files if isinstance(file, BinaryImage) ] Path('cafe.png').write_bytes(generated[0].data)

result.output 是模型的文本输出,生成的图片作为 tool result 返回,可以从 result.all_messages() 中读取。图片也会保留在对话中——当模型需要继续处理自己刚生成的图片时(比如为它写 alt text),这正是你想要的,下文的工具示例就是这种场景。 这里 native=False 确保 capability 使用我们配置的生成器。写成 ImageGeneration(local=images) 时,如果 agent 的模型原生支持图像生成就优先用原生方式,否则回退到配置的生成器。单独的 ImageGeneration() 只支持原生方式,不会自动配置回退方案。"Local" 指的是在你的应用中实现的工具;生成器仍然调用远程的图像 provider。这是基于模型能力的回退机制,而不是请求失败后在图像 provider 之间自动切换。 原生路径通过 ImageGenerationTool 让对话式模型生成图像。 为什么我们要加入图像生成 大约三月份之前,我们并没认真考虑支持这个功能:图像生成看起来就是又一个可以自己手搓然后插进来的工具。 用户的请求改变了我们的考量。Pydantic AI 的定位是 Python AI 应用开发事实上的标准库的一部分,就像 Pydantic 之于数据校验——标准库就该提供大家常用的功能,而不是让每个团队重复造轮子。我们也低估了集成图像生成能带来的价值: 减少适配代码。ImageGenerator 统一处理 provider 配置、请求映射,以及把生成的图片解码成通用的结果类型。 带类型的设置和更早的反馈。尺寸、aspect_ratio 等常见设置有一套统一接口;provider 专属的参数保留各自前缀。适配层会校验支持的尺寸并对被忽略或覆盖的设置发出警告,当然 provider 依然会执行自己的限制,具体差异见设置指南。 更容易做模型对比。通过同一套生成接口就能换一家 provider 试用,只需调整凭证和 provider 专属设置,不需要为了适配不同的响应结构重写应用代码。 与框架其他部分集成。生成的 BinaryImage 可以作为 agent 输入或 tool result。Pydantic AI Harness 还提供媒体外置功能,把大型数据从持久化的消息历史中移出去。存储需单独配置,生成图片不会自动持久化。 OpenTelemetry 埋点。在生成器上启用 tracing,即可在 Logfire 中把它的调用和 agent 及 tool 的 span 放在一起查看。 而且,说实话,我们也喜欢这种简洁的 Pydantic 风格语法。 有人认为,既然 coding agent 已经能可靠地写出这些样板代码和跨 SDK 的并行实现,就不必太在意了。但复杂度始终是所有人的敌人。一套实现加一个可调的配置,意味着更少的代码要理解、更少的地方会出现行为漂移。只要这样能让代码库更便宜、更好维护,我们就会继续打磨更干净的 API。 自己写工具并在 Logfire 中追踪 你也可以把生成器包在自己的工具里。当你想控制工具的返回内容时很有用,比如把生成的图片回传给 agent,让它写 alt text。 下面的追踪示例还需要安装 Logfire(uv add logfire),并通过 LOGFIRE_TOKEN 配置 project token。项目连接方式见 Logfire 配置指南。

import logfire from pydantic_ai import Agent, ImageGenerator from pydantic_ai.messages import BinaryImage logfire.configure() logfire.instrument_pydantic_ai() images = ImageGenerator('openai:gpt-image-2', instrument=True) agent = Agent('openai:gpt-5-mini') @agent.tool_plain async def create_illustration(prompt: str) -> list[str | BinaryImage]: """Generate an illustration from a visual prompt.""" result = await images.generate(prompt) return ['Illustration ready.', result.image] result = agent.run_sync( 'Generate an illustration of acoustic live music at a cafe. ' 'Then write alt text for it.' ) print(result.output)

工具可以返回混合了文本和二进制内容的列表:文本成为模型读到的 tool result,BinaryImage 则作为图片进入模型输入。instrument=True 会追踪图像生成调用,logfire.instrument_pydantic_ai() 负责对 agent 埋点,下面的图片预览正是来自同一个列表。 探索上方的 span,或查看完整 trace。这段录制的咖啡馆工作流还在图像生成之前包含了一个 visual-brief 子 agent 和 alt text。 该 trace 使用 Pydantic AI 2.41.0 和 Logfire 5.0.0。在这个版本中,capability 直接返回的图片在 Logfire 中以 JSON 形式展示,而不是工具自身二进制内容那样的预览图。我们正在跟进工具结果预览的一致性。 让开源保持乐趣 这个功能的诞生过程也有一段人的故事。 coding agent 能力的跃升让我们能承接更多工作,同时也改变了开源生态。越来越多 issue 和 PR 是借助 coding agent 提交的。面对海量提交,我们面临筛选难题:哪些 issue 该优先处理,如何协调分工? 这些我以后会详细写。目前一个有效的做法是主动联系贡献者,邀请他们来 Slack 上聊聊。 我们安排了几次通话,了解他们用 Pydantic AI 做什么、最大的痛点(框架内外的都聊)、以及希望看到什么新功能。这些交流让我们有机会引导用户用更新的 API 替代旧 workaround、学习他们的技巧,也催生了更宏大的想法。比如用 scratchpad 提高复杂输出类型的成功率。 Egon Ferri 对图像生成特别感兴趣。我们讨论了种种约束,然后他就动手做了最初的 PR。谢谢你,Egon,感谢你为此付出并拓展了框架的边界! 我们希望的就是这样的模式。一个有吸引力的功能,当由真正需要它的人来推动时,落地最快:他们带来使用场景、参与方案设计,并坚持走完 review 流程。图像生成功能因此得以发布,而不是躺在 backlog 里吃灰——同样的大门向你需要的任何功能敞开。 从那个 PR 到最终发布之间,我们推出了 Pydantic AI Harness、大量 capabilities,还有 Pydantic AI v2。终于轮到图像生成登场了。 如果你正在应用中试用这个功能,或者有一个你认为我们该了解的 workaround,欢迎来 Slack 上和我们聊聊。

评论 (0)