跳到主要内容

Pydantic AI

Pydantic AI 是用于构建类型化 LLM 应用的 Python Agent 框架，涵盖工具、依赖注入、结构化输出和校验。它可以通过 OpenAIResponsesModel 和 OpenAIProvider 使用 OpenAI Responses API。

当 Pydantic AI 应用需要保留 Agent 和校验工作流，同时通过 AISIX 路由模型请求时，请使用此配置。

本指南使用 OpenAI Responses 模型。你将使用 AISIX 代理 URL、调用方 API Key 和模型别名配置 OpenAIProvider。

前置条件​

开始前，请准备以下内容：

  • 一个受 Pydantic AI 支持的 Python 环境。
  • 一个代理监听器可用的运行中 AISIX 网关。
  • 一个 AISIX 调用方 API Key。
  • 一个调用方 API Key 可通过Responses API访问的模型别名。

配置 Pydantic AI​

如果应用尚未包含 Pydantic AI，请先安装：

pip install pydantic-ai

设置 Pydantic AI 应用要使用的值：

# Replace with your values
export AISIX_BASE_URL="http://127.0.0.1:3000/v1"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

使用 AISIX 值创建 OpenAI Responses 模型：

import os

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIResponsesModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIResponsesModel(
  os.environ["AISIX_MODEL"],
  provider=OpenAIProvider(
    base_url=os.environ["AISIX_BASE_URL"],
    api_key=os.environ["AISIX_API_KEY"],
  ),
)

agent = Agent(model)
response = agent.run_sync("Write one sentence about typed AI applications.")

print(response.output)

模型值应填写 AISIX 模型别名，而不是上游服务提供方模型 ID。AISIX 管理模型请求路径，而 Pydantic AI 继续负责 Agent 执行、工具调用、依赖注入、结构化输出和校验。

Pydantic AI 还提供用于 Chat Completions 的 OpenAIChatModel。当工作流需要广泛的兼容 OpenAI 聊天支持时，请使用该模型。

验证集成​

在已设置 AISIX 环境变量的 Shell 中运行脚本。

请求成功后，请确认以下结果：

  • 脚本输出 Agent 响应。
  • AISIX 为所选模型别名记录一条成功的 POST /v1/responses 请求。

对于托管部署，请在托管网关日志中验证请求。对于自托管网关，请使用已配置的日志、指标或上游服务提供方日志。

如果请求失败，请先确认调用方 API Key 可以访问所选模型别名，且 base_url 指向包含 /v1 的 AISIX 代理 API 根路径。

Pydantic AI 支持多个 OpenAI 模型接口。Responses 工作流使用 OpenAIResponsesModel，需要广泛兼容 OpenAI Chat Completions 支持时使用 OpenAIChatModel。在依赖网关为该工作流执行策略或采集遥测前，请使用确切的别名验证结构化输出、工具定义和重试。

后续步骤​

  • Responses API：查看面向网关的 Responses 行为。
  • 兼容 OpenAI 的 API：当工作流需要广泛的兼容 OpenAI 支持时使用 Chat Completions。
  • 工具调用：在启用 Pydantic AI 工具前确认工具调用行为。
  • 预算：在支出控制中考虑重试或校验循环。