Ir al contenido
Destacado

Python Google GenAI SDK voor de Gemini API

Referentiegids en geavanceerde configuratie voor de nieuwe verenigde google-genai SDK van de Gemini API in Portelcore.

Technische moeilijkheidsgraad:
0lecturas

Deel 1: Fundamentele Concepten en Initiële Configuratie

Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»

Deze sectie schept de context voor de nieuwe SDK, pakt de belangrijkste verwarring van de gebruiker aan over de bibliotheekwissel, en biedt een robuuste handleiding om correct te beginnen, inclusief de installatie en de twee kritieke authenticatieroutes.

1.1. De Nieuwe Standaard: Migreren van google-generativeai naar google-genai

Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»

Het ontwikkel-ecosysteem voor de generatieve AI-modellen van Google is geëvolueerd. De bibliotheek google-genai is nu de officiële, verenigde en aanbevolen Python SDK voor interactie met de Gemini API en andere generatieve AI-modellen van Google. Deze bereikte de General Availability (GA) in mei 2025 en vervangt de verouderde bibliotheek, google-generativeai.

De vorige bibliotheek, google-generativeai, is gemarkeerd als “Inactief” in de Python Package Index (PyPI) en bevindt zich op een pad naar veroudering. De ondersteuning voor dit pakket, inclusief kritieke bugfixes, zal eind september 2025 stoppen, hoewel sommige bronnen een iets eerdere einddatum voor de ondersteuning aangeven, namelijk 31 augustus 2025. Ontwikkelaars wordt geadviseerd de vroegste datum aan te houden om een naadloze overgang te garanderen.

Deze wijziging is niet simpelweg een naamswijziging, maar een strategische unificatie gedreven door feedback van ontwikkelaars. Het doel was om één enkele SDK te creëren die de toegang tot het volledige scala aan Google generatieve AI-modellen (Gemini, Veo, Imagen, enz.) vereenvoudigt en een duidelijkere en meer coherente ontwikkelingsroute biedt. Een van de belangrijkste ontwerpbeslissingen van de nieuwe SDK google-genai is dat deze fungeert als een enkele interface voor twee verschillende backend-services: de gemakkelijk toegankelijke Gemini developer API en het enterprise-waardige Vertex AI-platform.

Deze verenigde architectuur biedt een vloeiende toegangsweg voor ontwikkelaars. Ze kunnen snel aan de slag gaan, vaak met een gratis niveau, door gebruik te maken van een API-sleutel voor de Gemini developer API. Naarmate hun applicaties volwassen worden en meer schaalbaarheid, governance en integratie met andere Google Cloud-services vereisen, kunnen ze overstappen naar de Vertex AI-backend met minimale wijzigingen in de code, voornamelijk in de client-initialisatie. De SDK google-genai fungeert als een brug, waardoor de drempel wordt verlaagd terwijl er een duidelijk pad naar productie in Google Cloud wordt geboden. Daarom wordt alle gebruikers van de legacy-bibliotheek dringend verzocht te migreren om toegang te garanderen tot de nieuwste functies (zoals Live API en Veo), prestatieverbeteringen en voortdurende ondersteuning.

Voordat u de SDK installeert, is het een best practice om een Python-virtuele omgeving in te stellen. Dit isoleert de projectafhankelijkheden, waardoor conflicten met andere projecten of systeempakketten worden voorkomen.

Om een virtuele omgeving te maken en te activeren met behulp van venv:

Ventana de terminal
# En macOS/Linux
python3 -m venv gemini-env
source gemini-env/bin/activate
# En Windows
py -m venv gemini-env
.\gemini-env\Scripts\activate

Zodra de virtuele omgeving actief is, kan de nieuwste versie van de Google Gen AI SDK worden geïnstalleerd met behulp van pip. Het gebruik van de indicator --upgrade zorgt ervoor dat de nieuwste versie wordt verkregen.

Ventana de terminal
pip install --upgrade google-genai

Het is essentieel om rekening te houden met de Python-versievereisten. De SDK google-genai vereist Python 3.9 of hoger. Het gebruik van een niet-ondersteunde versie kan onverwachte fouten veroorzaken tijdens de installatie of tijdens de runtime.

Voor applicaties die een hoge asynchrone prestatie vereisen, biedt de SDK de mogelijkheid om aiohttp te gebruiken als HTTP-transport-backend in plaats van de standaard httpx. Dit kan worden geïnstalleerd als een extra onderdeel:

Ventana de terminal
pip install google-genai[aiohttp]

Authenticatie is de meest kritieke configuratiestap en de methode verschilt afhankelijk van de backend-service die u wilt gebruiken: de Gemini Developer API of de Gemini API in Vertex AI.

1.3.1. De Gemini Developer API-route (aanbevolen voor prototypes en het gratis niveau)

Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»

Dit is de snelste manier om te beginnen met bouwen met Gemini. Hiervoor is een API-sleutel nodig die u gratis kunt verkrijgen via Google AI Studio.

Het proces om een API-sleutel te verkrijgen is als volgt:

  1. Navigeer naar (https://ai.google.dev/) en log in met een Google-account.
  2. Klik op "Get API key" (API-sleutel ophalen).
  3. Kies ervoor om de API-sleutel aan te maken in een nieuw of bestaand Google Cloud-project.
  4. De API-sleutel wordt automatisch gegenereerd.

API-sleutels zijn gevoelige inloggegevens en moeten als wachtwoorden worden behandeld. Ze moeten veilig worden opgeslagen en mogen nooit worden blootgesteld in client-side code of worden gecommit in publieke versiebeheersystemen.

De veiligste en aanbevolen methode om de sleutel te gebruiken is om deze als omgevingsvariabele te configureren. De SDK is ontworpen om omgevingsvariabelen GOOGLE_API_KEY of GEMINI_API_KEY automatisch te detecteren en te gebruiken. Als beide zijn geconfigureerd, heeft GOOGLE_API_KEY prioriteit.

Om de omgevingsvariabele te configureren:

  • Op 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
  • In Windows: Gebruik de grafische interface van “Omgevingsvariabelen” in de systeeminstellingen om een nieuwe gebruikers- of systeemvariabele genaamd GOOGLE_API_KEY toe te voegen met uw sleutel als waarde.

1.3.2. De Vertex AI-route (Aanbevolen voor productie en integratie met Google Cloud)

Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»

Voor applicaties op productieniveau die de zakelijke functies van Google Cloud vereisen, wordt het gebruik van de Gemini API via Vertex AI aanbevolen. Deze aanpak vereist een Google Cloud-project met ingeschakelde facturering.

De initiële configuratiestappen zijn:

  1. Selecteer of maak een Google Cloud-project.
  2. Zorg ervoor dat de facturering is ingeschakeld voor het project.
  3. Schakel de Vertex AI API (aiplatform.googleapis.com) in voor het project.

Authenticatie voor Vertex AI kan op twee manieren worden uitgevoerd:

  • Standaardtoepassingsreferenties (ADC) (Aanbevolen voor productie): Dit is de voorkeursmethode voor de meeste productiescenario's. ADC vindt automatisch de referenties op basis van de omgeving. In een lokale ontwikkelomgeving kan dit worden geconfigureerd door een commando uit te voeren in de gcloud CLI:

    Ventana de terminal
    gcloud auth application-default login

    Wanneer het wordt uitgevoerd in een Google Cloud-omgeving (bijvoorbeeld Cloud Run, Google Kubernetes Engine, Cloud Functions), gebruikt ADC automatisch het serviceaccount dat gekoppeld is aan die resource, waardoor het beheer van sleutels overbodig wordt.

  • API-sleutels (voor testen in Vertex): Het is mogelijk om een API-sleutel te gebruiken om te authenticeren bij het Vertex AI-endpoint, maar het proces is complexer dan bij de ontwikkelaars-API. Dit vereist machtigingen op organisatieniveau om het aanmaken van API-sleutels voor serviceaccounts in te schakelen, een serviceaccount aan te maken met een passende rol (bijvoorbeeld, Vertex AI User), en vervolgens een API-sleutel aan te maken die is beperkt tot dat serviceaccount. Vanwege de complexiteit wordt deze methode doorgaans gebruikt voor specifieke testscenario's in plaats van algemene applicatieontwikkeling.

1.4. Clientinitialisatie: Verbinding maken met het Model

Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»

Zodra de authenticatie is geconfigureerd, is de volgende stap het instantiëren van het object genai.Client. De verenigde SDK vereenvoudigt dit door één enkele client te bieden die geconfigureerd kan worden voor elk van de twee backends.

Hieronder volgen de vier belangrijkste scenario's voor de initialisatie van de client.

  • Scenario 1: Gemini Developer API (Expliciete sleutel) Deze methode is handig voor notebooks of snelle scripts waarbij geen omgevingsvariabelen geconfigureerd willen worden. De API-sleutel wordt rechtstreeks als argument meegegeven.

    from google import genai
    client = genai.Client(api_key="SU_CLAVE_DE_API_AQUI")
  • Scenario 2: Gemini Developer API (Omgevingsvariabele) Dit is de schoonste en aanbevolen aanpak voor applicatiecode, aangezien het de credentials loskoppelt van de code. De client vindt en gebruikt automatisch de omgevingsvariabele GOOGLE_API_KEY.

    # Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configurada
    from google import genai
    client = genai.Client()
  • Scenario 3: Vertex AI API (Expliciete parameters) Om verbinding te maken met Vertex AI, wordt de flag vertexai ingesteld op True en worden de project-ID en locatie opgegeven. Deze methode gebruikt automatisch Application Default Credentials (ADC) voor authenticatie.

    from google import genai
    client = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1")
  • Scenario 4: Vertex AI API (Omgevingsvariabelen) Als alternatief voor Vertex AI kan de configuratie worden geëxternaliseerd naar omgevingsvariabelen. De client detecteert deze variabelen en wordt geconfigureerd om de Vertex AI-backend te gebruiken.

    Ventana de terminal
    export GOOGLE_GENAI_USE_VERTEXAI=true
    export GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'
    export GOOGLE_CLOUD_LOCATION='us-central1'
    # El cliente se configurará automáticamente para Vertex AI
    from google import genai
    client = genai.Client()

De volgende tabel vat deze methoden samen voor een snelle referentie.

Tabel 1: Snelle referentie voor client-initialisatie

Use CasePython-codeVereiste omgevingsvariabelenNotities
Developer API met expliciete sleutelclient = genai.Client(api_key="SU_CLAVE...")GeenHandig voor notities en snelle tests. Vermijden in productiecode.
Developer API met omgevingsvariabeleclient = genai.Client()GOOGLE_API_KEY of GEMINI_API_KEYVoorkeursmethode voor schone en veilige applicatiecode.
Vertex AI met expliciete parametersclient = genai.Client(vertexai=True, project="...", location="...")Geen (gebruikt ADC)Expliciete methode om naar Vertex AI te verwijzen. Vereist ADC-authenticatie (gcloud auth...).
Vertex AI met omgevingsvariabelenclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONConfigureert de client voor Vertex AI zonder parameters in de code. Vereist ADC-authenticatie.

Deel 2: Belangrijkste mogelijkheden: Tekst en Chat

Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»

Dit deel duikt in de meest voorkomende use cases: het genereren van tekst en het bouwen van conversatie-agenten. Het details de belangrijkste methoden en objecten die betrokken zijn.

2.1. Content genereren: De methode generate_content

Sección titulada «2.1. Generando Contenido: El Método generate_content»

De belangrijkste methode voor alle single-turn generatietaken is client.models.generate_content(). Deze veelzijdige methode vormt de basis voor interactie met de Gemini-modellen.

Een basisgebruik houdt in dat u een eenvoudige tekstreeks opgeeft zoals contents en de naam van het te gebruiken model specificeert, zoals gemini-2.5-flash.

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado como se describió anteriormente
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explica brevemente por qué el cielo es azul."
)
print(response.text)

Hoewel het doorgeven van een eenvoudige string handig is, is het essentieel om de onderliggende datastructuur te begrijpen die de SDK gebruikt. Intern zet de SDK alle invoer om in een gestandaardiseerde structuur die bestaat uit types.Content en types.Part objecten. Het begrijpen van deze structuur is de sleutel tot het ontsluiten van geavanceerde SDK-functionaliteiten, zoals multimodale prompts en functieaanroepen.

  • types.Content: Vertegenwoordigt een enkel bericht of een beurt in een gesprek. Het heeft twee hoofdeigenschappen: een role (meestal 'user' voor de invoer of 'model' voor de uitvoer) en een lijst met parts.
  • types.Part: Vertegenwoordigt een datapunt binnen een Content object. Een deel kan tekst, afbeeldingsgegevens, een bestandverwijzing, een functieaanroep, etc. zijn.

De SDK verwerkt op intelligente wijze verschillende soorten invoer voor het argument contents en zet deze om naar het juiste Content/Part formaat:

  • Een enkele string: contents='¿Por qué el cielo es azul?' wordt omgezet in een UserContent met één enkele Part van tekst.
  • Een lijst met strings: contents=['Pregunta 1', 'Pregunta 2'] wordt omgezet in één enkele UserContent die twee Part van tekst bevat.
  • Een types.Part object: Maakt meer gedetailleerde controle mogelijk, zoals het specificeren van afbeeldingsgegevens.
  • Een volledig gevormd types.Content object: Biedt maximale controle over de rol en de inhoud van het bericht.

Om toegang te krijgen tot het gegenereerde antwoord is de handige response.text accessor de eenvoudigste methode. Het is echter belangrijk om te weten dat deze accessor alleen werkt voor eenvoudige antwoorden die bestaan uit een enkel tekstgedeelte. Als het antwoord wordt geblokkeerd door veiligheidsfilters, meerdere kandidaten bevat of niet-tekstuele datatypen bevat, zal toegang tot response.text een fout veroorzaken. De meest robuuste en veilige methode voor productie is om rechtstreeks toegang te krijgen tot de kandidaat en de bijbehorende delen:

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}")

Voor interactieve applicaties zoals chatbots verbetert het streamen van het modelantwoord de gebruikerservaring drastisch. In plaats van te wachten tot het volledige antwoord is gegenereerd, worden tekstfragmenten weergegeven zodra ze binnenkomen, wat zorgt voor onmiddellijke feedback.

Deze functionaliteit wordt bereikt met de methode generate_content_stream(). Deze methode geeft een iterator terug die fragmenten van het antwoord produceert zodra deze door het model worden gegenereerd.

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
response_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 final

2.3. Conversational AI Meester worden: De Chatinterface

Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»

De SDK biedt twee primaire mechanismen voor het beheren van gesprekken met meerdere beurten. Een benadering is het handmatig beheren van de gesprekshistorie door een lijst met Content objecten te maken die elke beurt vertegenwoordigen en deze bij elke aanroep naar generate_content() te sturen. Hoewel dit flexibel is, kan deze methode omslachtig zijn.

De aanbevolen en meest handige aanpak voor het maken van chatbots is het gebruik van de stateful chatinterface die wordt aangeboden door client.chats. Dit object op hoog niveau abstraheert het beheer van de geschiedenis, wat de applicatiecode aanzienlijk vereenvoudigt. Dit is een bewuste ontwerpkeuze in de SDK: het bieden van een hoogwaardige stateful abstractie (client.chats) voor een veelvoorkomende use case (chat), wat de ontwikkeling enorm vereenvoudigt in vergelijking met de stateless methode op laag niveau generate_content.

De workflow voor het gebruik van de chatinterface is als volgt:

  1. Een chatsessie initialiseren: client.chats.create() wordt gebruikt om een nieuw gesprek te starten. Je kunt het model specificeren en optioneel een initiële geschiedenis verstrekken om het gesprek te contextualiseren.
  2. Berichten verzenden: De methode chat.send_message() wordt gebruikt om het volgende bericht van de gebruiker te verzenden. De SDK beheert automatisch de status door het bericht van de gebruiker en het daaropvolgende antwoord van het model aan de gesprekshistorie toe te voegen.
  3. Toegang tot de geschiedenis: Op elk moment kan de volledige gesprekshistorie worden opgehaald met behulp van chat.get_history().

Hieronder volgt een volledig voorbeeld van een gesprek met meerdere beurten:

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Crear una nueva sesión de chat
chat_session = client.chats.create(
model="gemini-2.0-flash"
)
# 2. Enviar el primer mensaje
print("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 seguimiento
print("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ón
print("--- 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}")

Om het gedrag van het model te verfijnen, accepteert de methode generate_content een parameter config, die een object types.GenerateContentConfig aanneemt. Dit object stelt ontwikkelaars in staat om verschillende aspecten van het generatieproces te controleren.

Een van de meest nuttige configuraties is system_instruction. Een systeeminstructie biedt een richtlijn op hoog niveau of stelt een persoonlijkheid vast voor het model die gedurende het hele gesprek behouden blijft. Het model kan bijvoorbeeld worden geïnstrueerd om als een specifiek personage op te treden of om bepaalde regels in zijn antwoorden te volgen.

from google.genai import types
# Asumiendo que 'client' ha sido inicializado
response = 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)

Naast systeeminstructies zijn er verschillende andere parameters die kunnen worden aangepast om de creativiteit en de structuur van de output van het model te controleren. De volgende tabel beschrijft de belangrijkste.

Tabel 2: Belangrijkste parameters voor generatieconfiguratie

ParameterBeschrijvingBereikEffect op de output
temperatureControleert de willekeur van de tokenselectie.0.0 - 1.0Lagere waarden (bijv. 0.2) maken de output deterministischer en minder creatief. Hogere waarden (bijv. 0.9) verhogen de willekeur en creativiteit.
top_pNucleus sampling. Houdt rekening met de kleinste set tokens waarvan de cumulatieve waarschijnlijkheid groter is dan top_p.0.0 - 1.0Een waarde als 0.95 betekent dat alleen de tokens worden overwogen die de bovenste 95% van de waarschijnlijkheidsmassa vormen. Dit helpt om zeer onwaarschijnlijke tokens te vermijden.
top_kOverweeg alleen de k meest waarschijnlijke tokens bij elke stap van de generatie.IntegerEen top_k van 1 is een greedy decoding. Een waarde zoals 40 beperkt de selectie tot de 40 meest waarschijnlijke tokens.
candidate_countHet aantal kandidaat-antwoorden om te genereren.Integer (bijv. 1-8)Genereer meerdere mogelijke antwoorden voor dezelfde prompt. Handig om opties aan de gebruiker te bieden.
max_output_tokensHet maximale aantal tokens dat in het antwoord kan worden gegenereerd.IntegerBeperkt de lengte van de output. Essentieel voor het beheersen van kosten en latentie.
stop_sequencesEen lijst met strings die de output stoppen wanneer ze worden gegenereerd.Lijst met stringsHandig om de generatie op een specifiek punt te stoppen, zoals een einde van een zin of een specifiek formaat.
seedWillekeurige seed voor de generatie.IntegerHet verstrekken van een seed maakt de output deterministisch en reproduceerbaar (zolang temperature niet 0 is).

Deel 3: Geavanceerde interacties: Multimodaliteit en functieaanroepen

Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»

Dit deel laat de ware kracht van de Gemini-modellen zien door uit te leggen hoe je met niet-tekstuele input werkt en het model verbindt met externe tools.

Een van de kenmerkende eigenschappen van de Gemini-modelfamilie is de inherente multimodale capaciteit. Dit betekent dat ze verschillende soorten gegevens, of 'modaliteiten', zoals tekst, afbeeldingen, audio en video, kunnen verwerken en analyseren binnen een enkele prompt.

Deze capaciteit wordt mogelijk gemaakt door het argument contents op te bouwen als een lijst die meerdere objecten Part bevat, waarbij elk Part een ander datatype kan bevatten. Bijvoorbeeld, één enkele aanvraag kan een afbeelding en een tekstvraag over die afbeelding bevatten.

De SDK biedt twee strategisch verschillende methoden voor het afhandelen van afbeeldingsgegevens. De keuze tussen deze twee hangt af van de specifieke vereisten van de use case, zoals bestandsgrootte en herbruikbaarheid.

Deze dualiteit van methoden is geen redundantie, maar een bewuste ontwerpkeuze die verschillende operationele behoeften adresseert. De inline-methode is eenvoudig en uitstekend voor eenmalige analyses en gebruiksgemak tijdens de ontwikkeling. De Files API vereist weliswaar een extra uploadstap, maar is essentieel voor productieomgevingen waar efficiëntie, schaalbaarheid en het afhandelen van grote bestanden cruciaal zijn.

Methode 1: Inline afbeeldingsgegevens (Inline)

Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»

Deze methode is ideaal voor kleinere afbeeldingsbestanden (de totale aanvraag, inclusief prompts en bytes, moet minder dan 20 MB zijn) en voor eenvoud tijdens de ontwikkeling. De afbeeldingsgegevens worden rechtstreeks meegegeven in de aanroep van generate_content.

  • Vanuit een lokaal bestand: Het afbeeldingsbestand wordt in binaire modus ('rb') ingelezen en doorgegeven aan types.Part.from_bytes(), waarbij het juiste MIME-type wordt opgegeven.

    import google.genai as genai
    from google.genai import types
    # Asumiendo que 'client' ha sido inicializado
    with 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 solicitud
    response = client.models.generate_content(
    model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-vision
    contents=[prompt_part, image_part]
    )
    print(response.text)
  • Vanuit een URL: Er kan een bibliotheek zoals requests worden gebruikt om de afbeeldingsbytes van een URL op te halen en deze vervolgens op dezelfde manier door te geven.

Deze methode wordt aanbevolen voor grote afbeeldingsbestanden (groter dan 20 MB) of voor scenario's waarin hetzelfde bestand opnieuw wordt gebruikt in meerdere prompt-aanvragen. Het gebruik van de Files API voorkomt dat dezelfde bytes bij elke aanroep opnieuw moeten worden geüpload.

De workflow bestaat uit twee stappen:

  1. Uploaden: client.files.upload() wordt gebruikt om het bestand naar de servers van Google te uploaden. Deze methode geeft een bestandsobject terug dat als referentie dient.
  2. Prompten: Het teruggegeven bestandsobject wordt rechtstreeks in de lijst contents van een aanroep naar generate_content doorgegeven. De SDK regelt het oplossen van de referentie naar het geüploade bestand.
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar el archivo usando la API de Archivos
print("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ón
prompt = "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 uso
client.files.delete(name=sample_file.name)
print(f"Archivo eliminado: {sample_file.name}")

Bestanden die via de Files API zijn geüpload, worden tijdelijk 48 uur bewaard voordat ze automatisch worden verwijderd. De API biedt ook methoden om deze bestanden te beheren, zoals get(), list() en delete().

De concepten voor het afhandelen van afbeeldingen zijn rechtstreeks toepasbaar op andere modaliteiten zoals audio en video. Omdat deze bestanden meestal groot zijn, is de Files API de primaire methode om ermee te werken.

Het proces is identiek aan dat van de grote afbeeldingen:

  1. Gebruik client.files.upload() om het audiobestand (bijv. MP3, WAV) of videobestand (bijv. MP4) te uploaden.
  2. Voeg het geretourneerde bestandsobject toe aan de prompt voor generate_content.

Het volgende voorbeeld laat zien hoe u een audiobestand uploadt en het model vraagt om het te transcriberen.

import google.genai as genai
import time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audio
print("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é ACTIVO
while 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ón
prompt = "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. Function Calling: De capaciteiten van het model uitbreiden

Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»

Function calling, ook wel bekend als tool use, is een krachtige techniek die het taalmodel in staat stelt om met externe systemen te communiceren. Het stelt het model in staat om vragen te beantwoorden of acties uit te voeren die verder gaan dan de inherente kennis, zoals het ophalen van realtime gegevens via een API, het raadplegen van een database of het aansturen van een apparaat.

De algemene workflow is als volgt:

  1. Tools definiëren: Er wordt een set tools (Python-functies) gedefinieerd die het model kan aanroepen. Deze definitie bevat de naam van de functie, een beschrijving van wat deze doet en het schema van de parameters.
  2. Tools doorgeven aan het model: De gedefinieerde lijst met tools wordt naar het model doorgegeven in de aanroep naar generate_content.
  3. Het model besluit aan te roepen: Het model analyseert de prompt van de gebruiker. Als het vaststelt dat een van de verstrekte tools kan helpen bij het beantwoorden, bevat de respons een Part object van het type function_call in plaats van tekst te genereren. Dit object specificeert de naam van de functie die moet worden aangeroepen en de argumenten waarmee deze moet worden aangeroepen.
  4. De functie uitvoeren: De applicatiecode detecteert deze function_call, voert de bijbehorende Python-functie uit met de verstrekte argumenten en verkrijgt een resultaat.
  5. Het resultaat teruggeven aan het model: Er wordt een tweede aanroep naar generate_content gedaan, waarbij de gesprekshistorie samen met het resultaat van de functie-uitvoering (verpakt in een types.Part.from_function_response()) wordt meegegeven.
  6. Eindantwoord: Het model gebruikt het resultaat van de functie om een definitief antwoord in natuurlijke taal te genereren voor de gebruiker.

Hoewel de onderzoeksfragmenten geen voorbeeldcode voor een end-to-end functie-aanroep bieden, vormt de structuur van de Part objecten voor function_call en function_response de basis voor het implementeren van dit geavanceerde patroon.


Deel 4: Productievoorbereiding: Foutafhandeling, Beveiliging en Beheer

Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»

Dit laatste deel biedt de cruciale informatie die nodig is om robuuste, betrouwbare en verantwoorde applicaties te bouwen.

In een productieomgeving is robuuste foutafhandeling niet onderhandelbaar. API-aanroepen kunnen mislukken om verschillende redenen, zoals ongeldige inloggegevens, netwerkproblemen, het overschrijden van quota of ongeldige invoer.

De SDK maakt gebruik van het standaard Python-exceptionsysteem. De meeste API-gerelateerde fouten kunnen worden opgevangen met een try...except blok dat zoekt naar exceptions van het module google.api_core.exceptions of, indien beschikbaar, een specifiekere klasse zoals errors.APIError.

from google.api_core import exceptions as core_exceptions
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
try:
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}")

Bij het opvangen van een uitzondering bevat het uitzonderingsobject vaak waardevolle informatie voor logging en debugging, zoals een statuscode en een beschrijvende melding.

Het is belangrijk om te overwegen dat foutmeldingen, hoewel ze nuttig zijn voor ontwikkelaars, een tweesnijdend zwaard kunnen zijn. Ze kunnen details over interne implementaties lekken die kunnen worden misbruikt bij aanvallen door kwaadwillenden. Bijvoorbeeld: een analyse van beveiligingsvalidatiefouten kan interne drempelwaarden of verdedigingsmechanismen onthullen, wat een kwaadwillende actor helpt om beveiligingen te omzeilen. Daarom moeten fouten weliswaar uitgebreid in de backend worden gelogd, maar moet de informatie die aan eindgebruikers wordt getoond zorgvuldig worden gecontroleerd. Vaak is het veiliger om een generieke melding weer te geven zoals “Er is een fout opgetreden bij het verwerken van uw aanvraag” in plaats van de ongefilterde foutmelding van de API te tonen.

De volgende tabel vat de meest voorkomende API-foutcodes samen en hoe deze op te lossen.

Tabel 3: Veelvoorkomende API-foutcodes en oplossingen

HTTP-codeStatusWaarschijnlijke oorzaakAanbevolen actie in Python
400INVALID_ARGUMENTDe verzoekbody is ongeldig geformatteerd (bijv. een parameter met een onjuist type, een ontbrekend verplicht veld).Controleer of de parameters in GenerateContentConfig en het formaat van contents correct zijn. Zorg ervoor dat het model compatibel is met de aangevraagde kenmerken.
403PERMISSION_DENIEDDe API-sleutel is onjuist, u heeft niet de benodigde machtigingen of u probeert toegang te krijgen tot een beperkte bron (bijv. een aangepast model).Controleer of de API-sleutel (of de ADC-authenticatie voor Vertex) correct is geconfigureerd en de benodigde machtigingen heeft.
429RESOURCE_EXHAUSTEDDe API-rate limit (verzoeken per minuut) is overschreden.Implementeer exponential backoff in uw retry-logica. Overweeg een quotumverhoging aan te vragen als dit nodig is voor uw applicatie.
500INTERNALEr is een onverwachte fout opgetreden aan de zijde van Google. Dit kan soms worden veroorzaakt door een zeer lange inputcontext.Verklein de lengte van de prompt. Probeer de aanvraag opnieuw na een korte wachttijd. Als het probleem aanhoudt, overweeg dan om tijdelijk over te stappen naar een ander model.
503UNAVAILABLEDe service is tijdelijk overbelast of niet beschikbaar.Probeer de aanvraag opnieuw na een korte wachttijd met behulp van een exponential backoff-strategie. Als het probleem aanhoudt, rapporteer dan het probleem.

De Gemini API bevat ingebouwde beveiligingsfuncties om potentieel schadelijke inhoud te filteren. Deze functies zijn ontworpen om ontwikkelaars te helpen veiligere en verantwoordere applicaties te bouwen.

De API classificeert inhoud in vier hoofdcategorieën van schade:

  • Pesten (HARM_CATEGORY_HARASSMENT)
  • Haatzaaiende taal (HARM_CATEGORY_HATE_SPEECH)
  • Seksueel expliciete inhoud (HARM_CATEGORY_SEXUALLY_EXPLICIT)
  • Gevaarlijke inhoud (HARM_CATEGORY_DANGEROUS_CONTENT)

Voor elke categorie wijst het model een waarschijnlijkheid toe dat de inhoud onveilig is. Standaard blokkeert de API prompts en antwoorden die een waarschijnlijkheid van MEDIUM of HIGH hebben om onveilig te zijn in een van deze categorieën.

Ontwikkelaars kunnen deze standaardinstelling per aanvraag overschrijven door een lijst met SafetySetting objecten door te geven aan de parameter safety_settings. Dit maakt een nauwkeurige controle mogelijk over de blokkendrempel voor elke categorie.

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}")

Wanneer een antwoord leeg lijkt of er een fout optreedt, is het cruciaal om de beveiligingsfeedback te inspecteren. Het respons-object bevat prompt_feedback (voor de invoerprompt) en candidates.safety_ratings (voor het gegenereerde antwoord). Deze attributen laten zien of de inhoud is geblokkeerd en waarom, wat essentieel is voor het debuggen.

De volgende tabel verduidelijkt de betekenis van de verschillende blokkendrempels.

Tabel 4: Drempels voor beveiligingsinstellingen

API-constanteConfiguratie in Google AI StudioBeschrijving
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/ADe drempelwaarde is niet gespecificeerd; de standaard drempelwaarde van het model wordt gebruikt.
BLOCK_NONEBlock none (Geen blokkering)Blokkeer nooit inhoud, ongeacht de waarschijnlijkheid dat het onveilig is. Moet met uiterste voorzichtigheid worden gebruikt.
BLOCK_ONLY_HIGHBlock few (Weinig blokkeren)Alleen blokkeren wanneer de waarschijnlijkheid van onveilige inhoud HIGH is.
BLOCK_MEDIUM_AND_ABOVEBlock some (Sommige blokkeren)(Standaard voor de meeste modellen) Blokkeren wanneer de waarschijnlijkheid van onveilige inhoud MEDIUM of HIGH is.
BLOCK_LOW_AND_ABOVEBlokkeer de meeste (Blokkeer de meeste)Blokkeren wanneer de waarschijnlijkheid van onveilige inhoud LOW, MEDIUM of HIGH is.

De SDK biedt een programmeerbare manier om de beschikbare modellen en hun mogelijkheden te ontdekken. Dit is nuttig voor het bouwen van applicaties die kunnen worden aangepast aan verschillende modellen of om de mogelijkheden van een model te controleren voordat het wordt gebruikt.

De methode client.models.list() geeft een iterator terug over de beschikbare modellen.

Python

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
print("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)

Deze functionaliteit kan ook worden gebruikt om specifiek de door de gebruiker fijn afgestelde (fine-tuned) modellen te lijsten door query_base=False in de configuratie van de lijstopvraag in te stellen. Dit stelt applicaties in staat om dynamisch aangepaste modellen te ontdekken en te gebruiken.


Deel 5: Omgevingsvalidatie en Technische Checklist

Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»

Om de provisioning van integraties op basis van de unificerende SDK google-genai in de Portelcore-tenant te voltooien, moet de naleving van de volgende technische mijlpalen worden gevalideerd:

  • Ik heb alle scripts van de tenant gemigreerd van de verouderde bibliotheek google-generativeai naar de nieuwe standaard google-genai. ✓
  • API-sleutels worden uitsluitend beheerd via de omgevingsvariabele GOOGLE_API_KEY of geobfusceerd in de Google Cloud Secret Manager in plaats van in platte tekst te worden geschreven. ✓
  • Er is een robuuste uitzonderingsafhandeling (google.api_core.exceptions) geïmplementeerd om statuscode 429 (Resource Exhausted) te vangen met exponential backoff-beleid. ✓
  • De temperatuur en de veiligheidsdrempels (safety_settings) zijn formeel geparametriseerd in overeenstemming met de domein-use case portelcore.com. ✓