Google GenAI Python SDK для Gemini API
Справочное руководство и расширенная настройка нового унифицированного SDK google-genai для Gemini API в Portelcore.
Часть 1: Основные понятия и начальная настройка
Sección titulada «Parte 1: Conceptos Fundamentales y Configuración Inicial»Этот раздел устанавливает контекст для нового SDK, устраняя основную путаницу пользователя при смене библиотеки и предоставляя надежное руководство для начала работы, охватывающее установку и два критически важных метода аутентификации.
1.1. Новый стандарт: миграция от google-generativeai к google-genai
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»Экосистема разработки для моделей генеративного ИИ Google эволюционировала. Библиотека google-genai теперь является официальным, унифицированным и рекомендуемым SDK Python для взаимодействия с API Gemini и другими моделями генеративного ИИ Google. Она достигла общей доступности (GA) в мае 2025 года и заменяет наследованную библиотеку google-generativeai.
Предыдущая библиотека, google-generativeai, была помечена как "Неактивная" в Python Package Index (PyPI) и находится на пути к устареванию. Поддержка этого пакета, включая исправления критических ошибок, прекратится в конце сентября 2025 года, хотя некоторые источники указывают на немного более раннюю дату окончания поддержки - 31 августа 2025 года. Рекомендуется, чтобы разработчики ориентировались на более раннюю дату, чтобы обеспечить бесперебойную трансляцию.
Этот переход не является просто сменой названия, а стратегическим объединением, стимулированным комментариями разработчиков. Целью было создание единого SDK, который упрощал бы доступ ко всему спектру моделей генеративного ИИ Google (Gemini, Veo, Imagen и т. д.) и предлагал более четкий и последовательный путь разработки. Одним из наиболее значимых решений по дизайну нового SDK google-genai является то, что он выступает в качестве единого интерфейса для двух различных сервисов бэкэнда: API разработчика Gemini, доступного для всех, и платформы Vertex AI, уровня предприятия.
Эта унифицированная архитектура обеспечивает плавный путь для разработчиков. Они могут быстро начать работу, часто с бесплатным уровнем, используя ключ API для API разработчика Gemini. По мере того, как их приложения созревают и требуют большей масштабируемости, управления и интеграции с другими сервисами Google Cloud, они могут перейти на бэкэнд Vertex AI с минимальными изменениями в коде, в основном в инициализации клиента. SDK работает как мост, снижая барьер для входа и обеспечивая четкий путь к производству в Google Cloud. Следовательно, всех пользователей устаревшей библиотеки призываем перейти, чтобы гарантировать доступ к последним функциям (таким как Live API и Veo), улучшениям производительности и непрерывной поддержке.
1.2. Установка и Среда
Sección titulada «1.2. Instalación y Entorno»Перед установкой SDK рекомендуется настроить виртуальную среду Python. Это изолирует зависимости проекта, предотвращая конфликты с другими проектами или пакетами системы.
Чтобы создать и активировать виртуальную среду с помощью venv:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activateКак только виртуальная среда активирована, можно установить последнюю версию SDK Google Gen AI, используя pip. Использование флага --upgrade гарантирует получение последней версии.
pip install --upgrade google-genaiОчень важно учитывать требования версии Python. SDK google-genai требует Python 3.9 или выше. Использование несовместимой версии может привести к непредвиденным ошибкам во время установки или выполнения.
Для приложений, требующих высокопроизводительного асинхронного выполнения, SDK предлагает возможность использовать aiohttp в качестве бэкэнда HTTP-транспорта вместо стандартного httpx. Это можно установить как дополнительный пакет:
pip install google-genai[aiohttp]1.3. Аутентификация: Ваш Ключ для API Gemini
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»Аутентификация является наиболее важным шагом настройки, и метод отличается в зависимости от используемого сервиса backend: API разработчика Gemini или API Gemini в Vertex AI.
1.3.1. Путь разработчика Gemini API (рекомендуется для прототипов и бесплатного уровня)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»Это самый быстрый способ начать работать с Gemini. Требуется ключ API, который можно получить бесплатно в Google AI Studio.
Процесс получения ключа API следующий:
- Перейдите по адресу (https://ai.google.dev/) и войдите в систему с помощью учетной записи Google.
- Нажмите кнопку «Get API key» (Получить ключ API).
- Выберите создание ключа API в новом или существующем проекте Google Cloud.
- Ключ API будет сгенерирован автоматически.
Ключи API являются конфиденциальными учетными данными и должны обрабатываться как пароли. Они должны храниться в безопасности и никогда не должны раскрываться в коде на стороне клиента или в публичных системах контроля версий.
Наиболее безопасный и рекомендуемый способ использования ключа — настроить его как переменную среды. SDK предназначен для автоматического обнаружения и использования переменных среды GOOGLE_API_KEY или GEMINI_API_KEY. Если обе они настроены, GOOGLE_API_KEY имеет приоритет.
Чтобы настроить переменную среды:
-
В 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 -
В Windows: Используйте графический интерфейс «Переменные среды» в системных настройках, чтобы добавить новую переменную пользователя или системы с именем
GOOGLE_API_KEYи своим ключом в качестве значения.
1.3.2. Путь Vertex AI (Рекомендуется для Производства и Интеграции с Google Cloud)
Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»Для производственных приложений, требующих корпоративных функций Google Cloud, рекомендуется использовать API Gemini через Vertex AI. Этот подход требует проекта Google Cloud с включенной оплатой.
Первоначальные шаги настройки включают:
- Выберите или создайте проект Google Cloud.
- Убедитесь, что оплата включена для проекта.
- Включение API Vertex AI (
aiplatform.googleapis.com) для проекта.
Аутентификация для Vertex AI может быть выполнена двумя способами:
-
Предустановленные учетные данные приложения (ADC) (Рекомендуется для производства): Это предпочтительный метод для большинства сценариев производства. ADC автоматически находит учетные данные в зависимости от среды. В локальной среде разработки это можно настроить, выполнив команду CLI gcloud:
Ventana de terminal gcloud auth application-default loginПри выполнении в среде Google Cloud (например, Cloud Run, Google Kubernetes Engine, Cloud Functions) ADC автоматически использует сервисную учетную запись, прикрепленную к этому ресурсу, исключая необходимость управления ключами.
-
Ключи API (для тестирования в Vertex): Возможно использовать ключ API для аутентификации в конечной точке Vertex AI, но процесс более сложный, чем с API разработчика. Требует разрешений на уровне организации для включения создания ключей API сервисных аккаунтов, создания сервисного аккаунта с подходящей ролью (например,
Vertex AI User), а затем создания ограниченного ключа API для этого сервисного аккаунта. Из-за своей сложности этот метод обычно используется для конкретных тестовых сценариев, а не для общего развития приложений.
1.4. Инициализация клиента: подключение к модели
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»Как только настройка аутентификации завершена, следующим шагом является создание объекта genai.Client. Унифицированный SDK упрощает это, предоставляя единого клиента, который можно настроить для любого из двух бэкендов.
Ниже представлены четыре основных сценария инициализации клиента.
-
Сценарий 1: API разработчика Gemini (Явный ключ) Этот метод удобен для блокнотов или быстрых скриптов, где не требуется настраивать переменные среды. Ключ API передается直接 как аргумент.
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
Сценарий 2: API разработчика Gemini (Переменная среды) Это самый чистый и рекомендуемый подход для кода приложения, поскольку он отделяет учетные данные от кода. Клиент находит и автоматически использует переменную среды
GOOGLE_API_KEY.# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
Сценарий 3: API Vertex AI (Явные параметры) Чтобы подключиться к Vertex AI, устанавливается флаг
vertexaiвTrueи предоставляются идентификатор проекта и местоположение. Этот метод будет использовать автоматически учетные данные приложения по умолчанию (ADC) для аутентификации.from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
Сценарий 4: API Vertex AI (Переменные среды) В качестве альтернативы для Vertex AI конфигурация может быть вынесена в переменные среды. Клиент обнаружит эти переменные и настроит себя для использования бэкенда 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()
Следующая таблица суммирует эти методы для быстрого справочника.
Таблица 1: Быстрый Справочник по Инициализации Клиента
| Случай использования | Код Python | Требуемые переменные среды | Примечания |
|---|---|---|---|
| API Разработчика с Явным Ключом | client = genai.Client(api_key="SU_CLAVE...") | Никакие | Полезно для ноутбуков и быстрых тестов. Избегайте использования в производственном коде. |
| API Разработчика с Переменной Окружения | client = genai.Client() | GOOGLE_API_KEY или GEMINI_API_KEY | Предпочтительный метод для чистого и безопасного кода приложения. |
| Vertex AI c Parametriami Razreshennymi | client = genai.Client(vertexai=True, project="...", location="...") | Никакие (используется ADC) | Metod razreshennogo ukazaniya na Vertex AI. Trebuetsya avtorizatsiya ADC ([['PC_BLOCK_0']]). |
| Vertex AI c Var. Sredy | client = genai.Client() | [['PC_BLOCK_0']], [['PC_BLOCK_1']], [['PC_BLOCK_2]] | Настраивает клиент для Vertex AI без параметров в коде. Требуется аутентификация ADC. |
Chast 2: Glavnye Vozmozhnosti: Tekst i Dialog
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»Эта часть погружается в наиболее распространенные случаи использования: генерация текста и построение разговорных агентов. Подробно описаны основные методы и задействованные объекты.
2.1. Генерация содержания: метод generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»Основным методом для всех задач генерации текста на один оборот является client.models.generate_content(). Этот универсальный метод является базой для взаимодействия с моделями Gemini.
Базовый вариант использования предполагает предоставление простой строки текста, например contents, и указание имени модели, которую следует использовать, например 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)Хотя передача простой строки удобна, важно понять базовую структуру данных, используемую SDK. Внутри SDK все входные данные преобразуются в стандартизированную структуру, состоящую из объектов types.Content и types.Part. Понимание этой структуры является ключом к разблокировке расширенных возможностей SDK, таких как многомодальные подсказки и вызовы функций.
types.Content: Представляет один сообщение или ход в разговоре. Имеет два основных атрибута:role(обычно 'пользователь' для ввода или 'модель' для вывода) и списокparts.types.Part: Представляет часть данных внутри объектаContent. Часть может быть текстом, изображением, ссылкой на файл, вызовом функции и т. д.
SDK умело обрабатывает различные типы входных данных для аргумента contents, преобразуя их в подходящий формат Content/Part:
- Одна строка:
contents='¿Por qué el cielo es azul?'преобразуется вUserContentс одной частью текста. - Список строк:
contents=['Pregunta 1', 'Pregunta 2']преобразуется в одинUserContent, содержащий две части текста. - Объект
types.Part: Позволяет более детально контролировать, например, указывать изображения. - Полностью сформированный объект
types.Content: Предоставляет максимальный контроль над ролью и содержанием сообщения.
Для доступа к сгенерированной ответу удобный аксессор response.text является наиболее простым методом. Однако важно знать, что этот аксессор работает только для простых ответов, состоящих из одной части текста. Если ответ блокируется фильтрами безопасности, содержит несколько кандидатов или включает нетекстовые типы данных, доступ к response.text генерирует ошибку. Более прочный и безопасный метод для производства - прямой доступ к кандидату и его частям:
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. Потоковые ответы для обратной связи в реальном времени
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»Для интерактивных приложений, таких как чат-боты, потоковая передача ответа модели значительно улучшает опыт пользователя. Вместо ожидания генерации всего ответа фрагменты текста отображаются по мере их поступления, обеспечивая немедленную обратную связь.
Эта функциональность достигается с помощью метода generate_content_stream(). Этот метод возвращает итератор, производящий фрагменты ответа по мере их генерации моделью.
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. Освоение разговорного ИИ: Интерфейс чата
Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»SDK предоставляет два основных механизма для управления разговорами с несколькими ходами. Один подход заключается в ручном управлении историей разговора, создавая список объектов Content, представляющих каждый ход и передавая его в generate_content() при каждом вызове. Хотя этот метод гибок, он может быть громоздким.
Рекомендуемый и наиболее удобный подход к созданию чат-ботов - использовать интерфейс чата с состоянием, предоставляемый client.chats. Этот объект высокого уровня абстрагирует управление историей, значительно упрощая код приложения. Это преднамеренное решение по дизайну в SDK: предоставление абстракции высокого уровня и со состоянием (client.chats) для распространенного случая использования (чат), что значительно упрощает разработку по сравнению с методом низкого уровня и без состояния generate_content.
Рабочий процесс для использования интерфейса чата следующий:
- Инициализация сеанса чата: Используется
client.chats.create(), чтобы начать новый разговор. Можно указать модель и, опционально, предоставить начальную историю для контекстуализации разговора. - Отправка сообщений: Используется метод
chat.send_message(), чтобы отправить следующее сообщение пользователя. SDK автоматически управляет состоянием, добавляя сообщение пользователя и последующую реакцию модели к истории разговора. - Доступ к истории: В любой момент можно получить полную историю разговора, используя
chat.get_history().
Ниже приведен пример полного разговора с несколькими раундами:
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. Расширенный контроль генерации
Sección titulada «2.4. Control Avanzado de la Generación»Чтобы настроить поведение модели, метод generate_content принимает параметр config, который принимает объект types.GenerateContentConfig. Этот объект позволяет разработчикам контролировать различные аспекты процесса генерации.
Одна из наиболее полезных настроек - это system_instruction. Системная инструкция предоставляет высокоуровневое руководство или задает личность модели, которая сохраняется на протяжении всего разговора. Например, можно указать модели вести себя как определенный персонаж или следовать определенным правилам в своих ответах.
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)Помимо системных инструкций, есть несколько других параметров, которые можно регулировать для управления креативностью и структурой вывода модели. В следующей таблице подробно описаны наиболее важные из них.
Таблица 2: Ключевые параметры конфигурации генерации
| Параметр | Описание | Диапазон | Влияние на вывод |
|---|---|---|---|
temperature | Контролирует случайность выбора токенов. | 0.0 - 1.0 | Меньшие значения (напр., 0.2) делают выход более детерминированным и менее креативным. Большие значения (напр., 0.9) увеличивают случайность и креативность. |
top_p | Сэмплирование ядра (nucleus sampling). Рассматривает наименьший набор токенов, чья накопленная вероятность больше top_p. | 0.0 - 1.0 | Значение как 0.95 означает, что рассматриваются только токены, которые составляют верхние 95% вероятностной массы. Помогает избежать очень маловероятных токенов. |
top_k | Рассматривает только k наиболее вероятные токены на каждом шаге генерации. | Целое число | top_k из 1 - это жадная декодировка (greedy). Значение как 40 ограничивает выбор 40 наиболее вероятными токенами. |
candidate_count | Количество ответ-кандидатов, которые необходимо сгенерировать. | Целое число (напр., 1-8) | Генерирует несколько возможных ответов на один и тот же запрос. Полезно для предоставления пользователю выбора. |
max_output_tokens | Максимальное количество токенов, которые можно сгенерировать в ответе. | Целое число | Ограничивает длину вывода. Существенно для контроля затрат и задержки. |
stop_sequences | Список строк, которые при генерации остановят вывод. | Список строк | Полезно для остановки генерации в определенной точке, такой как маркер конца предложения или определенный формат. |
seed | Случайная seed для генерации. | Целое число | Предоставление семи делает вывод детерминированным и воспроизводимым (если только temperature не равно 0). |
Часть 3: Расширенные взаимодействия: Мультимодальность и вызов функций
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»Эта часть показывает истинную силу моделей Gemini, объясняя, как работать с нетестовыми входами и подключать модель к внешним инструментам.
3.1. За пределами текста: Понимание мультимодальных входных данных
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Одной из определяющих характеристик семейства моделей Gemini является их врожденная многомодальная способность. Это означает, что они могут обрабатывать и рассуждать о разных типах данных, или «модальностях», таких как текст, изображения, аудио и видео, в рамках одного запроса.
Эта возможность реализуется путем построения аргумента contents как списка, содержащего несколько объектов Part, где каждый Part может содержать разный тип данных. Например, один запрос может включать изображение и текстовый вопрос об этом изображении.
3.2. Работа с изображениями
Sección titulada «3.2. Trabajando con Imágenes»SDK предоставляет два стратегически разных метода для обработки данных изображений. Выбор между ними зависит от конкретных требований случая использования, таких как размер файла и повторное использование.
Эта двойственность методов не является избыточностью, а преднамеренным дизайном, который учитывает различные операционные потребности. Онлайн-метод прост и отлично подходит для единственных анализов и удобства в разработке. API файлов, хотя и предполагает дополнительный шаг загрузки, имеет решающее значение для производственных сценариев, где эффективность, масштабируемость и обработка больших файлов являются первостепенными.
Метод 1: Данные изображения в línea (Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»Этот метод идеален для небольших файлов изображений (общий размер запроса, включая указания и байты, должен быть меньше 20 МБ) и для простоты разработки. Данные изображения передаются直接 в вызов generate_content.
-
Из локального файла: Файл изображения читается в бинарном режиме (
'rb') и передается вtypes.Part.from_bytes(), указывая правильный тип 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) -
Из URL: Можно использовать библиотеку, такую как
requests, чтобы получить байты изображения из URL, а затем передать их таким же образом.
Метод 2: API-файлов (Files API)
Sección titulada «Método 2: La API de Archivos (Files API)»Этот метод рекомендуется для больших файлов изображений (более 20 МБ) или для сценариев, в которых один и тот же файл будет повторно использоваться в нескольких запросах подсказок. Использование API файлов исключает необходимость повторно загружать одни и те же байты с каждым вызовом.
Рабочий процесс состоит из двух шагов:
- Загрузка: используется
client.files.upload()для загрузки файла на серверы Google. Этот метод возвращает объект файла, который действует как ссылка. - Указание: возвращенный объект файла передается напрямую в список
contentsвызоваgenerate_content. SDK занимается решением ссылки на загруженный файл.
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}")Файлы, загруженные через API Файлов, хранятся временно в течение 48 часов, прежде чем будут автоматически удалены. API также предоставляет методы для управления этими файлами, такие как get(), list() и delete().
3.3. Взаимодействие с Аудио и Видео
Sección titulada «3.3. Interacción con Audio y Vídeo»Концепции обработки изображений напрямую распространяются на другие модальности, такие как аудио и видео. Поскольку эти файлы обычно большие, API файлов является основным методом работы с ними.
Процесс идентичен процессу для больших изображений:
- Используйте
client.files.upload(), чтобы загрузить аудиофайл (например, MP3, WAV) или видеофайл (например, MP4). - Включите возвращаемый файловый объект в указание
generate_content.
Следующий пример показывает, как загрузить файл аудио и попросить модель его транскрибировать.
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. Вызов функций: Расширение возможностей модели
Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»Вызов функций, также известный как использование инструментов, является мощной техникой, которая позволяет модели языка взаимодействовать с внешними системами. Она позволяет модели отвечать на вопросы или выполнять действия, которые выходят за пределы ее внутреннего знания, такие как получение данных в режиме реального времени из API, запрос базы данных или управление устройством.
Общий рабочий процесс выглядит следующим образом:
- Определение инструментов: Определяется набор инструментов (функций Python), которые модель может вызвать. Это определение включает в себя имя функции, описание того, что она делает, и схему ее параметров.
- Передача инструментов модели: Передается список определенных инструментов модели при вызове
generate_content. - Модель решает вызвать: Модель анализирует указание пользователя и, если определяет, что одна из предоставленных инструментов может помочь ответить, вместо генерации текста, ее ответ будет содержать объект
Partтипаfunction_call. Этот объект указывает имя функции, которую необходимо вызвать, и аргументы, с которыми ее необходимо вызвать. - Выполнить функцию: Код приложения обнаруживает этот
function_call, выполняет соответствующую функцию Python с предоставленными аргументами и получает результат. - Вернуть результат модели: Осуществляется второй вызов
generate_content, предоставляя историю разговора плюс результат выполнения функции (завернутый вtypes.Part.from_function_response()). - Окончательный ответ: Модель использует результат функции для генерации окончательного ответа на естественном языке для пользователя.
Хотя исследовательские фрагменты не предоставляют пример кода вызова функций от конца до конца, структура объектов Part для function_call и function_response является основой для реализации этого продвинутого шаблона.
Часть 4: Подготовка к производству: Обработка ошибок, безопасность и управление
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»Эта заключительная часть предоставляет критически важную информацию, необходимую для создания прочных, надежных и ответственных приложений.
4.1. Надежная обработка ошибок
Sección titulada «4.1. Manejo Robusto de Errores»В производственной среде надежная обработка ошибок не является предметом обсуждения. Вызовы API могут завершиться неудачей по различным причинам, таким как недопустимые учетные данные, проблемы с сетью, исчерпание квоты или неправильно сформированные входные данные.
SDK использует стандартную систему исключений Python. Большинство ошибок, связанных с API, можно перехватить с помощью блока try...except, который ищет исключения из модуля google.api_core.exceptions или, если доступно, более конкретный класс, такой как 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}")При перехвате исключения объект исключения часто содержит ценную информацию для регистрации и отладки, такую как код состояния и описательное сообщение.
Важно учитывать, что сообщения об ошибках, хотя и полезны для разработчиков, могут быть двусмысленными. Они могут раскрывать детали внутренней реализации, которые могут быть использованы при враждебных атаках. Например, анализ сообщений об ошибках безопасности может раскрыть внутренние пороги или механизмы защиты, помогая злоумышленнику избежать защитных мер. Поэтому, хотя ошибки должны быть тщательно записаны на бэкенде, информация, представленная конечным пользователям, должна быть тщательно контролируема. Часто более безопасно отображать общее сообщение, такое как «Произошла ошибка при обработке вашего запроса», вместо того, чтобы раскрывать непереработанное сообщение об ошибке API.
В следующей таблице суммируются наиболее распространенные коды ошибок API и способы их решения.
Таблица 3: Распространенные коды ошибок API и решения
| Код HTTP | Состояние | Вероятная причина | Рекомендуемое действие на Python |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | Тело запроса неправильно сформировано (например, параметр с неправильным типом, обязательное поле отсутствует). | Проверьте, что параметры в и формат являются правильными. Убедитесь, что модель совместима с запрошенными функциями. |
| 403 | PERMISSION_DENIED | Ключ API неверен, у вас нет необходимых разрешений или вы пытаетесь получить доступ к ограниченному ресурсу (например, настроенной модели). | Проверьте, что ключ API (или аутентификация ADC для Vertex) настроен правильно и имеет необходимые разрешения. |
| 429 | RESOURCE_EXHAUSTED | Превышен лимит скорости API (запросов в минуту). | Реализуйте экспоненциальное отступление в вашей логике повтора. Рассмотрите возможность запроса увеличения квоты, если это необходимо для вашего приложения. |
| 500 | INTERNAL | Произошла непредвиденная ошибка на стороне Google. Иногда может быть вызвана очень длинным контекстом ввода. | Уменьшите длину подсказки. Попробуйте повторить запрос после короткой паузы. Если проблема сохраняется, рассмотрите возможность перехода на другую модель временно. |
| 503 | UNAVAILABLE | Сервис временно перегружен или недоступен. | Попробуйте повторить запрос после короткой паузы, используя стратегию экспоненциального отступления. Если проблема сохраняется, сообщите о проблеме. |
4.2. Управление безопасностью контента
Sección titulada «4.2. Gestión de la Seguridad del Contenido»API Gemini включает встроенные функции безопасности для фильтрации потенциально вредоносного контента. Эти функции предназначены для того, чтобы помочь разработчикам создавать более безопасные и ответственные приложения.
API классифицирует контент на четыре основные категории вреда:
- Преследование (
HARM_CATEGORY_HARASSMENT) - Подстрекательство к ненависти (
HARM_CATEGORY_HATE_SPEECH) - Сексуально откровенный контент (
HARM_CATEGORY_SEXUALLY_EXPLICIT) - Опасный контент (
HARM_CATEGORY_DANGEROUS_CONTENT)
Для каждой категории модель присваивает вероятность того, что контент является небезопасным. По умолчанию API блокирует подсказки и ответы, которые имеют вероятность MEDIUM или HIGH быть небезопасными в любой из этих категорий.
Разработчики могут переопределить эту настройку по умолчанию, передавая список объектов SafetySetting в параметр safety_settings в запросе. Это позволяет осуществлять детальный контроль над порогом блокировки для каждой категории.
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}")Когда ответ кажется пустым или происходит ошибка, крайне важно проверить обратную связь по безопасности. Объект ответа содержит prompt_feedback (для указания входных данных) и candidates.safety_ratings (для сгенерированного ответа). Эти атрибуты раскроют, был ли контент заблокирован и почему, что имеет решающее значение для отладки.
Следующая таблица проясняет значение различных порогов блокировки.
Таблица 4: Пороги конфигурации безопасности
| Константа API | Настройки в Google AI Studio | Описание |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | Н/Д | Порог не указан; используется порог модели по умолчанию. |
BLOCK_NONE | Блокировать none (Не блокировать) | Никогда не блокировать контент, независимо от вероятности того, что он небезопасен. Должно использоваться с крайней осторожностью. |
BLOCK_ONLY_HIGH | Блокировать few (Блокировать мало) | Блокировать только тогда, когда вероятность незащищенного контента равна HIGH. |
BLOCK_MEDIUM_AND_ABOVE | Блокировать some (Блокировать некоторые) | (По умолчанию для большинства моделей) Блокировать, когда вероятность незащищенного контента равна MEDIUM или HIGH. |
BLOCK_LOW_AND_ABOVE | Блокировать most (Блокировать большинство) | Блокировать, когда вероятность содержания незащищенного контента равна LOW, MEDIUM или HIGH. |
4.3. Управление Моделями
Sección titulada «4.3. Gestión de Modelos»SDK предоставляет программный способ обнаружения доступных моделей и их возможностей. Это полезно для создания приложений, которые могут адаптироваться к разным моделям или для проверки возможностей модели перед ее использованием.
Метод client.models.list() возвращает итератор по доступным моделям.
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)Эта функциональность также может быть использована для перечисления конкретно моделей, которые были доработаны (fine-tuned) пользователем, установив query_base=False в конфигурации запроса списка. Это позволяет приложениям обнаруживать и использовать динамически настраиваемые модели.
Часть 5: Проверка Окружения и Технический Чек-лист
Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»Для завершения подготовки интеграций на основе унифицированного SDK google-genai в аренду Portelcore, проверьте выполнение следующих технических этапов:
- Я перенес все скрипты аренды из устаревшей библиотеки
google-generativeaiна новый стандартgoogle-genai. ✓ - Ключи API управляются исключительно через переменную среды
GOOGLE_API_KEYили шифруются в менеджере секретов Google Cloud вместо записи в открытом тексте. ✓ - Реализуется надежный контроль исключений (
google.api_core.exceptions) для перехвата кодов состояния 429 (Resource Exhausted) с политикой экспоненциального повторного подключения (exponential backoff). ✓ - Температура и пороги безопасности (
safety_settings) формализованы в соответствии с деловым случаем доменаportelcore.com. ✓

