Ir al contenido
Wyróżniony

Google GenAI Python SDK dla API Gemini

Przewodnik referencyjny i zaawansowana konfiguracja nowego, ujednoliconego SDK google-genai dla API Gemini w Portelcore.

Trudność techniczna:
0odwiedzin

Część 1: Podstawowe pojęcia i wstępna konfiguracja

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

Ta sekcja określa kontekst dla nowego SDK, adresując główną niepewność użytkowników dotyczącą zmiany biblioteki, oraz zapewnia solidny przewodnik, aby właściwie rozpocząć, obejmując instalację i dwie krytyczne ścieżki uwierzytelniania.

1.1. Nowy Standard: Migracja z google-generativeai do google-genai

Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»

Ekosystem rozwoju modeli generatywnej sztucznej inteligencji Google ewoluował. Biblioteka google-genai jest teraz oficjalnym, ujednoliconym i rekomendowanym SDK dla Python, służącym do interakcji z API Gemini oraz innymi modelami generatywnej sztucznej inteligencji Google. Osiągnęła ogólną dostępność (GA) w maju 2025 r. i zastępuje starszą bibliotekę google-generativeai.

Poprzednia biblioteka, google-generativeai, została oznaczona jako „Nieaktywna” w Python Package Index (PyPI) i znajduje się na ścieżce wycofywania. Wsparcie dla tego pakietu, w tym poprawki krytycznych błędów, zakończy się pod koniec września 2025 r., choć niektóre źródła wskazują na nieco wcześniejszą datę zakończenia wsparcia, 31 sierpnia 2025 r. Deweloperom zaleca się kierowanie do wcześniejszej daty, aby zapewnić płynne przejście.

Ta zmiana to nie tylko zmiana nazwy, lecz strategiczna unifikacja napędzana opiniami deweloperów. Celem było stworzenie pojedynczego SDK, które uprościłoby dostęp do całego wachlarza modeli generatywnej sztucznej inteligencji Google (Gemini, Veo, Imagen itp.) i zapewniło jaśniejszą oraz spójniejszą ścieżkę rozwoju. Jedną z najważniejszych decyzji projektowych nowego SDK google-genai jest to, że działa ono jako jednolity interfejs dla dwóch różnych usług backendowych: łatwo dostępnego API deweloperskiego Gemini oraz platformy Vertex AI na poziomie korporacyjnym.

Ta ujednolicona architektura zapewnia deweloperom płynny proces wchodzenia. Mogą oni szybko rozpocząć pracę, często korzystając z darmowego poziomu, używając klucza API dla deweloperskiego API Gemini. W miarę jak ich aplikacje dojrzewają i wymagają większej skalowalności, zarządzania oraz integracji z innymi usługami Google Cloud, mogą przejść na backend Vertex AI przy minimalnych zmianach w kodzie, głównie w zakresie inicjalizacji klienta. SDK google-genai działa jak most, obniżając barierę wejścia, jednocześnie zapewniając jasną ścieżkę do wdrożenia produkcyjnego w Google Cloud. Dlatego też wszystkich użytkowników starszej biblioteki zachęca się do migracji, aby zapewnić dostęp do najnowszych funkcji (takich jak Live API i Veo), ulepszeń wydajności oraz ciągłego wsparcia.

Przed instalacją SDK zaleca się skonfigurowanie wirtualnego środowiska Python. Pozwala to na odizolowanie zależności projektu, zapobiegając konfliktom z innymi projektami lub pakietami systemowymi.

Aby utworzyć i aktywować wirtualne środowisko przy użyciu 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

Po aktywacji środowiska wirtualnego można zainstalować najnowszą wersję SDK Google Gen AI, używając pip. Użycie flagi --upgrade zapewnia pobranie najnowszej wersji.

Ventana de terminal
pip install --upgrade google-genai

Należy pamiętać o wymaganiach dotyczących wersji Pythona. SDK google-genai wymaga wersji Python 3.9 lub nowszej. Użycie niekompatybilnej wersji może spowodować nieoczekiwane błędy podczas instalacji lub w czasie wykonywania programu.

W przypadku aplikacji wymagających wysokiej wydajności asynchronicznej, SDK oferuje możliwość użycia aiohttp jako backendu transportu HTTP zamiast domyślnego httpx. Można to zainstalować jako dodatkowe rozszerzenie :

Ventana de terminal
pip install google-genai[aiohttp]

Uwierzytelnianie jest najważniejszym krokiem konfiguracji, a metoda różni się w zależności od wybranej usługi backendowej: Gemini Developer API lub Gemini API w Vertex AI.

1.3.1. Ścieżka Gemini Developer API (Zalecana dla prototypów i darmowego poziomu)

Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»

Jest to najszybszy sposób na rozpoczęcie pracy z Gemini. Wymaga on klucza API, który można uzyskać bezpłatnie w Google AI Studio.

Proces uzyskiwania klucza API wygląda następująco :

  1. Przejdź do (https://ai.google.dev/) i zaloguj się za pomocą konta Google.
  2. Kliknij „Get API key” (Pobierz klucz API).
  3. Wybierz opcję utworzenia klucza API w nowym lub istniejącym projekcie Google Cloud.
  4. Klucz API zostanie wygenerowany automatycznie.

Klucze API są poufnymi danymi uwierzytelniającymi i należy je traktować jak hasła. Powinny być przechowywane w bezpieczny sposób i nigdy nie powinny być ujawniane w kodzie po stronie klienta ani zatwierdzane w publicznych systemach kontroli wersji.

Najbezpieczniejszą i zalecaną metodą użycia klucza jest skonfigurowanie go jako zmiennej środowiskowej. SDK jest zaprojektowane tak, aby automatycznie wykrywać i używać zmiennych środowiskowych GOOGLE_API_KEY lub GEMINI_API_KEY. Jeśli obie są skonfigurowane, priorytet ma GOOGLE_API_KEY.

Aby skonfigurować zmienną środowiskową:

  • W 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
  • W systemie Windows: Użyj interfejsu graficznego „Zmienne środowiskowe” w ustawieniach systemu, aby dodać nową zmienną użytkownika lub systemową o nazwie GOOGLE_API_KEY z kluczem jako wartością.

1.3.2. Ścieżka Vertex AI (Zalecana dla środowisk produkcyjnych i integracji z Google Cloud)

Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»

W przypadku aplikacji w skali produkcyjnej, które wymagają funkcji klasy korporacyjnej Google Cloud, zaleca się korzystanie z API Gemini za pośrednictwem Vertex AI. Podejście to wymaga projektu Google Cloud z włączonym rozliczaniem.

Pierwsze kroki konfiguracji obejmują:

  1. Wybierz lub utwórz projekt Google Cloud.
  2. Upewnij się, że fakturowanie jest włączone dla projektu.
  3. Włącz API Vertex AI (aiplatform.googleapis.com) dla projektu.

Uwierzytelnianie w Vertex AI można przeprowadzić na dwa sposoby:

  • Domyślne poświadczenia aplikacji (ADC) (Zalecane do produkcji): Jest to preferowana metoda dla większości scenariuszy produkcyjnych. ADC automatycznie znajduje poświadczenia w zależności od środowiska. W lokalnym środowisku deweloperskim można to skonfigurować, uruchamiając polecenie interfejsu wiersza poleceń gcloud:

    Ventana de terminal
    gcloud auth application-default login

    Po uruchomieniu w środowisku Google Cloud (np. Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC automatycznie używa konta usługi przypisanego do tego zasobu, co eliminuje konieczność zarządzania kluczami.

  • Klucze API (do testów w Vertex): Można użyć klucza API do uwierzytelnienia w punkcie końcowym Vertex AI, ale proces ten jest bardziej skomplikowany niż w przypadku API deweloperskiego. Wymaga uprawnień na poziomie organizacji do włączania tworzenia kluczy API kont usług, utworzenia konta usługi z odpowiednią rolą (np. Vertex AI User), a następnie utworzenia klucza API ograniczonego do tej konta usługi. Ze względu na swoją złożoność, metoda ta jest zazwyczaj używana w specyficznych scenariuszach testowych, a nie do ogólnego rozwoju aplikacji.

Po skonfigurowaniu uwierzytelniania kolejnym krokiem jest zainicjowanie obiektu genai.Client. Ujednolicony zestaw SDK upraszcza ten proces, dostarczając pojedynczego klienta, który można skonfigurować dla dowolnego z dwóch backendów.

Poniżej przedstawiono cztery główne scenariusze inicjalizacji klienta.

  • Scenariusz 1: API dla programistów Gemini (jawny klucz) Ta metoda jest wygodna dla notatników lub szybkich skryptów, w których nie chce się konfigurować zmiennych środowiskowych. Klucz API jest przekazywany bezpośrednio jako argument.

    from google import genai
    client = genai.Client(api_key="SU_CLAVE_DE_API_AQUI")
  • Scenariusz 2: API dla programistów Gemini (zmienna środowiskowa) Jest to najczystsze i najbardziej zalecane podejście dla kodu aplikacji, ponieważ oddziela dane uwierzytelniające od kodu. Klient automatycznie znajduje i wykorzystuje zmienną środowiskową GOOGLE_API_KEY.

    # Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configurada
    from google import genai
    client = genai.Client()
  • Scenariusz 3: API Vertex AI (jawne parametry) Aby połączyć się z Vertex AI, flagę vertexai ustawia się na True oraz podaje się identyfikator projektu i lokalizację. Metoda ta automatycznie użyje domyślnych poświadczeń aplikacji (ADC) do uwierzytelnienia.

    from google import genai
    client = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1")
  • Scenariusz 4: API Vertex AI (Zmienne środowiskowe) Jako alternatywę dla Vertex AI, konfigurację można wyprowadzić do zmiennych środowiskowych. Klient wykryje te zmienne i zostanie skonfigurowany tak, aby korzystać z 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()

Poniższa tabela podsumowuje te metody w celu szybkiego odniesienia.

Tabela 1: Szybka referencja inicjalizacji klienta

Przypadek użyciaKod PythonWymagane zmienne środowiskoweUwagi
API programisty z jawnym kluczemclient = genai.Client(api_key="SU_CLAVE...")BrakPrzydatne do notatników i szybkich testów. Unikać w kodzie produkcyjnym.
API programisty ze zmiennymi środowiskowymiclient = genai.Client()GOOGLE_API_KEY lub GEMINI_API_KEYPreferowana metoda dla czystego i bezpiecznego kodu aplikacji.
Vertex AI z jawnymi parametramiclient = genai.Client(vertexai=True, project="...", location="...")Brak (używa ADC)Jawna metoda wskazywania Vertex AI. Wymaga uwierzytelnienia ADC (gcloud auth...).
Vertex AI ze zmiennymi środowiskowymiclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONKonfiguruje klienta Vertex AI bez parametrów w kodzie. Wymaga uwierzytelnienia ADC.

Część 2: Główne możliwości: Tekst i Czat

Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»

Ta część zagłębia się w najczęstsze przypadki użycia: generowanie tekstu i budowanie agentów konwersacyjnych. Szczegółowo opisuje główne metody i zaangażowane obiekty.

2.1. Generowanie zawartości: Metoda generate_content

Sección titulada «2.1. Generando Contenido: El Método generate_content»

Główną metodą dla wszystkich zadań generowania typu single-turn jest client.models.generate_content(). Ta wszechstronna metoda stanowi podstawę interakcji z modelami Gemini.

Podstawowe użycie polega na przekazaniu prostego ciągu znaków, takiego jak contents, i określeniu nazwy modelu do użycia, np. 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)

Choć przekazywanie prostego ciągu znaków jest wygodne, kluczowe jest zrozumienie podkładowej struktury danych wykorzystywanej przez SDK. Wewnętrznie SDK konwertuje wszystkie dane wejściowe na ustandaryzowaną strukturę składającą się z obiektów types.Content i types.Part. Zrozumienie tej struktury jest kluczem do odblokowania zaawansowanych możliwości SDK, takich jak zapytania multimodalne i wywołania funkcji.

  • types.Content: Reprezentuje pojedynczą wiadomość lub turę w konwersacji. Posiada dwa główne atrybuty: role (zazwyczaj „user” dla wejścia lub „model” dla wyjścia) oraz listę parts.
  • types.Part: Reprezentuje element danych wewnątrz obiektu Content. Może to być tekst, dane obrazu, referencja do pliku, wywołanie funkcji itp.

SDK inteligentnie obsługuje różne typy danych wejściowych dla argumentu contents, konwertując je na odpowiedni format Content/Part:

  • Pojedynczy ciąg znaków: contents='¿Por qué el cielo es azul?' zostaje przekształcony w UserContent z pojedynczym elementem Part tekstowym.
  • Lista ciągów znaków: contents=['Pregunta 1', 'Pregunta 2'] zostaje przekształcony w pojedynczy UserContent, który zawiera dwa elementy Part tekstowe.
  • Obiekt types.Part: Pozwala na bardziej szczegółową kontrolę, np. poprzez określanie danych obrazu.
  • W pełni uformowany obiekt types.Content: Zapewnia maksymalną kontrolę nad rolą i treścią komunikatu.

Aby uzyskać dostęp do wygenerowanej odpowiedzi, najprostszą metodą jest użycie wygodnego akcesora response.text. Należy jednak pamiętać, że akcesor ten działa tylko w przypadku prostych odpowiedzi składających się z jednej części tekstowej. Jeśli odpowiedź zostanie zablokowana przez filtry bezpieczeństwa, będzie zawierać wielu kandydatów lub typy danych niebędące tekstem, próba dostępu do response.text spowoduje błąd. Najbardziej solidną i bezpieczną metodą w środowisku produkcyjnym jest bezpośredni dostęp do kandydata i jego części:

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. Odpowiedzi w trybie streamingu dla informacji zwrotnych w czasie rzeczywistym

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

W przypadku aplikacji interaktywnych, takich jak chatboty, przesyłanie strumieniowe odpowiedzi modelu drastycznie poprawia doświadczenie użytkownika. Zamiast czekać na wygenerowanie całej odpowiedzi, fragmenty tekstu są wyświetlane w miarę ich napływania, co zapewnia natychmiastową informację zwrotną.

Funkcjonalność ta jest realizowana za pomocą metody generate_content_stream(). Metoda ta zwraca iterator, który generuje fragmenty odpowiedzi w miarę ich tworzenia przez model.

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. Opanowanie konwersacyjnej sztucznej inteligencji: Interfejs czatu

Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»

SDK zapewnia dwa główne mechanizmy zarządzania rozmowami wieloturowymi. Jednym z podejść jest ręczne zarządzanie historią rozmowy poprzez tworzenie listy obiektów Content reprezentujących każdy tur i przekazywanie jej do generate_content() przy każdym wywołaniu. Choć jest to rozwiązanie elastyczne, metoda ta może być uciążliwa.

Zalecanym i najwygodniejszym podejściem do tworzenia chatbotów jest korzystanie z interfejsu czatu stanowego dostarczanego przez client.chats. Ten obiekt wysokiego poziomu abstrahuje zarządzanie historią, co znacząco upraszcza kod aplikacji. Jest to świadoma decyzja projektowa w SDK: zapewnienie wysokopoziomowej abstrakcji stanowej (client.chats) dla powszechnego przypadku użycia (czat), co znacznie ułatwia rozwój w porównaniu z niskopoziomową metodą bezstanową generate_content.

Przepływ pracy przy użyciu interfejsu czatu wygląda następująco:

  1. Inicjalizacja sesji czatu: Używa się client.chats.create() do rozpoczęcia nowej rozmowy. Można określić model i opcjonalnie dostarczyć początkową historię, aby nadać rozmowie odpowiedni kontekst.
  2. Wysyłanie wiadomości: Metoda chat.send_message() służy do wysyłania kolejnej wiadomości użytkownika. SDK automatycznie zarządza stanem, dodając wiadomość użytkownika oraz następującą po niej odpowiedź modelu do historii rozmowy.
  3. Dostęp do historii: W dowolnym momencie można pobrać pełną historię rozmowy, korzystając z chat.get_history().

Poniżej znajduje się pełny przykład wieloturowej rozmowy:

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. Zaawansowane sterowanie generowaniem

Sección titulada «2.4. Control Avanzado de la Generación»

Aby dostroić zachowanie modelu, metoda generate_content przyjmuje parametr config, który przyjmuje obiekt types.GenerateContentConfig. Obiekt ten pozwala programistom kontrolować różne aspekty procesu generowania.

Jedną z najbardziej przydatnych konfiguracji jest system_instruction. Instrukcja systemowa dostarcza wytycznych na wysokim poziomie lub ustanawia osobowość modelu, która utrzymuje się przez całą rozmowę. Na przykład model można instruować, aby zachowywał się jak konkretna postać lub przestrzegał określonych zasad w swoich odpowiedziach.

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)

Oprócz instrukcji systemowych istnieje kilka innych parametrów, które można dostosować, aby kontrolować kreatywność i strukturę wyjścia modelu. Poniższa tabela szczegółowo opisuje najważniejsze z nich.

Tabela 2: Kluczowe parametry konfiguracji generowania

ParametrOpisZakresWpływ na wyjście
temperatureKontroluje losowość wyboru tokenów.0.0 - 1.0Niższe wartości (np., 0.2) sprawiają, że wynik jest bardziej deterministyczny i mniej kreatywny. Wyższe wartości (np., 0.9) zwiększają losowość i kreatywność.
top_pPróbkowanie jądrowe (nucleus sampling). Rozważa najmniejszy zestaw tokenów, których skumulowane prawdopodobieństwo jest większe niż top_p.0.0 - 1.0Wartość taka jak 0.95 oznacza, że uwzględniane są tylko tokeny stanowiące górne 95% masy prawdopodobieństwa. Pomaga to uniknąć bardzo mało prawdopodobnych tokenów.
top_kRozważa tylko k najbardziej prawdopodobnych tokenów w każdym kroku generowania.Liczba całkowitaWartość top_k rzędu 1 to dekodowanie zachłanne (greedy). Wartość taka jak 40 ogranicza wybór do 40 najbardziej prawdopodobnych tokenów.
candidate_countLiczba kandydatów na odpowiedzi do wygenerowania.Liczba całkowita (np., 1-8)Generuje wiele możliwych odpowiedzi dla tego samego polecenia. Jest to przydatne, aby zaoferować użytkownikowi opcje.
max_output_tokensMaksymalna liczba tokenów, które mogą zostać wygenerowane w odpowiedzi.Liczba całkowitaOgranicza długość wyjścia. Jest niezbędne do kontrolowania kosztów i opóźnień.
stop_sequencesLista ciągów znaków, których wygenerowanie zatrzyma wyjście.Lista ciągów znakówPrzydatne do zatrzymywania generowania w określonym punkcie, np. w znaczniku końca zdania lub konkretnym formacie.
seedLosowe ziarno do generowania.Liczba całkowitaPodanie ziarna sprawia, że wyjście jest deterministyczne i powtarzalne (pod warunkiem, że temperature nie jest 0).

Część 3: Zaawansowane interakcje: Multimodalność i wywoływanie funkcji

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

Ta część pokazuje prawdziwą moc modeli Gemini, wyjaśniając, jak pracować z danymi wejściowymi innych niż tekst oraz jak łączyć model z zewnętrznymi narzędziami.

3.1. Poza tekstem: Zrozumienie danych wejściowych multimodalnych

Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»

Jedną z definiujących cech rodziny modeli Gemini jest ich wrodzona zdolność multimodalna. Oznacza to, że mogą one przetwarzać i wnioskować na temat różnych typów danych, czyli „modalności”, takich jak tekst, obrazy, dźwięk i wideo, w ramach pojedynczego zapytania.

Zdolność ta jest realizowana poprzez konstruowanie argumentu contents jako listy zawierającej wiele obiektów Part, gdzie każdy Part może zawierać inny typ danych. Na przykład pojedyncze zapytanie może zawierać obraz oraz tekstowe pytanie dotyczące tego obrazu.

SDK udostępnia dwie strategicznie odmienne metody obsługi danych obrazów. Wybór między nimi zależy od specyficznych wymagań danego przypadku użycia, takich jak rozmiar pliku i możliwość ponownego wykorzystania.

Ta dwoistość metod nie jest redundancją, lecz celowym rozwiązaniem projektowym, które odpowiada na różne potrzeby operacyjne. Metoda inline jest prosta i doskonała do jednorazowych analiz oraz dla wygody podczas rozwoju. File API, mimo że wymaga dodatkowego kroku przesyłania, jest kluczowa w scenariuszach produkcyjnych, gdzie priorytetem jest wydajność, skalowalność i obsługa dużych plików.

Metoda ta jest idealna dla mniejszych plików obrazów (całe zapytanie, w tym instrukcje i bajty, musi być mniejsze niż 20 MB) oraz dla uproszczenia procesu tworzenia. Dane obrazu są przekazywane bezpośrednio w wywołaniu generate_content.

  • Z pliku lokalnego: Plik obrazu jest odczytywany w trybie binarnym ('rb') i przekazywany do types.Part.from_bytes(), przy czym należy określić odpowiedni 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 adresu URL: Można użyć biblioteki takiej jak requests, aby pobrać bajty obrazu z adresu URL, a następnie przekazać je w ten sam sposób.

Ta metoda jest zalecana dla dużych plików obrazów (powyżej 20 MB) lub w scenariuszach, w których ten sam plik będzie ponownie wykorzystywany w wielu zapytaniach promptów. Korzystanie z Files API eliminuje konieczność ponownego przesyłania tych samych bajtów przy każdym wywołaniu.

Przepływ pracy składa się z dwóch kroków:

  1. Przesyłanie: client.files.upload() służy do przesyłania pliku na serwery Google. Metoda ta zwraca obiekt pliku, który działa jako referencja.
  2. Promptowanie: Zwrócony obiekt pliku jest przekazywany bezpośrednio w liście contents wywołania generate_content. SDK zajmuje się rozwiązywaniem referencji do przesłanego pliku.
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}")

Pliki przesłane za pomocą File API są przechowywane tymczasowo przez 48 godzin, zanim zostaną automatycznie usunięte. API udostępnia również metody do zarządzania tymi plikami, takimi jak get(), list() i delete().

Koncepcje zarządzania obrazami przekładają się bezpośrednio na inne formaty, takie jak dźwięk i wideo. Ponieważ pliki te są zazwyczaj duże, File API jest główną metodą pracy z nimi.

Proces jest identyczny jak w przypadku dużych obrazów:

  1. Użyj client.files.upload(), aby przesłać plik dźwiękowy (np. MP3, WAV) lub wideo (np. MP4).
  2. Dołącz zwrócony obiekt pliku do promptu w generate_content.

Poniższy przykład pokazuje, jak przesłać plik dźwiękowy i poprosić model o jego transkrypcję.

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. Wywołanie funkcji: Rozszerzanie możliwości modelu

Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»

Wywołanie funkcji, znane również jako użycie narzędzi (tool use), to potężna technika, która pozwala modelowi językowemu na interakcję z zewnętrznymi systemami. Pozwala ona modelowi odpowiadać na pytania lub wykonywać działania wykraczające poza jego natywną wiedzę, takie jak pobieranie danych w czasie rzeczywistym z API, przeszukiwanie bazy danych lub sterowanie urządzeniem.

Ogólny przepływ pracy wygląda następująco:

  1. Definiowanie narzędzi: Definiuje się zestaw narzędzi (funkcji Python), które model może wywołać. Definicja ta zawiera nazwę funkcji, opis jej działania oraz schemat parametrów.
  2. Przekazywanie narzędzi do modelu: Lista zdefiniowanych narzędzi jest przekazywana do modelu podczas wywołania generate_content.
  3. Model decyduje o wywołaniu: Model analizuje prompt użytkownika i jeśli uzna, że jedno z dostarczonych narzędzi może pomóc w odpowiedzi, zamiast generować tekst, jego odpowiedź będzie zawierać obiekt Part typu function_call. Obiekt ten określa nazwę funkcji do wywołania oraz argumenty, z którymi należy ją wywołać.
  4. Wykonanie funkcji: Kod aplikacji wykrywa function_call, wykonuje odpowiednią funkcję Python z podanymi argumentami i uzyskuje wynik.
  5. Zwrócenie wyniku do modelu: Wykonuje się drugie wywołanie generate_content, dostarczając historię rozmowy wraz z wynikiem wykonania funkcji (opakowanym w types.Part.from_function_response() ).
  6. Ostateczna odpowiedź: Model wykorzystuje wynik funkcji do wygenerowania ostatecznej odpowiedzi w języku naturalnym dla użytkownika.

Chociaż fragmenty badawcze nie zapewniają przykładu kodu wywołania funkcji end-to-end, struktura obiektów Part dla function_call i function_response stanowi podstawę do implementacji tego zaawansowanego wzorca.


Część 4: Przygotowanie do produkcji: obsługa błędów, bezpieczeństwo i zarządzanie

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

Ta końcowa część dostarcza krytycznych informacji niezbędnych do budowy solidnych, niezawodnych i odpowiedzialnych aplikacji.

W środowisku produkcyjnym solidna obsługa błędów jest niepodlegająca negocjacjom. Wywołania API mogą zawodzić z różnych powodów, takich jak nieważne poświadczenia, problemy z siecią, wyczerpanie limitów (kwot) lub błędnie sformatowane dane wejściowe.

SDK korzysta ze standardowego systemu wyjątków Pythona. Większość błędów związanych z API można przechwycić za pomocą bloku try...except, który wyszukuje wyjątki z modułu google.api_core.exceptions lub, jeśli jest dostępna, bardziej specyficzną klasę, taką jak 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}")

Podczas przechwytywania wyjątku obiekt wyjątku często zawiera cenne informacje do logowania i debugowania, takie jak kod stanu i opisową wiadomość.

Ważne jest, aby wziąć pod uwagę, że komunikaty o błędach, choć są przydatne dla programistów, mogą być obosiecznym mieczem. Mogą one ujawniać szczegóły wewnętrznej implementacji, które mogą zostać wykorzystane w atakach typu adversarial. Na przykład analiza komunikatów o błędach walidacji bezpieczeństwa może ujawnić wewnętrzne progi lub mechanizmy obronne, pomagając napastnikowi w obejściu zabezpieczeń. Dlatego, choć błędy powinny być szczegółowo logowane w backendzie, informacje przekazywane użytkownikom końcowym muszą być starannie kontrolowane. Często bezpieczniej jest wyświetlić ogólny komunikat, taki jak „Wystąpił błąd podczas przetwarzania żądania”, zamiast ujawniać surowy komunikat błędu z API.

Poniższa tabela podsumowuje najczęstsze kody błędów API oraz sposoby ich rozwiązania.

Tabela 3: Częste kody błędów API i rozwiązania

Kod HTTPStatusPrawdopodobna przyczynaZalecane działanie w Pythonie
400INVALID_ARGUMENTCiało żądania jest błędnie sformatowane (np. parametr o nieprawidłowym typie, brak obowiązkowego pola).Sprawdź, czy parametry w GenerateContentConfig oraz format contents są poprawne. Upewnij się, że model jest zgodny z żądanymi cechami.
403PERMISSION_DENIEDKlucz API jest nieprawidłowy, nie posiada wymaganych uprawnień lub próbuje uzyskać dostęp do zasobu chronionego (np. dostrojonego modelu).Sprawdź, czy klucz API (lub uwierzytelnianie ADC dla Vertex) jest poprawnie skonfigurowany i posiada wymagane uprawnienia.
429RESOURCE_EXHAUSTEDPrzekroczono limit prędkości API (liczba żądań na minutę).Zaimplementuj wykładnicze opóźnienie (exponential backoff) w swojej logice ponawiania prób. Jeśli jest to konieczne dla Twojej aplikacji, rozważ poproszenie o zwiększenie limitu (quota).
500INTERNALWystąpił nieoczekiwany błąd po stronie Google. Czasami może to być spowodowane zbyt długim kontekstem wejściowym.Skróć długość promptu. Ponów żądanie po krótkiej przerwie. Jeśli problem będzie się powtarzał, rozważ tymczasową zmianę na inny model.
503UNAVAILABLEUsługa jest tymczasowo przeciążona lub niedostępna.Ponów żądanie po krótkiej przerwie, korzystając ze strategii wykładniczego opóźnienia (exponential backoff). Jeśli problem będzie się powtarzał, zgłoś błąd.

API Gemini zawiera wbudowane funkcje bezpieczeństwa służące do filtrowania potencjalnie szkodliwych treści. Funkcje te zostały zaprojektowane, aby pomóc programistom w budowaniu bezpieczniejszych i bardziej odpowiedzialnych aplikacji.

API klasyfikuje treści do czterech głównych kategorii szkód:

  • Nękanie (HARM_CATEGORY_HARASSMENT)
  • Mowa nienawiści (HARM_CATEGORY_HATE_SPEECH)
  • Treści o charakterze seksualnym (HARM_CATEGORY_SEXUALLY_EXPLICIT)
  • Treści niebezpieczne (HARM_CATEGORY_DANGEROUS_CONTENT)

Dla każdej kategorii model przypisuje prawdopodobieństwo, że treść jest niezabezpieczona. Domyślnie API blokuje polecenia i odpowiedzi, które mają prawdopodobieństwo MEDIUM lub HIGH bycia niezabezpieczonymi w którejkolwiek z tych kategorii.

Programiści mogą nadpisać tę domyślną konfigurację dla poszczególnych zapytań, przekazując listę obiektów SafetySetting do parametru safety_settings. Pozwala to na granularną kontrolę progu blokowania dla każdej 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}")

Gdy odpowiedź wydaje się pusta lub występuje błąd, kluczowe jest sprawdzenie informacji zwrotnej dotyczącej bezpieczeństwa. Obiekt odpowiedzi zawiera prompt_feedback (dla wejściowego promptu) oraz candidates.safety_ratings (dla wygenerowanej odpowiedzi). Atrybuty te ujawnią, czy treść została zablokowana i dlaczego, co jest niezbędne do debugowania.

Poniższa tabela wyjaśnia znaczenie różnych progów blokowania.

Tabela 4: Progi konfiguracji bezpieczeństwa

Stała APIKonfiguracja w Google AI StudioOpis
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/APróg nie jest określony; stosowany jest domyślny próg modelu.
BLOCK_NONEBlock none (Nie blokuj niczego)Nigdy nie blokuj treści, niezależnie od prawdopodobieństwa, że są niebezpieczne. Należy używać z zachowaniem szczególnej ostrożności.
BLOCK_ONLY_HIGHBlock few (Blokuj nieliczne)Blokuj tylko wtedy, gdy prawdopodobieństwo niebezpiecznej treści wynosi HIGH.
BLOCK_MEDIUM_AND_ABOVEBlokuj niektóre(Domyślne dla większości modeli) Blokuj, gdy prawdopodobieństwo wystąpienia niebezpiecznej zawartości wynosi MEDIUM lub HIGH.
BLOCK_LOW_AND_ABOVEBlokuj większośćBlokuj, gdy prawdopodobieństwo wystąpienia niebezpiecznej zawartości wynosi LOW, MEDIUM lub HIGH.

SDK zapewnia programową metodę odkrywania dostępnych modeli i ich możliwości. Jest to przydatne przy budowaniu aplikacji, które mogą adaptować się do różnych modeli, lub do weryfikacji możliwości modelu przed jego użyciem.

Metoda client.models.list() zwraca iterator po dostępnych modelach.

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)

Ta funkcjonalność może być również używana do wymieniania konkretnie modeli, które zostały dostrojone (fine-tuned) przez użytkownika, poprzez ustawienie query_base=False w konfiguracji żądania listy. Pozwala to aplikacjom na dynamiczne odkrywanie i korzystanie z niestandardowych modeli.


Część 5: Walidacja środowiska i techniczna lista kontrolna

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

Aby zakończyć proces aprowizacji integracji opartych na jednolitym SDK google-genai w tenancie Portelcore, zweryfikuj spełnienie następujących technicznych kamieni milowych:

  • Zmigrowałem wszystkie skrypty z tenanta starej biblioteki google-generativeai na nowy standard google-genai. ✓
  • Klucze API są zarządzane wyłącznie za pomocą zmiennej środowiskowej GOOGLE_API_KEY lub są obfuskowane w menedżerze sekretów Google Cloud, zamiast być zapisywane w postaci tekstu jawnego. ✓
  • Zaimplementowano solidną obsługę wyjątków (google.api_core.exceptions), aby przechwytywać kody stanu 429 (Resource Exhausted) z polityką wykładniczego opóźnienia ponawiania prób (exponential backoff). ✓
  • Temperatura i progi bezpieczeństwa (safety_settings) są formalnie sparametryzowane zgodnie z przypadkiem użycia domeny portelcore.com. ✓