Google GenAI 的 Python SDK 用于 Gemini API
Portelcore 中 Gemini API 新统一 SDK 的参考指南和高级配置
本部分为新SDK设定了背景,解决了用户对库变更的主要困惑,并提供了全面的入门指南,涵盖安装和两种关键的认证途径。
1.1. 新标准:从 google-generativeai 迁移到 google-genai
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»Google的生成式AI模型开发生态系统已演进。库 google-genai 现已成为官方统一的Python SDK,推荐用于与Gemini API和其他Google生成式AI模型交互。该库于2025年5月达到一般可用性(GA),取代了遗留库 google-generativeai。
前一库 google-generativeai 已在Python包索引(PyPI)中标记为“不活跃”,正处于淘汰过程中。该包的支持(包括关键错误修复)将于2025年9月底终止,尽管一些来源表明终止日期可能较早,为2025年8月31日。建议开发者尽快迁移以确保平稳过渡。
此变更不仅是名称更改,更是由开发者反馈推动的战略性统一。目标是创建一个单一SDK,简化对Google所有生成式AI模型(Gemini、Veo、Imagen等)的访问,并提供更清晰连贯的开发路径。新SDK google-genai 最具影响力的架构决策之一是作为两个不同后端服务的统一接口:易于访问的Gemini开发者API和企业级Vertex AI平台。
这种统一架构为开发者提供了流畅的入门体验。他们可以快速开始,通常使用Gemini开发者API的免费层级,通过API密钥进行操作。随着应用成熟并需要更高可扩展性、治理和与Google Cloud其他服务的集成,他们可以切换到Vertex AI后端,主要在客户端初始化代码中进行最小修改。SDK google-genai 作为一个桥梁,降低了入门门槛,同时为Google Cloud生产环境提供了清晰路径。因此,敦促所有旧库用户迁移,以确保访问最新功能(如Live API和Veo)、性能改进和持续支持。
在安装SDK之前,建议配置Python虚拟环境。这将隔离项目依赖项,避免与其他项目或系统包发生冲突。
要创建并激活虚拟环境,请使用venv:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activate一旦虚拟环境激活,可以使用pip安装 Google Gen AI SDK 的最新版本。使用指示符--upgrade可确保获取最新版本。
pip install --upgrade google-genai需要注意 Python 版本要求。SDK google-genai 需要 Python 3.9 或更高版本。使用不兼容版本可能导致安装或运行时出现意外错误。
对于需要高性能异步处理的应用,SDK 提供了使用aiohttp作为 HTTP 传输后端的选项,而不是默认的httpx。可以作为额外依赖安装:
pip install google-genai[aiohttp]1.3. 认证:您的Gemini API密钥
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»认证是配置步骤中最关键的部分,根据所要使用的后端服务不同,方法会有所不同:Gemini开发人员API或Vertex AI中的Gemini API。
1.3.1. Gemini开发人员API的途径(推荐用于原型和免费层级)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»这是使用Gemini快速构建的最简便方法。需要从Google AI Studio免费获取API密钥。
获取API密钥的步骤如下:
- 访问(https://ai.google.dev/) 并使用Google帐户登录。
- 点击“获取API密钥”(获取API密钥)
- 请选择在新的或现有的 Google Cloud 项目中创建 API 密钥。
- API 密钥将自动生成。
API 密钥是敏感凭据,应像密码一样处理。应安全存储,切勿在客户端代码中暴露或提交到公共版本控制系统。
使用 API 密钥最安全且推荐的方法是将其配置为环境变量。SDK 设计为检测并自动使用环境变量 GOOGLE_API_KEY 或 GEMINI_API_KEY。如果两者都配置了,GOOGLE_API_KEY 优先。
配置环境变量:
-
在 Linux/macOS (bash) 中:
Ventana de terminal export GOOGLE_API_KEY='SU_CLAVE_DE_API_AQUI'# Agregue esta línea a su archivo ~/.bashrc o ~/.zshrc para que sea permanente -
在 Windows 上: 通过系统设置中的“环境变量”图形界面,添加名为
GOOGLE_API_KEY的新的用户变量或系统变量,值为您的密钥。
1.3.2. Vertex AI 的途径(推荐用于生产环境和与 Google Cloud 集成)
Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»对于需要 Google Cloud 企业级功能的生产级应用程序,建议通过 Vertex AI 使用 Gemini API。此方法需要一个已启用计费功能的 Google Cloud 项目。
初始配置步骤包括:
- 选择或创建 Google Cloud 项目。
- 确保该项目已启用计费功能。
- 为该项目启用 Vertex AI API (
aiplatform.googleapis.com)。
Vertex AI 的身份验证可以通过两种方式完成:
-
默认应用凭证 (ADC)(推荐用于生产环境): 这是大多数生产场景的首选方法。ADC 会根据环境自动查找凭证。在本地开发环境中,可以通过运行 gcloud CLI 命令进行配置:
Ventana de terminal gcloud auth application-default login当在 Google Cloud 环境中运行时(例如 Cloud Run、Google Kubernetes Engine、Cloud Functions),ADC 会自动使用该资源关联的服务账号,无需管理密钥。
-
API 密钥(用于 Vertex 的测试): 可以使用 API 密钥对 Vertex AI 端点进行身份验证,但此过程比开发者 API 更复杂。需要组织级别的权限来启用服务账号 API 密钥的创建,创建具有适当角色(例如,
Vertex AI User)的服务账号,然后创建受限于该服务账号的 API 密钥。由于其复杂性,此方法通常用于特定的测试场景,而不是一般的应用程序开发。
一旦身份验证设置完成,下一步是实例化 genai.Client 对象。统一的 SDK 简化了这一点,通过提供一个可以配置为任一后端的单一客户端。
以下是客户端初始化的四个主要场景。
-
场景1:Gemini开发者API(显式密钥) 此方法适用于不需要设置环境变量的笔记本或快速脚本。API密钥直接作为参数传递。
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
场景2:Gemini开发者API(环境变量) 这是应用程序代码最干净和推荐的方法,因为它将凭证与代码解耦。客户端会自动查找并使用环境变量
GOOGLE_API_KEY。# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
场景3: Vertex AI API (显式参数) 为了连接到 Vertex AI,将标志
vertexai设置为True并提供项目ID和区域。此方法将自动使用默认应用凭证 (ADC) 进行身份验证。from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
场景4: Vertex AI API (环境变量) 作为 Vertex AI 的替代方案,可以将配置外部化到环境变量中。客户端将检测这些变量并配置为使用 Vertex AI 后端。
Ventana de terminal export GOOGLE_GENAI_USE_VERTEXAI=trueexport GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'export GOOGLE_CLOUD_LOCATION='us-central1'# El cliente se configurará automáticamente para Vertex AIfrom google import genaiclient = genai.Client()
下表总结了这些方法,以便快速参考。
表1:客户端初始化快速参考
| 用例 | Python 代码 | 所需环境变量 | 备注 |
|---|---|---|---|
| 带有显式密钥的开发者 API | client = genai.Client(api_key="SU_CLAVE...") | 无 | 适用于笔记本和快速测试。避免在生产代码中使用。 |
| 开发者API与环境变量 | client = genai.Client() | GOOGLE_API_KEY 或 GEMINI_API_KEY | 适用于应用代码的首选方法,保证清晰和安全。 |
| Vertex AI 显式参数 | client = genai.Client(vertexai=True, project="...", location="...") | 无(使用ADC) | 显式方法指向Vertex AI。需要ADC身份验证(gcloud auth...)。
|
| Vertex AI与环境变量 | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION | 配置Vertex AI客户端无需代码参数。需要ADC身份验证。 |
本部分深入探讨最常见的用例:生成文本和构建对话代理。详细说明涉及的主要方法和对象。
2.1. 生成内容:方法 generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»该方法是所有单次任务的主要方法 client.models.generate_content()。这种多功能方法是与Gemini模型交互的基础。
基本用法涉及提供一个简单的文本字符串如 contents 并指定要使用的模型名称,如 gemini-2.5-flash。
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado como se describió anteriormenteresponse = client.models.generate_content( model="gemini-2.5-flash", contents="Explica brevemente por qué el cielo es azul.")
print(response.text)虽然传递简单字符串很方便,但理解SDK使用的底层数据结构至关重要。内部,SDK会将所有输入转换为由types.Content和types.Part对象组成的标准化结构。理解此结构是解锁SDK高级功能(如多模态提示和函数调用)的关键。
types.Content: 表示对话中的一个唯一消息或回合。它有两个主要属性:一个role(通常是“user”用于输入或“model”用于输出)和一个parts列表。types.Part: 表示Content对象中的一个数据块。一个部分可以是文本、图像数据、文件引用、函数调用等。
SDK 会智能处理 contents 参数的多种输入类型,并将其转换为适当的 Content/Part 格式:
- 单一字符串:
contents='¿Por qué el cielo es azul?'转换为包含一个Part文本的UserContent。 - 字符串列表:
contents=['Pregunta 1', 'Pregunta 2']转换为包含两个Part文本的单一UserContent。 types.Part对象: 允许更精细的控制,例如指定图像数据。- 完全构建的
types.Content对象: 提供对消息角色和内容的最大控制。
要访问生成的响应,便捷访问器 response.text 是最简单的方法。然而,重要的是要知道此访问器仅适用于由单个文本部分组成的简单响应。如果响应被安全过滤器阻止、包含多个候选者或包含非文本数据类型,访问 response.text 将导致错误。生产环境中最稳健安全的方法是直接访问候选者及其部分:
try: # Método robusto para acceder al texto text_response = response.candidates.content.parts.text print(text_response)except (IndexError, AttributeError): # Manejar el caso en que no hay respuesta de texto válida print("No se pudo obtener una respuesta de texto válida.") # Se puede inspeccionar response.prompt_feedback para ver si fue bloqueado print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}")2.2. 流式响应以实现实时反馈
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»对于交互式应用如聊天机器人,模型的响应流显著提升用户体验。而不是等待整个响应生成,文本片段会随着到达而显示,提供即时反馈。
此功能通过generate_content_stream()方法实现。该方法返回一个迭代器,可按模型生成的顺序输出响应片段。
import google.genai as genai
# Asumiendo que 'client' ha sido inicializadoresponse_stream = client.models.generate_content_stream( model="gemini-2.0-flash", contents="Escribe un poema largo sobre el océano y sus misterios.")
print("Respuesta del modelo:")for chunk in response_stream: print(chunk.text, end="")print() # Para una nueva línea al finalSDK 提供了两种主要机制来处理多轮对话。一种方法是手动管理对话历史记录,构建代表每个回合的 Content 对象列表,并在每次调用时传递给 generate_content()。虽然灵活,但此方法可能较为繁琐。
推荐且更便捷的创建聊天机器人的方法是使用 client.chats 提供的带状态的聊天接口。此高级对象抽象了历史记录管理,显著简化了应用程序代码。这是 SDK 的有意设计决策:为常见用例(聊天)提供高级状态抽象 (client.chats),相较于低级无状态方法 generate_content,大大简化了开发。
使用聊天接口的工作流程如下:
- 初始化聊天会话: 使用
client.chats.create()启动新对话。可以指定模型,并可选地提供初始历史记录以设定对话上下文。 - 发送消息: 使用
chat.send_message()发送用户下一个消息。SDK 会自动管理状态,将用户消息和模型的后续响应添加到对话历史记录中。 - 访问历史记录: 随时可以使用
chat.get_history()检索完整的对话历史记录。
以下是一个多轮对话的完整示例:
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado# 1. Crear una nueva sesión de chatchat_session = client.chats.create( model="gemini-2.0-flash")
# 2. Enviar el primer mensajeprint("Usuario: Hola, ¿puedes ayudarme a planificar un viaje a la luna?")response = chat_session.send_message("Hola, ¿puedes ayudarme a planificar un viaje a la luna?")print(f"Modelo: {response.text}\n")
# 3. Enviar un segundo mensaje de seguimientoprint("Usuario: ¿Qué tres cosas debería empacar?")response = chat_session.send_message("¿Qué tres cosas debería empacar?")print(f"Modelo: {response.text}\n")
# 4. Mostrar el historial completo de la conversaciónprint("--- Historial de la Conversación ---")for message in chat_session.get_history(): # El rol y el texto están en message.role y message.parts.text role = "Usuario" if message.role == "user" else "Modelo" print(f"{role}: {message.parts.text}")为了调整模型的行为,方法generate_content接受参数config,该参数接受对象types.GenerateContentConfig。此对象允许开发人员控制生成过程的多个方面。
最有用的配置之一是system_instruction。系统指令提供了一个高层次的指导或为模型设定一种持续整个对话的个性。例如,可以指示模型扮演特定角色或在回答中遵循某些规则。
from google.genai import types
# Asumiendo que 'client' ha sido inicializadoresponse = client.models.generate_content( model='gemini-2.0-flash', contents='¡Ah del barco! Cuéntame un chiste sobre un loro.', config=types.GenerateContentConfig( system_instruction='Hablas como un pirata malhumorado y conciso.' ))print(response.text)除了系统指令外,还有其他几个参数可以调整以控制模型输出的创造性和结构。下表详细介绍了最重要的参数。
表2:生成配置的关键参数
| 参数 | 描述 | 范围 | 输出效果 |
|---|---|---|---|
temperature | 控制令牌选择的随机性。 | 0.0 - 1.0 | 较低的值(例如,0.2)会使输出更确定且更不具创造性。较高的值(例如,0.9)会增加随机性和创造力。 |
top_p | 核心采样(nucleus sampling)。考虑累积概率大于top_p的最小令牌集合。 | 0.0 - 1.0 | 值如0.95表示仅考虑包含95%最高概率质量的令牌。有助于避免非常不可能的令牌。 |
top_k | 仅考虑每一步生成中最可能的k个标记。 | 整数 | top_k的1是一种贪心解码(greedy)。40之类的值会将选择限制在最可能的40个标记内。 |
candidate_count | 要生成的候选回答数量。 | 整数(例如1-8) | 为同一指示生成多个可能的响应。对向用户提供选项很有用。 |
max_output_tokens | 生成响应中可以生成的最大标记数。 | 整数 | 限制输出长度。对于控制成本和延迟至关重要。 |
stop_sequences | 当生成时,将停止输出的一系列字符串。 | 字符串列表 | 用于在特定点停止生成,例如句末标记或特定格式。 |
seed | 生成的随机种子。 | 整数 | 提供种子可以使输出具有确定性和可重复性(只要temperature不是0)。 |
第3部分:高级交互:多模态和函数调用
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»本部分展示了Gemini模型的真正威力,解释了如何处理非文本输入并把模型连接到外部工具。
3.1. 超越文本:理解多模态输入
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Gemini模型家族的一个定义性特征是其内在的多模态能力。这意味着它们可以处理并推理不同类型的数据显示,或“模态”,如文本、图像、音频和视频,仅在一条提示请求中。
此功能通过将参数contents构建为包含多个对象Part的列表来实现,其中每个Part可以包含不同的数据类型。例如,单个请求可以包含一张图像和一个关于该图像的文本问题。
SDK提供了两种战略上不同的方法来处理图像数据。选择哪种方法取决于特定用例的要求,如文件大小和重用性。
这种双重方法并非冗余,而是为满足不同的操作需求而设计的。在线方法简单且非常适合单次分析和开发便利性。文件API虽然需要额外的上传步骤,但在需要高效性、可扩展性和处理大文件的生产场景中至关重要。
方法 1:在线图像数据(Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»此方法适用于较小的图像文件(总请求量,包括指令和字节,应低于 20 MB),并且开发简便。图像数据直接通过 generate_content 调用传递。
-
从本地文件: 文件图像以二进制模式读取(
'rb'),并通过types.Part.from_bytes()传递,同时指定正确的 MIME 类型。import google.genai as genaifrom google.genai import types# Asumiendo que 'client' ha sido inicializadowith open('imagen_scones.jpg', 'rb') as f:image_bytes = f.read()image_part = types.Part.from_bytes(data=image_bytes,mime_type='image/jpeg')prompt_part = "Describe lo que ves en esta imagen."# Combinar imagen y texto en una sola solicitudresponse = client.models.generate_content(model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-visioncontents=[prompt_part, image_part])print(response.text) -
从URL: 可以使用
requests之类的库来获取图像的字节,然后以相同的方式传递它们。
方法 2:文件 API (Files API)
Sección titulada «Método 2: La API de Archivos (Files API)»此方法推荐用于大于 20 MB 的图像文件或在同一文件在多个提示请求中重复使用的情况下。使用文件 API 可以避免每次调用时重新上传相同字节。
工作流程包含两个步骤:
- 上传: 使用
client.files.upload()将文件上传到 Google 服务器。此方法返回一个文件对象,作为引用。 - 提示: 将返回的文件对象直接传递到
contents中的列表。SDK 会处理解析已上传文件的引用。
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar el archivo usando la API de Archivosprint("Cargando archivo...")sample_file = client.files.upload( file_path="imagen_grande.png", display_name="Mi Imagen de Muestra")print(f"Archivo cargado: {sample_file.uri}")
# 2. Usar el archivo cargado en una indicaciónprompt = "Analiza esta imagen y describe los objetos principales y su disposición espacial."response = client.models.generate_content( model='gemini-2.5-flash', contents=[prompt, sample_file] # Pasar el objeto de archivo directamente)
print(response.text)
# Opcional: Eliminar el archivo después de su usoclient.files.delete(name=sample_file.name)print(f"Archivo eliminado: {sample_file.name}")通过文件API上传的文件将在48小时后自动删除。API还提供了用于管理这些文件的方法,如get()、list()和delete()。
3.3. 与音频和视频的交互
Sección titulada «3.3. Interacción con Audio y Vídeo»图像处理的概念直接扩展到其他模式,如音频和视频。由于这些文件通常较大,文件API是处理它们的主要方法。
该过程与处理大图像完全相同:
- 使用
client.files.upload()加载音频文件(例如,MP3、WAV)或视频文件(例如,MP4) - 将返回的文件对象包含在
generate_content的指示中
以下示例展示了如何加载音频文件并请求模型进行转录
import google.genai as genaiimport time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audioprint("Cargando archivo de audio...")audio_file = client.files.upload( file_path="discurso_muestra.mp3", display_name="Discurso de Muestra")
# El procesamiento del archivo puede llevar tiempo, se espera a que esté ACTIVOwhile audio_file.state.name == "PROCESSING": print("Procesando archivo... esperando.") time.sleep(10) audio_file = client.files.get(name=audio_file.name)
if audio_file.state.name == "FAILED": raise ValueError(audio_file.state.name)
# 2. Usar el archivo de audio en una indicaciónprompt = "Transcribe el discurso en este archivo de audio."response = client.models.generate_content( model='gemini-2.5-flash', contents=[prompt, audio_file])print("\n--- Transcripción ---")print(response.text)函数调用,也称为工具使用(tool use),是一种强大的技术,允许语言模型与外部系统交互。它使模型能够回答超出其固有知识范围的问题或执行操作,例如从API获取实时数据、查询数据库或控制设备。
一般的工作流程如下:
- 定义工具: 定义一组工具(Python函数),模型可以调用这些工具。此定义包括函数名称、功能描述以及参数模式。
- 将工具传递给模型: 在调用
generate_content时传递定义的工具列表。 - 模型决定调用: 模型分析用户指示,如果确定提供的工具之一可以协助回答,则其响应将包含类型为
function_call的对象Part,而不是生成文本。此对象指定要调用的函数名称和调用参数。 - 执行函数: 应用程序代码检测到
function_call,使用提供的参数执行相应的Python函数并获取结果。 - 将结果返回给模型: 再次调用
generate_content,提供包含函数执行结果(封装在types.Part.from_function_response()中)的对话历史。 - 最终响应: 模型使用函数结果生成自然语言的最终响应提供给用户。
尽管研究片段未提供端到端函数调用的代码示例,但function_call和function_response的Part对象结构是实现此高级模式的基础。
第4部分:生产准备:错误处理、安全性和管理
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»本部分提供构建健壮、可靠和负责任的应用程序所需的关键信息。
在生产环境中,健壮的错误处理是不可选的。API调用可能因多种原因失败,如无效凭据、网络问题、配额耗尽或格式错误的输入。
SDK使用Python标准异常系统。大多数API相关错误可以通过捕获try...except块中的异常来处理,这些异常来自模块google.api_core.exceptions,或者如果可用的话,来自更具体的类errors.APIError。
from google.api_core import exceptions as core_exceptionsimport google.genai as genai
# Asumiendo que 'client' ha sido inicializadotry: response = client.models.generate_content( model="nombre-de-modelo-invalido", contents="¿Cuál es tu nombre?" ) print(response.text)except core_exceptions.GoogleAPICallError as e: # 'e' es una superclase para muchos errores de API print(f"Ha ocurrido un error en la API: {e}") # En muchos casos, 'e' tendrá atributos como 'code' y 'message' # aunque esto puede variar. Se recomienda inspeccionar el objeto de excepción.
except core_exceptions.NotFound as e: # Un error más específico si se sabe qué buscar print(f"Error: Recurso no encontrado. ¿Es correcto el nombre del modelo? - {e.message}")
except core_exceptions.ResourceExhausted as e: # Específico para errores de cuota print(f"Error: Se ha excedido la cuota de la API. - {e.message}")捕获异常时,异常对象通常包含可用于记录和调试的有价值信息,如状态码和描述性消息。
需要注意的是,错误消息虽然对开发人员很有用,但可能是一把双刃剑。它们可能泄露内部实现细节,这些细节可能被对抗性攻击利用。例如,安全验证错误消息的分析可能揭示内部阈值或防御机制,帮助恶意行为者绕过防护。因此,尽管应在后端全面记录错误,但提供给最终用户的信息必须仔细控制。通常,显示通用消息如“处理您的请求时发生错误”比暴露原始 API 错误消息更安全。
下表总结了最常见的 API 错误代码及其解决方法。
表 3:常见 API 错误代码及解决方案
| HTTP 状态码 | 状态 | 可能原因 | Python 中的推荐操作 |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | 请求正文格式不正确(例如,参数类型错误,缺少必填字段)。 | 请检查 GenerateContentConfig 中的参数和 contents 的格式是否正确。确保模型与所请求的特性兼容。 |
| 403 | PERMISSION_DENIED | API 密钥错误,缺少必要权限,或尝试访问受限制的资源(例如,经过微调的模型)。 | 请检查 API 密钥(或 Vertex 的 ADC 认证)是否正确配置并具有必要权限。 |
| 429 | RESOURCE_EXHAUSTED | 已超出 API 速率限制(每分钟请求数)。 | 在重试逻辑中实现指数退避(exponential backoff)。如需,可申请增加配额。 |
| 500 | INTERNAL | Google端发生了意外错误。有时可能是由于输入上下文过长导致的。 | 请减少指示的长度。短暂等待后重试请求。如果问题仍然存在,请考虑暂时更换模型。 |
| 503 | UNAVAILABLE | 服务暂时过载或不可用。 | 请在短暂等待后,使用指数退避策略重新尝试请求。如果问题仍然存在,请报告问题。 |
Gemini API 包含内置的安全功能,用于过滤潜在有害的内容。这些功能旨在帮助开发人员构建更安全和负责任的应用程序。
API 将内容分为四类主要损害类别:
- 骚扰 (
HARM_CATEGORY_HARASSMENT) - 鼓动仇恨 (
HARM_CATEGORY_HATE_SPEECH) - 色情内容 (
HARM_CATEGORY_SEXUALLY_EXPLICIT) - 危险内容 (
HARM_CATEGORY_DANGEROUS_CONTENT)
对于每个类别,模型会分配内容不安全的概率。默认情况下,API 会阻止那些在这些类别中不安全概率为 MEDIUM 或 HIGH 的提示和响应。
开发者可以通过请求传递 SafetySetting 对象列表到 safety_settings 参数来覆盖此默认设置。这允许对每个类别的阻止阈值进行细粒度控制。
from google.genai import types
# Asumiendo que 'client' ha sido inicializado
# Ejemplo: Relajar el umbral para el acoso, pero mantener el predeterminado para otros.# ¡Use esta configuración con precaución y solo si es necesario para su caso de uso!safety_config =
try: response = client.models.generate_content( model='gemini-2.0-flash', contents="Escribe un diálogo entre dos personajes que están discutiendo acaloradamente.", safety_settings=safety_config ) print(response.text)except ValueError: # A menudo, una respuesta bloqueada puede generar un ValueError al intentar acceder a.text print("La respuesta fue bloqueada o está vacía.") # Inspeccionar la retroalimentación de seguridad para depurar print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}") if response.candidates: print(f"Calificaciones de seguridad del candidato: {response.candidates.safety_ratings}")当响应似乎为空或发生错误时,检查安全反馈至关重要。响应对象包含 prompt_feedback(用于输入提示)和 candidates.safety_ratings(用于生成的响应)。这些属性将揭示内容是否被阻止以及原因,这对于调试至关重要。
下表解释了不同阻塞阈值的含义。
表4:安全配置阈值
| API常量 | Google AI Studio中的设置 | 描述 |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | 无 | 阈值未指定;将使用模型的默认阈值。 |
BLOCK_NONE | 不阻止(阻止全部) | 从不阻止内容,无论其不安全的可能性如何。应极其谨慎使用。 |
BLOCK_ONLY_HIGH | 限制少数(阻止少数) | 仅在不安全内容概率为 HIGH 时阻止。 |
BLOCK_MEDIUM_AND_ABOVE | 阻止一些(限制一些) | (默认适用于大多数模型) 当不安全内容概率为 MEDIUM 或 HIGH 时阻止。 |
BLOCK_LOW_AND_ABOVE | 限制大部分(阻止大部分) | 当不安全内容概率为 LOW、MEDIUM 或 HIGH 时阻止。 |
SDK 提供了一种编程方式来发现可用的模型及其功能。这有助于构建可以适应不同模型的应用程序,或在使用前检查模型的功能。
方法 client.models.list() 返回可用模型的迭代器。
Python
import google.genai as genai
# Asumiendo que 'client' ha sido inicializadoprint("Modelos disponibles:")for model in client.models.list(): # El objeto 'model' contiene metadatos detallados print(f" - Nombre: {model.name}") print(f" - Nombre para mostrar: {model.display_name}") print(f" - Métodos soportados: {model.supported_generation_methods}") # Verificar si el modelo soporta chat (create_chat) if 'create_chat' in model.supported_generation_methods: print(" - ¡Este modelo soporta chat!") print("-" * 20)此功能还可用于专门列出用户调整(微调)的模型,在列表请求的配置中设置 query_base=False。这使得应用程序能够动态发现和使用自定义模型。
要完成在Portelcore租户中基于统一SDK google-genai 的集成预配,请验证以下技术里程碑的合规性:
- 我已将过时库
google-generativeai租户的所有脚本迁移到新的标准google-genai。 ✓ - API密钥仅通过环境变量
GOOGLE_API_KEY进行管理,或在Google Cloud秘密管理器中混淆处理,而不是以明文形式编写。 ✓ - 实施了强大的异常控制 (
google.api_core.exceptions),以捕获状态码429(资源耗尽)并采用指数退避重试策略。 ✓ - 温度和安全阈值 (
safety_settings) 已根据领域用例portelcore.com正式参数化。 ✓

