Google GenAI Python SDK für die Gemini API
Referenzhandbuch und fortgeschrittene Konfiguration für das neue vereinheitlichte google-genai SDK der Gemini API bei Portelcore.
Teil 1: Grundbegriffe und Erstkonfiguration
Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»Dieser Abschnitt schafft den Kontext für das neue SDK, geht auf die Hauptverwirrung der Benutzer bezüglich des Bibliothekswechsels ein und bietet eine robuste Anleitung für den korrekten Einstieg, einschließlich der Installation und der zwei kritischen Authentifizierungsmethoden.
1.1. Der neue Standard: Migration von google-generativeai zu google-genai
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»Das Entwicklungs-Ökosystem für die generativen KI-Modelle von Google hat sich weiterentwickelt. Die Bibliothek google-genai ist nun das offizielle, vereinheitlichte und empfohlene Python-SDK zur Interaktion mit der Gemini-API und anderen generativen KI-Modellen von Google. Sie erreichte im Mai 2025 die allgemeine Verfügbarkeit (GA) und ersetzt die veraltete Bibliothek google-generativeai.
Die vorherige Bibliothek google-generativeai wurde im Python Package Index (PyPI) als „inaktiv“ markiert und befindet sich auf dem Weg zur Einstellung. Der Support für dieses Paket, einschließlich kritischer Fehlerbehebungen, wird Ende September 2025 eingestellt, obwohl einige Quellen ein etwas früheres Datum für das Ende des Supports angeben, nämlich den 31. August 2025. Entwicklern wird empfohlen, das frühere Datum anzupeilen, um einen reibungslosen Übergang zu gewährleisten.
Diese Änderung ist nicht nur eine bloße Umbenennung, sondern eine strategische Vereinheitlichung, die durch Feedback von Entwicklern vorangetrieben wurde. Das Ziel war es, ein einziges SDK zu schaffen, das den Zugang zu der gesamten Palette der generativen KI-Modelle von Google (Gemini, Veo, Imagen usw.) vereinfacht und einen klareren und konsistenteren Entwicklungsweg bietet. Eine der bedeutendsten Designentscheidungen des neuen SDKs google-genai ist, dass es als einheitliche Schnittstelle für zwei verschiedene Backend-Dienste fungiert: die leicht zugängliche Gemini-Developer-API und die Vertex AI-Plattform für Unternehmen.
Diese vereinheitlichte Architektur bietet Entwicklern einen nahtlosen Einstieg. Sie können schnell starten, oft mit einem kostenlosen Kontingent, indem sie einen API-Schlüssel für die Gemini-Developer-API verwenden. Sobald Ihre Anwendungen reifen und eine größere Skalierbarkeit, Governance und Integration in andere Google Cloud-Dienste erfordern, können Sie mit minimalen Codeänderungen – hauptsächlich bei der Client-Initialisierung – zum Vertex AI-Backend wechseln. Das SDK google-genai fungiert als Brücke, die die Eintrittsbarriere senkt und gleichzeitig einen klaren Weg zur Produktion in der Google Cloud ebnet. Daher werden alle Benutzer der veralteten Bibliothek dringend zur Migration aufgefordert, um den Zugriff auf die neuesten Funktionen (wie Live API und Veo), Leistungsverbesserungen und kontinuierlichen Support zu gewährleisten.
1.2. Installation und Umgebung
Sección titulada «1.2. Instalación y Entorno»Bevor Sie das SDK installieren, ist es empfehlenswert, eine Python-virtuelle Umgebung einzurichten. Dies isoliert die Projektabhängigkeiten und verhindert Konflikte mit anderen Projekten oder Systempaketen.
Um eine virtuelle Umgebung mit venv zu erstellen und zu aktivieren:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateSobald die virtuelle Umgebung aktiviert ist, kann die neueste Version des Google Gen AI SDKs unter Verwendung von pip installiert werden. Die Verwendung des Flags --upgrade stellt sicher, dass die aktuellste Version abgerufen wird.
pip install --upgrade google-genaiEs ist wichtig, die Anforderungen an die Python-Version zu beachten. Das SDK google-genai erfordert Python 3.9 oder höher. Die Verwendung einer inkompatiblen Version kann zu unerwarteten Fehlern während der Installation oder zur Laufzeit führen.
Für Anwendungen, die eine hochperformante asynchrone Leistung erfordern, bietet das SDK die Option, aiohttp als HTTP-Transport-Backend anstelle des Standard- httpx zu verwenden. Dies kann als Extra installiert werden:
pip install google-genai[aiohttp]1.3. Authentifizierung: Ihr Schlüssel zur Gemini API
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»Die Authentifizierung ist der kritischste Konfigurationsschritt, und die Methode unterscheidet sich je nach dem Backend-Service, der verwendet werden soll: die Gemini Developer API oder die Gemini API in Vertex AI.
1.3.1. Der Weg über die Gemini Developer API (Empfohlen für Prototypen und die kostenlose Stufe)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»Dies ist der schnellste Weg, um mit Gemini zu bauen. Es erfordert einen API-Schlüssel, der kostenlos über das Google AI Studio bezogen werden kann.
Der Prozess zum Erhalt eines API-Schlüssels ist wie folgt:
- Navigieren Sie zu (https://ai.google.dev/) und melden Sie sich mit einem Google-Konto an.
- Klicken Sie auf „Get API key“ (API-Schlüssel abrufen).
- Wählen Sie aus, ob Sie den API-Schlüssel in einem neuen oder bestehenden Google Cloud-Projekt erstellen möchten.
- Der API-Schlüssel wird automatisch generiert.
API-Schlüssel sind sensible Anmeldedaten und müssen wie Passwörter behandelt werden. Sie müssen sicher gespeichert werden und dürfen niemals im clientseitigen Code offengelegt oder in öffentlichen Versionsverwaltungssystemen committet werden.
Die sicherste und empfohlene Methode zur Verwendung des Schlüssels besteht darin, ihn als Umgebungsvariable zu konfigurieren. Das SDK ist darauf ausgelegt, die Umgebungsvariablen GOOGLE_API_KEY oder GEMINI_API_KEY automatisch zu erkennen und zu verwenden. Wenn beide konfiguriert sind, hat GOOGLE_API_KEY Vorrang.
Um die Umgebungsvariable zu konfigurieren:
-
Unter 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 -
Unter Windows: Verwenden Sie die grafische Benutzeroberfläche „Umgebungsvariablen“ in den Systemeinstellungen, um eine neue Benutzer- oder Systemvariable namens
GOOGLE_API_KEYmit Ihrem Schlüssel als Wert hinzuzufügen.
1.3.2. Der Vertex AI-Weg (Empfohlen für die Produktion und die Integration mit Google Cloud)
Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»Für produktionsreife Anwendungen, die die Enterprise-Funktionen von Google Cloud erfordern, wird empfohlen, die Gemini API über Vertex AI zu verwenden. Dieser Ansatz erfordert ein Google Cloud-Projekt mit aktivierter Abrechnung.
Die ersten Konfigurationsschritte umfassen:
- Ein Google Cloud-Projekt auswählen oder erstellen.
- Sicherstellen, dass die Abrechnung für das Projekt aktiviert ist.
- Die Vertex AI API (
aiplatform.googleapis.com) für das Projekt aktivieren.
Die Authentifizierung für Vertex AI kann auf zwei Arten erfolgen:
-
Anwendungsstandard-Anmeldedaten (ADC) (Empfohlen für die Produktion): Dies ist die bevorzugte Methode für die meisten Produktionsszenarien. ADC findet die Anmeldedaten automatisch basierend auf der Umgebung. In einer lokalen Entwicklungsumgebung kann dies durch Ausführen eines gcloud CLI-Befehls konfiguriert werden:
Ventana de terminal gcloud auth application-default loginWenn es in einer Google Cloud-Umgebung ausgeführt wird (z. B. Cloud Run, Google Kubernetes Engine, Cloud Functions), verwendet ADC automatisch das an diese Ressource gebundene Dienstkonto, wodurch die Verwaltung von Schlüsseln entfällt.
-
API-Schlüssel (für Tests in Vertex): Es ist möglich, einen API-Schlüssel zur Authentifizierung am Vertex AI-Endpunkt zu verwenden, aber der Prozess ist komplexer als bei der Developer API. Er erfordert Berechtigungen auf Organisationsebene, um die Erstellung von API-Schlüsseln für Dienstkonten zu ermöglichen, die Erstellung eines Dienstkontos mit einer geeigneten Rolle (z. B.
Vertex AI User) und die anschließende Erstellung eines auf dieses Dienstkonto beschränkten API-Schlüssels. Aufgrund seiner Komplexität wird diese Methode im Allgemeinen für spezifische Testszenarien anstelle der allgemeinen Anwendungsentwicklung verwendet.
1.4. Client-Initialisierung: Verbindung zum Modell herstellen
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»Sobald die Authentifizierung konfiguriert ist, besteht der nächste Schritt darin, das Objekt genai.Client zu instanziieren. Das einheitliche SDK vereinfacht dies, indem es einen einzigen Client bereitstellt, der für eines der beiden Backends konfiguriert werden kann.
Im Folgenden werden die vier Hauptszenarien für die Client-Initialisierung vorgestellt.
-
Szenario 1: Gemini Developer API (Expliziter Schlüssel) Diese Methode ist praktisch für Notebooks oder schnelle Skripte, bei denen keine Umgebungsvariablen konfiguriert werden sollen. Der API-Schlüssel wird direkt als Argument übergeben.
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
Szenario 2: Gemini Developer API (Umgebungsvariable) Dies ist der sauberste und empfohlene Ansatz für Anwendungscode, da die Anmeldedaten vom Code entkoppelt werden. Der Client findet und verwendet automatisch die Umgebungsvariable
GOOGLE_API_KEY.# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
Szenario 3: Vertex AI API (Explizite Parameter) Um sich mit Vertex AI zu verbinden, wird der Flag
vertexaiaufTruegesetzt und die Projekt-ID sowie der Standort angegeben. Diese Methode verwendet automatisch die Application Default Credentials (ADC) zur Authentifizierung.from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
Szenario 4: Vertex AI API (Umgebungsvariablen) Als Alternative für Vertex AI kann die Konfiguration in Umgebungsvariablen ausgelagert werden. Der Client erkennt diese Variablen und wird so konfiguriert, dass er das Vertex AI-Backend verwendet.
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()
Die folgende Tabelle fasst diese Methoden für einen schnellen Überblick zusammen.
Tabelle 1: Schnelle Referenz zur Client-Initialisierung
| Anwendungsfall | Python-Code | Erforderliche Umgebungsvariablen | Hinweise |
|---|---|---|---|
| Developer API mit explizitem Schlüssel | client = genai.Client(api_key="SU_CLAVE...") | Keine | Nützlich für Notebooks und schnelle Tests. In Produktionscode vermeiden. |
| Entwickler-API mit Umgebungsvariablen | client = genai.Client() | GOOGLE_API_KEY oder GEMINI_API_KEY | Bevorzugte Methode für sauberen und sicheren Anwendungscode. |
| Vertex AI mit expliziten Parametern | client = genai.Client(vertexai=True, project="...", location="...") | Keine (nutzt ADC) | Explizite Methode zur Ansteuerung von Vertex AI. Erfordert ADC-Authentifizierung (gcloud auth...). |
| Vertex AI mit Umgebungsvariablen | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Konfiguriert den Client für Vertex AI ohne Parameter im Code. Erfordert ADC-Authentifizierung. |
Teil 2: Hauptfunktionen: Text und Chat
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»Dieser Teil befasst sich mit den gängigsten Anwendungsfällen: Texterzeugung und Aufbau von Konversationsagenten. Er erläutert die wichtigsten beteiligten Methoden und Objekte.
2.1. Inhaltserzeugung: Die Methode generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»Die Hauptmethode für alle Single-Turn-Generierungsaufgaben ist client.models.generate_content(). Diese vielseitige Methode bildet die Grundlage für die Interaktion mit Gemini-Modellen.
Eine grundlegende Verwendung besteht darin, eine einfache Zeichenfolge wie contents bereitzustellen und den zu verwendenden Modellnamen, wie gemini-2.5-flash, anzugeben.
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)Obwohl die Übergabe einer einfachen Zeichenfolge praktisch ist, ist es entscheidend, die zugrunde liegende Datenstruktur des SDKs zu verstehen. Intern konvertiert das SDK alle Eingaben in eine standardisierte Struktur, die aus den Objekten types.Content und types.Part besteht. Das Verständnis dieser Struktur ist der Schlüssel zur Freischaltung fortgeschrittener SDK-Funktionen wie multimodale Prompts und Funktionsaufrufe.
types.Content: Repräsentiert eine einzelne Nachricht oder einen Turn in einer Konversation. Es hat zwei Hauptattribute: einrole(normalerweise ‘user’ für den Input oder ‘model’ für den Output) und eine Liste vonparts.types.Part: Repräsentiert ein Datenstück innerhalb einesContent-Objekts. Ein Teil kann Text, Bilddaten, eine Dateireferenz, ein Funktionsaufruf usw. sein.
Das SDK verarbeitet intelligent verschiedene Eingabetypen für das Argument contents, und konvertiert diese in das entsprechende Content/Part-Format :
-
contents='¿Por qué el cielo es azul?'wird in einUserContentmit einer einzigenPartaus Text konvertiert. -
contents=['Pregunta 1', 'Pregunta 2']wird in ein einzigesUserContentkonvertiert, das zweiPartaus Text enthält. - types.Part-Objekt: Ermöglicht eine detailliertere Kontrolle, wie z. B. das Spezifizieren von Bilddaten.
- types.Content-Objekt: Bietet die maximale Kontrolle über die Rolle und den Inhalt der Nachricht.
Um auf die generierte Antwort zuzugreifen, ist der Convenience-Accessor response.text die einfachste Methode. Es ist jedoch wichtig zu wissen, dass dieser Accessor nur für einfache Antworten funktioniert, die aus einem einzigen Textteil bestehen. Wenn die Antwort durch Sicherheitsfilter blockiert wird, mehrere Kandidaten enthält oder nicht-textuelle Datentypen beinhaltet, wird der Zugriff auf response.text einen Fehler verursachen. Die robusteste und sicherste Methode für die Produktion ist der direkte Zugriff auf den Kandidaten und seine Teile:
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}")Für interaktive Anwendungen wie Chatbots verbessert das Streaming der Modellantwort die Benutzererfahrung drastisch. Anstatt darauf zu warten, dass die gesamte Antwort generiert wird, werden Textfragmente angezeigt, sobald sie eintreffen, was ein sofortiges Feedback ermöglicht.
Diese Funktionalität wird mit der Methode generate_content_stream() erreicht. Diese Methode gibt einen Iterator zurück, der Antwortfragmente erzeugt, sobald diese vom Modell generiert werden.
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 final2.3. Beherrschung der konversationellen KI: Das Chat-Interface
Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»Das SDK bietet zwei Hauptmechanismen zur Verwaltung von Multi-Turn-Konversationen. Ein Ansatz besteht darin, den Gesprächsverlauf manuell zu verwalten, indem eine Liste von Objekten Content erstellt wird, die jede Runde repräsentieren, und diese bei jedem Aufruf an generate_content() übergeben wird. Obwohl dieser Ansatz flexibel ist, kann er umständlich sein.
Der empfohlene und bequemste Ansatz zur Erstellung von Chatbots ist die Verwendung des vom client.chats bereitgestellten zustandsbehafteten Chat-Interfaces. Dieses High-Level-Objekt abstrahiert die Verwaltung des Verlaufs und vereinfacht den Anwendungscode erheblich. Dies ist eine bewusste Designentscheidung im SDK: eine High-Level- und zustandsbehaftete Abstraktion (client.chats) für einen gängigen Anwendungsfall (Chat) bereitzustellen, was die Entwicklung im Vergleich zur zustandslosen Low-Level-Methode generate_content enorm vereinfacht.
Der Workflow zur Nutzung des Chat-Interfaces ist wie folgt:
- Initialisierung einer Chat-Sitzung:
client.chats.create()wird verwendet, um eine neue Konversation zu starten. Das Modell kann spezifiziert und optional ein initialer Verlauf bereitgestellt werden, um die Konversation zu kontextualisieren. - Nachrichten senden: Die Methode
chat.send_message()wird verwendet, um die nächste Benutzernachricht zu senden. Das SDK verwaltet den Zustand automatisch, indem es die Benutzernachricht und die anschließende Modellantwort zum Gesprächsverlauf hinzufügt. - Auf den Verlauf zugreifen: Der vollständige Gesprächsverlauf kann jederzeit unter Verwendung von
chat.get_history()abgerufen werden.
Nachfolgend finden Sie ein vollständiges Beispiel für eine Multi-Turn-Konversation:
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}")2.4. Erweiterte Steuerung der Generierung
Sección titulada «2.4. Control Avanzado de la Generación»Um das Verhalten des Modells zu verfeinern, akzeptiert die Methode generate_content einen Parameter config, der ein Objekt types.GenerateContentConfig annimmt. Dieses Objekt ermöglicht es Entwicklern, verschiedene Aspekte des Generierungsprozesses zu steuern.
Eine der nützlichsten Konfigurationen ist system_instruction. Eine Systemanweisung bietet eine High-Level-Anleitung oder legt eine Persönlichkeit für das Modell fest, die über das gesamte Gespräch hinweg bestehen bleibt. Zum Beispiel kann das Modell angewiesen werden, als eine bestimmte Figur zu agieren oder bestimmte Regeln in seinen Antworten zu befolgen.
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)Neben den Systemanweisungen gibt es mehrere weitere Parameter, die angepasst werden können, um die Kreativität und die Struktur der Modellausgabe zu steuern. Die folgende Tabelle beschreibt die wichtigsten im Detail.
Tabelle 2: Wichtige Konfigurationsparameter für die Generierung
| Parameter | Beschreibung | Bereich | Auswirkung auf die Ausgabe |
|---|---|---|---|
temperature | Steuert die Zufälligkeit der Token-Auswahl. | 0.0 - 1.0 | Niedrigere Werte (z. B. 0.2) machen die Ausgabe deterministischer und weniger kreativ. Höhere Werte (z. B. 0.9) erhöhen die Zufälligkeit und die Kreativität. |
top_p | Nucleus Sampling. Berücksichtigt den kleinsten Satz von Token, dessen kumulierte Wahrscheinlichkeit größer als top_p ist. | 0.0 - 1.0 | Ein Wert wie 0.95 bedeutet, dass nur die Tokens berücksichtigt werden, die die obersten 95 % der Wahrscheinlichkeitsmasse ausmachen. Dies hilft, sehr unwahrscheinliche Tokens zu vermeiden. |
top_k | Berücksichtigt bei jedem Schritt der Generierung nur die k wahrscheinlichsten Tokens. | Integer | Ein top_k von 1 ist eine Greedy-Dekodierung. Ein Wert wie 40 schränkt die Auswahl auf die 40 wahrscheinlichsten Tokens ein. |
candidate_count | Die Anzahl der zu generierenden Antwortkandidaten. | Integer (z. B. 1-8) | Generiert mehrere mögliche Antworten für denselben Prompt. Nützlich, um dem Benutzer Optionen anzubieten. |
max_output_tokens | Die maximale Anzahl der Tokens, die in der Antwort generiert werden können. | Integer | Begrenzt die Ausgabelänge. Essenziell zur Kontrolle von Kosten und Latenz. |
stop_sequences | Eine Liste von Zeichenfolgen, die die Ausgabe stoppen, wenn sie generiert werden. | Liste von Zeichenfolgen | Nützlich, um die Generierung an einem bestimmten Punkt zu stoppen, wie zum Beispiel bei einem Satzendzeichen oder einem bestimmten Format. |
seed | Zufälliger Seed für die Generierung. | Integer | Die Bereitstellung eines Seeds macht die Ausgabe deterministisch und reproduzierbar (sofern temperature nicht 0 ist). |
Teil 3: Erweiterte Interaktionen: Multimodalität und Funktionsaufruf
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»Dieser Teil zeigt die wahre Leistungsfähigkeit der Gemini-Modelle, indem er erklärt, wie man mit nicht-textuellen Eingaben arbeitet und das Modell mit externen Tools verbindet.
3.1. Jenseits von Text: Verständnis multimodaler Eingaben
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Eines der definierenden Merkmale der Gemini-Modellfamilie ist ihre inhärente multimodale Fähigkeit. Das bedeutet, dass sie verschiedene Datentypen oder „Modalitäten“ wie Text, Bilder, Audio und Video innerhalb einer einzigen Prompt-Anfrage verarbeiten und interpretieren können.
Diese Fähigkeit wird ermöglicht, indem das Argument contents als eine Liste aufgebaut wird, die mehrere Objekte Part enthält, wobei jedes Part einen anderen Datentyp enthalten kann. Zum Beispiel kann eine einzige Anfrage ein Bild und eine Textfrage zu diesem Bild enthalten.
3.2. Arbeiten mit Bildern
Sección titulada «3.2. Trabajando con Imágenes»Das SDK bietet zwei strategisch unterschiedliche Methoden zur Handhabung von Bilddaten. Die Wahl zwischen ihnen hängt von den spezifischen Anforderungen des Anwendungsfalls ab, wie z. B. der Dateigröße und der Wiederverwendbarkeit.
Diese Dualität der Methoden ist keine Redundanz, sondern ein bewusstes Design, das unterschiedliche betriebliche Anforderungen adressiert. Die Inline-Methode ist einfach und eignet sich hervorragend für einmalige Analysen und die Bequemlichkeit in der Entwicklung. Die File-API erfordert zwar einen zusätzlichen Upload-Schritt, ist aber entscheidend für Produktionsszenarien, in denen Effizienz, Skalierbarkeit und der Umgang mit großen Dateien von primärer Bedeutung sind.
Methode 1: Inline-Bilddaten
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»Diese Methode ist ideal für kleinere Bilddateien (die Gesamtanfrage, einschließlich der Prompts und Bytes, darf 20 MB nicht überschreiten) und für die Einfachheit in der Entwicklung. Die Bilddaten werden direkt im Aufruf an generate_content übergeben.
-
Von einer lokalen Datei: Die Bilddatei wird im Binärmodus (
'rb') gelesen und antypes.Part.from_bytes()übergeben, wobei der korrekte MIME-Typ angegeben wird.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) -
Von einer URL: Man kann eine Bibliothek wie
requestsverwenden, um die Bytes des Bildes von einer URL abzurufen und sie dann auf die gleiche Weise zu übergeben.
Methode 2: Die Files API
Sección titulada «Método 2: La API de Archivos (Files API)»Diese Methode wird für große Bilddateien (über 20 MB) oder für Szenarien empfohlen, in denen dieselbe Datei in mehreren Prompt-Anfragen wiederverwendet wird. Die Verwendung der Files API erspart das erneute Hochladen derselben Bytes bei jedem Aufruf.
Der Workflow besteht aus zwei Schritten:
- Hochladen:
client.files.upload()wird verwendet, um die Datei auf die Google-Server hochzuladen. Diese Methode gibt ein Dateiobjekt zurück, das als Referenz dient. - Prompt: Das zurückgegebene Dateiobjekt wird direkt in die Liste
contentseines Aufrufs vongenerate_contentübergeben. Das SDK kümmert sich um die Auflösung der Referenz zur hochgeladenen Datei.
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}")Dateien, die über die Files API hochgeladen werden, werden vor der automatischen Löschung 48 Stunden lang temporär gespeichert. Die API bietet außerdem Methoden zur Verwaltung dieser Dateien, wie get(), list() und delete().
3.3. Interaktion mit Audio und Video
Sección titulada «3.3. Interacción con Audio y Vídeo»Die Konzepte der Bildverarbeitung lassen sich direkt auf andere Modalitäten wie Audio und Video übertragen. Da diese Dateien oft groß sind, ist die Files API die primäre Methode für deren Bearbeitung.
Der Prozess ist identisch mit dem bei großen Bildern:
- Verwenden Sie
client.files.upload(), um die Audio- (z. B. MP3, WAV) oder Videodatei (z. B. MP4) hochzuladen. - Fügen Sie das zurückgegebene Datei-Objekt dem Prompt für
generate_contenthinzu.
Das folgende Beispiel zeigt, wie eine Audiodatei hochgeladen und das Modell angewiesen wird, sie zu transkribieren.
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)3.4. Funktionsaufruf: Erweiterung der Modellkapazitäten
Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»Der Funktionsaufruf, auch bekannt als Tool-Nutzung (tool use), ist eine leistungsstarke Technik, die es dem Sprachmodell ermöglicht, mit externen Systemen zu interagieren. Er ermöglicht es dem Modell, Fragen zu beantworten oder Aktionen auszuführen, die über sein inhärentes Wissen hinausgehen, wie z. B. das Abrufen von Echtzeitdaten aus einer API, das Abfragen einer Datenbank oder das Steuern eines Geräts.
Der allgemeine Workflow ist wie folgt:
- Werkzeuge definieren: Es wird eine Sammlung von Werkzeugen (Python-Funktionen) definiert, die das Modell aufrufen kann. Diese Definition umfasst den Funktionsnamen, eine Beschreibung dessen, was sie tut, und das Schema ihrer Parameter.
- Werkzeuge an das Modell übergeben: Die Liste der definierten Werkzeuge wird dem Modell beim Aufruf von
generate_contentübergeben. - Das Modell entscheidet über den Aufruf: Das Modell analysiert den Benutzer-Prompt und wenn es feststellt, dass eines der bereitgestellten Werkzeuge bei der Beantwortung helfen kann, enthält seine Antwort anstelle von Text ein
Part-Objekt vom Typfunction_call. Dieses Objekt gibt den Namen der aufzurufenden Funktion und die Argumente für den Aufruf an. - Funktion ausführen: Der Anwendungscode erkennt dieses
function_call, führt die entsprechende Python-Funktion mit den bereitgestellten Argumenten aus und erhält ein Ergebnis. - Ergebnis an das Modell zurückgeben: Es erfolgt ein zweiter Aufruf von
generate_content, bei dem der Gesprächsverlauf zusammen mit dem Ergebnis der Funktionsausführung (eingebettet intypes.Part.from_function_response()) bereitgestellt wird. - Abschließende Antwort: Das Modell verwendet das Ergebnis der Funktion, um eine endgültige Antwort in natürlicher Sprache für den Benutzer zu generieren.
Obwohl die Forschungsfragmente kein Beispiel für einen End-to-End-Funktionsaufruf enthalten, bildet die Struktur der Objekte Part für function_call und function_response die Grundlage für die Implementierung dieses fortgeschrittenen Musters.
Teil 4: Produktionsvorbereitung: Fehlerbehandlung, Sicherheit und Management
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»Dieser abschließende Teil liefert die kritischen Informationen, die für den Aufbau robuster, zuverlässiger und verantwortungsbewusster Anwendungen erforderlich sind.
4.1. Robuste Fehlerbehandlung
Sección titulada «4.1. Manejo Robusto de Errores»In einer Produktionsumgebung ist eine robuste Fehlerbehandlung unverzichtbar. API-Aufrufe können aus verschiedenen Gründen fehlschlagen, wie z. B. ungültige Anmeldedaten, Netzwerkprobleme, Kontingenterschöpfung oder fehlerhafte Eingaben.
Das SDK verwendet das Standard-Exception-System von Python. Die meisten API-bezogenen Fehler können durch einen Block try...except abgefangen werden, der nach Exceptions aus dem Modul google.api_core.exceptions oder, falls verfügbar, nach einer spezifischeren Klasse wie errors.APIError sucht.
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}")Beim Abfangen einer Ausnahme enthält das Ausnahmeobjekt oft wertvolle Informationen für das Logging und das Debugging, wie z. B. einen Statuscode und eine beschreibende Meldung.
Es ist wichtig zu bedenken, dass Fehlermeldungen zwar für Entwickler nützlich sind, aber ein zweischneidiges Schwert sein können. Sie können Details der internen Implementierung preisgeben, die bei Angriffen ausgenutzt werden könnten. Beispielsweise könnte eine Analyse von Sicherheitsvalidierungsfehlermeldungen interne Schwellenwerte oder Verteidigungsmechanismen offenlegen und einem böswilligen Akteur helfen, die Schutzmaßnahmen zu umgehen. Daher sollten Fehler zwar im Backend ausführlich protokolliert werden, die den Endbenutzern präsentierten Informationen müssen jedoch sorgfältig kontrolliert werden. Oft ist es sicherer, eine generische Meldung wie „Bei der Verarbeitung Ihrer Anfrage ist ein Fehler aufgetreten“ anzuzeigen, anstatt die ungefilterte Fehlermeldung der API preiszugeben.
Die folgende Tabelle fasst die häufigsten API-Fehlercodes und deren Behebung zusammen.
Tabelle 3: Häufige API-Fehlercodes und Lösungen
| HTTP-Code | Status | Wahrscheinliche Ursache | Empfohlene Aktion in Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | Der Anforderungskörper ist fehlerhaft formatiert (z. B. ein Parameter mit einem falschen Typ, ein fehlendes Pflichtfeld). | Überprüfen Sie, ob die Parameter in GenerateContentConfig und das Format von contents korrekt sind. Stellen Sie sicher, dass das Modell mit den angeforderten Merkmalen kompatibel ist. |
| 403 | PERMISSION_DENIED | Der API-Schlüssel ist falsch, Sie verfügen nicht über die erforderlichen Berechtigungen oder versuchen auf eine eingeschränkte Ressource zuzugreifen (z. B. ein feingetuntes Modell). | Stellen Sie sicher, dass der API-Schlüssel (oder die ADC-Authentifizierung für Vertex) korrekt konfiguriert ist und über die erforderlichen Berechtigungen verfügt. |
| 429 | RESOURCE_EXHAUSTED | Das API-Rate-Limit (Anfragen pro Minute) wurde überschritten. | Implementieren Sie ein Exponential Backoff in Ihrer Retry-Logik. Erwägen Sie, eine Erhöhung des Kontingents zu beantragen, falls dies für Ihre Anwendung erforderlich ist. |
| 500 | INTERNAL | Ein unerwarteter Fehler auf Google-Seite ist aufgetreten. Dies kann manchmal durch einen sehr langen Eingabekontext verursacht werden. | Verringern Sie die Länge des Prompts. Versuchen Sie es nach einer kurzen Wartezeit erneut. Wenn das Problem weiterhin besteht, ziehen Sie in Erwägung, vorübergehend zu einem anderen Modell zu wechseln. |
| 503 | UNAVAILABLE | Der Dienst ist vorübergehend überlastet oder nicht verfügbar. | Versuchen Sie die Anfrage nach einer kurzen Wartezeit unter Verwendung einer Exponential-Backoff-Strategie erneut. Wenn das Problem weiterhin besteht, melden Sie das Problem. |
4.2. Verwaltung der Inhalts-Sicherheit
Sección titulada «4.2. Gestión de la Seguridad del Contenido»Die Gemini API enthält integrierte Sicherheitsfunktionen, um potenziell schädliche Inhalte zu filtern. Diese Funktionen sind darauf ausgelegt, Entwickler dabei zu unterstützen, sicherere und verantwortungsbewusstere Anwendungen zu erstellen.
Die API klassifiziert Inhalte in vier Hauptkategorien von Schäden:
- Belästigung (
HARM_CATEGORY_HARASSMENT) - Hassrede (
HARM_CATEGORY_HATE_SPEECH) - Sexuell explizite Inhalte (
HARM_CATEGORY_SEXUALLY_EXPLICIT) - Gefährliche Inhalte (
HARM_CATEGORY_DANGEROUS_CONTENT)
Für jede Kategorie weist das Modell eine Wahrscheinlichkeit zu, mit der der Inhalt unsicher ist. Standardmäßig blockiert die API Prompts und Antworten, die in einer dieser Kategorien eine Wahrscheinlichkeit von MEDIUM oder HIGH aufweisen, unsicher zu sein.
Entwickler können diese Standardkonfiguration auf Anfrage überschreiben, indem sie eine Liste von Objekten SafetySetting an den Parameter safety_settings übergeben. Dies ermöglicht eine granulare Kontrolle über den Blockierschwellenwert für jede Kategorie.
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}")Wenn eine Antwort leer erscheint oder ein Fehler auftritt, ist es entscheidend, das Sicherheits-Feedback zu untersuchen. Das Antwortobjekt enthält prompt_feedback (für den Eingabe-Prompt) und candidates.safety_ratings (für die generierte Antwort). Diese Attribute zeigen an, ob der Inhalt blockiert wurde und warum, was für die Fehlerbehebung unerlässlich ist.
Die folgende Tabelle erläutert die Bedeutung der verschiedenen Blockierschwellenwerte.
Tabelle 4: Sicherheitskonfigurationsschwellenwerte
| API-Konstante | Konfiguration in Google AI Studio | Beschreibung |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | Der Schwellenwert ist nicht spezifiziert; es wird der Standard-Schwellenwert des Modells verwendet. |
BLOCK_NONE | Keine blockieren | Inhalte niemals blockieren, unabhängig von der Wahrscheinlichkeit, dass sie unsicher sind. Muss mit äußerster Vorsicht verwendet werden. |
BLOCK_ONLY_HIGH | Wenige blockieren | Nur blockieren, wenn die Wahrscheinlichkeit für unsichere Inhalte HIGH beträgt. |
BLOCK_MEDIUM_AND_ABOVE | Einige blockieren | (Standard für die meisten Modelle) Blockieren, wenn die Wahrscheinlichkeit für unsichere Inhalte MEDIUM oder HIGH beträgt. |
BLOCK_LOW_AND_ABOVE | Die meisten blockieren | Blockieren, wenn die Wahrscheinlichkeit für unsicheren Inhalt LOW, MEDIUM oder HIGH beträgt. |
4.3. Modellverwaltung
Sección titulada «4.3. Gestión de Modelos»Das SDK bietet eine programmatische Möglichkeit, die verfügbaren Modelle und deren Funktionen zu entdecken. Dies ist nützlich, um Anwendungen zu entwickeln, die sich an verschiedene Modelle anpassen können, oder um die Fähigkeiten eines Modells vor dessen Verwendung zu überprüfen.
Die Methode client.models.list() gibt einen Iterator über die verfügbaren Modelle zurück.
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)Diese Funktionalität kann auch verwendet werden, um gezielt die vom Benutzer feinabgestimmten (fine-tuned) Modelle aufzulisten, indem query_base=False in der Konfiguration der Listenanfrage gesetzt wird. Dies ermöglicht es Anwendungen, benutzerdefinierte Modelle dynamisch zu entdecken und zu nutzen.
Teil 5: Umgebungsvalidierung und technische Checkliste
Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»Um die Bereitstellung von Integrationen auf Basis des vereinheitlichten google-genai SDK im Portelcore-Tenant abzuschließen, validieren Sie die Einhaltung der folgenden technischen Meilensteine:
- Ich habe alle Skripte des Tenants von der veralteten Bibliothek
google-generativeaiauf den neuen Standardgoogle-genaimigriert. ✓ - API-Schlüssel werden ausschließlich über die Umgebungsvariable
GOOGLE_API_KEYverwaltet oder im Google Cloud Secret Manager verschleiert, anstatt im Klartext geschrieben zu werden. ✓ - Es wird eine robuste Ausnahmebehandlung (
google.api_core.exceptions) implementiert, um 429-Statuscodes (Resource Exhausted) mit Exponential-Backoff-Wiederholungsrichtlinien abzufangen. ✓ - Die Temperatur und die Sicherheitsschwellenwerte (
safety_settings) sind formal entsprechend dem Anwendungsfall der Domäneportelcore.comparametrisiert. ✓

