SDK de Python Google GenAI per a l'API de Gemini
Guia de referència i configuració avançada per al nou SDK unificat google-genai de l'API de Gemini a Portelcore.
Part 1: Conceptes Fonamentals i Configuració Inicial
Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»Aquesta secció estableix el context per al nou SDK, abordant la principal confusió de l'usuari sobre el canvi de biblioteca, i proporciona una guia robusta per començar correctament, cobrint la instal·lació i les dues vies d'autenticació crítiques.
1.1. El Nou Estàndard: Migrar de google-generativeai a google-genai
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»L'ecosistema de desenvolupament per als models d'IA generativa de Google ha evolucionat. La biblioteca google-genai és ara l'SDK de Python oficial, unificat i recomanat per interactuar amb l'API de Gemini i altres models d'IA generativa de Google. Va arribar a la Disponibilitat General (GA) el maig de 2025 i substitueix la biblioteca heredada, google-generativeai.
La biblioteca anterior, google-generativeai, ha estat marcada com a “Inactiva” al Python Package Index (PyPI) i es troba en un camí d'obsolescència. El suport per a aquest paquet, incloent-hi les correccions d'errors crítics, cesarà a finals de setembre de 2025, tot i que algunes fonts indiquen una data de finalització del suport lleugerament anterior, el 31 d'agost de 2025. Es recomana als desenvolupadors que es targetin la data més temprana per garantir una transició sense problemes.
Aquest canvi no és simplement un canvi de nom, sinó una unificació estratègica impulsada pels comentaris dels desenvolupadors. L'objectiu era crear un únic SDK que simplificara l'accés a tota la gamma de models d'IA generativa de Google (Gemini, Veo, Imagen, etc.) i oferís una ruta de desenvolupament més clara i coherent. Una de les decisions de disseny més significatives del nou SDK google-genai és que actua com una interfície única per a dos serveis de backend diferents: l'API de desenvolupador de Gemini, de fàcil accés, i la plataforma Vertex AI, de nivell empresarial.
Aquesta arquitectura unificada proporciona una rampa d'accés fluida per als desenvolupadors. Poden començar ràpidament, sovint amb un nivell gratuït, utilitzant una clau d'API per a l'API de desenvolupador de Gemini. A mesura que les seves aplicacions maduren i requereixin una major escalabilitat, governança i integració amb altres serveis de Google Cloud, poden canviar al backend de Vertex AI amb canvis mínims en el codi, principalment en la inicialització del client. L'SDK google-genai funciona com un pont, reduint la barrera d'entrada alhora que proporciona un camí clar cap a la producció a Google Cloud. Per tant, s'insta tots els usuaris de la biblioteca heretada a migrar per garantir l'accés a les últimes característiques (com Live API i Veo), millores de rendiment i suport continu.
1.2. Instal·lació i Entorn
Sección titulada «1.2. Instalación y Entorno»Abans d'instal·lar l'SDK, una bona pràctica és configurar un entorn virtual de Python. Això aïlla les dependències del projecte, evitant conflictes amb altres projectes o amb els paquets del sistema.
Per crear i activar un entorn virtual utilitzant venv:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateUn cop l'entorn virtual estigui actiu, es pot instal·lar l'última versió de l'SDK de Google Gen AI utilitzant pip. L'ús de l'indicador --upgrade assegura que s'obtingui la versió més recent.
pip install --upgrade google-genaiÉs fonamental tenir en compte els requisits de la versió de Python. L'SDK google-genai requereix Python 3.9 o superior. L'ús d'una versió no compatible pot provocar errors inesperats durant la instal·lació o l'execució.
Per a aplicacions que requereixen un rendiment asíncron d'alt rendiment, l'SDK ofereix una opció per utilitzar aiohttp com a backend de transport HTTP en lloc de l'estàndard httpx. Això es pot instal·lar com un extra:
pip install google-genai[aiohttp]1.3. Autenticació: La seva clau per a l'API de Gemini
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»L'autenticació és el pas de configuració més crític i el mètode difereix segons el servei de backend que es vulgui utilitzar: l'API de desenvolupador de Gemini o l'API de Gemini a Vertex AI.
1.3.1. La via de l'API de desenvolupador de Gemini (Recomanada per a prototips i nivell gratuït)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»Aquesta és la manera més ràpida de començar a construir amb Gemini. Requereix una clau d'API que es pot obtenir de forma gratuïta des de Google AI Studio.
El procés per obtenir una clau d'API és el següent:
- Navegueu a (https://ai.google.dev/) i inicieu sessió amb un compte de Google.
- Fageu clic a “Get API key” (Obtenir la clau de l'API).
- Trieu crear la clau d'API en un projecte de Google Cloud nou o existent.
- La clau d'API es generarà automàticament.
Les claus d'API són credencials sensibles i s'han de tractar com a contrasenyes. S'han d'emmagatzemar de forma segura i mai no s'han d'exposar en el codi del costat del client ni s'han de confirmar en sistemes de control de versions públics.
El mètode més segur i recomanat per utilitzar la clau és configurar-la com una variable d'entorn. L'SDK està dissenyat per detectar i utilitzar automàticament les variables d'entorn GOOGLE_API_KEY o GEMINI_API_KEY. Si ambdues estan configurades, GOOGLE_API_KEY té prioritat.
Per configurar la variable d'entorn:
-
A 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 -
A Windows: utilitza la interfície gràfica de “Variables d'entorn” a la configuració del sistema per afegir una nova variable d'usuari o de sistema anomenada
GOOGLE_API_KEYamb la seva clau com a valor.
1.3.2. La via de Vertex AI (Recomanada per a producció i integració amb 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 a aplicacions a escala de producció que requereixen les característiques empresarials de Google Cloud, es recomana utilitzar l'API de Gemini a través de Vertex AI. Aquest enfocament requereix un projecte de Google Cloud amb la facturació habilitada.
Els passos de configuració inicial inclouen:
- Seleccionar o crear un projecte de Google Cloud.
- Assegurar-se que la facturació estigui habilitada per al projecte.
- Habilitar l'API de Vertex AI (
aiplatform.googleapis.com) per al projecte.
L'autenticació per a Vertex AI es pot realitzar de dues maneres:
-
Credencials Predeterminades d'Aplicació (ADC) (Recomanat per a producció): Aquest és el mètode preferit per a la majoria dels escenaris de producció. L'ADC troba automàticament les credencials segons l'entorn. En un entorn de desenvolupament local, això es pot configurar executant un comandament de la CLI de gcloud :
Ventana de terminal gcloud auth application-default loginQuan s'executa en un entorn de Google Cloud (per exemple, Cloud Run, Google Kubernetes Engine, Cloud Functions), l'ADC utilitza automàticament el compte de servei adjunt a aquell recurs, eliminant la necessitat de gestionar claus.
-
Claus d'API (per a proves a Vertex): És possible utilitzar una clau d'API per autenticar-se en l'endpoint de Vertex AI, però el procès és més complex que amb l'API de desenvolupador. Requereix permisos a nivell d'organització per habilitar la creació de claus d'API de comptes de servei, crear un compte de servei amb un rol apropiat (per exemple,
Vertex AI User), i després crear una clau d'API restringida a aquell compte de servei. A causa de la seva complexitat, aquest mètode s'utilitza generalment per a escenaris de prova específics en lloc del desenvolupament d'aplicacions generals.
1.4. Inicialització del client: Connectant-se al model
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»Un cop l'autenticació estigui configurada, el següent pas és instanciar l'objecte genai.Client. L'SDK unificat simplifica això proporcionant un únic client que es pot configurar per a qualsevol dels dos backends.
A continuació es presenten els quatre escenaris principals per a la inicialització del client.
-
Escenari 1: API de desenvolupador de Gemini (clau explícita) Aquest mètode és còmode per a notebooks o scripts ràpids on no es vol configurar variables d'entorn. La clau d'API es passa directament com un argument.
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
Escenari 2: API de Desenvolupador de Gemini (Variable d'Entorn) Aquest és l'enfocament més net i recomanat per al codi de l'aplicació, ja que desacopla les credencials del codi. El client troba i utilitza automàticament la variable d'entorn
GOOGLE_API_KEY.# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
Escenari 3: API de Vertex AI (Paràmetres Explícits) Per connectar-se a Vertex AI, s'estableix l'indicador
vertexaiaTruei s'introdueixen l'ID del projecte i la ubicació. Aquest mètode utilitzarà automàticament les Credencials Predeterminades d'Aplicació (ADC) per a l'autenticació.from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
Escenari 4: API de Vertex AI (Variables d'Entorn) Com a alternativa per a Vertex AI, la configuració es pot externalitzar a variables d'entorn. El client detectarà aquestes variables i es configurarà per utilitzar el backend de 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 següent taula resumeix aquests mètodes per a una referència ràpida.
Taula 1: Referència Ràpida d'Inicialització del Client
| Cas d'ús | Codi Python | Variables d'entorn requerides | Notes |
|---|---|---|---|
| API de Desenvolupador amb Clau Explícita | client = genai.Client(api_key="SU_CLAVE...") | Cap | Útil per a notebooks i proves ràpides. Evitar en codi de producció. |
| API de Desenvolupador amb Var. d'Entorn | client = genai.Client() | GOOGLE_API_KEY o GEMINI_API_KEY | Mètode preferit per a codi d'aplicació net i segur. |
| Vertex AI amb Paràmetres Explícits | client = genai.Client(vertexai=True, project="...", location="...") | Cap (usa ADC) | Mètode explícit per apuntar a Vertex AI. Requereix autenticació ADC (gcloud auth...). |
| Vertex AI amb Var. d'Entorn | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Configura el client per a Vertex AI sense paràmetres al codi. Requereix autenticació ADC. |
Part 2: Capacitats Principals: Text i Chat
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»Aquesta part s'enfoca en els casos d'ús més comuns: generar text i construir agents conversacionals. Detalla els principals mètodes i objectes implicats.
2.1. Generant contingut: El mètode generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»El mètode principal per a totes les tasques de generació de un sol torn és client.models.generate_content(). Aquest mètode versàtil és la base per interactuar amb els models de Gemini.
Un ús bàsic implica proporcionar una cadena de text simple com contents i especificar el nom del model a utilitzar, com 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)Encara que passar una cadena simple és còmode, és fonamental comprendre l'estructura de dades subjacenta que utilitza l'SDK. Internament, l'SDK converteix totes les entrades en una estructura estandaritzada que consta d'objectes types.Content i types.Part. Comprendre aquesta estructura és clau per desbloquejar les capacitats avançades de l'SDK, com les indicacions multimodals i les crides a funcions.
types.Content: Representa un únic missatge o torn en una conversa. Té dos atributs principals: unrole(generalment 'user' per a l'entrada o 'model' per a la sortida) i una llista departs.types.Part: Representa una peça de dades dins d'un objecteContent. Una part pot ser text, dades de imatge, una referència de fitxer, una crida a una funció, etc.
L'SDK gestiona intel·ligentment diversos tipus d'entrada per a l'argument contents, convertint-los al format Content/Part apropiat:
- Una sola cadena:
contents='¿Por qué el cielo es azul?'es converteix en unUserContentamb una solaPartde text. - Una llista de cadenes:
contents=['Pregunta 1', 'Pregunta 2']es converteix en un únicUserContentque conté duesPartde text. - Un objecte
types.Part: Permet un control més detallat, com especificar dades d'imatge. - Un objecte
types.Contentcompletament format: Proporciona el màxim control sobre el rol i el contingut del missatge.
Per accedir a la resposta generada, l'accessor de conveniència response.text és el mètode més senzill. Tanmateix, és important saber que aquest accessor només funciona per a respostes senzilles que consisteixen en una única part de text. Si la resposta és bloquejada per filtres de seguretat, conté múltiples candidats o inclou tipus de dades no textuals, accedir a response.text generarà un error. El mètode més robust i segur per a producció és accedir directament al candidat i a les seves parts:
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. Respostes en Streaming per a retroalimentació en temps real
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»Per a aplicacions interactives com els chatbots, el streaming de la resposta del model millora dràsticament l'experiència de l'usuari. En lloc d'esperar que es generi tota la resposta, els fragments de text es mostren a mesura que arriben, proporcionant una retroalimentació immediata.
Aquesta funcionalitat s'aconsegueix amb el mètode generate_content_stream(). Aquest mètode retorna un iterador que produeix fragments de la resposta a mesura que són generats pel model.
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. Dominant la IA Conversacional: La Interfície de Xat
Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»L'SDK proporciona dos mecanismes principals per gestionar converses de múltiples torns. Un enfoc és gestionar manualment l'historial de la conversa, construint una llista d'objectes Content que representen cada torn i passant-la a generate_content() en cada trucada. Tot i que és flexible, aquest mètode pot resultar engorros.
L'enfoc recomanat i més convenient per crear chatbots és utilitzar la interfície de xat amb estat proporcionada per client.chats. Aquest objecte de nivell superior abstrau la gestió de l'historial, simplificant significativament el codi de l'aplicació. Aquesta és una decisió de disseny deliberada de l'SDK: proporcionar una abstracció de nivell alt i amb estat (client.chats) per a un cas d'ús comú (xat), cosa que simplifica enormement el desenvolupament en comparació amb el mètode de nivell baix i sense estat generate_content.
El flux de treball per utilitzar la interfície de xat és el següent:
- Inicialitzar una sessió de xat: S'utilitza
client.chats.create()per iniciar una nova conversa. Es pot especificar el model i, opcionalment, proporcionar un historial inicial per contextualitzar la conversa. - Enviar missatges: S'utilitza el mètode
chat.send_message()per enviar el següent missatge de l'usuari. L'SDK gestiona automàticament l'estat, afegint el missatge de l'usuari i la posterior resposta del model a l'historial de la conversa. - Accedir a l'historial: En qualsevol moment, es pot recuperar l'historial complet de la conversa utilitzant
chat.get_history().
A continuació es mostra un exemple complet d'una conversa de diversos torns:
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. Control avançat de la generació
Sección titulada «2.4. Control Avanzado de la Generación»Per afinar el comportament del model, el mètode generate_content accepta un paràmetre config, que accepta un objecte types.GenerateContentConfig. Aquest objecte permet als desenvolupadors controlar diversos aspectes del procés de generació.
Una de les configuracions més útils és system_instruction. Una instrucció del sistema proporciona una guia d'alt nivell o estableix una personalitat per al model que persiste durant tota la conversa. Per exemple, es pot instruir el model perquè actuï com un personatge específic o perquè segueixi certes regles en les seves respostes.
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)A part de les instruccions del sistema, hi ha diversos altres paràmetres que es poden ajustar per controlar la creativitat i l'estructura de la sortida del model. La següent taula detalla els més importants.
Taula 2: Paràmetres clau de configuració de la generació
| Paràmetre | Descripció | Rang | Efecte en la sortida |
|---|---|---|---|
temperature | Controla l'aleatorietat de la selecció de tokens. | 0.0 - 1.0 | Els valors més baixos (p. ex., 0.2) fan que la sortida sigui més determinista i menys creativa. Els valors més alts (p. ex., 0.9) augmenten l'aleatorietat i la creativitat. |
top_p | Muestreig de nucli (nucleus sampling). Considera el conjunt més petit de tokens la cui probabilitat acumulada és superior a top_p. | 0.0 - 1.0 | Un valor com 0.95 significa que només es consideren els tokens que comprenen el 95% superior de la massa de probabilitat. Ajuda a evitar tokens molt improbables. |
top_k | Considera només els k tokens més probables en cada pas de la generació. | Enter | Un top_k de 1 és una decodificació codiciosa (greedy). Un valor com 40 restricteix la selecció als 40 tokens més probables. |
candidate_count | El nombre de respostes candidates a generar. | Enter (p. ex., 1-8) | Genera múltiples respostes possibles per a la mateixa indicació. Útil per oferir opcions a l'usuari. |
max_output_tokens | El nombre màxim de tokens que es poden generar en la resposta. | Enter | Limita la longitud de la sortida. Essencial per controlar els costos i la latència. |
stop_sequences | Una llista de cadenes que, quan es generen, aturaran la sortida. | Llista de cadenes | Útil per aturar la generació en un punt específic, com un marcador de final de frase o un format particular. |
seed | Llavor aleatòria per a la generació. | Enter | Proporcionar una llavor fa que la sortida sigui determinista i reproduïble (sempre que temperature no sigui 0). |
Part 3: Interaccions Avançades: Multimodalitat i Crida de Funcions
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»Aquesta part mostra el veritable poder dels models Gemini en explicar com treballar amb entrades no textuals i connectar el model a eines externes.
3.1. Més Allà del Text: Comprendre les Entrades Multimodals
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Una de les característiques definidores de la família de models Gemini és la seva capacitat multimodal inherent. Això significa que poden processar i raonar sobre diferents tipus de dades, o “modalitats”, com text, imatges, àudio i vídeo, dins d'una única sol·licitud d'indicació.
Aquesta capacitat s'habilita construint l'argument contents com una llista que conté múltiples objectes Part, on cada Part pot contenir un tipus de dada diferent. Per exemple, una sola sol·licitud pot incloure una imatge i una pregunta de text sobre aquesta imatge.
3.2. Treballant amb Imatges
Sección titulada «3.2. Trabajando con Imágenes»L'SDK proporciona dos mètodes estratègicament distints per gestionar dades d'imatges. L'elecció entre ells depèn dels requisits específics del cas d'ús, com la mida del fitxer i la reutilització.
Aquesta dualitat de mètodes no és una redundància, sinó un disseny deliberat que aborda diferents necessitats operatives. El mètode en línia és senzill i excel·lent per a anàlisis únics i la comoditat en el desenvolupament. L'API de fitxers, tot i que implica un pas de càrrega addicional, és fonamental per a escenaris de producció on l'eficiència, l'escalabilitat i la gestió de fitxers grans són primordials.
Mètode 1: Dades d'imatge en línia (Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»Aquest mètode és ideal per a fitxers d'imatge més petits (la sol·licitud total, incloent les indicacions i els bytes, ha de ser inferior a 20 MB) i per a la simplicitat en el desenvolupament. Les dades de la imatge es passen directament a la trucada a generate_content.
-
Des d'un fitxer local: El fitxer d'imatge es llegeix en mode binari (
'rb') i es passa atypes.Part.from_bytes(), especificant el tipus MIME correcte.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) -
Des d'una URL: Es pot utilitzar una biblioteca com
requestsper obtenir els bytes de la imatge d'una URL i després passar-los de la mateixa manera.
Mètode 2: L'API de fitxers (Files API)
Sección titulada «Método 2: La API de Archivos (Files API)»Aquest mètode es recomana per a fitxers d'imatge grans (superiors a 20 MB) o per a escenaris en els quals el mateix fitxer es reutilitzarà en múltiples sol·licituds d'indicació. L'ús de l'API de Fitxers evita la necessitat de tornar a carregar els mateixos bytes amb cada trucada.
El flux de treball consta de dos passos:
- Cargar: Se utiliza
client.files.upload()para cargar el archivo a los servidores de Google. Este método devuelve un objeto de archivo que actúa como una referencia. - Indicar: Se pasa el objeto de archivo devuelto directamente en la lista
contentsde una llamada agenerate_content. El SDK se encarga de resolver la referencia al archivo cargado.
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}")Els fitxers carregats a través de l'API de Fitxers s'emmagatzemen temporalment durant 48 hores abans de ser eliminats automàticament. L'API també proporciona mètodes per gestionar aquests fitxers, com get(), list() i delete().
3.3. Interacció amb àudio i vídeo
Sección titulada «3.3. Interacción con Audio y Vídeo»Els conceptes de gestió de imatges s'estenen directament a altres modalitats com l'àudio i el vídeo. Com que aquests fitxers solen ser grans, l'API de fitxers és el mètode principal per treballar amb ells.
El procés és idèntic al de les imatges grans:
- Utilitza
client.files.upload()per carregar el fitxer d'àudio (p. ex., MP3, WAV) o de vídeo (p. ex., MP4). - Inclou l'objecte de fitxer retornat en l'indicació a
generate_content.
L'exemple següent mostra com carregar un fitxer d'àudio i demanar al model que el transcrigui.
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. Crida de funcions: Ampliant les capacitats del model
Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»La crida de funcions, també coneguda com ús d'eines (tool use), és una tècnica poderosa que permet al model de llenguatge interactuar amb sistemes externs. Permet al model respondre preguntes o realitzar accions que van més enllà del seu coneixement inherent, com obtenir dades en temps real d'una API, consultar una base de dades o controlar un dispositiu.
El flux de treball general és el següent:
- Definir eines: Es defineix un conjunt d'eines (funcions de Python) que el model pot cridar. Aquesta definició inclou el nom de la funció, una descripció del que fa i l'esquema dels seus paràmetres.
- Passar eines al model: Es passa la llista d'eines definides al model en la crida a
generate_content. - El model decide cridar: El model analitza la indicació de l'usuari i, si determina que una de les eines proporcionades pot ajudar a respondre, en lloc de generar text, la seva resposta contindrà un objecte
Partde tipusfunction_call. Aquest objecte especifica el nom de la funció a cridar i els arguments amb els quals cridar-la. - Executar la funció: El codi de l'aplicació detecta aquesta
function_call, executa la funció de Python corresponent amb els arguments proporcionats i obté un resultat. - Devolver el resultat al model: Es realitza una segona crida a
generate_content, proporcionant l'historial de la conversa més el resultat de l'execució de la funció (envoltat en untypes.Part.from_function_response()). - Resposta final: El model utilitza el resultat de la funció per generar una resposta final en llenguatge natural per a l'usuari.
Encara que els fragments de recerca no proporcionen un exemple de codi de crida de funcions de punta a punta, l'estructura dels objectes Part per a function_call i function_response és la base per implementar aquest patró avançat.
Part 4: Preparació per a Producció: Gestió d'errors, seguretat i gestió
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»Aquesta part final proporciona la informació crítica necessària per construir aplicacions robustes, fiables i responsables.
4.1. Gestió robusta d'errors
Sección titulada «4.1. Manejo Robusto de Errores»En un entorn de producció, una gestió d'errors robusta no és negociable. Les trucades a l'API poden fallar per diverses raons, com credencials no vàlides, problemes de xarxa, esgotament de quotes o entrades malformades.
L'SDK utilitza el sistema d'excepcions estàndard de Python. La majoria d'errors relacionats amb l'API es poden capturar utilitzant un bloc try...except que busca excepcions del mòdul google.api_core.exceptions o, si està disponible, una classe més específica com 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}")En capturar una excepció, l'objecte d'excepció sovint conté informació valuosa per al registre i la depuració, com un codi d'estat i un missatge descriptiu.
És important considerar que els missatges d'error, tot i que són útils per als desenvolupadors, poden ser una arma de doble tall. Poden filtrar detalls de la implementació interna que podrien ser explotats en atacs adversos. Per exemple, un anàlisi dels missatges d'error de validació de seguretat podria revelar llargs interns o mecanismes de defensa, ajudant un actor malintencionat a eludir les proteccions. Per tant, tot i que els errors s'han de registrar exhaustivament al backend, la informació presentada als usuaris finals s'ha de controlar amb cura. Sovint és més segur mostrar un missatge genèric com “S'ha produït un error en processar la seva sol·licitud” en lloc d'exposar el missatge d'error brut de l'API.
La següent taula resume els codis d'error de l'API més comuns i com resoldre'ls.
Taula 3: Códigs d'error comuns de l'API i resolucions
| Codi HTTP | Status | Causa probable | Acció recomanada en Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | El cos de la sol·licitud està malformat (p. ex., un paràmetre amb un tipus incorrecte, un camp obligatori absent). | Comproveu que els paràmetres a GenerateContentConfig i el format de contents siguin correctes. Assegureu-vos que el model sigui compatible amb les característiques sol·licitades. |
| 403 | PERMISSION_DENIED | La clau de l'API és incorrecta, no té els permisos necessaris o està intentant accedir a un recurs restringit (p. ex., un model ajustat). | Comproveu que la clau de l'API (o l'autenticació ADC per a Vertex) estigui configurada correctament i tingui els permisos necessaris. |
| 429 | RESOURCE_EXHAUSTED | S'ha excedit el límit de velocitat de l'API (sol·licituds per minut). | Implementeu una retirada exponencial (exponential backoff) en la vostra lògica de reintents. Considereu sol·licitar un augment de quota si és necessari per a la vostra aplicació. |
| 500 | INTERNAL | S'ha produït un error inesperat al costat de Google. A vegades pot ser causat per un context d'entrada molt llarg. | Redueix la longitud de l'indicació. Torna a intentar la sol·licitud després d'una breu espera. Si el problema persisteix, considera canviar a un model diferent temporalment. |
| 503 | UNAVAILABLE | El servei està temporalment sobrecarregat o no disponible. | Torna a intentar la sol·licitud després d'una breu espera utilitzant una estratègia de retirada exponencial. Si el problema persisteix, informa del problema. |
4.2. Gestió de la seguretat del contingut
Sección titulada «4.2. Gestión de la Seguridad del Contenido»L'API de Gemini inclou característiques de seguretat integrades per filtrar contingut potencialment perillós. Aquestes característiques estan dissenyades per ajudar els desenvolupadors a construir aplicacions més segures i responsables.
L'API classifica el contingut en quatre categories principals de dany:
- Assetjament (
HARM_CATEGORY_HARASSMENT) - Incitatió a l'odi (
HARM_CATEGORY_HATE_SPEECH) - Contingut sexualment explícit (
HARM_CATEGORY_SEXUALLY_EXPLICIT) - Contingut perillós (
HARM_CATEGORY_DANGEROUS_CONTENT)
Per a cada categoria, el model assigna una probabilitat que el contingut sigui insegur. Per defecte, l'API bloqueja les indicacions i respostes que tenen una probabilitat MEDIUM o HIGH de ser insegures en qualsevol d'aquestes categories.
Els desenvolupadors poden anular aquesta configuració predeterminada per sol·licitud passant una llista d'objectes SafetySetting al paràmetre safety_settings. Això permet un control granular sobre l'umbral de bloqueig per a cada 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}")Quan una resposta sembli buida o es produeixi un error, és crucial inspeccionar la retroalimentació de seguretat. L'objecte de resposta conté prompt_feedback (per a l'indicació d'entrada) i candidates.safety_ratings (per a la resposta generada). Aquests atributs revelaran si el contingut va ser bloquejat i per què, la qual cosa és essencial per a la depuració.
La següent taula aclarirà el significat dels diferents llindars de bloqueig.
Taula 4: Llindars de configuració de seguretat
| Constant de l'API | Configuració a Google AI Studio | Descripció |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | El llindar no està especificat; s'utilitza el llindar per defecte del model. |
BLOCK_NONE | Blocar res (Blocar cap) | Mai blocar contingut, independentment de la probabilitat que sigui insegur. S'ha d'utilitzar amb extrema precaució. |
BLOCK_ONLY_HIGH | Block few (Bloquejar pocs) | Bloquejar només quan la probabilitat de contingut insegur és HIGH. |
BLOCK_MEDIUM_AND_ABOVE | Block some (Bloquejar alguns) | (Predeterminat per a la majoria de models) Bloquejar quan la probabilitat de contingut insegur és MEDIUM o HIGH. |
BLOCK_LOW_AND_ABOVE | Block most (Bloquejar la majoria) | Bloquejar quan la probabilitat de contingut insegur és LOW, MEDIUM o HIGH. |
4.3. Gestió de Models
Sección titulada «4.3. Gestión de Modelos»L'SDK proporciona una manera programàtica de descobrir els models disponibles i les seves capacitats. Això és útil per construir aplicacions que es puguin adaptar a diferents models o per verificar les capacitats d'un model abans d'utilitzar-lo.
El mètode client.models.list() retorna un iterador sobre els models disponibles.
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)Aquesta funcionalitat també es pot utilitzar per llistar específicament els models que han estat ajustats (fine-tuned) per l'usuari, establint query_base=False a la configuració de la sol·licitud de llista. Això permet a les aplicacions descobrir i utilitzar dinàmicament models personalitzats.
Part 5: Validació de l'entorn i checklist tècnica
Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»Per finalitzar l'aprovisionament d'integracions basades en l'SDK unificat google-genai al tenant de Portelcore, valida el compliment dels següents fites tècniques:
- He migrat tots els scripts del tenant de la biblioteca obsoleta
google-generativeaial nou estàndardgoogle-genai. ✓ - Les claus d'API estan gestionades exclusivament a través de la variable d'entorn
GOOGLE_API_KEYu ofuscades al gestor de secrets de Google Cloud en lloc d'escriure-les en text pla. ✓ - S'implementa un control d'excepcions robust (
google.api_core.exceptions) per capturar codis d'estat 429 (Resource Exhausted) amb polítiques de reintent exponencial (exponential backoff). ✓ - La temperatura i els llindars de seguretat (
safety_settings) estan parametrizats formalment d'acord amb el cas d'ús del dominiportelcore.com. ✓

