Gemini

注意

我们开发了一个新的 Google 模型，名为 GoogleModel，它在底层使用 google-genai。

老实说，Google 的软件包一团糟，这就是为什么我们使用纯 httpx 而不是依赖他们自己的客户端来创建 GeminiModel。话虽如此，直接使用 google-genai 包会更容易，因为他们会保持该包与最新的 API 更改同步。因此，我们创建了一个名为 GoogleModel 的新模型，它在底层使用 google-genai。

请点击此处查看。

Pydantic AI 支持通过两种不同的 API 使用 Google 的 Gemini 模型

Generative Language API (generativelanguage.googleapis.com)
Vertex AI API (*-aiplatform.googleapis.com)

通过 Generative Language API 使用 Gemini

安装

要使用 GeminiModel 模型，您只需安装 pydantic-ai 或 pydantic-ai-slim，无需额外的依赖项。

配置

GeminiModel 允许您通过 Google 的 Generative Language API (generativelanguage.googleapis.com) 使用 Gemini 模型。

GeminiModelName 包含可通过此接口使用的可用 Gemini 模型列表。

要使用 GeminiModel，请访问 aistudio.google.com 并选择“创建 API 密钥”。

环境变量

获得 API 密钥后，可以将其设置为环境变量

export GEMINI_API_KEY=your-api-key

然后您可以通过名称使用 GeminiModel

from pydantic_ai import Agent

agent = Agent('google-gla:gemini-2.0-flash')
...

注意

google-gla 提供商前缀代表用于 GeminiModel 的 Google Generative Language API。google-vertex 与 Vertex AI 一起使用。

或者直接使用模型名称和提供商初始化模型

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel

model = GeminiModel('gemini-2.0-flash', provider='google-gla')
agent = Agent(model)
...

`provider` 参数

您可以通过 provider 参数提供自定义的 Provider

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_gla import GoogleGLAProvider

model = GeminiModel(
    'gemini-2.0-flash', provider=GoogleGLAProvider(api_key='your-api-key')
)
agent = Agent(model)
...

您还可以使用自定义的 http_client 来自定义 GoogleGLAProvider

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_gla import GoogleGLAProvider

custom_http_client = AsyncClient(timeout=30)
model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleGLAProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)
...

通过 VertexAI 使用 Gemini

如果您是企业用户，您应该将 google-vertex 提供商与 GeminiModel 一起使用，它使用 *-aiplatform.googleapis.com API。

GeminiModelName 包含可通过此接口使用的可用 Gemini 模型列表。

安装

要将 google-vertex 提供商与 GeminiModel 一起使用，您需要安装 pydantic-ai，或者安装带有 vertexai 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[vertexai]"

uv add "pydantic-ai-slim[vertexai]"

配置

与上面记录的 generativelanguage.googleapis.com 相比，此接口有许多优势

VertexAI API 提供了更多的企业级就绪保证。
您可以通过 VertexAI 购买预配吞吐量来保证容量。
如果您在 GCP 内部运行 Pydantic AI，则无需设置身份验证，它应该可以“开箱即用”。
您可以决定使用哪个区域，这从监管角度看可能很重要，并且可能会改善延迟。

最大的缺点是，对于本地开发，您可能需要创建和配置一个“服务账号”，这可能很难正确设置。

无论您采用哪种身份验证方式，您都需要在您的 GCP 帐户中启用 VertexAI。

应用程序默认凭据

幸运的是，如果您在 GCP 内部运行 Pydantic AI，或者您已经安装并配置了 gcloud CLI，您应该能够无需任何额外设置即可使用 VertexAIModel。

要使用 VertexAIModel，在配置了应用程序默认凭据（例如，使用 gcloud）的情况下，您可以简单地使用

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel

model = GeminiModel('gemini-2.0-flash', provider='google-vertex')
agent = Agent(model)
...

这在内部使用 google-auth 包中的 google.auth.default() 来获取凭据。

直到调用 agent.run() 才会失败

因为 google.auth.default() 需要网络请求并且可能很慢，所以直到您调用 agent.run() 时它才会被运行。

如果应用程序默认凭据没有设置项目，您可能还需要将 project_id 参数传递给 GoogleVertexProvider。如果您传递了 project_id 并且它与应用程序默认凭据设置的项目冲突，则会引发错误。

服务账号

如果您想使用服务账号进行身份验证而不是应用程序默认凭据，您需要创建一个服务账号，将其添加到您的 GCP 项目（注意：即使您在项目内创建了服务账号，此步骤也是必需的），为该服务账号授予“Vertex AI 服务代理”角色，并下载服务账号 JSON 文件。

一旦您有了 JSON 文件，您可以这样使用它

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleVertexProvider(service_account_file='path/to/service-account.json'),
)
agent = Agent(model)
...

或者，如果您已经在内存中有了服务账号信息，您可以将其作为字典传递

import json

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

service_account_info = json.loads(
    '{"type": "service_account", "project_id": "my-project-id"}'
)
model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleVertexProvider(service_account_info=service_account_info),
)
agent = Agent(model)
...

自定义区域

无论您选择哪种身份验证方式，您都可以通过 region 参数指定请求将发送到哪个区域。

使用靠近您的应用程序的区域可以改善延迟，并且从监管角度看可能很重要。

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

model = GeminiModel(
    'gemini-2.0-flash', provider=GoogleVertexProvider(region='asia-east1')
)
agent = Agent(model)
...

您还可以使用自定义的 http_client 来自定义 GoogleVertexProvider

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

custom_http_client = AsyncClient(timeout=30)
model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleVertexProvider(region='asia-east1', http_client=custom_http_client),
)
agent = Agent(model)
...

模型设置

您可以使用 GeminiModelSettings 类来自定义模型请求。

禁用思考

您可以通过在 google_thinking_config 上将 thinking_budget 设置为 0 来禁用思考。

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel, GeminiModelSettings

model_settings = GeminiModelSettings(gemini_thinking_config={'thinking_budget': 0})
model = GeminiModel('gemini-2.0-flash')
agent = Agent(model, model_settings=model_settings)
...

有关思考的更多信息，请查看 Gemini API 文档。

安全设置

您可以通过设置 google_safety_settings 字段来自定义安全设置。

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel, GeminiModelSettings

model_settings = GeminiModelSettings(
    gemini_safety_settings=[
        {
            'category': 'HARM_CATEGORY_DANGEROUS_CONTENT',
            'threshold': 'BLOCK_ONLY_HIGH',
        }
    ]
)
model = GeminiModel('gemini-2.0-flash')
agent = Agent(model, model_settings=model_settings)
...

有关安全设置的更多信息，请查看 Gemini API 文档。