Ir al contenido
Destacato

SDK Python Google GenAI per l'API Gemini

Guida di riferimento e configurazione avanzata per il nuovo SDK unificato google-genai dell'API Gemini in Portelcore.

Difficoltà tecnica:
0letture

Parte 1: Concetti Fondamentali e Configurazione Iniziale

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

Questa sezione stabilisce il contesto per il nuovo SDK, affrontando la principale confusione dell'utente riguardo al cambio di libreria, e fornisce una guida robusta per iniziare correttamente, coprendo l'installazione e le due modalità di autenticazione critiche.

1.1. Il Nuovo Standard: Migrazione da google-generativeai a google-genai

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

L'ecosistema di sviluppo per i modelli di IA generativa di Google è evoluto. La libreria google-genai è ora l'SDK Python ufficiale, unificato e raccomandato per interagire con l'API di Gemini e altri modelli di IA generativa di Google. Ha raggiunto la Disponibilità Generale (GA) nel maggio 2025 e sostituisce la libreria legacy, google-generativeai.

La libreria precedente, google-generativeai, è stata contrassegnata come “Inattiva” nel Python Package Index (PyPI) e si trova in un percorso di obsolescenza. Il supporto per questo pacchetto, incluse le correzioni di bug critici, cesserà alla fine di settembre 2025, sebbene alcune fonti indichino una data di fine supporto leggermente precedente, il 31 agosto 2025. Si raccomanda agli sviluppatori di fare riferimento alla data più anticipata per garantire una transizione senza intoppi.

Questo cambiamento non è semplicemente un cambio di nome, ma un'unificazione strategica guidata dai feedback degli sviluppatori. L'obiettivo era creare un unico SDK che semplificasse l'accesso a tutta la gamma di modelli di IA generativa di Google (Gemini, Veo, Imagen, ecc.) e offrisse un percorso di sviluppo più chiaro e coerente. Una delle decisioni di progettazione più significative del nuovo SDK google-genai è che funge da interfaccia unica per due diversi servizi di backend: l'API per sviluppatori di Gemini, di facile accesso, e la piattaforma Vertex AI, di livello enterprise.

Questa architettura unificata fornisce una rampa di accesso fluida per gli sviluppatori. Possono iniziare rapidamente, spesso con un livello gratuito, utilizzando una chiave API per l'API per sviluppatori di Gemini. Man mano che le loro applicazioni maturano e richiedono maggiore scalabilità, governance e integrazione con altri servizi di Google Cloud, possono passare al backend di Vertex AI con modifiche minime al codice, principalmente nell'inizializzazione del client. L'SDK google-genai funge da ponte, riducendo la barriera all'ingresso e fornendo al contempo un percorso chiaro verso la produzione su Google Cloud. Pertanto, si esorta tutti gli utenti della libreria legacy a migrare per garantire l'accesso alle ultime funzionalità (come Live API e Veo), miglioramenti delle prestazioni e supporto continuo.

Prima di installare l'SDK, è una pratica consigliata configurare un ambiente virtuale Python. Ciò isola le dipendenze del progetto, evitando conflitti con altri progetti o con i pacchetti di sistema.

Per creare e attivare un ambiente virtuale utilizzando 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

Una volta che l'ambiente virtuale è attivo, è possibile installare l'ultima versione del SDK di Google Gen AI utilizzando pip. L'uso del flag --upgrade assicura di ottenere la versione più recente.

Ventana de terminal
pip install --upgrade google-genai

È fondamentale tenere conto dei requisiti della versione di Python. L'SDK google-genai richiede Python 3.9 o superiore. L'uso di una versione non compatibile può causare errori imprevisti durante l'installazione o l'esecuzione.

Per le applicazioni che richiedono prestazioni asincrone elevate, l'SDK offre l'opzione di utilizzare aiohttp come backend di trasporto HTTP invece del predefinito httpx. Questo può essere installato come un extra:

Ventana de terminal
pip install google-genai[aiohttp]

1.3. Autenticazione: la chiave per l'API di Gemini

Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»

L'autenticazione è il passaggio di configurazione più critico e il metodo varia in base al servizio backend che si intende utilizzare: l'API per sviluppatori di Gemini o l'API di Gemini in Vertex AI.

1.3.1. La via dell'API per sviluppatori di Gemini (Consigliata per prototipi e livello gratuito)

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

Questo è il modo più veloce per iniziare a costruire con Gemini. Richiede una chiave API che può essere ottenuta gratuitamente da Google AI Studio.

Il processo per ottenere una chiave API è il seguente:

  1. Vai su (https://ai.google.dev/) e accedi con un account Google.
  2. Fai clic su “Get API key” (Ottieni chiave API).
  3. Scegli di creare la chiave API in un nuovo progetto Google Cloud o in uno esistente.
  4. La chiave API verrà generata automaticamente.

Le chiavi API sono credenziali sensibili e devono essere trattate come password. Devono essere memorizzate in modo sicuro e non devono mai essere esposte nel codice lato client o caricate in sistemi di controllo versione pubblici.

Il metodo più sicuro e raccomandato per utilizzare la chiave è configurarla come variabile d'ambiente. L'SDK è progettato per rilevare e utilizzare automaticamente le variabili d'ambiente GOOGLE_API_KEY o GEMINI_API_KEY. Se entrambe sono configurate, GOOGLE_API_KEY ha la priorità.

Per configurare la variabile d'ambiente:

  • In 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: usa l'interfaccia grafica di “Variabili d'ambiente” nelle impostazioni di sistema per aggiungere una nuova variabile utente o di sistema chiamata GOOGLE_API_KEY con la propria chiave come valore.

1.3.2. La via di Vertex AI (Consigliata per la produzione e l'integrazione con Google Cloud)

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

Per le applicazioni su scala di produzione che richiedono le funzionalità aziendali di Google Cloud, si raccomanda l'uso dell'API di Gemini tramite Vertex AI. Questo approccio richiede un progetto Google Cloud con la fatturazione abilitata.

I passaggi di configurazione iniziale includono:

  1. Selezionare o creare un progetto Google Cloud.
  2. Assicurarsi che la fatturazione sia abilitata per il progetto.
  3. Abilitare l'API di Vertex AI (aiplatform.googleapis.com) per il progetto.

L'autenticazione per Vertex AI può essere eseguita in due modi:

  • Application Default Credentials (ADC) (Consigliato per la produzione): Questo è il metodo preferito per la maggior parte degli scenari di produzione. ADC trova automaticamente le credenziali in base all'ambiente. In un ambiente di sviluppo locale, è possibile configurarlo eseguendo un comando della CLI di gcloud :

    Ventana de terminal
    gcloud auth application-default login

    Quando viene eseguito in un ambiente Google Cloud (ad esempio, Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC utilizza automaticamente l'account di servizio associato a quella risorsa, eliminando la necessità di gestire le chiavi.

  • Chiavi API (per i test su Vertex): È possibile utilizzare una chiave API per autenticarsi nell'endpoint di Vertex AI, ma il processo è più complesso rispetto all'API per sviluppatori. Richiede permessi a livello di organizzazione per abilitare la creazione di chiavi API per gli account di servizio, creare un account di servizio con un ruolo appropriato (ad esempio, Vertex AI User), e quindi creare una chiave API limitata a quell'account di servizio. A causa della sua complessità, questo metodo viene generalmente utilizzato per scenari di test specifici piuttosto che per lo sviluppo di applicazioni generali.

1.4. Inizializzazione del Client: Connessione al Modello

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

Una volta configurata l'autenticazione, il passaggio successivo è istanziare l'oggetto genai.Client. L'SDK unificato semplifica questo processo fornendo un unico client che può essere configurato per uno dei due backend.

Di seguito sono riportati i quattro scenari principali per l'inizializzazione del client.

  • Scenario 1: Gemini Developer API (Chiave Esplicita) Questo metodo è comodo per notebook o script rapidi in cui non si desidera configurare variabili d'ambiente. La chiave API viene passata direttamente come argomento.

    from google import genai
    client = genai.Client(api_key="SU_CLAVE_DE_API_AQUI")
  • Scenario 2: Gemini Developer API (Variabile d'ambiente) Questo è l'approccio più pulito e consigliato per il codice dell'applicazione, poiché disaccoppia le credenziali dal codice. Il client trova e utilizza automaticamente la variabile d'ambiente 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 (Parametri Espliciti) Per connettersi a Vertex AI, si imposta l'indicatore vertexai su True e si forniscono l'ID del progetto e la posizione. Questo metodo utilizzerà automaticamente le Application Default Credentials (ADC) per l'autenticazione.

    from google import genai
    client = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1")
  • Scenario 4: API di Vertex AI (Variabili d'ambiente) Come alternativa per Vertex AI, la configurazione può essere esternalizzata tramite variabili d'ambiente. Il client rileverà queste variabili e verrà configurato per utilizzare il backend di Vertex AI.

    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()

La seguente tabella riassume questi metodi per un rapido riferimento.

Tabella 1: Riferimento rapido per l'inizializzazione del client

Caso d'usoCodice PythonVariabili d'ambiente richiesteNote
API per sviluppatori con chiave esplicitaclient = genai.Client(api_key="SU_CLAVE...")NessunaUtile per notebook e test rapidi. Evitare nel codice di produzione.
API per sviluppatori con variabili d'ambienteclient = genai.Client()GOOGLE_API_KEY o GEMINI_API_KEYMetodo preferito per un codice applicativo pulito e sicuro.
Vertex AI con parametri espliciticlient = genai.Client(vertexai=True, project="...", location="...")Nessuna (usa ADC)Metodo esplicito per puntare a Vertex AI. Richiede l'autenticazione ADC (gcloud auth...).
Vertex AI con variabili d'ambienteclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONConfigura il client per Vertex AI senza parametri nel codice. Richiede l'autenticazione ADC.

Questa parte approfondisce i casi d'uso più comuni: la generazione di testo e la costruzione di agenti conversazionali. Dettaglia i principali metodi e oggetti coinvolti.

2.1. Generazione di contenuti: Il metodo generate_content

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

Il metodo principale per tutti i compiti di generazione a turno singolo è client.models.generate_content(). Questo metodo versatile è la base per interagire con i modelli Gemini.

Un uso di base implica fornire una semplice stringa di testo come contents e specificare il nome del modello da utilizzare, come 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)

Sebbene passare una stringa semplice sia comodo, è fondamentale comprendere la struttura dati sottostante utilizzata dall'SDK. Internamente, l'SDK converte tutti gli input in una struttura standardizzata composta da oggetti types.Content e types.Part. Comprendere questa struttura è fondamentale per sbloccare le funzionalità avanzate dell'SDK, come i prompt multimodali e le chiamate a funzioni.

  • types.Content: Rappresenta un singolo messaggio o turno in una conversazione. Ha due attributi principali: un role (generalmente 'user' per l'input o 'model' per l'output) e una lista di parts.
  • types.Part: Rappresenta un elemento di dati all'interno di un oggetto Content. Una parte può essere testo, dati immagine, un riferimento a un file, una chiamata a funzione, ecc.

L'SDK gestisce in modo intelligente vari tipi di input per l'argomento contents, convertendoli nel formato Content/Part appropriato:

  • Una singola stringa: contents='¿Por qué el cielo es azul?' viene convertito in un UserContent con una singola Part di testo.
  • Una lista di stringhe: contents=['Pregunta 1', 'Pregunta 2'] viene convertito in un unico UserContent che contiene due Part di testo.
  • Un oggetto types.Part: Consente un controllo più dettagliato, come la specifica di dati immagine.
  • Un oggetto types.Content completamente formato: Fornisce il massimo controllo sul ruolo e sul contenuto del messaggio.

Per accedere alla risposta generata, l'accessor di convenienza response.text è il metodo più semplice. Tuttavia, è importante sapere che questo accessor funziona solo per risposte semplici che consistono in un'unica parte di testo. Se la risposta viene bloccata dai filtri di sicurezza, contiene più candidati o include tipi di dati non testuali, l'accesso a response.text genererà un errore. Il metodo più robusto e sicuro per la produzione consiste nell'accedere direttamente al candidato e alle sue parti:

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

Per applicazioni interattive come i chatbot, lo streaming della risposta del modello migliora drasticamente l'esperienza dell'utente. Invece di attendere la generazione dell'intera risposta, i frammenti di testo vengono visualizzati man mano che arrivano, fornendo un feedback immediato.

Questa funzionalità si ottiene con il metodo generate_content_stream(). Questo metodo restituisce un iteratore che produce frammenti della risposta man mano che vengono generati dal modello.

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. Dominare l'IA Conversazionale: L'interfaccia di chat

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

L'SDK fornisce due meccanismi principali per gestire conversazioni multi-turno. Un approccio consiste nel gestire manualmente la cronologia della conversazione, costruendo una lista di oggetti Content che rappresentano ogni turno e passandola a generate_content() in ogni chiamata. Sebbene sia flessibile, questo metodo può risultare macchinoso.

L'approccio consigliato e più conveniente per creare chatbot consiste nell'utilizzare l'interfaccia di chat con stato fornita da client.chats. Questo oggetto di alto livello abstrae la gestione della cronologia, semplificando significativamente il codice dell'applicazione. Si tratta di una scelta progettuale deliberata nel SDK: fornire un'astrazione di alto livello e con stato (client.chats) per un caso d'uso comune (chat), semplificando enormemente lo sviluppo rispetto al metodo di basso livello e senza stato generate_content.

Il flusso di lavoro per utilizzare l'interfaccia di chat è il seguente:

  1. Inizializzare una sessione di chat: Si utilizza client.chats.create() per avviare una nuova conversazione. È possibile specificare il modello e, opzionalmente, fornire una cronologia iniziale per contestualizzare la conversazione.
  2. Inviare messaggi: Si utilizza il metodo chat.send_message() per inviare il messaggio successivo dell'utente. L'SDK gestisce automaticamente lo stato, aggiungendo il messaggio dell'utente e la successiva risposta del modello alla cronologia della conversazione.
  3. Accedere alla cronologia: In qualsiasi momento, è possibile recuperare la cronologia completa della conversazione utilizzando chat.get_history().

Di seguito è riportato un esempio completo di una conversazione a più turni:

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

2.4. Controllo avanzato della generazione

Sección titulada «2.4. Control Avanzado de la Generación»

Per affinare il comportamento del modello, il metodo generate_content accetta un parametro config, che riceve un oggetto types.GenerateContentConfig. Questo oggetto consente agli sviluppatori di controllare vari aspetti del processo di generazione.

Una delle configurazioni più utili è system_instruction. Un'istruzione di sistema fornisce una guida di alto livello o stabilisce una personalità per il modello che persiste durante l'intera conversazione. Ad esempio, si può istruire il modello ad agire come un personaggio specifico o a seguire determinate regole nelle sue risposte.

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)

Oltre alle istruzioni di sistema, ci sono diversi altri parametri che possono essere regolati per controllare la creatività e la struttura dell'output del modello. La seguente tabella dettaglia i più importanti.

Tabella 2: Parametri Chiave di Configurazione della Generazione

ParametroDescrizioneIntervalloEffetto in uscita
temperatureControlla la casualità della selezione dei token.0.0 - 1.0I valori più bassi (ad es., 0.2) rendono l'output più deterministico e meno creativo. I valori più alti (ad es., 0.9) aumentano la casualità e la creatività.
top_pCampionamento nucleare (nucleus sampling). Considera l'insieme più piccolo di token la cui probabilità cumulativa è superiore a top_p.0.0 - 1.0Un valore come 0.95 significa che vengono considerati solo i token che comprendono il 95% superiore della massa di probabilità. Aiuta a evitare token molto improbabili.
top_kConsidera solo i k token più probabili in ogni fase della generazione.InteroUn top_k di 1 è una decodifica greedy (codiciosa). Un valore come 40 restringe la selezione ai 40 token più probabili.
candidate_countIl numero di risposte candidate da generare.Intero (es. 1-8)Genera più risposte possibili per lo stesso prompt. Utile per offrire opzioni all'utente.
max_output_tokensIl numero massimo di token che possono essere generati nella risposta.InteroLimita la lunghezza dell'output. Essenziale per controllare i costi e la latenza.
stop_sequencesUn elenco di stringhe che, quando generate, interrompono l'output.Elenco di stringheUtile per interrompere la generazione in un punto specifico, come un marcatore di fine frase o un formato particolare.
seedSeed casuale per la generazione.InteroFornire un seed rende l'output deterministico e riproducibile (purché temperature non sia 0).

Parte 3: Interazioni Avanzate: Multimodalità e Chiamata a Funzioni

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

Questa parte mostra il vero potere dei modelli Gemini spiegando come lavorare con input non testuali e connettere il modello a strumenti esterni.

Una delle caratteristiche distintive della famiglia di modelli Gemini è la sua capacità multimodale intrinseca. Ciò significa che possono elaborare e ragionare su diversi tipi di dati, o "modalità", come testo, immagini, audio e video, all'interno di un singolo prompt.

Questa funzionalità viene abilitata costruendo l'argomento contents come una lista che contiene più oggetti Part, dove ogni Part può contenere un tipo di dato differente. Ad esempio, una singola richiesta può includere un'immagine e una domanda testuale su quell'immagine.

L'SDK fornisce due metodi strategicamente distinti per gestire i dati delle immagini. La scelta tra di essi dipende dai requisiti specifici del caso d'uso, come la dimensione del file e il riutilizzo.

Questa dualità di metodi non è una ridondanza, ma un design deliberato che risponde a diverse esigenze operative. Il metodo inline è semplice ed eccellente per analisi singole e per la praticità nello sviluppo. L'API File, sebbene comporti un passaggio di caricamento aggiuntivo, è fondamentale per gli scenari di produzione in cui l'efficienza, la scalabilità e la gestione di file di grandi dimensioni sono primarie.

Questo metodo è ideale per file di immagine più piccoli (la richiesta totale, inclusi i prompt e i byte, deve essere inferiore a 20 MB) e per la semplicità nello sviluppo. I dati dell'immagine vengono passati direttamente nella chiamata a generate_content.

  • Da un file locale: Il file immagine viene letto in modalità binaria ('rb') e passato a types.Part.from_bytes(), specificando il tipo MIME corretto.

    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)
  • Da un URL: È possibile utilizzare una libreria come requests per ottenere i byte dell'immagine da un URL e poi passarli allo stesso modo.

Questo metodo è consigliato per file immagine di grandi dimensioni (superiori a 20 MB) o per scenari in cui lo stesso file verrà riutilizzato in molteplici richieste di prompt. L'uso della Files API evita la necessità di ricaricare gli stessi byte ad ogni chiamata.

Il flusso di lavoro consiste in due passaggi:

  1. Caricamento: Si utilizza client.files.upload() per caricare il file sui server di Google. Questo metodo restituisce un oggetto file che funge da riferimento.
  2. Specifica: L'oggetto file restituito viene passato direttamente nella lista contents di una chiamata a generate_content. L'SDK si occupa di risolvere il riferimento al file caricato.
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}")

I file caricati tramite l'API Files vengono memorizzati temporaneamente per 48 ore prima di essere eliminati automaticamente. L'API fornisce anche metodi per gestire questi file, come get(), list() e delete().

I concetti di gestione delle immagini si estendono direttamente ad altre modalità come l'audio e il video. Poiché questi file sono spesso di grandi dimensioni, l'API Files è il metodo principale per lavorarci.

Il processo è identico a quello delle immagini grandi:

  1. Utilizza client.files.upload() per caricare il file audio (ad es., MP3, WAV) o video (ad es., MP4).
  2. Includi l'oggetto file restituito nel prompt a generate_content.

L'esempio seguente mostra come caricare un file audio e chiedere al modello di trascriverlo.

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. Chiamata alle Funzioni: Ampliare le Capacità del Modello

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

La chiamata alle funzioni, nota anche come utilizzo di strumenti (tool use), è una tecnica potente che consente al modello linguistico di interagire con sistemi esterni. Consente al modello di rispondere a domande o eseguire azioni che vanno oltre la sua conoscenza intrinseca, come ottenere dati in tempo reale da un'API, interrogare un database o controllare un dispositivo.

Il flusso di lavoro generale è il seguente:

  1. Definizione degli Strumenti: Viene definito un insieme di strumenti (funzioni Python) che il modello può chiamare. Questa definizione include il nome della funzione, una descrizione di ciò che fa e lo schema dei suoi parametri.
  2. Passaggio degli Strumenti al Modello: L'elenco degli strumenti definiti viene passato al modello nella chiamata a generate_content.
  3. Il Modello Decide di Chiamare: Il modello analizza il prompt dell'utente e, se determina che uno degli strumenti forniti può aiutare a rispondere, invece di generare testo, la sua risposta conterrà un oggetto Part di tipo function_call. Questo oggetto specifica il nome della funzione da chiamare e gli argomenti per la chiamata.
  4. Eseguire la funzione: Il codice dell'applicazione rileva questo function_call, esegue la funzione Python corrispondente con gli argomenti forniti e ottiene un risultato.
  5. Restituire il risultato al modello: Viene effettuata una seconda chiamata a generate_content, fornendo la cronologia della conversazione insieme al risultato dell'esecuzione della funzione (racchiuso in un types.Part.from_function_response()).
  6. Risposta finale: Il modello utilizza il risultato della funzione per generare una risposta finale in linguaggio naturale per l'utente.

Sebbene i frammenti di ricerca non forniscano un esempio di codice di chiamata alle funzioni end-to-end, la struttura degli oggetti Part per function_call e function_response costituisce la base per implementare questo pattern avanzato.


Parte 4: Preparazione per la produzione: gestione degli errori, sicurezza e gestione

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

Questa parte finale fornisce le informazioni critiche necessarie per costruire applicazioni robuste, affidabili e responsabili.

In un ambiente di produzione, una gestione robusta degli errori non è negoziabile. Le chiamate alle API possono fallire per diverse ragioni, come credenziali non valide, problemi di rete, esaurimento delle quote o input malformati.

L'SDK utilizza il sistema di eccezioni standard di Python. La maggior parte degli errori relativi alle API può essere catturata utilizzando un blocco try...except che cerca eccezioni del modulo google.api_core.exceptions o, se disponibile, una classe più specifica come 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}")

Quando viene catturata un'eccezione, l'oggetto dell'eccezione contiene spesso informazioni preziose per il logging e il debugging, come un codice di stato e un messaggio descrittivo.

È importante considerare che i messaggi di errore, sebbene utili per gli sviluppatori, possono essere un'arma a doppio taglio. Possono rivelare dettagli di implementazione interna che potrebbero essere sfruttati in attacchi avversari. Ad esempio, un'analisi dei messaggi di errore di validazione della sicurezza potrebbe rivelare soglie interne o meccanismi di difesa, aiutando un malintenzionato a eludere le protezioni. Pertanto, sebbene gli errori debbano essere registrati esaustivamente nel backend, le informazioni presentate agli utenti finali devono essere controllate con cura. Spesso è più sicuro mostrare un messaggio generico come “Si è verificato un errore durante l'elaborazione della richiesta” invece di esporre il messaggio di errore grezzo dell'API.

La seguente tabella riassume i codici di errore API più comuni e come risolverli.

Tabella 3: Codici di errore API comuni e relative soluzioni

Codice HTTPStatoCausa ProbabileAzione Raccomandata in Python
400INVALID_ARGUMENTIl corpo della richiesta è malformato (ad es., un parametro con un tipo errato, un campo obbligatorio mancante).Verifica che i parametri in GenerateContentConfig e il formato di contents siano corretti. Assicurati che il modello sia compatibile con le caratteristiche richieste.
403PERMISSION_DENIEDLa chiave API è errata, non disponi dei permessi necessari o stai tentando di accedere a una risorsa limitata (ad es., un modello personalizzato).Verifica che la chiave API (o l'autenticazione ADC per Vertex) sia configurata correttamente e abbia i permessi necessari.
429RESOURCE_EXHAUSTEDÈ stato superato il limite di velocità dell'API (richieste al minuto).Implementa un backoff esponenziale (exponential backoff) nella tua logica di retry. Considera di richiedere un aumento della quota se necessario per la tua applicazione.
500INTERNALSi è verificato un errore imprevisto lato Google. A volte può essere causato da un contesto di input molto lungo.Riduci la lunghezza del prompt. Riprova la richiesta dopo una breve attesa. Se il problema persiste, considera di passare temporaneamente a un modello diverso.
503UNAVAILABLEIl servizio è temporaneamente sovraccarico o non disponibile.Riprova la richiesta dopo una breve attesa utilizzando una strategia di backoff esponenziale. Se il problema persiste, segnala il problema.

L'API di Gemini include funzionalità di sicurezza integrate per filtrare contenuti potenzialmente dannosi. Queste funzionalità sono progettate per aiutare gli sviluppatori a costruire applicazioni più sicure e responsabili.

L'API classifica i contenuti in quattro categorie principali di danno:

  • Molestie (HARM_CATEGORY_HARASSMENT)
  • Incitamento all'odio (HARM_CATEGORY_HATE_SPEECH)
  • Contenuto sessualmente esplicito (HARM_CATEGORY_SEXUALLY_EXPLICIT)
  • Contenuto pericoloso (HARM_CATEGORY_DANGEROUS_CONTENT)

Per ogni categoria, il modello assegna una probabilità che il contenuto sia non sicuro. Per impostazione predefinita, l'API blocca i prompt e le risposte che hanno una probabilità MEDIUM o HIGH di essere non sicuri in una qualsiasi di queste categorie.

Gli sviluppatori possono sovrascrivere questa configurazione predefinita per singola richiesta passando una lista di oggetti SafetySetting al parametro safety_settings. Ciò consente un controllo granulare sulla soglia di blocco per ogni categoria.

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

Quando una risposta sembra vuota o si verifica un errore, è fondamentale ispezionare il feedback di sicurezza. L'oggetto di risposta contiene prompt_feedback (per il prompt di input) e candidates.safety_ratings (per la risposta generata). Questi attributi riveleranno se il contenuto è stato bloccato e perché, il che è essenziale per il debugging.

La seguente tabella chiarisce il significato delle diverse soglie di blocco.

Tabella 4: Soglie di Configurazione della Sicurezza

Costante APIConfigurazione in Google AI StudioDescrizione
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/ALa soglia non è specificata; viene utilizzata la soglia predefinita del modello.
BLOCK_NONENessun blocco (Non bloccare nulla)Non bloccare mai i contenuti, indipendentemente dalla probabilità che siano non sicuri. Deve essere utilizzato con estrema cautela.
BLOCK_ONLY_HIGHBlocca pochiBloccare solo quando la probabilità di contenuti non sicuri è HIGH.
BLOCK_MEDIUM_AND_ABOVEBlocca alcuni(Predefinito per la maggior parte dei modelli) Bloccare quando la probabilità di contenuti non sicuri è MEDIUM o HIGH.
BLOCK_LOW_AND_ABOVEBlocca la maggior parte (Blocca la maggior parte)Blocca quando la probabilità di contenuto non sicuro è LOW, MEDIUM o HIGH.

L'SDK fornisce un modo programmatico per scoprire i modelli disponibili e le loro capacità. Ciò è utile per costruire applicazioni che possono adattarsi a diversi modelli o per verificare le capacità di un modello prima di utilizzarlo.

Il metodo client.models.list() restituisce un iteratore sui modelli disponibili.

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)

Questa funzionalità può anche essere utilizzata per elencare specificamente i modelli che sono stati perfezionati (fine-tuned) dall'utente, impostando query_base=False nella configurazione della richiesta di elenco. Ciò consente alle applicazioni di scoprire e utilizzare dinamicamente modelli personalizzati.


Parte 5: Validazione dell'ambiente e checklist tecnica

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

Per completare il provisioning delle integrazioni basate sull'SDK unificato google-genai nel tenant di Portelcore, valida il rispetto dei seguenti traguardi tecnici:

  • Ho migrato tutti gli script del tenant dalla libreria obsoleta google-generativeai al nuovo standard google-genai. ✓
  • Le chiavi API sono gestite esclusivamente tramite la variabile d'ambiente GOOGLE_API_KEY o offuscate nel gestore di segreti di Google Cloud, invece di essere scritte in testo in chiaro. ✓
  • È implementato un robusto controllo delle eccezioni (google.api_core.exceptions) per catturare i codici di stato 429 (Resource Exhausted) con politiche di retry esponenziale (exponential backoff). ✓
  • La temperatura e le soglie di sicurezza (safety_settings) sono parametrizzate formalmente in base al caso d'uso del dominio portelcore.com. ✓