Python SDK Google GenAI pro API Gemini
Referenční příručka a pokročilé nastavení pro nové jednotné SDK google-genai pro API Gemini v Portelcore.
Část 1: Základní koncepty a počáteční konfigurace
Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»Tato sekce stanovuje kontext pro nové SDK, řeší hlavní zmatky uživatelů ohledně změny knihovny a poskytuje robustní návod pro správný začátek, pokrývající instalaci a dvě kritické cesty autentizace.
1.1. Nový standard: Migrace z google-generativeai na google-genai
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»Ekosystém vývoje pro modely generativní AI od Googlu se vyvinul. Knihovna google-genai je nyní oficiální, sjednocené a doporučené Python SDK pro interakci s Gemini API a dalšími modely generativní AI od Googlu. Dosáhla obecné dostupnosti (GA) v květnu 2025 a nahrazuje starší knihovnu google-generativeai.
Předchozí knihovna google-generativeai byla v Python Package Index (PyPI) označena jako „Neaktivní“ a nachází se na cestě k zastarání. Podpora pro tento balíček, včetně oprav kritických chyb, skončí na konci září 2025, i když některé zdroje uvádějí o něco dřívější datum ukončení podpory, 31. srpna 2025. Vývojářům se doporučuje orientovat se podle dřívějšího data, aby zajistili hladký přechod.
Tato změna není pouhým přejmenováním, ale strategickou unifikací poháněnou zpětnou vazbou vývojářů. Cílem bylo vytvořit jednotné SDK, které zjednoduší přístup k celé řadě modelů generativní AI od Googlu (Gemini, Veo, Imagen atd.) a nabídne jasnější a konzistentnější vývojovou cestu. Jedním z nejvýznamnějších rozhodnutí při návrhu nového SDK google-genai je, že funguje jako jednotné rozhraní pro dvě odlišné backendové služby: snadno přístupné vývojářské API Gemini a podnikovou platformu Vertex AI.
Tato jednotná architektura poskytuje vývojářům plynulý nástup. Mohou začít rychle, často s bezplatnou úrovní, pomocí API klíče pro vývojářské API Gemini. Jak jejich aplikace dozrávají a vyžadují vyšší škálovatelnost, správu a integraci s dalšími službami Google Cloud, mohou přejít na backend Vertex AI s minimálními změnami v kódu, především při inicializaci klienta. SDK google-genai funguje jako most, který snižuje vstupní bariéru a zároveň poskytuje jasnou cestu k produkci v Google Cloud. Proto se všem uživatelům starší knihovny doporučuje migrovat, aby si zajistili přístup k nejnovějším funkcím (jako Live API a Veo), vylepšení výkonu a nepřetržitou podporu.
1.2. Instalace a prostředí
Sección titulada «1.2. Instalación y Entorno»Před instalací SDK se doporučuje nakonfigurovat virtuální prostředí Pythonu. To izoluje závislosti projektu a zabraňuje konfliktům s jinými projekty nebo systémovými balíčky.
Pro vytvoření a aktivaci virtuálního prostředí pomocí venv:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateJakmile je virtuální prostředí aktivní, lze pomocí pip nainstalovat nejnovější verzi Google Gen AI SDK. Použití značky --upgrade zajišťuje získání nejnovější verze.
pip install --upgrade google-genaiJe nezbytné vzít v úvahu požadavky na verzi Pythonu. SDK google-genai vyžaduje Python 3.9 nebo novější. Použití nekompatibilní verze může způsobit neočekávané chyby během instalace nebo za běhu.
Pro aplikace vyžadující vysoký výkon asynchronního zpracování nabízí SDK možnost použít aiohttp jako HTTP transportní backend místo výchozího httpx. To lze nainstalovat jako doplněk (extra):
pip install google-genai[aiohttp]1.3. Autentizace: Váš klíč k rozhraní Gemini API
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»Autentizace je nejdůležitějším konfiguračním krokem a metoda se liší podle toho, kterou backendovou službu plánujete použít: Gemini Developer API nebo Gemini API ve Vertex AI.
1.3.1. Cesta přes Gemini Developer API (doporučeno pro prototypování a bezplatnou úroveň)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»Toto je nejrychlejší způsob, jak začít stavět s Gemini. Vyžaduje API klíč, který lze zdarma získat v Google AI Studio.
Proces získání API klíče je následující:
- Přejděte na (https://ai.google.dev/) a přihlaste se pomocí Google účtu.
- Klikněte na „Get API key“ (Získat API klíč).
- Vyberte možnost vytvoření API klíče v novém nebo stávajícím projektu Google Cloud.
- API klíč bude vygenerován automaticky.
API klíče jsou citlivé přihlašovací údaje a musí se s nimi zacházet jako s hesly. Musí být bezpečně uloženy a nesmí být nikdy odhaleny v kódu na straně klienta ani potvrzeny v systémech pro veřejné verzování.
Nejjistější a doporučený způsob použití klíče je nastavení jako proměnná prostředí. SDK je navrženo tak, aby automaticky detekovalo a používalo proměnné prostředí GOOGLE_API_KEY nebo GEMINI_API_KEY. Pokud jsou obě nastavena, má přednost GOOGLE_API_KEY.
Pro nastavení proměnné prostředí:
-
V Linuxu/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 -
Ve Windows: Použijte grafické rozhraní „Proměnné prostředí“ v nastavení systému pro přidání nové uživatelské nebo systémové proměnné s názvem
GOOGLE_API_KEYs vaším klíčem jako hodnotou.
1.3.2. Cesta přes Vertex AI (doporučeno pro produkci a integraci s Google Cloud)
Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»Pro aplikace v produkčním měřítku, které vyžadují firemní funkce Google Cloud, se doporučuje používat API Gemini prostřednictvím Vertex AI. Tento přístup vyžaduje projekt Google Cloud s povoleným fakturováním.
Počáteční kroky konfigurace zahrnují:
- Vybrat nebo vytvořit projekt Google Cloud.
- Ujistěte se, že pro projekt je povolena fakturace.
- Povolte Vertex AI API (
aiplatform.googleapis.com) pro projekt.
Autentizace pro Vertex AI může probíhat dvěma způsoby:
-
Přednastavené pověření aplikace (ADC) (doporučeno pro produkci): Tento je preferovaná metoda pro většinu produkčních scénářů. ADC automaticky najde pověření podle prostředí. V lokálním vývojovém prostředí lze toto nakonfigurovat spuštěním příkazu gcloud CLI:
Ventana de terminal gcloud auth application-default loginPři spuštění v prostředí Google Cloud (např. Cloud Run, Google Kubernetes Engine, Cloud Functions) používá ADC automaticky služební účet přidružený k danému zdroji, čímž eliminuje potřebu spravovat klíče.
-
Klíče API (pro testování ve Vertex): Je možné použít klíč API k ověření u endpointu Vertex AI, ale proces je složitější než u API vývojáře. Vyžaduje oprávnění na úrovni organizace k povolení vytváření klíčů API servisních účtů, vytvoření servisního účtu s vhodnou rolí (například
Vertex AI User), a poté vytvoření klíče API omezeného na tento servisní účet. Kvůli své složitosti se tato metoda obvykle používá pro specifické testovací scénáře namísto obecného vývoje aplikací.
1.4. Inicializace klienta: Připojení k modelu
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»Jakmile je autentizace nakonfigurována, dalším krokem je vytvoření instance objektu genai.Client. Sjednocené SDK to usnadňuje tím, že poskytuje jediného klienta, který lze nakonfigurovat pro jakýkoli ze dvou backendů.
Níže je uvedeno čtyři hlavní scénáře pro inicializaci klienta.
-
Scénář 1: Gemini Developer API (explicitní klíč) Tato metoda je vhodná pro notebooky nebo rychlé skripty, kde není třeba konfigurovat proměnné prostředí. API klíč je předáván přímo jako argument.
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
Scénář 2: Gemini Developer API (proměnná prostředí) Toto je nejčistší a doporučený přístup pro kód aplikace, protože odděluje přihlašovací údaje od kódu. Klient automaticky najde a použije proměnnou prostředí
GOOGLE_API_KEY.# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
Scénář 3: Vertex AI API (explicitní parametry) Pro připojení k Vertex AI se přepínač
vertexainastaví naTruea poskytne se ID projektu a lokalita. Tato metoda automaticky použije Aplikační výchozí údaje (ADC) pro autentizaci.from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
Scénář 4: Vertex AI API (proměnné prostředí) Jako alternativu k Vertex AI lze konfiguraci externalizovat do proměnných prostředí. Klient tyto proměnné detekuje a bude nakonfigurován tak, aby používal backend 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()
Následující tabulka tyto metody shrnuje pro rychlý přehled.
Tabulka 1: Rychlá reference inicializace klienta
| Případ použití | Python kód | Vyžadované proměnné prostředí | Poznámky |
|---|---|---|---|
| Vývojářské API s explicitním klíčem | client = genai.Client(api_key="SU_CLAVE...") | Žádné | Vhodné pro notebooky a rychlé testování. Vyhýbejte se v produkčním kódu. |
| Developer API s proměnnými prostředí | client = genai.Client() | GOOGLE_API_KEY nebo GEMINI_API_KEY | Preferovaná metoda pro čistý a bezpečný aplikační kód. |
| Vertex AI s explicitními parametry | client = genai.Client(vertexai=True, project="...", location="...") | Žádná (používá ADC) | Explicitní metoda pro cílení na Vertex AI. Vyžaduje autentizaci ADC (gcloud auth...). |
| Vertex AI s proměnnými prostředí | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Konfiguruje klienta pro Vertex AI bez parametrů v kódu. Vyžaduje autentizaci ADC. |
Část 2: Hlavní schopnosti: Text a chat
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»Tato část se zaměřuje na nejčastější případy použití: generování textu a vytváření konverzačních agentů. Podrobně popisuje hlavní metody a související objekty.
2.1. Generování obsahu: Metoda generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»Hlavní metodou pro všechny jednoturntové generovací úkoly je client.models.generate_content(). Tato všestranná metoda je základem pro interakci s modely Gemini.
Základní použití zahrnuje poskytnutí jednoduchého textového řetězce, jako je contents, a specifikaci názvu použitého modelu, jako je 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)Ačkoliv je poskytnutí jednoduchého řetězce pohodlné, je zásadní porozumět podkladové struktuře dat, kterou SDK používá. Interně SDK převádí všechny vstupy do standardizované struktury složené z objektů types.Content a types.Part. Porozumění této struktuře je klíčové pro odemknutí pokročilých schopností SDK, jako jsou multimodální podněty a volání funkcí.
types.Content: Reprezentuje jednu zprávu nebo tah v konverzaci. Má dva hlavní atributy:role(obvykle 'user' pro vstup nebo 'model' pro výstup) a seznamparts.types.Part: Reprezentuje kus dat uvnitř objektuContent. Tato část může tvořit text, obrazová data, odkaz na soubor, volání funkce atd.
SDK inteligentně zpracovává různé typy vstupů pro argument contents a převádí je do příslušného formátu Content/Part:
- Jeden řetězec:
contents='¿Por qué el cielo es azul?'se převede naUserContents jednímParttextu. - Seznam řetězců:
contents=['Pregunta 1', 'Pregunta 2']se převede na jedenUserContent, který obsahuje dvaParttextu. - Objekt
types.Part: Umožňuje detailnější kontrolu, například specifikaci dat obrázku. - Úplně vytvořený objekt
types.Content: Poskytuje maximální kontrolu nad rolí a obsahem zprávy.
Pro přístup k vygenerované odpovědi je nejjednodušší metodou pomocný přístupový parametr response.text. Je však důležité vědět, že tento přístupový parametr funguje pouze pro jednoduché odpovědi, které se skládají z jedné části textu. Pokud je odpověď blokována bezpečnostními filtry, obsahuje více kandidátů nebo zahrnuje netextové datové typy, pokus o přístup k response.text způsobí chybu. Robustnějším a bezpečnějším způsobem pro produkci je přístup přímo k kandidátovi a jeho částem:
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. Streamované odpovědi pro zpětnou vazbu v reálném čase
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»U interaktivních aplikací, jako jsou chatboty, streamování odpovědi modelu dramaticky zlepšuje uživatelský zážitek. Místo čekání na vygenerování celé odpovědi se textové fragmenty zobrazují jakmile přicházejí, což poskytuje okamžitou zpětnou vazbu.
Tato funkce je dosaženo pomocí metody generate_content_stream(). Tato metoda vrací iterátor, který produkuje fragmenty odpovědi, jak je model generuje.
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. Ovládání konverzační AI: Chatové rozhraní
Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»SDK poskytuje dva hlavní mechanismy pro správu vícestupňových konverzací. Jedním z přístupů je manuální správa historie konverzace vytvořením seznamu objektů Content, které představují každý krok, a jeho předávání do generate_content() při každém volání. Ačkoliv je tento způsob flexibilní, může být náročný na implementaci.
Doporučeným a nejvhodnějším přístupem pro vytváření chatbotů je použití stavového chatového rozhraní poskytovaného client.chats. Tento objekt nejvyšší úrovně abstrahuje správu historie a výrazně zjednodušuje kód aplikace. Toto je záměrné rozhodnutí o návrhu v rámci SDK: poskytnout vysokoúrovňovou stavovou abstrakci (client.chats) pro běžný případ použití (chat), což nesmírně usnadňuje vývoj ve srovnání s nízkoúrovňovou bezstavovou metodou generate_content.
Pracovní postup pro použití chatového rozhraní je následující:
- Inicializace chatovací relace: K zahájení nové konverzace se používá
client.chats.create(). Lze specifikovat model a volitelně poskytnout počáteční historii pro kontextualizaci konverzace. - Odesílání zpráv: Metoda
chat.send_message()se používá k odeslání další zprávy uživatele. SDK automaticky spravuje stav tím, že přidává zprávu uživatele a následnou odpověď modelu do historie konverzace. - Přístup k historii: Během jakékoli doby lze pomocí
chat.get_history()získat celou historii konverzace.
Níže je uveden úplný příklad vícestupňové konverzace:
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. Pokročilé ovládání generování
Sección titulada «2.4. Control Avanzado de la Generación»Pro vyladění chování modelu metoda generate_content přijímá parametr config, který přijímá objekt types.GenerateContentConfig. Tento objekt umožňuje vývojářům ovládat různé aspekty procesu generování.
Jedním z nejužitečnějších nastavení je system_instruction. Systémová instrukce poskytuje vysokoúrovňový průvodce nebo nastavuje osobnost modelu, která přetrvává po celou konverzaci. Například modelu lze instruovat, aby jednal jako konkrétní postava nebo aby v odpovědích dodržoval určitá pravidla.
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)Kromě systémových instrukcí existuje několik dalších parametrů, které lze upravit pro ovládání kreativity a struktury výstupu modelu. Následující tabulka podrobně uvádí ty nejdůležitější.
Tabulka 2: Klíčové parametry konfigurace generování
| Parametr | Popis | Rozsah | Vliv na výstup |
|---|---|---|---|
temperature | Ovládá náhodnost výběru tokenů. | 0.0 - 1.0 | Nižší hodnoty (např. 0.2) činí výstup determinističtějším a méně kreativním. Vyšší hodnoty (např. 0.9) zvyšují náhodnost a kreativitu. |
top_p | Nucleus sampling (vzorkování jádra). Bere v úvahu nejmenší množinu tokenů, jejichž kumulativní pravděpodobnost je vyšší než top_p. | 0.0 - 1.0 | Hodnota jako 0.95 znamená, že jsou zvažovány pouze ty tokeny, které tvoří horních 95 % pravděpodobnostní hmoty. Pomáhá to vyhnout se velmi nepravděpodobným tokenům. |
top_k | Zvažuje pouze k nejpravděpodobnějších tokenů v každém kroku generování. | Celé číslo | top_k 1 je greedy (hladové) dekódování. Hodnota jako 40 omezuje výběr na 40 nejpravděpodobnějších tokenů. |
candidate_count | Počet kandidátních odpovědí k vygenerování. | Celé číslo (např. 1-8) | Generuje více možných odpovědí pro stejný prompt. Užitečné pro nabízení možností uživateli. |
max_output_tokens | Maximální počet tokenů, které lze ve odpovědi vygenerovat. | Celé číslo | Omezuje délku výstupu. Je nezbytné pro kontrolu nákladů a latence. |
stop_sequences | Seznam řetězců, které po vygenerování zastaví výstup. | Seznam řetězců | Užitečné pro zastavení generování v konkrétním bodě, jako je značka konce věty nebo určité formátování. |
seed | Náhodné semeno pro generování. | Celé číslo | Poskytnutí semena činí výstup deterministickým a reprodukovatelným (pokud temperature není 0). |
Část 3: Pokročilé interakce: Multimodalita a volání funkcí
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»Tato část ukazuje skutečnou sílu modelů Gemini tím, že vysvětluje, jak pracovat s netextovými vstupy a jak připojit model k externím nástrojům.
3.1. Za hranicemi textu: Pochopení multimodálních vstupů
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Jednou z definujících vlastností rodiny modelů Gemini je jejich vrozená multimodální schopnost. To znamená, že dokážou zpracovávat a uvažovat o různých typech dat, neboli „modalitách“, jako je text, obrázky, zvuk a video, v rámci jednoho promptu.
Tato schopnost je umožněna tím, že se argument contents sestaví jako seznam obsahující více objektů Part, přičemž každý Part může obsahovat jiný typ dat. Například jeden požadavek může obsahovat obrázek a textový dotaz k tomuto obrázku.
3.2. Práce s obrázky
Sección titulada «3.2. Trabajando con Imágenes»SDK poskytuje dva strategicky odlišné metody pro manipulaci s daty obrázků. Výběr mezi nimi závisí na konkrétních požadavcích daného použití, jako je velikost souboru a opětovné použití.
Tato dualita metodů není redundancí, ale záměrným návrhem, který řeší různé provozní potřeby. Inline metoda je jednoduchá a vynikající pro jednorázové analýzy a pohodlí při vývoji. File API, ačkoliv vyžaduje další krok načítání, je zásadní pro produkční scénáře, kde jsou prioritou efektivita, škálovatelnost a manipulace s velkými soubory.
Metoda 1: Inline obrazová data (Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»Tato metoda je ideální pro menší obrazové soubory (celková žádost, včetně promptů a bajtů, musí být menší než 20 MB) a pro jednoduchost vývoje. Obrazová data se předávají přímo při volání generate_content.
-
Z místního souboru: Obrazový soubor je čten v binárním režimu (
'rb') a předán dotypes.Part.from_bytes(), přičemž je specifikován správný MIME typ.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) -
Z URL: K získání bajtů obrázku z URL lze použít knihovnu jako
requestsa poté je předat stejným způsobem.
Metoda 2: Files API (API pro soubory)
Sección titulada «Método 2: La API de Archivos (Files API)»Tato metoda se doporučuje pro velké obrazové soubory (nad 20 MB) nebo pro scénáře, kdy je stejný soubor znovu využíván v mnoha požadavcích na prompt. Použití Files API eliminuje potřebu znovu nahrávat stejné bajty při každém volání.
Pracovní postup se skládá ze dvou kroků:
- Nahrát:
client.files.upload()se používá k nahrání souboru na servery Google. Tato metoda vrací objekt souboru, který funguje jako reference. - Promptovat: Vrácený objekt souboru se předá přímo do seznamu
contentspři volánígenerate_content. SDK se postará o vyřešení reference na nahráný soubor.
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}")Soubory nahrané prostřednictvím API pro soubory jsou dočasně uloženy po dobu 48 hodin, než jsou automaticky smazány. API také poskytuje metody pro správu těchto souborů, jako jsou get(), list() a delete().
3.3. Interakce s audiem a videem
Sección titulada «3.3. Interacción con Audio y Vídeo»Koncepty manipulace s obrázky se přímo vztahují na další formáty, jako je audio a video. Vzhledem k tomu, že tyto soubory bývají velké, je API pro soubory hlavním způsobem jejich zpracování.
Proces je identický jako u velkých obrázků:
- Pro nahrání audio souboru (např. MP3, WAV) nebo video souboru (např. MP4) použijte
client.files.upload(). - Zahrňte vrácený objekt souboru do promptu pro
generate_content.
Následující příklad ukazuje, jak nahrát zvukový soubor a požádat model, aby jej přepsal.
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. Volání funkcí: Rozšiřování schopností modelu
Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»Volání funkcí, známé také jako používání nástrojů (tool use), je mocná technika, která umožňuje jazykovému modelu interagovat s externími systémy. Umožňuje modelu odpovídat na otázky nebo provádět akce, které přesahují jeho vrozené znalosti, jako je získávání dat v reálném čase z rozhraní API, dotazování se v databázi nebo ovládání zařízení.
Obecný pracovní postup je následující:
- Definování nástrojů: Definuje se sada nástrojů (funkcí Python), které může model volat. Tato definice zahrnuje název funkce, popis toho, co dělá, a schéma jejích parametrů.
- Předání nástrojů modelu: Seznam definovaných nástrojů se předává modelu při volání
generate_content. - Model se rozhodne volat: Model analyzuje uživatelský prompt a pokud zjistí, že některý z poskytnutých nástrojů může pomoci s odpovědí, místo generování textu bude jeho odpověď obsahovat objekt
Parttypufunction_call. Tento objekt specifikuje název funkce, kterou má být zavolána, a argumenty pro její vyvolání. - Spuštění funkce: Kód aplikace detekuje
function_call, spustí odpovídající funkci Python s poskytnutými argumenty a získá výsledek. - Vrácení výsledku modelu: Proběhne druhé volání
generate_content, které poskytne historii konverzace spolu s výsledkem spuštění funkce (obaleným vtypes.Part.from_function_response()). - Finální odpověď: Model využije výsledek funkce k vygenerování finální odpovědi v přirozeném jazyce pro uživatele.
Ačkoliv výzkumné úryvky neposkytují příklad end-to-end volání funkcí, struktura objektů Part pro function_call a function_response je základem pro implementaci tohoto pokročilého vzoru.
Část 4: Příprava na produkci: Řízení chyb, bezpečnost a správa
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»Tato závěrečná část poskytuje kritické informace potřebné k budování robustních, spolehlivých a zodpovědných aplikací.
4.1. Robustní řízení chyb
Sección titulada «4.1. Manejo Robusto de Errores»V produkčním prostředí je robustní řízení chyb nekompromisní. Volání API může selhat z různých důvodů, jako jsou neplatné přihlašovací údaje, problémy se sítí, vyčerpání kvót nebo nesprávně formulované vstupy.
SDK využívá standardní systém výjimek Pythonu. Většinu chyb souvisejících s API lze zachytit pomocí bloku try...except, který hledá výjimky v modulu google.api_core.exceptions nebo, pokud je k dispozici, konkrétnější třídu, jako je 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}")Při zachycení výjimky obsahuje objekt výjimky často cenné informace pro logování a ladění, jako je stavový kód a popisná zpráva.
Je důležité zvážit, že chybové zprávy, ačkoliv jsou užitečné pro vývojáře, mohou být mečem s dvěma stranami. Mohou odhalit detaily interní implementace, které mohou být zneužity při útocích. Například analýza chybových zpráv z validace bezpečnosti by mohla odhalit interní prahy nebo obranné mechanismy, což by злоčinci pomohlo obejít ochrany. Proto by chyby měly být v backendu podrobně logovány, ale informace prezentované koncovým uživatelům musí být pečlivě kontrolovány. Často je bezpečnější zobrazit obecnou zprávu, jako je „Při zpracování požadavku došlo k chybě“, místo aby se vystavila surová chybová zpráva z API.
Následující tabulka shrnuje nejčastější chybové kódy API a způsoby jejich řešení.
Tabulka 3: Nejčastější chybové kódy API a jejich řešení
| HTTP kód | Stav | Pravděpodobná příčina | Doporučená akce v Pythonu |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | Tělo požadavku je neplatné (např. parametr s nesprávným typem, chybějící povinné pole). | Zkontrolujte, zda jsou parametry v GenerateContentConfig a formát contents správné. Ujistěte se, že model je kompatibilní s požadovanými vlastnostmi. |
| 403 | PERMISSION_DENIED | API klíč je neplatný, nemáte potřebná oprávnění nebo se pokoušíte o přístup k omezenému zdroji (např. laděný model). | Zkontrolujte, zda je API klíč (nebo autentizace ADC pro Vertex) správně nakonfigurován a zda má potřebná oprávnění. |
| 429 | RESOURCE_EXHAUSTED | Limit rychlosti API (počet požadavků za minutu) byl překročen. | Implementujte exponentiální odstup (exponential backoff) ve své logice opakování pokusů. Pokud je to pro vaši aplikaci nutné, zvažte žádost o zvýšení kvóty. |
| 500 | INTERNAL | Na straně Google došlo k neočekávané chybě. Někdy může být způsobena příliš dlouhým vstupním kontextem. | Zkraťte délku promptu. Po krátké době znovu zkuste požadavek odeslat. Pokud problém přetrvává, zvažte dočasnou změnu na jiný model. |
| 503 | UNAVAILABLE | Služba je dočasně přetížená nebo nedostupná. | Zkuste požadavek znovu po krátkém čekání pomocí strategie exponentiálního odstupování. Pokud problém přetrvává, nahlaste jej. |
4.2. Správa bezpečnosti obsahu
Sección titulada «4.2. Gestión de la Seguridad del Contenido»API Gemini obsahuje integrované bezpečnostní funkce pro filtrování potenciálně škodlivého obsahu. Tyto funkce jsou navrženy tak, aby pomohly vývojářům vytvářet bezpečnější a zodpovědnější aplikace.
API klasifikuje obsah do čtyř hlavních kategorií škodlivosti:
- Obelžnost (
HARM_CATEGORY_HARASSMENT) - Podněcování k nenávisti (
HARM_CATEGORY_HATE_SPEECH) - Sexuálně explicitní obsah (
HARM_CATEGORY_SEXUALLY_EXPLICIT) - Nebezpečný obsah (
HARM_CATEGORY_DANGEROUS_CONTENT)
Pro každou kategorii model přiřazuje pravděpodobnost, že obsah bude nebezpečný. Ve výchozím nastavení API blokuje dotazy a odpovědi, které mají pravděpodobnost MEDIUM nebo HIGH, že budou v některé z těchto kategorií nebezpečné.
Vývojáři mohou toto výchozí nastavení přebít na úrovni jednotlivých požadavků tím, že do parametru safety_settings předají seznam objektů SafetySetting. To umožňuje jemné ovládání prahu blokování pro každou kategorii.
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}")Pokud se zdá, že odpověď je prázdná, nebo dojde k chybě, je zásadní zkontrolovat zpětnou vazbu k bezpečnosti. Objekt odpovědi obsahuje prompt_feedback (pro vstupní prompt) a candidates.safety_ratings (pro vygenerovanou odpověď). Tyto atributy odhalí, zda byla obsah zablokována a proč, což je pro ladění nezbytné.
Následující tabulka vysvětluje význam jednotlivých prahů blokování.
Tabulka 4: Prahy konfigurace bezpečnosti
| Konstanta API | Konfigurace v Google AI Studio | Popis |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | Práh není specifikován; používá se výchozí práh modelu. |
BLOCK_NONE | Nezablokovat nic (Nezablokovat nic) | Obsah nikdy nezablokujte, bez ohledu na pravděpodobnost, že je nebezpečný. Používejte s velkou opatrností. |
BLOCK_ONLY_HIGH | Blokovat málo (Blokovat málo) | Blokovat pouze v případě, že pravděpodobnost nebezpečného obsahu je HIGH. |
BLOCK_MEDIUM_AND_ABOVE | Blokovat některé (Blokovat některé) | (Výchozí pro většinu modelů) Blokovat, pokud je pravděpodobnost nebezpečného obsahu MEDIUM nebo HIGH. |
BLOCK_LOW_AND_ABOVE | Blokovat většinu (Blokovat většinu) | Blokovat, pokud je pravděpodobnost nebezpečného obsahu LOW, MEDIUM nebo HIGH. |
4.3. Správa modelů
Sección titulada «4.3. Gestión de Modelos»SDK poskytuje programatický způsob, jak zjistit dostupné modely a jejich schopnosti. To je užitečné pro vytváření aplikací, které se mohou přizpůsobit různým modelům, nebo pro ověření schopností modelu před jeho použitím.
Metoda client.models.list() vrací iterátor dostupných modelů.
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)Tuto funkcionalitu lze také použít k výčtu konkrétních modelů, které uživatel doladil (fine-tuned), nastavením query_base=False v konfiguraci požadavku na výčet. To umožňuje aplikacím dynamicky objevovat a využívat personalizované modely.
Část 5: Validace prostředí a technický checklist
Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»Pro dokončení provizování integrací založených na jednotném SDK google-genai v tenantu Portelcore ověřte dodržení následujících technických milníků:
- Migroval jsem všechny skripty z tenantu ze zastaralé knihovny
google-generativeaina nový standardgoogle-genai. ✓ - API klíče jsou spravovány výhradně prostřednictvím proměnné prostředí
GOOGLE_API_KEYnebo jsou v Secret Manageru Google Cloud obfuskovány, místo aby byly zapsány v prostém textu. ✓ - Je implementována robustní kontrola výjimek (
google.api_core.exceptions) pro zachycení stavových kódů 429 (Resource Exhausted) s politikou exponenciálního zpětného zažehování (exponential backoff). ✓ - Teplota a bezpečnostní prahy (
safety_settings) jsou formálně parametrizovány v souladu s případem užití doményportelcore.com. ✓

