跳到主内容
@wquguru
精选88Google GenAI SDK Python（GitHub Releases）AI 编程与模型

Google GenAI SDK v3.0.0：API默认版v1、换httpx2

v3.0.0

原文
发到 X
推荐理由

依赖 Google GenAI SDK 的开发者必须升级或调整配置：API 默认版切到 v1、HTTP 客户端换成 httpx2、result 字段变 Union。建议检查线上调用是否受默认值变更影响，必要时设置 GOOGLE_GENAI_API_VERSION 或显式传入 api_version。

3.0.0 (2026-11-05)

⚠ BREAKING CHANGES

⚠ 重大变更

  • Default Gemini Developer API version is now v1 (was v1beta) (2d0f947)
  • Clients targeting the Gemini Developer API now default to API version v1 instead of v1beta.
  • No effect on Gemini Enterprise (Vertex AI) defaults: Clients with vertexai=True / enterprise=True are unaffected by this default change and continue to default to v1beta1.
  • How to configure or restore the previous default via environment variable: Set GOOGLE_GENAI_API_VERSION (works for both Gemini Developer API and Enterprise / Vertex AI clients when no version is set in code):
  • 默认 Gemini Developer API 版本现已变更为 v1（原为 v1beta）(2d0f947)
  • 针对 Gemini Developer API 的客户端现在默认使用 API 版本 v1，而非 v1beta。
  • 对 Gemini Enterprise (Vertex AI) 默认值无影响：设置 vertexai=True / enterprise=True 的客户端不受此默认值更改的影响，继续默认为 v1beta1。
  • 如何通过环境变量配置或恢复之前的默认值：设置 GOOGLE_GENAI_API_VERSION（当代码中未设置版本时，对 Gemini Developer API 和 Enterprise / Vertex AI 客户端均有效）：
代码 · 4 行
# Restores the beta default ('v1beta' on Gemini Developer API, 'v1beta1' on Enterprise / Vertex AI)
export GOOGLE_GENAI_API_VERSION=beta
# Or set an explicit API version string on either platform (e.g. 'v1', 'v1beta', 'v1beta1')
export GOOGLE_GENAI_API_VERSION=v1beta
  • How to set the API version in code: Pass api_version in HttpOptions (takes precedence over GOOGLE_GENAI_API_VERSION):
  • 如何在代码中设置 API 版本：在 HttpOptions 中传递 api_version（优先级高于 GOOGLE_GENAI_API_VERSION）：
代码 · 5 行
from google import genai
from google.genai import types
client = genai.Client(
    http_options=types.HttpOptions(api_version='v1beta')
)
  • Default HTTP client is now httpx2 (was httpx), and httpx is no longer installed by default (51285c8)
  • httpx is no longer installed by default. httpx2 is now the required dependency and default HTTP client.
  • How to restore the previous httpx default via environment variable: Because httpx2 is installed by default, installing google-genai[httpx] alone only makes import httpx available; to switch the SDK's default client back to httpx without code changes, both install the httpx extra and set GOOGLE_GENAI_HTTP_CLIENT=httpx:
  • 默认 HTTP 客户端现已变更为 httpx2（原为 httpx），且不再默认安装 httpx (51285c8)
  • httpx 不再默认安装。httpx2 现在是必需的依赖项和默认 HTTP 客户端。
  • 如何通过环境变量恢复之前的 httpx 默认值：由于默认安装的是 httpx2，仅安装 google-genai[httpx] 只会使 import httpx 可用；若要在不修改代码的情况下将 SDK 的默认客户端切换回 httpx，需同时安装 httpx extra 并设置 GOOGLE_GENAI_HTTP_CLIENT=httpx：
代码 · 2 行
pip install "google-genai[httpx]"
export GOOGLE_GENAI_HTTP_CLIENT=httpx
  • How to pass an httpx client in code: After installing google-genai[httpx], you can pass httpx.Client / httpx.AsyncClient directly via HttpOptions:
  • 如何在代码中传递 httpx 客户端：安装 google-genai[httpx] 后，您可以通过 HttpOptions 直接传递 httpx.Client / httpx.AsyncClient：
代码 · 9 行
import httpx
from google import genai
from google.genai import types
client = genai.Client(
    http_options=types.HttpOptions(
        httpx_client=httpx.Client(),
        httpx_async_client=httpx.AsyncClient(),
    )
)
  • Migrating existing httpx code to httpx2: In most cases, updating your imports with import httpx2 as httpx is sufficient.
  • SSL certificate verification: By default, httpx2 uses the OS certificate trust store (via truststore / httpx2.create_ssl_context()) instead of certifi when SSL_CERT_FILE and SSL_CERT_DIR are not set.
  • When httpx vs. httpx2 types matter: Package-specific objects passed in HttpOptions(client_args=..., async_client_args=...) (such as Timeout, Limits, MockTransport / BaseTransport, or custom Auth subclasses) and unwrapped transport exceptions caught from client.models, client.files, etc. (TimeoutException, ConnectError, HTTPError) must match the active HTTP client. (When GOOGLE_GENAI_HTTP_CLIENT is unset or auto, passing httpx objects in HttpOptions will also auto-select the httpx backend if google-genai[httpx] is installed.)
  • interactions: CodeExecutionResultStep.result changes from string to the CodeExecutionResultStepResult union. Code that reads result as a string must now check which variant is present and read the string from it. The JSON for text-only results is unchanged.
  • 将现有的 httpx 代码迁移至 httpx2：在大多数情况下，只需将导入语句更新为 import httpx2 as httpx 即可。
  • SSL 证书验证：默认情况下，当未设置 SSL_CERT_FILE 和 SSL_CERT_DIR 时，httpx2 使用操作系统证书信任存储区（通过 truststore / httpx2.create_ssl_context()），而非 certifi。
  • 当 httpx 与 httpx2 类型相关时：在 HttpOptions(client_args=..., async_client_args=...) 中传入的特定包对象（如 Timeout、Limits、MockTransport / BaseTransport 或自定义 Auth 子类），以及从 client.models、client.files 等捕获的未包装传输异常（TimeoutException、ConnectError、HTTPError）必须与当前活动的 HTTP 客户端匹配。（当 GOOGLE_GENAI_HTTP_CLIENT 未设置或为 auto 时，如果在已安装 google-genai[httpx] 的情况下在 HttpOptions 中传递 httpx 对象，也将自动选择 httpx 后端。）
  • interactions：CodeExecutionResultStep.result 的类型从 string 变为 CodeExecutionResultStepResult 联合类型。将 result 作为字符串读取的代码现在必须检查存在的变体并从中读取字符串。仅包含文本的结果的 JSON 保持不变。

Features

功能特性

  • Add source_text to AudioTranscriptionConfig and SmartTranscriptionMode. (1ac3c91)
  • Add MALFORMED_RESPONSE to FinishReason (6eb8523), refs #2937
  • cli: Use gemini-3.5-transcribe as default model for transcribe command (b18fd3c)
  • Default Gemini API version to v1 instead of v1beta across SDKs (2d0f947)
  • Disable GenerateVideos for Gemini API, update tests/READMEs (8ddc655)
  • interactions: Add Office and OpenDocument MIME types (753cc1c)
  • interactions: Support multimodal content in CodeExecutionResultStep.result (a216d95)
  • Support GOOGLE_GENAI_API_VERSION environment variable across SDKs (2d0f947)
  • Switch default HTTP client to httpx2 and use OS trust store by default (51285c8)
  • Update discovery doc (5647e1e)
  • 在 AudioTranscriptionConfig 和 SmartTranscriptionMode 中添加 source_text。(1ac3c91)
  • 将 MALFORMED_RESPONSE 添加到 FinishReason (6eb8523)，refs #2937
  • cli：将 gemini-3.5-transcribe 设为 transcribe 命令的默认模型 (b18fd3c)
  • 在各 SDK 中将 Gemini API 的默认版本从 v1beta 改为 v1 (2d0f947)
  • 禁用 Gemini API 的 GenerateVideos，更新 tests/READMEs (8ddc655)
  • interactions：添加 Office 和 OpenDocument MIME 类型 (753cc1c)
  • interactions：在 CodeExecutionResultStep.result 中支持多模态内容 (a216d95)
  • 在各 SDK 中支持 GOOGLE_GENAI_API_VERSION 环境变量 (2d0f947)
  • 将默认 HTTP 客户端切换为 httpx2，并默认使用操作系统信任存储区 (51285c8)
  • 更新 discovery doc (5647e1e)

Bug Fixes

  • interactions: Retries = attempts - 1 (0f688a6)
  • Preserve unknown fields and open-union variants in Interactions models (2eaf2d8)
  • Respect configured and default API version for Gemini API file uploads across SDKs (ddc45d0)
  • interactions：Retries = attempts - 1 (0f688a6)
  • 在 Interactions 模型中保留未知字段和 open-union 变体 (2eaf2d8)
  • 在各 SDK 中针对 Gemini API 文件上传尊重配置的及默认的 API 版本 (ddc45d0)

Documentation

  • Update embedding examples from gemini-embedding-2-preview to gemini-embedding-2 (d97752a)
  • Update remaining documentation links from ai.google.dev to aistudio.google.com. (0e34831)
  • 将嵌入示例从 gemini-embedding-2-preview 更新为 gemini-embedding-2 (d97752a)
  • 将所有剩余的文档链接从 ai.google.dev 更新为 aistudio.google.com。(0e34831)

更进一步：量化金融体系

看懂新闻只是起点——沿量化金融路径，把它变成能交付的工程能力

进入量化体系 →
话题#破坏性#Google GenAI SDK#Python

相似阅读

关联信息，但可能不是同一事件