Посмотреть на ai.google.dev | Запустить в Google Colab | Посмотреть исходный код на GitHub |
API Gemini поддерживает запросы с текстовыми, графическими и аудиоданными, также известные как мультимодальные запросы. В подсказки можно включать текст, изображения и аудио. Для небольших изображений вы можете указать модель Gemini непосредственно на локальный файл при предоставлении подсказки. Для больших изображений, видео (последовательностей кадров изображений) и аудио загрузите файлы с помощью File API , прежде чем включать их в запросы.
File API позволяет хранить до 20 ГБ файлов на проект, при этом размер каждого файла не превышает 2 ГБ. Файлы хранятся в течение 48 часов, и к ним можно получить доступ с помощью ключа API для генерации в течение этого периода времени. Он доступен бесплатно во всех регионах, где доступен Gemini API .
Информацию о допустимых форматах файлов (типах MIME) и поддерживаемых моделях см. в разделе Поддерживаемые форматы файлов .
В этом руководстве показано, как использовать File API для загрузки медиафайла и включения его в вызов GenerateContent
API Gemini. Дополнительные сведения см. в примерах кода .
Настраивать
Прежде чем использовать File API, вам необходимо установить пакет Gemini API SDK и настроить ключ API. В этом разделе описывается, как выполнить эти шаги настройки.
Установите Python SDK и импортируйте пакеты.
Python SDK для Gemini API содержится в пакете google-generativeai . Установите зависимость с помощью pip.
pip install -q -U google-generativeai
Импортируйте необходимые пакеты.
import google.generativeai as genai
from IPython.display import Markdown
Настройте свой ключ API
Файловый API использует ключи API для аутентификации и доступа. Загруженные файлы связаны с проектом, связанным с ключом API. В отличие от других API-интерфейсов Gemini, использующих ключи API, ваш ключ API также предоставляет доступ к данным, которые вы загрузили в File API, поэтому будьте особенно осторожны, обеспечивая безопасность своего ключа API. Дополнительные сведения о обеспечении безопасности ключей см. в разделе Рекомендации по использованию ключей API .
Сохраните свой ключ API в секрете Colab с именем GOOGLE_API_KEY
. Если у вас еще нет ключа API или вы не знакомы с секретами Colab, обратитесь к краткому руководству по аутентификации .
from google.colab import userdata
GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')
genai.configure(api_key=GOOGLE_API_KEY)
Загрузите файл в File API
File API позволяет загружать различные мультимодальные типы MIME, включая изображения и аудиоформаты. File API обрабатывает входные данные, которые можно использовать для создания контента с помощью model.generateContent
или model.streamGenerateContent
.
File API принимает файлы размером менее 2 ГБ и может хранить до 20 ГБ файлов на проект. Файлы хранятся 2 дня и не могут быть загружены через API.
Сначала вы подготовите образец изображения для загрузки в API.
Чтобы загрузить собственный файл, смотрите раздел Приложение .
curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg
Далее вы загрузите этот файл в File API.
sample_file = genai.upload_file(path="image.jpg",
display_name="Sample drawing")
print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")
Uploaded file 'Sample drawing' as: https://generativelanguage.googleapis.com/v1beta/files/ui00j5zfuqe0
response
показывает, что File API сохранил указанное display_name
для загруженного файла и uri
для ссылки на файл в вызовах Gemini API. Используйте response
, чтобы отслеживать, как загруженные файлы сопоставляются с URI.
В зависимости от ваших вариантов использования вы можете хранить URI в таких структурах, как dict
или база данных.
Получить файл
После загрузки файла вы можете убедиться, что API успешно получил файлы, вызвав files.get
.
Он позволяет вам получить метаданные файла, загруженные в API файлов, связанные с облачным проектом, которому принадлежит ваш ключ API. Только name
(и, соответственно, uri
) уникальны. Используйте displayName
для идентификации файлов только в том случае, если вы сами управляете уникальностью.
file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")
Генерировать контент
После загрузки файла вы можете отправлять запросы GenerateContent
, ссылающиеся на URI File API. В этом примере вы создаете приглашение, которое начинается с текста, за которым следует загруженное изображение.
# Set the model to Gemini 1.5 Pro.
model = genai.GenerativeModel(model_name="models/gemini-1.5-pro-latest")
response = model.generate_content(["Describe the image with a creative description.", sample_file])
Markdown(">" + response.text)
Удалить файлы
Файлы автоматически удаляются через 2 дня. Вы также можете удалить их вручную, используя files.delete()
.
genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')
Поддерживаемые форматы файлов
Модели Gemini поддерживают запросы к файлам нескольких форматов. В этом разделе объясняются особенности использования общих медиаформатов для подсказок, в частности изображений, аудио и видеофайлов. Вы можете использовать медиафайлы для запроса только в определенных версиях моделей, как показано в следующей таблице.
Модель | Изображений | Аудио | видео |
---|---|---|---|
Gemini 1.5 Pro (выпуск 008 и новее) | ✔ (максимум 3600 файлов изображений) | ✔ | ✔ |
Близнецы Про Видение | ✔ (максимум 16 файлов изображений) |
Форматы изображений
Вы можете использовать данные изображения для подсказок на моделях gemini-pro-vision
и gemini-1.5-pro
. При использовании изображений для подсказок на них распространяются следующие ограничения и требования:
- Изображения должны относиться к одному из следующих типов MIME данных изображения:
- PNG - изображение/png
- JPEG — изображение/jpeg
- WEBP — изображение/webp
- HEIC — изображение/heic
- HEIF - изображение/хеф
- Максимум 16 отдельных изображений для
gemini-pro-vision
и 3600 изображений дляgemini-1.5-pro
- Никаких конкретных ограничений на количество пикселей в изображении; однако изображения большего размера уменьшаются до максимального разрешения 3072 x 3072, сохраняя при этом исходное соотношение сторон.
Аудио форматы
Вы можете использовать аудиоданные для подсказок с помощью модели gemini-1.5-pro
. Когда вы используете аудио для подсказок, на них распространяются следующие ограничения и требования:
- Аудиоданные поддерживаются в следующих распространенных типах MIME аудиоформатов:
- WAV — аудио/wav
- MP3 - аудио/mp3
- AIFF — аудио/aiff
- AAC — аудио/aac
- OGG Vorbis — аудио/ogg
- FLAC — аудио/flac
- Максимальная поддерживаемая продолжительность аудиоданных в одном приглашении — 9,5 часов.
- Аудиофайлы преобразуются до разрешения данных 16 Кбит/с, а несколько каналов звука объединяются в один канал.
- Конкретного ограничения на количество аудиофайлов в одном приглашении не существует, однако общая продолжительность всех аудиофайлов в одном приглашении не может превышать 9,5 часов.
Видео форматы
Вы можете использовать видеоданные для подсказки с моделью gemini-1.5-pro
. Однако форматы видеофайлов не поддерживаются API Gemini в качестве прямого ввода. Вы можете использовать видеоданные в качестве подсказки, разбив видео на серию неподвижных изображений и отдельный аудиофайл. Этот подход позволяет вам управлять объемом данных и уровнем детализации видео, выбирая, сколько кадров в секунду будет включено в приглашение из видеофайла.
Приложение: Загрузка файлов в Colab
В этом блокноте используется файловый API с файлами, загруженными из Интернета. Если вы запускаете это в Colab и хотите использовать свои собственные файлы, сначала необходимо загрузить их в экземпляр Colab.
Сначала нажмите «Файлы» на левой боковой панели, затем нажмите кнопку «Загрузить» :
Далее вы загрузите этот файл в File API. В форме для ячейки кода ниже введите имя загруженного вами файла и укажите подходящее отображаемое имя для файла, а затем запустите ячейку.
my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}
my_file = genai.upload_file(path=my_filename,
display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")