Google GenAI Python SDK dla API Gemini
Przewodnik referencyjny i zaawansowana konfiguracja nowego, ujednoliconego SDK google-genai dla API Gemini w Portelcore.
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.
1.2. Instalacja i środowisko
Sección titulada «1.2. Instalación y Entorno»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:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activatePo aktywacji środowiska wirtualnego można zainstalować najnowszą wersję SDK Google Gen AI, używając pip. Użycie flagi --upgrade zapewnia pobranie najnowszej wersji.
pip install --upgrade google-genaiNależ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 :
pip install google-genai[aiohttp]1.3. Uwierzytelnianie: Twój klucz do Gemini API
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»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 :
- Przejdź do (https://ai.google.dev/) i zaloguj się za pomocą konta Google.
- Kliknij „Get API key” (Pobierz klucz API).
- Wybierz opcję utworzenia klucza API w nowym lub istniejącym projekcie Google Cloud.
- 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_KEYz 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ą:
- Wybierz lub utwórz projekt Google Cloud.
- Upewnij się, że fakturowanie jest włączone dla projektu.
- 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 loginPo 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.
1.4. Inicjalizacja klienta: Łączenie z modelem
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»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 genaiclient = 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é configuradafrom google import genaiclient = genai.Client() -
Scenariusz 3: API Vertex AI (jawne parametry) Aby połączyć się z Vertex AI, flagę
vertexaiustawia się naTrueoraz podaje się identyfikator projektu i lokalizację. Metoda ta automatycznie użyje domyślnych poświadczeń aplikacji (ADC) do uwierzytelnienia.from google import genaiclient = 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=trueexport GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'export GOOGLE_CLOUD_LOCATION='us-central1'# El cliente se configurará automáticamente para Vertex AIfrom google import genaiclient = genai.Client()
Poniższa tabela podsumowuje te metody w celu szybkiego odniesienia.
Tabela 1: Szybka referencja inicjalizacji klienta
| Przypadek użycia | Kod Python | Wymagane zmienne środowiskowe | Uwagi |
|---|---|---|---|
| API programisty z jawnym kluczem | client = genai.Client(api_key="SU_CLAVE...") | Brak | Przydatne do notatników i szybkich testów. Unikać w kodzie produkcyjnym. |
| API programisty ze zmiennymi środowiskowymi | client = genai.Client() | GOOGLE_API_KEY lub GEMINI_API_KEY | Preferowana metoda dla czystego i bezpiecznego kodu aplikacji. |
| Vertex AI z jawnymi parametrami | client = genai.Client(vertexai=True, project="...", location="...") | Brak (używa ADC) | Jawna metoda wskazywania Vertex AI. Wymaga uwierzytelnienia ADC (gcloud auth...). |
| Vertex AI ze zmiennymi środowiskowymi | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | Konfiguruje 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ó anteriormenteresponse = 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 obiektuContent. 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 wUserContentz pojedynczym elementemParttekstowym. - Lista ciągów znaków:
contents=['Pregunta 1', 'Pregunta 2']zostaje przekształcony w pojedynczyUserContent, który zawiera dwa elementyParttekstowe. - 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 inicializadoresponse_stream = client.models.generate_content_stream( model="gemini-2.0-flash", contents="Escribe un poema largo sobre el océano y sus misterios.")
print("Respuesta del modelo:")for chunk in response_stream: print(chunk.text, end="")print() # Para una nueva línea al final2.3. 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:
- 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. - 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. - 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 chatchat_session = client.chats.create( model="gemini-2.0-flash")
# 2. Enviar el primer mensajeprint("Usuario: Hola, ¿puedes ayudarme a planificar un viaje a la luna?")response = chat_session.send_message("Hola, ¿puedes ayudarme a planificar un viaje a la luna?")print(f"Modelo: {response.text}\n")
# 3. Enviar un segundo mensaje de seguimientoprint("Usuario: ¿Qué tres cosas debería empacar?")response = chat_session.send_message("¿Qué tres cosas debería empacar?")print(f"Modelo: {response.text}\n")
# 4. Mostrar el historial completo de la conversaciónprint("--- Historial de la Conversación ---")for message in chat_session.get_history(): # El rol y el texto están en message.role y message.parts.text role = "Usuario" if message.role == "user" else "Modelo" print(f"{role}: {message.parts.text}")2.4. 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 inicializadoresponse = client.models.generate_content( model='gemini-2.0-flash', contents='¡Ah del barco! Cuéntame un chiste sobre un loro.', config=types.GenerateContentConfig( system_instruction='Hablas como un pirata malhumorado y conciso.' ))print(response.text)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
| Parametr | Opis | Zakres | Wpływ na wyjście |
|---|---|---|---|
temperature | Kontroluje losowość wyboru tokenów. | 0.0 - 1.0 | Niż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_p | Pró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.0 | Wartość 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_k | Rozważa tylko k najbardziej prawdopodobnych tokenów w każdym kroku generowania. | Liczba całkowita | Wartość top_k rzędu 1 to dekodowanie zachłanne (greedy). Wartość taka jak 40 ogranicza wybór do 40 najbardziej prawdopodobnych tokenów. |
candidate_count | Liczba 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_tokens | Maksymalna liczba tokenów, które mogą zostać wygenerowane w odpowiedzi. | Liczba całkowita | Ogranicza długość wyjścia. Jest niezbędne do kontrolowania kosztów i opóźnień. |
stop_sequences | Lista ciągów znaków, których wygenerowanie zatrzyma wyjście. | Lista ciągów znaków | Przydatne do zatrzymywania generowania w określonym punkcie, np. w znaczniku końca zdania lub konkretnym formacie. |
seed | Losowe ziarno do generowania. | Liczba całkowita | Podanie 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.
3.2. Praca z obrazami
Sección titulada «3.2. Trabajando con Imágenes»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 1: Dane obrazu inline (Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»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 dotypes.Part.from_bytes(), przy czym należy określić odpowiedni typ MIME.import google.genai as genaifrom google.genai import types# Asumiendo que 'client' ha sido inicializadowith open('imagen_scones.jpg', 'rb') as f:image_bytes = f.read()image_part = types.Part.from_bytes(data=image_bytes,mime_type='image/jpeg')prompt_part = "Describe lo que ves en esta imagen."# Combinar imagen y texto en una sola solicitudresponse = client.models.generate_content(model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-visioncontents=[prompt_part, image_part])print(response.text) -
Z 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.
Metoda 2: API plików (Files API)
Sección titulada «Método 2: La API de Archivos (Files API)»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:
- 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. - Promptowanie: Zwrócony obiekt pliku jest przekazywany bezpośrednio w liście
contentswywołaniagenerate_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 Archivosprint("Cargando archivo...")sample_file = client.files.upload( file_path="imagen_grande.png", display_name="Mi Imagen de Muestra")print(f"Archivo cargado: {sample_file.uri}")
# 2. Usar el archivo cargado en una indicaciónprompt = "Analiza esta imagen y describe los objetos principales y su disposición espacial."response = client.models.generate_content( model='gemini-2.5-flash', contents=[prompt, sample_file] # Pasar el objeto de archivo directamente)
print(response.text)
# Opcional: Eliminar el archivo después de su usoclient.files.delete(name=sample_file.name)print(f"Archivo eliminado: {sample_file.name}")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().
3.3. Interakcja z dźwiękiem i wideo
Sección titulada «3.3. Interacción con Audio y Vídeo»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:
- Użyj
client.files.upload(), aby przesłać plik dźwiękowy (np. MP3, WAV) lub wideo (np. MP4). - 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 genaiimport time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audioprint("Cargando archivo de audio...")audio_file = client.files.upload( file_path="discurso_muestra.mp3", display_name="Discurso de Muestra")
# El procesamiento del archivo puede llevar tiempo, se espera a que esté ACTIVOwhile audio_file.state.name == "PROCESSING": print("Procesando archivo... esperando.") time.sleep(10) audio_file = client.files.get(name=audio_file.name)
if audio_file.state.name == "FAILED": raise ValueError(audio_file.state.name)
# 2. Usar el archivo de audio en una indicaciónprompt = "Transcribe el discurso en este archivo de audio."response = client.models.generate_content( model='gemini-2.5-flash', contents=[prompt, audio_file])print("\n--- Transcripción ---")print(response.text)3.4. 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:
- 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.
- Przekazywanie narzędzi do modelu: Lista zdefiniowanych narzędzi jest przekazywana do modelu podczas wywołania
generate_content. - 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
Parttypufunction_call. Obiekt ten określa nazwę funkcji do wywołania oraz argumenty, z którymi należy ją wywołać. - Wykonanie funkcji: Kod aplikacji wykrywa
function_call, wykonuje odpowiednią funkcję Python z podanymi argumentami i uzyskuje wynik. - Zwrócenie wyniku do modelu: Wykonuje się drugie wywołanie
generate_content, dostarczając historię rozmowy wraz z wynikiem wykonania funkcji (opakowanym wtypes.Part.from_function_response()). - 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.
4.1. Solidna obsługa błędów
Sección titulada «4.1. Manejo Robusto de Errores»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_exceptionsimport google.genai as genai
# Asumiendo que 'client' ha sido inicializadotry: response = client.models.generate_content( model="nombre-de-modelo-invalido", contents="¿Cuál es tu nombre?" ) print(response.text)except core_exceptions.GoogleAPICallError as e: # 'e' es una superclase para muchos errores de API print(f"Ha ocurrido un error en la API: {e}") # En muchos casos, 'e' tendrá atributos como 'code' y 'message' # aunque esto puede variar. Se recomienda inspeccionar el objeto de excepción.
except core_exceptions.NotFound as e: # Un error más específico si se sabe qué buscar print(f"Error: Recurso no encontrado. ¿Es correcto el nombre del modelo? - {e.message}")
except core_exceptions.ResourceExhausted as e: # Específico para errores de cuota print(f"Error: Se ha excedido la cuota de la API. - {e.message}")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 HTTP | Status | Prawdopodobna przyczyna | Zalecane działanie w Pythonie |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | Ciał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. |
| 403 | PERMISSION_DENIED | Klucz 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. |
| 429 | RESOURCE_EXHAUSTED | Przekroczono 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). |
| 500 | INTERNAL | Wystą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. |
| 503 | UNAVAILABLE | Usł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. |
4.2. Zarządzanie bezpieczeństwem treści
Sección titulada «4.2. Gestión de la Seguridad del Contenido»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 API | Konfiguracja w Google AI Studio | Opis |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | N/A | Próg nie jest określony; stosowany jest domyślny próg modelu. |
BLOCK_NONE | Block 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_HIGH | Block few (Blokuj nieliczne) | Blokuj tylko wtedy, gdy prawdopodobieństwo niebezpiecznej treści wynosi HIGH. |
BLOCK_MEDIUM_AND_ABOVE | Blokuj 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_ABOVE | Blokuj większość | Blokuj, gdy prawdopodobieństwo wystąpienia niebezpiecznej zawartości wynosi LOW, MEDIUM lub HIGH. |
4.3. Zarządzanie modelami
Sección titulada «4.3. Gestión de Modelos»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 inicializadoprint("Modelos disponibles:")for model in client.models.list(): # El objeto 'model' contiene metadatos detallados print(f" - Nombre: {model.name}") print(f" - Nombre para mostrar: {model.display_name}") print(f" - Métodos soportados: {model.supported_generation_methods}") # Verificar si el modelo soporta chat (create_chat) if 'create_chat' in model.supported_generation_methods: print(" - ¡Este modelo soporta chat!") print("-" * 20)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-generativeaina nowy standardgoogle-genai. ✓ - Klucze API są zarządzane wyłącznie za pomocą zmiennej środowiskowej
GOOGLE_API_KEYlub 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 domenyportelcore.com. ✓

