Ir al contenido
Vyznač

Python SDK Google GenAI pre API Gemini

Referenčný sprievodca a pokročilá konfigurácia pre nový jednotný SDK google-genai API Gemini v Portelcore.

Technická náročnosť:
0lecturas

Časť 1: Základné koncepcie a počiatočná konfigurácia

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

Táto časť stanovuje kontext pre nový SDK, rieši hlavnú zmätok používateľa týkajúcu sa zmeny knižnice a poskytuje robustného sprievodcu pre začatie správne, pokrývajúc inštaláciu a dve kritické cesty autentifikácie.

1.1. Nový štandard: Migrácia 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ývoja pre modely generatívnej AI spoločnosti Google sa vyvinul. Knižnica google-genai je teraz oficiálnym, zjednoteným a odporúčaným Python SDK pre interakciu s Gemini API a ďalšími modelmi generatívnej AI spoločnosti Google. Dosiahla všeobecnú dostupnosť (GA) v máji 2025 a nahrádza staršiu knižnicu google-generativeai.

Predchádzajúca knižnica, google-generativeai, bola označená ako „neaktívna“ v PyPI a nachádza sa na ceste k zastaraniu. Podpora pre tento balík, vrátane kritických opráv chýb, bude ukončená koncom septembra 2025, hoci niektoré zdroje uvádzajú mierne skorší dátum ukončenia podpory, 31. august 2025. Vývojárom sa odporúča, aby prešli na skorší dátum, aby sa zabezpečil hladký prechod.

Táto zmena nie je len premenovanie, ale strategické zjednotenie pohonom používateľských komentárov. Cieľom bolo vytvorenie jediného SDK, ktorý zjednodušuje prístup k celej škále modelov generatívnej AI spoločnosti Google (Gemini, Veo, Imagen atď.) a ponúka jasnejšiu a konzistentnejšiu vývojovú cestu. Jedným z významných návrhov nového SDK google-genai je, že funguje ako jednotné rozhranie pre dva rôzne backendové služby: ľahko dostupnú Gemini vývojársku API a podnikovej úrovne Vertex AI platformu.

Táto zjednotená architektúra poskytuje hladký vstup pre vývojárov. Môžu rýchlo začať, často s bezplatnou úrovňou, pomocou kľúča API pre Gemini vývojársku API. Ako ich aplikácie dozrievajú a vyžadujú väčšiu škálovateľnosť, správu a integráciu s ďalšími službami Google Cloud, môžu prejsť na Vertex AI backend s minimálnymi zmenami v kóde, hlavne v inicializácii klienta. SDK google-genai funguje ako most, znižuje vstupnú bariéru a poskytuje jasnú cestu k produkcii v Google Cloud. Preto sa vyzývajú všetci používatelia staršej knižnice, aby prešli na novú knižnicu, aby sa zabezpečil prístup k najnovším funkciám (ako Live API a Veo), vylepšeniam výkonu a priebežnej podpore.

Pred inštaláciou SDK je odporúčané nakonfigurovať virtuálne prostredie Python. Tým sa izolujú závislosti projektu, čím sa predchádza konfliktom s inými projektmi alebo systémovými balíkmi.

Ak chcete vytvoriť a aktivovať virtuálne prostredie pomocou 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

Keď je virtuálne prostredie aktívne, môže byť nainštalovaná najnovšia verzia Google Gen AI SDK pomocou pip. Použitie príznaku --upgrade zabezpečuje, že sa získa najnovšia verzia.

Ventana de terminal
pip install --upgrade google-genai

Je dôležité vziať do úvahy požiadavky na verziu Python. SDK google-genai vyžaduje Python 3.9 alebo vyšší. Použitie nekompatibilnej verzie môže spôsobiť neočakávané chyby počas inštalácie alebo spustenia.

Pre aplikácie vyžadujúce vysokovýkonný asynchrónny výkon ponúka SDK možnosť použiť aiohttp ako backend pre HTTP transport namiesto predvoleného httpx. To môže byť nainštalované ako extra:

Ventana de terminal
pip install google-genai[aiohttp]

Autentifikácia je najdôležitejší krok konfigurácie a metóda sa líši v závislosti na použitom backend servise: Gemini Developer API alebo Gemini API vo Vertex AI.

1.3.1. Cesta vývojára Gemini API (odporúčaná pre prototypy a bezplatnú ú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 najrýchlejší spôsob, ako začať stavať s Gemini. Vyžaduje si API kľúč, ktorý možno získať zadarmo z Google AI Studio.

Proces získania kľúča API je nasledujúci:

  1. Prejdite na (https://ai.google.dev/) a prihláste sa pomocou účtu Google.
  2. Kliknite na „Získať API kľúč“ (Get API key).
  3. Vyberte si vytvorenie API kľúča v novom alebo existujúcom projekte Google Cloud.
  4. API kľúč bude vygenerovaný automaticky.

API kľúče sú citlivé poverenia a mali by sa považovať za heslá. Mali by sa bezpečne uložiť a nikdy nezverejniť v klientskom kóde alebo potvrdiť vo verejných systémoch správy verzií.

Najbezpečnejší a odporúčaný spôsob použitia kľúča je nakonfigurovať ho ako premennú prostredia. SDK je navrhnutý tak, aby automaticky detekoval a používal premenné prostredia GOOGLE_API_KEY alebo GEMINI_API_KEY. Ak sú obe nakonfigurované, GOOGLE_API_KEY má prioritu.

Ak chcete nakonfigurovať premennú prostredia:

  • V systéme 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
  • V systéme Windows: Použite grafické rozhranie „Premenné prostredia“ v nastaveniach systému na pridanie novej premennej používateľa alebo systému s názvom GOOGLE_API_KEY s vaším kľúčom ako hodnotou.

1.3.2. Cesta cez Vertex AI (odporúčaná pre produkciu a integráciu 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)»

Pre produkčné aplikácie, ktoré vyžadujú podnikové funkcie Google Cloud, sa odporúča používať Gemini API cez Vertex AI. Tento prístup vyžaduje projekt Google Cloud s povolenou fakturáciou.

Prvé kroky konfigurácie zahŕňajú:

  1. Výber alebo vytvorenie projektu Google Cloud.
  2. Uistenie, že fakturácia je povolená pre projekt.
  3. Povolenie Vertex AI API (aiplatform.googleapis.com) pre projekt.

Autentifikácia pre Vertex AI sa môže vykonať dvoma spôsobmi:

  • Predvolené poverenia aplikácie (ADC) (odporúčané pre produkciu): Toto je preferovaná metóda pre väčšinu produkčných scenárov. ADC automaticky nájde poverenia na základe prostredia. V lokálnom vývojárskom prostredí to môže byť nakonfigurované spustením príkazu gcloud CLI :

    Ventana de terminal
    gcloud auth application-default login

    Keď sa spustí v prostredí Google Cloud (napríklad Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC automaticky používa priradený servisný účet, čím eliminuje potrebu spravovať kľúče.

  • Kľúče API (pre testovanie vo Vertex): Je možné použiť kľúč API na autentifikáciu na koncovom bode Vertex AI, ale proces je zložitejší ako pri vývojárskom API. Vyžaduje povolenia na úrovni organizácie na povolenie vytvárania kľúčov API servisných účtov, vytvorenie servisného účtu s vhodnou rolou (napríklad Vertex AI User), a potom vytvorenie kľúča API obmedzeného na tento servisný účet. Vzhľadom na jeho zložitosť sa táto metóda zvyčajne používa pre konkrétne testovacie scenáre namiesto všeobecného vývoja aplikácií.

Keď je autentifikácia nakonfigurovaná, ďalším krokom je inštancovanie objektu genai.Client. Unified SDK zjednodušuje toto poskytovaním jediného klienta, ktorý môže byť nakonfigurovaný pre ktorýkoľvek z týchto dvoch backendov.

Nasledujú štyri hlavné scenáre pre inicializáciu klienta.

  • Scenár 1: Gemini Developer API (Explicitný kľúč) Táto metóda je vhodná pre rýchle notebooky alebo skripty, kde nechcete konfigurovať premenné prostredia. Kľúč API sa prenáša priamo ako argument.

    from google import genai
    client = genai.Client(api_key="SU_CLAVE_DE_API_AQUI")
  • Scenár 2: Gemini Developer API (Premenná prostredia) Tento prístup je najčistejší a odporúčaný pre aplikačný kód, pretože oddeluje poverenia od kódu. Klient automaticky nájde a použije premennú prostredia GOOGLE_API_KEY.

    # Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configurada
    from google import genai
    client = genai.Client()
  • Scenár 3: Vertex AI API (Explicitné parametre) Pre pripojenie k Vertex AI sa indikátor vertexai nastaví na True a poskytne sa ID projektu a umiestnenie. Táto metóda automaticky použije predvolené poverenia aplikácie (ADC) pre autentifikáciu.

    from google import genai
    client = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1")
  • Scenár 4: Vertex AI API (Premenné prostredia) Ako alternatíva pre Vertex AI môže byť konfigurácia externalizovaná do premenných prostredia. Klient detekuje tieto premenné a nakonfiguruje sa na použitie backendu 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()

Nasledujúca tabuľka sumarizuje tieto metódy pre rýchlu referenciu.

Tabuľka 1: Rýchla referencia inicializácie klienta

Použitie prípaduKód PythonPožadované premenné prostrediaPoznámky
Vývojársky API s explicitným kľúčomclient = genai.Client(api_key="SU_CLAVE...")ŽiadneÚžitkové pre notebooky a rýchle testy. Vyhnite sa v produkčnom kóde.
Vývojárske API s premennými prostrediaclient = genai.Client()GOOGLE_API_KEY alebo GEMINI_API_KEYPreferovaná metóda pre čistý a bezpečný aplikačný kód.
Vertex AI s explicitnými parametramiclient = genai.Client(vertexai=True, project="...", location="...")Žiadne (používa ADC)Explicitná metóda pre cielený Vertex AI. Vyžaduje autentifikáciu ADC (gcloud auth...).
Vertex AI s premennými prostrediaclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONKonfiguruje klienta pre Vertex AI bez parametrov v kóde. Vyžaduje autentifikáciu ADC.

Táto časť sa ponorí do najbežnejších prípadov použitia: generovanie textu a vytváranie konverzačných agentov. Opisuje hlavné metódy a objekty.

Hlavná metóda pre všetky úlohy generovania jedného tahu je client.models.generate_content(). Táto všestranná metóda je základom pre interakciu s modelmi Gemini.

Základné použitie zahŕňa poskytnutie jednoduchého textového reťazca ako contents a špecifikáciu názvu modelu, ktorý sa má použiť, ako 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)

Aj keď je prechod jednoduchého reťazca pohodlný, je dôležité pochopiť základnú štruktúru údajov, ktorú používa SDK. Interné SDK konvertuje všetky vstupy do štandardizovanej štruktúry, ktorá pozostáva z objektov types.Content a types.Part. Pochopenie tejto štruktúry je kľúčom k odomknutiu pokročilých funkcií SDK, ako sú multimodálne výzvy a funkčné volania.

  • types.Content: Predstavuje jednu správu alebo ťah v konverzácii. Má dva hlavné atribúty: role (zvyčajne 'user' pre vstup alebo 'model' pre výstup) a zoznam parts.
  • types.Part: Predstavuje kus údajov v rámci objektu Content. Časť môže byť text, obrazové dáta, referencia súboru, funkčné volanie atď.

SDK inteligentne spracováva rôzne typy vstupov pre argument contents, konvertujúc ich do vhodného formátu Content/Part:

  • Jednoduchý reťazec: contents='¿Por qué el cielo es azul?' sa konvertuje na UserContent s jednou Part textu.
  • Zoznam reťazcov: contents=['Pregunta 1', 'Pregunta 2'] sa konvertuje na jeden UserContent, ktorý obsahuje dve Part textu.
  • Objekt types.Part: Umožňuje podrobnejšie ovládanie, ako je špecifikácia obrazových údajov.
  • Úplne vytvorený objekt types.Content: Poskytuje maximálne ovládanie nad rolou a obsahom správy.

Na prístup k vygenerovanej odpovedi je pohodlný prístup response.text najjednoduchšou metódou. Avšak je dôležité vedieť, že tento prístup funguje iba pre jednoduché odpovede, ktoré pozostávajú z jednej časti textu. Ak je odpoveď zablokovaná bezpečnostnými filtrami, obsahuje viac kandidátov alebo zahŕňa netextové typy údajov, prístup k response.text vyvolá chybu. Najrobustnejšia a najbezpečnejšia metóda pre produkciu je priamo pristupovať ku kandidátovi a jeho častiam:

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é odpovede pre spätnú väzbu v reálnom čase

Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»

Pre interaktívne aplikácie, ako sú chatboty, streamovanie odpovede modelu dramaticky zlepšuje používateľský zážitok. Namiesto čakania na vygenerovanie celej odpovede sa časti textu zobrazujú podľa toho, ako prichádzajú, poskytujúc okamžitú spätnú väzbu.

Táto funkcionalita sa dosahuje metódou generate_content_stream(). Táto metóda vracia iterátor, ktorý produkuje časti odpovede v reálnom čase.

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

SDK poskytuje dva hlavné mechanizmy pre správu viacnásobných konverzácií. Jeden prístup je manuálne spravovať históriu konverzácie, vytvárať zoznam objektov Content, ktoré predstavujú každý ťah a prechádzajú do generate_content() pri každom volaní. Aj keď je flexibilný, tento prístup môže byť ťažkopádny.

Odporúčaný a pohodlný prístup pre vytváranie chatbotov je využitie rozhrania chatu s stavom poskytnutého client.chats. Tento objekt na vyššej úrovni abstrahuje správu histórie, výrazne zjednodušuje kód aplikácie. Toto je zámerné dizajnové rozhodnutie v SDK: poskytnúť vysokú úroveň abstrakcie a stavu (client.chats) pre bežný prípad použitia (chat), čo výrazne zjednodušuje vývoj v porovnaní s nízkouhlovým a bezstavovým prístupom generate_content.

Tok pracovného postupu pre použitie rozhraní chatu je nasledujúci:

  1. Inicializácia chatovej relácie: client.chats.create() sa používa na spustenie novej konverzácie. Môžete špecifikovať model a voliteľne poskytnúť počiatočný kontext pre konverzáciu.
  2. Odoslanie správ: Metóda chat.send_message() sa používa na odoslanie ďalšej správy používateľa. SDK automaticky spravuje stav, pridáva správu používateľa a následnú odpoveď modelu do histórie konverzácie.
  3. Prístup k histórii: V každom okamihu môžete získať kompletnú históriu konverzácie pomocou chat.get_history().

Nasleduje kompletný príklad viacotáčkovej konverzácie:

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

Na dolaďovanie správania modelu metóda generate_content akceptuje parameter config, ktorý preberá objekt types.GenerateContentConfig. Tento objekt umožňuje vývojárom ovládať rôzne aspekty procesu generovania.

Jedným z najužitočnejších nastavení je system_instruction. Systémová inštrukcia poskytuje vysokú úroveň vedenia alebo nastavuje osobnosť pre model, ktorý pretrváva počas celej konverzácie. Napríklad môžete instruovať model, aby konal ako konkrétna postava alebo aby dodržiaval určité pravidlá vo svojich odpovediach.

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)

Okrem systémových inštrukcií existuje niekoľko ďalších parametrov, ktoré možno upraviť pre ovládanie kreativity a štruktúry výstupu modelu. Nasledujúca tabuľka podrobne popisuje najdôležitejšie.

Tabuľka 2: Kľúčové parametre konfigurácie generovania

ParametrPopisRozsahVplyv na výstup
temperatureOvláda náhodnosť výberu tokenov.0.0 - 1.0Nízke hodnoty (napr. 0.2) robia výstup viac deterministickým a menej kreatívnym. Vyššie hodnoty (napr. 0.9) zvyšujú náhodnosť a kreativitu.
top_pVýber jadra (nucleus sampling). Zvažuje najmenšiu množinu tokenov, ktorých kumulatívna pravdepodobnosť je väčšia ako top_p.0.0 - 1.0Hodnota ako 0.95 znamená, že sa zvažujú len tokeny, ktoré tvoria 95% hornej časti pravdepodobnostnej hmoty. Pomáha vyhnúť sa veľmi nepravdepodobným tokenom.
top_kZvažuje len k najpravdepodobnejších tokenov v každom kroku generovania.Celé číslotop_k z 1 je chamtivá dekódovanie. Hodnota ako 40 obmedzuje výber na 40 najpravdepodobnejších tokenov.
candidate_countPočet kandidátskych odpovedí na vygenerovanie.Celé číslo (napr. 1-8)Generuje viac možných odpovedí pre rovnakú výzvu. Užitočné pre ponuku používateľovi.
max_output_tokensMaximálny počet tokenov, ktoré možno vygenerovať v odpovedi.Celé čísloObmedzuje dĺžku výstupu. Základné pre ovládanie nákladov a latencie.
stop_sequencesSeznam reťazcov, ktoré pri vygenerovaní zastavia výstup.Seznam reťazcovUžitočné pre zastavenie generovania v konkrétnom bode, ako je značka konca vety alebo konkrétny formát.
seedNáhodné semeno pre generovanie.Celé čísloPoskytnutie semena robí výstup deterministickým a reprodukovateľným (pokiaľ temperature nie je 0).

Časť 3: Pokročilé interakcie: Multimodalita a volanie funkcií

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

Táto časť ukazuje skutočnú silu modelov Gemini tým, že vysvetľuje, ako pracovať s netextovými vstupmi a pripojiť model k externým nástrojom.

Jednou z definujúcich charakteristík rodiny modelov Gemini je ich inherentná multimodálna schopnosť. To znamená, že môžu spracovať a uvažovať o rôznych typoch údajov alebo „modalitách“, ako je text, obrázky, zvuk a video, v rámci jednej výzvy.

Táto schopnosť sa umožňuje konštrukciou argumentu contents ako zoznamu obsahujúceho viacero objektov Part, kde každý Part môže obsahovať iný typ údajov. Napríklad jedna výzva môže obsahovať obrázok a textovú otázku o tomto obrázku.

SDK poskytuje dva strategicky odlišné metódy pre spracovanie obrazových údajov. Výber medzi nimi závisí od konkrétnych požiadaviek použitia, ako je veľkosť súboru a opätovné použitie.

Táto dualita metód nie je redundanciou, ale zámerným návrhom, ktorý rieši rôzne prevádzkové potreby. Inline metóda je jednoduchá a vhodná pre jediné analýzy a pohodlie vo vývoji. API súborov, hoci vyžaduje ďalší krok nahrávania, je nevyhnutné pre produkčné scenáre, kde je účinnosť, škálovateľnosť a spracovanie veľkých súborov prvoradé.

Táto metóda je ideálna pre menšie súbory obrázkov (celá požiadavka, vrátane výziev a bajtov, musí byť nižšia ako 20 MB) a pre jednoduchosť vo vývoji. Údaje obrázku sa priamo prenášajú do volania generate_content.

  • Od lokálneho súboru: Súbor obrázka sa číta v binárnom režime ('rb') a odovzdá sa do types.Part.from_bytes(), pričom sa špecifikuje správny typ MIME.

    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 adresy URL: Môžete použiť knižnicu ako requests na získanie bajtov obrázka z adresy URL a potom ich odovzdať rovnakým spôsobom.

Táto metóda sa odporúča pre veľké obrazové súbory (nad 20 MB) alebo pre scenáre, v ktorých bude rovnaký súbor znovu použitý vo viacerých výzvach. Použitie API súborov zabraňuje potrebe znovu nahrávať rovnaké bajty s každým volaním.

Pracovný postup pozostáva z dvoch krokov:

  1. Nahrávanie: Používa sa client.files.upload() na nahrávanie súboru na servery Google. Táto metóda vráti objekt súboru, ktorý funguje ako referencia.
  2. Výzva: Vrátený objekt súboru sa priamo odovzdá do zoznamu contents volania generate_content. SDK sa stará o rozlíšenie referencie na nahraný súbor.
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}")

Súbory nahrané cez API súborov sa dočasne ukladajú počas 48 hodín pred automatickým odstránením. API tiež poskytuje metódy na správu týchto súborov, ako napríklad get(), list() a delete().

Koncepty spracovania obrazu sa priamo rozšíria na iné modality, ako je zvuk a video. Pretože tieto súbory sú zvyčajne veľké, API súborov je hlavnou metódou pre prácu s nimi.

Postup je identický s postupom pre veľké obrázky:

  1. Použite client.files.upload() na nahrávanie zvukového súboru (napr. MP3, WAV) alebo videosúboru (napr. MP4).
  2. Zahrňte vrátený objekt súboru do výzvy pre generate_content.

Nasledujúci príklad ukazuje, ako nahrať zvukový súbor a požiadať model, aby ho prepisoval.

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)

Volanie funkcií, tiež známe ako použitie nástrojov, je výkonná technika, ktorá umožňuje jazykovému modelu interagovať s externými systémami. Umožňuje modelu odpovedať na otázky alebo vykonávať akcie, ktoré idú za hranice jeho vlastných znalostí, ako je získavanie údajov v reálnom čase z API, dotazovanie databáze alebo ovládanie zariadenia.

Všeobecný pracovný postup je nasledujúci:

  1. Definovať nástroje: Definuje sa súbor nástrojov (funkcií Python), ktoré môže model zavolať. Táto definícia zahŕňa názov funkcie, popis toho, čo robí, a schéma jej parametrov.
  2. Odovzdať nástroje modelu: Zoznam definovaných nástrojov sa odovzdá modelu pri volaní generate_content.
  3. Model sa rozhodne zavolať: Model analyzuje výzvu používateľa a ak určí, že jeden z poskytnutých nástrojov môže pomôcť odpovedať, namiesto generovania textu bude jeho odpoveď obsahovať objekt Part typu function_call. Tento objekt špecifikuje názov funkcie, ktorá sa má zavolať, a argumenty, s ktorými sa má zavolať.
  4. Vykonať funkciu: Kód aplikácie detekuje túto function_call, vykoná zodpovedajúcu funkciu Python s poskytnutými argumentmi a získava výsledok.
  5. Vrátiť výsledok modelu: Vykoná sa druhé volanie generate_content, poskytujúce históriu konverzácie plus výsledok vykonania funkcie (zabalený do types.Part.from_function_response()).
  6. Konečná odpoveď: Model používa výsledok funkcie na vygenerovanie konečnej odpovede v prirodzenom jazyku pre používateľa.

Aj keď výskumné fragmenty neposkytujú príklad kódu volania funkcií od začiatku do konca, štruktúra objektov Part pre function_call a function_response je základom pre implementáciu tohto pokročilého vzoru.


Časť 4: Príprava na produkciu: Spracovanie chýb, zabezpečenie a riadenie

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

Táto záverečná časť poskytuje kritické informácie potrebné na vytvorenie robustných, spoľahlivých a zodpovedných aplikácií.

V produkčnom prostredí nie je robustné spracovanie chýb diskutabilné. Volania API môžu zlyhať z rôznych dôvodov, ako sú neplatné poverenia, problémy so sieťou, vyčerpanie kvót alebo nesprávne vytvorené vstupy.

SDK používa štandardný systém výnimiek Pythonu. Väčšina chýb súvisiacich s API môže byť zachytená pomocou bloku try...except, ktorý hľadá výnimky z modulu google.api_core.exceptions alebo, ak je k dispozícii, konkrétnejšiu triedu, ako 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}")

Pri zachytávaní výnimky často objekt výnimky obsahuje cenné informácie pre protokolovanie a ladenie, ako je kód stavu a popisná správa.

Es importante considerar que los mensajes de error, si bien son útiles para los desarrolladores, pueden ser una espada de doble filo. Pueden filtrar detalles de implementación interna que podrían ser explotados en ataques adversarios. Por ejemplo, un análisis de los mensajes de error de validación de seguridad podría revelar umbrales internos o mecanismos de defensa, ayudando a un actor malicioso a eludir las protecciones. Por lo tanto, si bien los errores deben registrarse exhaustivamente en el backend, la información presentada a los usuarios finales debe ser cuidadosamente controlada. A menudo es más seguro mostrar un mensaje genérico como “Ocurrió un error al procesar su solicitud” en lugar de exponer el mensaje de error sin procesar de la API.

Nasledujúca tabuľka sumarizuje najbežnejšie kódy chýb API a ako ich vyriešiť.

Tabla 3: Códigos de Error Comunes de la API y Resoluciones

Kód HTTPStavPravdepodobná príčinaOdporúčaná akcia v Pythone
400INVALID_ARGUMENTTelo žiadosti je nesprávne vytvorené (napr. parameter s nesprávnym typom, chýbajúci povinný poľ)Verifique que los parámetros en GenerateContentConfig y el formato de contents sean correctos. Asegúrese de que el modelo sea compatible con las características solicitadas.
403PERMISSION_DENIEDKľúč API je nesprávny, nemáte potrebné povolenia alebo sa pokúšate o prístup k obmedzenému zdroju (napr. vyladený model)Overte, či je kľúč API (alebo autentifikácia ADC pre Vertex) správne nakonfigurovaný a či máte potrebné povolenia.
429RESOURCE_EXHAUSTEDBola prekročená rýchlostná kvóta API (žiadosti za minútu).Implementujte exponenciálne oneskorenie vo svojej logike opätovného pokusu. Zvážte požiadanie o zvýšenie kvóty, ak je to potrebné pre vašu aplikáciu.
500INTERNALNastala neočakávaná chyba na strane Google. Niekedy môže byť spôsobená veľmi dlhým vstupným kontextom.Znížte dĺžku indikácie. Pokúste sa znova o požiadavku po krátkom oneskorení. Ak problém pretrváva, zvážte dočasné prepnutie na iný model.
503UNAVAILABLEServis je dočasne preťažený alebo nedostupný.Pokúste sa znova o požiadavku po krátkom oneskorení pomocou stratégie exponenciálneho oneskorenia. Ak problém pretrváva, nahláste problém.

API Gemini obsahuje zabudované bezpečnostné funkcie na filtrovanie potenciálne škodlivého obsahu. Tieto funkcie sú navrhnuté tak, aby pomohli vývojárom vytvárať bezpečnejšie a zodpovednejšie aplikácie.

API klasifikuje obsah do štyroch hlavných kategórií poškodenia:

  • Acoso (HARM_CATEGORY_HARASSMENT)
  • Incitación al odio (HARM_CATEGORY_HATE_SPEECH)
  • Contenido sexualmente explícito (HARM_CATEGORY_SEXUALLY_EXPLICIT)
  • Contenido peligroso (HARM_CATEGORY_DANGEROUS_CONTENT)

Para cada categoría, el modelo asigna una probabilidad de que el contenido sea inseguro. Por defecto, la API bloquea las indicaciones y respuestas que tienen una probabilidad MEDIUM o HIGH de ser inseguras en cualquiera de estas categorías.

Los desarrolladores pueden anular esta configuración predeterminada por solicitud pasando una lista de objetos SafetySetting al parámetro safety_settings. Esto permite un control granular sobre el umbral de bloqueo para cada categoría.

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

Cuando una respuesta parece vacía o se produce un error, es crucial inspeccionar la retroalimentación de seguridad. El objeto de respuesta contiene prompt_feedback (para la indicación de entrada) y candidates.safety_ratings (para la respuesta generada). Estos atributos revelarán si el contenido fue bloqueado y por qué, lo cual es esencial para la depuración.

Nasledujúca tabuľka objasňuje význam rôznych prahov blokovania.

Tabla 4: Umbrales de Configuración de Seguridad

Konštanta rozhrania APIKonfigurácia v Google AI StudioPopis
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/APrah nie je špecifikovaný; používa sa predvolený prah modelu.
BLOCK_NONEBlock none (Zablokovať žiadne)Nikdy neblokovať obsah, bez ohľadu na pravdepodobnosť, že je nebezpečný. Mali by sa používať s extrémnou opatrnosťou.
BLOCK_ONLY_HIGHBlock few (Zablokovať niektoré)Zablokovať iba vtedy, ak pravdepodobnosť nebezpečného obsahu je HIGH.
BLOCK_MEDIUM_AND_ABOVEBlock some (Zablokovať niektoré)(Predvolené pre väčšinu modelov) Zablokovať, keď pravdepodobnosť nebezpečného obsahu je MEDIUM alebo HIGH.
BLOCK_LOW_AND_ABOVEBlock most (Zablokovať väčšinu)Zablokovať, keď pravdepodobnosť nebezpečného obsahu je LOW, MEDIUM alebo HIGH.

SDK poskytuje programový spôsob objavovania dostupných modelov a ich schopností. To je užitočné pre vytváranie aplikácií, ktoré sa môžu prispôsobiť rôznym modelom alebo pre overenie schopností modelu pred jeho použitím.

Metóda client.models.list() vracia iterátor nad dostupnými modelmi.

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)

Táto funkcionalita sa dá použiť aj na konkrétne vymenovanie modelov, ktoré boli vylepšené používateľom, nastavením query_base=False v konfigurácii žiadosti o zoznam. To umožňuje aplikáciám dynamicky objavovať a používať vlastné modely.


Časť 5: Overenie prostredia a technický kontrolný zoznam

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

Na dokončenie poskytovania integrácií založených na unifikovanom SDK google-genai v nájomcovi Portelcore overte splnenie nasledujúcich technických míľnikov:

  • Migroval som všetky skripty z nájomcovej knižnice zastaralej google-generativeai na nový štandard google-genai. ✓
  • Kľúče rozhrania API sú spravované výlučne prostredníctvom premennej prostredia GOOGLE_API_KEY alebo sú utajené v správcovi tajom stlačenia Google Cloud namiesto toho, aby boli zapísané ako čistý text. ✓
  • Implementovaný je robustný výnimkový kontrol (google.api_core.exceptions) na zachytávanie stavových kódov 429 (vyčerpaný zdroj) s exponenciálnymi politikami opakovania. ✓
  • Teplota a bezpečnostné prahy (safety_settings) sú formálne parametrizované v súlade s prípadom použitia domény portelcore.com. ✓