Ir al contenido
Doporučené

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.

Technická náročnost:
0čtení

Čá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.

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:

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

Jakmile 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.

Ventana de terminal
pip install --upgrade google-genai

Je 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):

Ventana de terminal
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í:

  1. Přejděte na (https://ai.google.dev/) a přihlaste se pomocí Google účtu.
  2. Klikněte na „Get API key“ (Získat API klíč).
  3. Vyberte možnost vytvoření API klíče v novém nebo stávajícím projektu Google Cloud.
  4. 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_KEY s 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í:

  1. Vybrat nebo vytvořit projekt Google Cloud.
  2. Ujistěte se, že pro projekt je povolena fakturace.
  3. 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 login

    Př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í.

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 genai
    client = 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é configurada
    from google import genai
    client = genai.Client()
  • Scénář 3: Vertex AI API (explicitní parametry) Pro připojení k Vertex AI se přepínač vertexai nastaví na True a poskytne se ID projektu a lokalita. Tato metoda automaticky použije Aplikační výchozí údaje (ADC) pro autentizaci.

    from google import genai
    client = 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=true
    export GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'
    export GOOGLE_CLOUD_LOCATION='us-central1'
    # El cliente se configurará automáticamente para Vertex AI
    from google import genai
    client = genai.Client()

Následující tabulka tyto metody shrnuje pro rychlý přehled.

Tabulka 1: Rychlá reference inicializace klienta

Případ použitíPython kódVyžadované proměnné prostředíPoznámky
Vývojářské API s explicitním klíčemclient = 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_KEYPreferovaná metoda pro čistý a bezpečný aplikační kód.
Vertex AI s explicitními parametryclient = 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_LOCATIONKonfiguruje klienta pro Vertex AI bez parametrů v kódu. Vyžaduje autentizaci ADC.

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.

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ó anteriormente
response = 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 seznam parts.
  • types.Part: Reprezentuje kus dat uvnitř objektu Content. 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 na UserContent s jedním Part textu.
  • Seznam řetězců: contents=['Pregunta 1', 'Pregunta 2'] se převede na jeden UserContent, který obsahuje dva Part textu.
  • 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 inicializado
response_stream = client.models.generate_content_stream(
model="gemini-2.0-flash",
contents="Escribe un poema largo sobre el océano y sus misterios."
)
print("Respuesta del modelo:")
for chunk in response_stream:
print(chunk.text, end="")
print() # Para una nueva línea al final

2.3. 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í:

  1. 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.
  2. 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.
  3. 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 chat
chat_session = client.chats.create(
model="gemini-2.0-flash"
)
# 2. Enviar el primer mensaje
print("Usuario: Hola, ¿puedes ayudarme a planificar un viaje a la luna?")
response = chat_session.send_message("Hola, ¿puedes ayudarme a planificar un viaje a la luna?")
print(f"Modelo: {response.text}\n")
# 3. Enviar un segundo mensaje de seguimiento
print("Usuario: ¿Qué tres cosas debería empacar?")
response = chat_session.send_message("¿Qué tres cosas debería empacar?")
print(f"Modelo: {response.text}\n")
# 4. Mostrar el historial completo de la conversación
print("--- Historial de la Conversación ---")
for message in chat_session.get_history():
# El rol y el texto están en message.role y message.parts.text
role = "Usuario" if message.role == "user" else "Modelo"
print(f"{role}: {message.parts.text}")

2.4. 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 inicializado
response = client.models.generate_content(
model='gemini-2.0-flash',
contents='¡Ah del barco! Cuéntame un chiste sobre un loro.',
config=types.GenerateContentConfig(
system_instruction='Hablas como un pirata malhumorado y conciso.'
)
)
print(response.text)

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í

ParametrPopisRozsahVliv na výstup
temperatureOvládá náhodnost výběru tokenů.0.0 - 1.0Nižší 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_pNucleus sampling (vzorkování jádra). Bere v úvahu nejmenší množinu tokenů, jejichž kumulativní pravděpodobnost je vyšší než top_p.0.0 - 1.0Hodnota 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_kZvažuje pouze k nejpravděpodobnějších tokenů v každém kroku generování.Celé číslotop_k 1 je greedy (hladové) dekódování. Hodnota jako 40 omezuje výběr na 40 nejpravděpodobnějších tokenů.
candidate_countPoč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_tokensMaximální počet tokenů, které lze ve odpovědi vygenerovat.Celé čísloOmezuje délku výstupu. Je nezbytné pro kontrolu nákladů a latence.
stop_sequencesSeznam ř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í.
seedNáhodné semeno pro generování.Celé čísloPoskytnutí 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.

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.

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 do types.Part.from_bytes(), přičemž je specifikován správný MIME typ.

    import google.genai as genai
    from google.genai import types
    # Asumiendo que 'client' ha sido inicializado
    with open('imagen_scones.jpg', 'rb') as f:
    image_bytes = f.read()
    image_part = types.Part.from_bytes(
    data=image_bytes,
    mime_type='image/jpeg'
    )
    prompt_part = "Describe lo que ves en esta imagen."
    # Combinar imagen y texto en una sola solicitud
    response = client.models.generate_content(
    model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-vision
    contents=[prompt_part, image_part]
    )
    print(response.text)
  • Z URL: K získání bajtů obrázku z URL lze použít knihovnu jako requests a poté je předat stejným způsobem.

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ů:

  1. Nahrát: client.files.upload() se používá k nahrání souboru na servery Google. Tato metoda vrací objekt souboru, který funguje jako reference.
  2. Promptovat: Vrácený objekt souboru se předá přímo do seznamu contents př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 Archivos
print("Cargando archivo...")
sample_file = client.files.upload(
file_path="imagen_grande.png",
display_name="Mi Imagen de Muestra"
)
print(f"Archivo cargado: {sample_file.uri}")
# 2. Usar el archivo cargado en una indicación
prompt = "Analiza esta imagen y describe los objetos principales y su disposición espacial."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=[prompt, sample_file] # Pasar el objeto de archivo directamente
)
print(response.text)
# Opcional: Eliminar el archivo después de su uso
client.files.delete(name=sample_file.name)
print(f"Archivo eliminado: {sample_file.name}")

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

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ů:

  1. Pro nahrání audio souboru (např. MP3, WAV) nebo video souboru (např. MP4) použijte client.files.upload().
  2. 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 genai
import time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audio
print("Cargando archivo de audio...")
audio_file = client.files.upload(
file_path="discurso_muestra.mp3",
display_name="Discurso de Muestra"
)
# El procesamiento del archivo puede llevar tiempo, se espera a que esté ACTIVO
while audio_file.state.name == "PROCESSING":
print("Procesando archivo... esperando.")
time.sleep(10)
audio_file = client.files.get(name=audio_file.name)
if audio_file.state.name == "FAILED":
raise ValueError(audio_file.state.name)
# 2. Usar el archivo de audio en una indicación
prompt = "Transcribe el discurso en este archivo de audio."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=[prompt, audio_file]
)
print("\n--- Transcripción ---")
print(response.text)

3.4. 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í:

  1. 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ů.
  2. Předání nástrojů modelu: Seznam definovaných nástrojů se předává modelu při volání generate_content.
  3. 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 Part typu function_call. Tento objekt specifikuje název funkce, kterou má být zavolána, a argumenty pro její vyvolání.
  4. 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.
  5. 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 v types.Part.from_function_response()).
  6. 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í.

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_exceptions
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
try:
response = client.models.generate_content(
model="nombre-de-modelo-invalido",
contents="¿Cuál es tu nombre?"
)
print(response.text)
except core_exceptions.GoogleAPICallError as e:
# 'e' es una superclase para muchos errores de API
print(f"Ha ocurrido un error en la API: {e}")
# En muchos casos, 'e' tendrá atributos como 'code' y 'message'
# aunque esto puede variar. Se recomienda inspeccionar el objeto de excepción.
except core_exceptions.NotFound as e:
# Un error más específico si se sabe qué buscar
print(f"Error: Recurso no encontrado. ¿Es correcto el nombre del modelo? - {e.message}")
except core_exceptions.ResourceExhausted as e:
# Específico para errores de cuota
print(f"Error: Se ha excedido la cuota de la API. - {e.message}")

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ódStavPravděpodobná příčinaDoporučená akce v Pythonu
400INVALID_ARGUMENTTě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.
403PERMISSION_DENIEDAPI 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í.
429RESOURCE_EXHAUSTEDLimit 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.
500INTERNALNa 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.
503UNAVAILABLESluž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.

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 APIKonfigurace v Google AI StudioPopis
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/APráh není specifikován; používá se výchozí práh modelu.
BLOCK_NONENezablokovat nic (Nezablokovat nic)Obsah nikdy nezablokujte, bez ohledu na pravděpodobnost, že je nebezpečný. Používejte s velkou opatrností.
BLOCK_ONLY_HIGHBlokovat málo (Blokovat málo)Blokovat pouze v případě, že pravděpodobnost nebezpečného obsahu je HIGH.
BLOCK_MEDIUM_AND_ABOVEBlokovat 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_ABOVEBlokovat většinu (Blokovat většinu)Blokovat, pokud je pravděpodobnost nebezpečného obsahu LOW, MEDIUM nebo HIGH.

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 inicializado
print("Modelos disponibles:")
for model in client.models.list():
# El objeto 'model' contiene metadatos detallados
print(f" - Nombre: {model.name}")
print(f" - Nombre para mostrar: {model.display_name}")
print(f" - Métodos soportados: {model.supported_generation_methods}")
# Verificar si el modelo soporta chat (create_chat)
if 'create_chat' in model.supported_generation_methods:
print(" - ¡Este modelo soporta chat!")
print("-" * 20)

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-generativeai na nový standard google-genai. ✓
  • API klíče jsou spravovány výhradně prostřednictvím proměnné prostředí GOOGLE_API_KEY nebo 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ény portelcore.com. ✓