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.
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.
1.2. Installazione e Ambiente
Sección titulada «1.2. Instalación y Entorno»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:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateUna 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.
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:
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:
- Vai su (https://ai.google.dev/) e accedi con un account Google.
- Fai clic su “Get API key” (Ottieni chiave API).
- Scegli di creare la chiave API in un nuovo progetto Google Cloud o in uno esistente.
- 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_KEYcon 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:
- Selezionare o creare un progetto Google Cloud.
- Assicurarsi che la fatturazione sia abilitata per il progetto.
- 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 loginQuando 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 genaiclient = 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é configuradafrom google import genaiclient = genai.Client() -
Scenario 3: Vertex AI API (Parametri Espliciti) Per connettersi a Vertex AI, si imposta l'indicatore
vertexaisuTruee si forniscono l'ID del progetto e la posizione. Questo metodo utilizzerà automaticamente le Application Default Credentials (ADC) per l'autenticazione.from google import genaiclient = 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=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()
La seguente tabella riassume questi metodi per un rapido riferimento.
Tabella 1: Riferimento rapido per l'inizializzazione del client
| Caso d'uso | Codice Python | Variabili d'ambiente richieste | Note |
|---|---|---|---|
| API per sviluppatori con chiave esplicita | client = genai.Client(api_key="SU_CLAVE...") | Nessuna | Utile per notebook e test rapidi. Evitare nel codice di produzione. |
| API per sviluppatori con variabili d'ambiente | client = genai.Client() | GOOGLE_API_KEY o GEMINI_API_KEY | Metodo preferito per un codice applicativo pulito e sicuro. |
| Vertex AI con parametri espliciti | client = 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'ambiente | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Configura il client per Vertex AI senza parametri nel codice. Richiede l'autenticazione ADC. |
Parte 2: Capacità principali: Testo e Chat
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»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ó anteriormenteresponse = 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: unrole(generalmente 'user' per l'input o 'model' per l'output) e una lista diparts.types.Part: Rappresenta un elemento di dati all'interno di un oggettoContent. 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 unUserContentcon una singolaPartdi testo. - Una lista di stringhe:
contents=['Pregunta 1', 'Pregunta 2']viene convertito in un unicoUserContentche contiene duePartdi testo. - Un oggetto
types.Part: Consente un controllo più dettagliato, come la specifica di dati immagine. - Un oggetto
types.Contentcompletamente 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}")2.2. Risposte in streaming per il feedback in tempo reale
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»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 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. 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:
- 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. - 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. - 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 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. 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 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)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
| Parametro | Descrizione | Intervallo | Effetto in uscita |
|---|---|---|---|
temperature | Controlla la casualità della selezione dei token. | 0.0 - 1.0 | I 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_p | Campionamento nucleare (nucleus sampling). Considera l'insieme più piccolo di token la cui probabilità cumulativa è superiore a top_p. | 0.0 - 1.0 | Un 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_k | Considera solo i k token più probabili in ogni fase della generazione. | Intero | Un top_k di 1 è una decodifica greedy (codiciosa). Un valore come 40 restringe la selezione ai 40 token più probabili. |
candidate_count | Il 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_tokens | Il numero massimo di token che possono essere generati nella risposta. | Intero | Limita la lunghezza dell'output. Essenziale per controllare i costi e la latenza. |
stop_sequences | Un elenco di stringhe che, quando generate, interrompono l'output. | Elenco di stringhe | Utile per interrompere la generazione in un punto specifico, come un marcatore di fine frase o un formato particolare. |
seed | Seed casuale per la generazione. | Intero | Fornire 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.
3.1. Oltre il testo: Comprendere gli input multimodali
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»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.
3.2. Lavorare con le immagini
Sección titulada «3.2. Trabajando con Imágenes»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.
Metodo 1: Dati immagine inline
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»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 atypes.Part.from_bytes(), specificando il tipo MIME corretto.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) -
Da un URL: È possibile utilizzare una libreria come
requestsper ottenere i byte dell'immagine da un URL e poi passarli allo stesso modo.
Metodo 2: Files API
Sección titulada «Método 2: La API de Archivos (Files API)»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:
- Caricamento: Si utilizza
client.files.upload()per caricare il file sui server di Google. Questo metodo restituisce un oggetto file che funge da riferimento. - Specifica: L'oggetto file restituito viene passato direttamente nella lista
contentsdi una chiamata agenerate_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 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}")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().
3.3. Interazione con audio e video
Sección titulada «3.3. Interacción con Audio y Vídeo»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:
- Utilizza
client.files.upload()per caricare il file audio (ad es., MP3, WAV) o video (ad es., MP4). - 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 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. 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:
- 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.
- Passaggio degli Strumenti al Modello: L'elenco degli strumenti definiti viene passato al modello nella chiamata a
generate_content. - 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
Partdi tipofunction_call. Questo oggetto specifica il nome della funzione da chiamare e gli argomenti per la chiamata. - Eseguire la funzione: Il codice dell'applicazione rileva questo
function_call, esegue la funzione Python corrispondente con gli argomenti forniti e ottiene un risultato. - 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 untypes.Part.from_function_response()). - 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.
4.1. Gestione Robusta degli Errori
Sección titulada «4.1. Manejo Robusto de Errores»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_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}")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 HTTP | Stato | Causa Probabile | Azione Raccomandata in Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | Il 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. |
| 403 | PERMISSION_DENIED | La 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. |
| 429 | RESOURCE_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. |
| 500 | INTERNAL | Si è 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. |
| 503 | UNAVAILABLE | Il 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. |
4.2. Gestione della Sicurezza dei Contenuti
Sección titulada «4.2. Gestión de la Seguridad del Contenido»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 API | Configurazione in Google AI Studio | Descrizione |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | La soglia non è specificata; viene utilizzata la soglia predefinita del modello. |
BLOCK_NONE | Nessun blocco (Non bloccare nulla) | Non bloccare mai i contenuti, indipendentemente dalla probabilità che siano non sicuri. Deve essere utilizzato con estrema cautela. |
BLOCK_ONLY_HIGH | Blocca pochi | Bloccare solo quando la probabilità di contenuti non sicuri è HIGH. |
BLOCK_MEDIUM_AND_ABOVE | Blocca alcuni | (Predefinito per la maggior parte dei modelli) Bloccare quando la probabilità di contenuti non sicuri è MEDIUM o HIGH. |
BLOCK_LOW_AND_ABOVE | Blocca la maggior parte (Blocca la maggior parte) | Blocca quando la probabilità di contenuto non sicuro è LOW, MEDIUM o HIGH. |
4.3. Gestione dei Modelli
Sección titulada «4.3. Gestión de Modelos»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 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)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-generativeaial nuovo standardgoogle-genai. ✓ - Le chiavi API sono gestite esclusivamente tramite la variabile d'ambiente
GOOGLE_API_KEYo 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 dominioportelcore.com. ✓

