Live API - WebSockets API reference

Live API — это API с сохранением состояния, использующий WebSockets . В этом разделе вы найдете дополнительные сведения об API WebSockets.

Сессии

Соединение WebSocket устанавливает сессию между клиентом и сервером Gemini. После того, как клиент инициирует новое соединение, сессия может обмениваться сообщениями с сервером, чтобы:

  • Отправляйте текст, аудио или видео на сервер Gemini.
  • Получайте аудио-, текстовые запросы или запросы на выполнение функциональных задач с сервера Gemini.

WebSocket-соединение

Для начала сеанса подключитесь к следующему адресу веб-сокета:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Настройки сессии

Первоначальное сообщение, отправляемое после установления соединения WebSocket, задает конфигурацию сессии, которая включает в себя модель, параметры генерации, системные инструкции и инструменты.

Вы не можете обновить конфигурацию, пока соединение открыто. Однако вы можете изменить параметры конфигурации, за исключением модели, при приостановке и возобновлении сессии с помощью механизма возобновления сессии .

См. следующий пример конфигурации. Обратите внимание, что регистр имен в SDK может различаться. Параметры конфигурации Python SDK можно найти здесь .


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Для получения дополнительной информации о поле API см. generationConfig .

Отправляйте сообщения

Для обмена сообщениями по WebSocket-соединению клиент должен отправить JSON-объект по открытому WebSocket-соединению. JSON-объект должен содержать ровно одно из полей из следующего набора объектов:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Поддерживаемые клиентские сообщения

Список поддерживаемых клиентских сообщений приведен в следующей таблице:

Сообщение Описание
BidiGenerateContentSetup Настройки сессии будут отправлены в первом сообщении.
BidiGenerateContentClientContent Постепенное обновление содержимого текущей беседы, предоставляемое клиентом.
BidiGenerateContentRealtimeInput Ввод аудио, видео или текста в реальном времени.
BidiGenerateContentToolResponse Ответ на сообщение ToolCallMessage полученное от сервера.

Получайте сообщения

Для получения сообщений от Gemini необходимо прослушивать событие WebSocket 'message', а затем анализировать результат в соответствии с определением поддерживаемых серверных сообщений.

См. следующее:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Сообщения сервера могут содержать поле usageMetadata но в остальном будут включать ровно одно из других полей сообщения BidiGenerateContentServerMessage . (Объединение messageType не выражается в формате JSON, поэтому поле будет отображаться на верхнем уровне сообщения.)

Сообщения и события

Завершение активности

Этот тип не содержит полей.

Отмечает завершение активности пользователя.

Обработка действий

Различные способы обработки активности пользователей.

Перечисления
ACTIVITY_HANDLING_UNSPECIFIED Если параметр не указан, по умолчанию используется поведение START_OF_ACTIVITY_INTERRUPTS .
START_OF_ACTIVITY_INTERRUPTS Если это так, начало активности прервёт ответ модели (также называемое «вмешательством»). Текущий ответ модели будет прерван в момент прерывания. Это поведение по умолчанию.
NO_INTERRUPTION Реакция модели не будет прервана.

ActivityStart

Этот тип не содержит полей.

Отмечает начало активности пользователя.

AudioTranscriptionConfig

Этот тип не содержит полей.

Настройка транскрипции аудио.

Автоматическое определение активности

Настраивает автоматическое обнаружение активности.

Поля
disabled

bool

Необязательно. Если включено (по умолчанию), обнаруженный голосовой и текстовый ввод засчитывается как активность. Если отключено, клиент должен отправлять сигналы активности.

startOfSpeechSensitivity

StartSensitivity

Необязательный параметр. Определяет вероятность обнаружения речи.

prefixPaddingMs

int32

Необязательно. Требуемая продолжительность обнаруженной речи до момента её начала. Чем ниже это значение, тем чувствительнее определение начала речи и тем короче распознаётся речь. Однако это также увеличивает вероятность ложных срабатываний.

endOfSpeechSensitivity

EndSensitivity

Необязательный параметр. Определяет вероятность прекращения обнаруженной речи.

silenceDurationMs

int32

Необязательно. Требуемая продолжительность обнаруженного отсутствия речи (например, тишины) до окончания речи. Чем больше это значение, тем дольше могут быть паузы в речи, не прерывая активность пользователя, но это увеличит задержку модели.

BidiGenerateContentClientContent

Постепенное обновление текущей переписки, предоставляемой клиентом. Весь контент безоговорочно добавляется к истории переписки и используется в качестве запроса к модели для генерации контента.

Сообщение, размещенное здесь, прервет процесс генерации текущей модели.

Поля
turns[]

Content

Необязательно. Содержимое, добавляемое к текущей беседе с моделью.

Для запросов с одним циклом обработки это один экземпляр. Для запросов с несколькими циклами обработки это повторяющееся поле, содержащее историю переписки и последний запрос.

turnComplete

bool

Необязательный параметр. Если значение равно true, указывает, что генерация контента на сервере должна начинаться с текущего накопленного запроса. В противном случае сервер ожидает дополнительных сообщений перед началом генерации.

BidiGenerateContentRealtimeInput

Пользовательский ввод, отправляемый в режиме реального времени.

Различные форматы (аудио, видео и текст) обрабатываются как параллельные потоки. Порядок потоков не гарантируется.

Это отличается от BidiGenerateContentClientContent по нескольким параметрам:

  • Может непрерывно и без перерыва отправляться на этап генерации модели.
  • Если возникает необходимость смешивать данные, чередующиеся между BidiGenerateContentClientContent и BidiGenerateContentRealtimeInput , сервер пытается оптимизировать отклик для достижения наилучшего результата, но гарантий нет.
  • Конец реплики явно не указан, а определяется действиями пользователя (например, окончанием речи).
  • Еще до окончания хода обработки данные обрабатываются поэтапно для оптимизации и обеспечения быстрого запуска реакции модели.
Поля
mediaChunks[]

Blob

Необязательно. Встроенные байтовые данные для ввода мультимедиа. Использование нескольких mediaChunks не поддерживается, все, кроме первого, будут проигнорированы.

УСТАРЕВШИЙ ВАРИАНТ: Используйте вместо него audio , video или text .

audio

Blob

Необязательно. Они формируют поток входного аудиосигнала в реальном времени.

video

Blob

Необязательно. Они формируют поток видеовхода в реальном времени.

activityStart

ActivityStart

Необязательный параметр. Отмечает начало активности пользователя. Этот параметр может быть отправлен только в том случае, если автоматическое (т.е. на стороне сервера) обнаружение активности отключено.

activityEnd

ActivityEnd

Необязательно. Отмечает окончание активности пользователя. Это сообщение может быть отправлено только в том случае, если автоматическое (т.е. на стороне сервера) обнаружение активности отключено.

audioStreamEnd

bool

Необязательно. Указывает на то, что аудиопоток завершился, например, из-за выключения микрофона.

Это сообщение следует отправлять только при включенном автоматическом обнаружении активности (что является настройкой по умолчанию).

Клиент может возобновить трансляцию, отправив аудиосообщение.

text

string

Необязательно. Они формируют поток ввода текста в реальном времени.

BidiGenerateContentServerContent

Постепенные обновления сервера, генерируемые моделью в ответ на сообщения клиента.

Контент генерируется максимально быстро, но не в режиме реального времени. Клиенты могут по своему выбору буферизовать и воспроизводить его в режиме реального времени.

Поля
generationComplete

bool

Только вывод. Если значение равно true, это означает, что генерация модели завершена.

Если генерация модели прерывается, сообщение 'generation_complete' в прерванном цикле не появится, процесс продолжится по схеме 'interrupted > turn_complete'.

Когда модель предполагает воспроизведение в реальном времени, между generation_complete и turn_complete возникает задержка, вызванная ожиданием моделью завершения воспроизведения.

turnComplete

bool

Только вывод. Если значение равно true, это означает, что модель завершила свой ход. Генерация начнётся только в ответ на дополнительные сообщения от клиента.

interrupted

bool

Только вывод. Если значение равно true, это означает, что сообщение от клиента прервало текущую генерацию модели. Если клиент воспроизводит контент в реальном времени, это хороший сигнал для остановки и очистки текущей очереди воспроизведения.

groundingMetadata

GroundingMetadata

Только для вывода. Метаданные для сгенерированного контента.

inputTranscription

BidiGenerateContentTranscription

Только вывод. Входная аудиотранскрипция. Транскрипция отправляется независимо от других сообщений сервера, и гарантированного порядка нет.

outputTranscription

BidiGenerateContentTranscription

Только вывод. Вывод аудиозаписи. Транскрипция отправляется независимо от других сообщений сервера, и гарантированного порядка нет, в частности, между serverContent и этим outputTranscription .

urlContextMetadata

UrlContextMetadata

modelTurn

Content

Только выходные данные. Контент, сгенерированный моделью в рамках текущего диалога с пользователем.

BidiGenerateContentServerMessage

Ответное сообщение для вызова функции BidiGenerateContent.

Поля
usageMetadata

UsageMetadata

Только вывод. Метаданные об использовании ответа(ов).

Поле объединения messageType . Тип сообщения. messageType может принимать только одно из следующих значений:
setupComplete

BidiGenerateContentSetupComplete

Только для вывода. Отправляется в ответ на сообщение BidiGenerateContentSetup от клиента после завершения настройки.

serverContent

BidiGenerateContentServerContent

Только выходные данные. Контент, сгенерированный моделью в ответ на сообщения клиента.

toolCall

BidiGenerateContentToolCall

Только вывод. Запрос к клиенту на выполнение functionCalls и возврат ответов с соответствующими id .

toolCallCancellation

BidiGenerateContentToolCallCancellation

Только вывод. Уведомление для клиента о том, что ранее отправленное сообщение ToolCallMessage с указанным id должно быть отменено.

goAway

GoAway

Только вывод. Уведомление о скором отключении сервера.

sessionResumptionUpdate

SessionResumptionUpdate

Только вывод. Обновление состояния возобновления сессии.

BidiGenerateContentSetup

Сообщение, которое будет отправлено в первом (и только в первом) BidiGenerateContentClientMessage . Содержит конфигурацию, которая будет применяться на протяжении всего процесса потокового RPC-вызова.

Клиентам следует дождаться сообщения BidiGenerateContentSetupComplete прежде чем отправлять какие-либо дополнительные сообщения.

Поля
model

string

Обязательно. Имя ресурса модели. Оно служит идентификатором для используемой модели.

Формат: models/{model}

generationConfig

GenerationConfig

Необязательно. Конфигурация генерации.

Следующие поля не поддерживаются:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
systemInstruction

Content

Необязательно. Пользователь предоставил системные инструкции для данной модели.

Примечание: текст должен использоваться только по частям, содержание каждой части должно быть в отдельном абзаце.

tools[]

Tool

Необязательно. Список Tools модель может использовать для генерации следующего ответа.

Tool — это фрагмент кода, позволяющий системе взаимодействовать с внешними системами для выполнения действия или набора действий, выходящих за рамки знаний и возможностей модели.

realtimeInputConfig

RealtimeInputConfig

Необязательный параметр. Настраивает обработку ввода в реальном времени.

sessionResumption

SessionResumptionConfig

Необязательный параметр. Настраивает механизм возобновления сессии.

Если эта опция включена, сервер будет отправлять сообщения SessionResumptionUpdate .

contextWindowCompression

ContextWindowCompressionConfig

Необязательный параметр. Настраивает механизм сжатия контекстного окна.

Если эта опция включена, сервер автоматически уменьшит размер контекста, когда он превысит заданную длину.

inputAudioTranscription

AudioTranscriptionConfig

Необязательный параметр. Если задан, включает транскрипцию голосового ввода. Транскрипция соответствует языку входного аудио, если это настроено.

outputAudioTranscription

AudioTranscriptionConfig

Необязательный параметр. Если задан, включает транскрипцию аудиовыхода модели. Транскрипция соответствует языковому коду, указанному для выходного аудио, если таковой задан.

proactivity

ProactivityConfig

Необязательный параметр. Настраивает проактивность модели.

Это позволяет модели заблаговременно реагировать на входные данные и игнорировать нерелевантную информацию.

BidiGenerateContentSetupComplete

Этот тип не содержит полей.

Отправлено в ответ на сообщение BidiGenerateContentSetup от клиента.

BidiGenerateContentToolCall

Запрос к клиенту на выполнение functionCalls и возврат ответов с соответствующими id .

Поля
functionCalls[]

FunctionCall

Только вывод. Вызов функции, которая будет выполнена.

BidiGenerateContentToolCallCancellation

Уведомление для клиента о том, что ранее отправленное сообщение ToolCallMessage с указанным id не должно было быть выполнено и должно быть отменено. Если эти вызовы инструментов имели побочные эффекты, клиенты могут попытаться отменить их. Это сообщение появляется только в случаях, когда клиенты прерывают работу сервера.

Поля
ids[]

string

Только вывод. Идентификаторы вызовов инструментов, которые необходимо отменить.

BidiGenerateContentToolResponse

Ответ клиента, сгенерированный на ToolCall полученный от сервера. Отдельные объекты FunctionResponse сопоставляются с соответствующими объектами FunctionCall по полю id .

Обратите внимание, что в одностороннем и серверно-потоковом режимах вызов функции GenerateContent API происходит путем обмена частями Content , тогда как в двунаправленном режиме вызов функции GenerateContent API происходит через этот выделенный набор сообщений.

Поля
functionResponses[]

FunctionResponse

Необязательно. Ответ на вызовы функций.

BidiGenerateContentТранскрипция

Транскрипция аудио (входного или выходного сигнала).

Поля
text

string

Текст транскрипции.

ContextWindowCompressionConfig

Включает сжатие контекстного окна — механизм управления контекстным окном модели таким образом, чтобы оно не превышало заданную длину.

Поля
Union field compressionMechanism . Механизм сжатия контекстного окна. compressionMechanism может принимать только одно из следующих значений:
slidingWindow

SlidingWindow

Механизм раздвижного окна.

triggerTokens

int64

Количество токенов (до начала хода), необходимое для запуска сжатия контекстного окна.

Это можно использовать для баланса между качеством и задержкой, поскольку более короткие контекстные окна могут привести к более быстрой реакции модели. Однако любая операция сжатия вызовет временное увеличение задержки, поэтому их не следует запускать часто.

Если значение не задано, по умолчанию используется 80% от лимита контекстного окна модели. Это оставляет 20% для следующего запроса пользователя/ответа модели.

EndSensitivity

Определяет способ определения конца речи.

Перечисления
END_SENSITIVITY_UNSPECIFIED Значение по умолчанию — END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH Автоматическое распознавание чаще прерывает речь.
END_SENSITIVITY_LOW Автоматическое распознавание реже прерывает речь.

Уходите

Уведомление о том, что сервер скоро отключится.

Поля
timeLeft

Duration

Оставшееся время до завершения соединения будет помечено как «ПРЕРЫВНО».

Эта продолжительность никогда не будет меньше минимального значения, установленного для конкретной модели, которое будет указано вместе с ограничениями скорости для данной модели.

ProactivityConfig

Настройка функций проактивного управления.

Поля
proactiveAudio

bool

Необязательно. Если включено, модель может отказаться отвечать на последний запрос. Например, это позволяет модели игнорировать речь вне контекста или молчать, если пользователь еще не отправлял запрос.

RealtimeInputConfig

Настраивает поведение ввода в реальном времени в BidiGenerateContent .

Поля
automaticActivityDetection

AutomaticActivityDetection

Необязательно. Если не задано, автоматическое определение активности включено по умолчанию. Если автоматическое определение голоса отключено, клиент должен отправлять сигналы активности.

activityHandling

ActivityHandling

Необязательный параметр. Определяет, какое воздействие оказывает данное действие.

turnCoverage

TurnCoverage

Необязательный параметр. Определяет, какой ввод будет включен в ход пользователя.

SessionResumptionConfig

Настройка возобновления сессии.

Это сообщение включается в конфигурацию сессии как BidiGenerateContentSetup.sessionResumption . Если это настроено, сервер будет отправлять сообщения SessionResumptionUpdate .

Поля
handle

string

Идентификатор предыдущей сессии. Если он отсутствует, создается новая сессия.

Дескрипторы сессий берутся из значений SessionResumptionUpdate.token в предыдущих соединениях.

Обновление возобновления сессии

Обновление состояния возобновления сессии.

Отправляется только в том случае, если задан параметр BidiGenerateContentSetup.sessionResumption .

Поля
newHandle

string

Новый дескриптор, представляющий состояние, которое можно возобновить. Пусто, если resumable = false.

resumable

bool

Истина, если текущую сессию можно возобновить на данном этапе.

Возобновление сессии невозможно на некоторых этапах. Например, когда модель выполняет вызовы функций или генерирует данные. Возобновление сессии (с использованием токена предыдущей сессии) в таком состоянии приведет к потере данных. В этих случаях newHandle будет пустым, а resumable — false.

СлайдингВанно

Метод SlidingWindow работает путем удаления содержимого в начале контекстного окна. Полученный контекст всегда будет начинаться с начала хода роли USER. Системные инструкции и любые BidiGenerateContentSetup.prefixTurns всегда будут оставаться в начале результата.

Поля
targetTokens

int64

Целевое количество токенов для сохранения. Значение по умолчанию: trigger_tokens/2.

Удаление части контекстного окна приводит к временному увеличению задержки, поэтому это значение следует калибровать, чтобы избежать частых операций сжатия.

Начальная чувствительность

Определяет способ определения начала речи.

Перечисления
START_SENSITIVITY_UNSPECIFIED Значение по умолчанию — START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH Автоматическое распознавание будет чаще определять начало речи.
START_SENSITIVITY_LOW Автоматическое распознавание будет реже обнаруживать начало речи.

TurnCoverage

Варианты выбора того, какой ввод будет включен в ход пользователя.

Перечисления
TURN_COVERAGE_UNSPECIFIED Если параметр не указан, по умолчанию используется поведение TURN_INCLUDES_ONLY_ACTIVITY .
TURN_INCLUDES_ONLY_ACTIVITY В ходе выполнения действия пользователем учитывается только активность с момента последнего хода, исключая бездействие (например, тишина в аудиопотоке). Это поведение по умолчанию.
TURN_INCLUDES_ALL_INPUT В ходе хода пользователя учитывается весь ввод данных в реальном времени с момента последнего хода, включая периоды бездействия (например, тишина в аудиопотоке).

UrlContextMetadata

Метаданные, относящиеся к инструменту получения контекста URL-адреса.

Поля
urlMetadata[]

UrlMetadata

Список контекста URL-адреса.

UsageMetadata

Метаданные об использовании ответа(ов).

Поля
promptTokenCount

int32

Только вывод. Количество токенов в приглашении. Если задан параметр cachedContent , это по-прежнему общий эффективный размер приглашения, то есть он включает количество токенов в кэшированном содержимом.

cachedContentTokenCount

int32

Количество токенов в кэшированной части запроса (кэшированное содержимое)

responseTokenCount

int32

Только вывод. Общее количество токенов по всем сгенерированным вариантам ответа.

toolUsePromptTokenCount

int32

Только вывод. Количество токенов, присутствующих в подсказках использования инструмента.

thoughtsTokenCount

int32

Только вывод. Количество токенов мыслей для моделей мышления.

totalTokenCount

int32

Только вывод. Общее количество токенов для запроса на генерацию (кандидаты запроса + ответа).

promptTokensDetails[]

ModalityTokenCount

Только выходные данные. Список модальностей, которые были обработаны во входном запросе.

cacheTokensDetails[]

ModalityTokenCount

Только вывод. Список вариантов содержимого, кэшированного в запросе.

responseTokensDetails[]

ModalityTokenCount

Только вывод. Список модальностей, которые были возвращены в ответе.

toolUsePromptTokensDetails[]

ModalityTokenCount

Только выходные данные. Список модальностей, обработанных для обработки запросов на использование инструмента.

Временные токены аутентификации

Временные токены аутентификации можно получить, вызвав AuthTokenService.CreateToken , а затем использовать с GenerativeService.BidiGenerateContentConstrained , либо передав токен в параметре запроса access_token , либо в заголовке HTTP Authorization с префиксом " Token ".

CreateAuthTokenRequest

Создайте временный токен аутентификации.

Поля
authToken

AuthToken

Обязательно. Токен для создания.

AuthToken

Запрос на создание временного токена аутентификации.

Поля
name

string

Только вывод. Идентификатор. Сам токен.

expireTime

Timestamp

Необязательно. Только для ввода. Неизменяемо. Необязательное время, по истечении которого при использовании полученного токена сообщения в сессиях BidiGenerateContent будут отклонены. (Gemini может превентивно закрыть сессию по истечении этого времени.)

Если значение не задано, то по умолчанию устанавливается интервал в 30 минут. Если значение задано, оно должно быть меньше 20 часов.

newSessionExpireTime

Timestamp

Необязательный параметр. Только для ввода. Неизменяемый. Время, по истечении которого новые сессии Live API, использующие токен, полученный в результате этого запроса, будут отклонены.

Если значение не задано, по умолчанию устанавливается интервал в 60 секунд. Если задано, это значение должно быть меньше 20 часов.

fieldMask

FieldMask

Необязательно. Только для ввода. Неизменяемо. Если field_mask пуст и bidiGenerateContentSetup отсутствует, то эффективное сообщение BidiGenerateContentSetup берется из соединения Live API.

Если field_mask пуст, а bidiGenerateContentSetup присутствует , то в этом запросе эффективное сообщение BidiGenerateContentSetup полностью берется из bidiGenerateContentSetup . Сообщение настройки от соединения Live API игнорируется.

Если field_mask не пуст, то соответствующие поля из bidiGenerateContentSetup перезапишут поля из сообщения настройки в соединении Live API.

config поля объединения. Конфигурация, специфичная для метода, для результирующего токена. config может принимать только одно из следующих значений:
bidiGenerateContentSetup

BidiGenerateContentSetup

Необязательный параметр. Только для ввода. Неизменяемый. Конфигурация, специфичная для BidiGenerateContent .

uses

int32

Необязательный параметр. Только для ввода. Неизменяемый. Количество раз, которое можно использовать токен. Если это значение равно нулю, ограничение не применяется. Возобновление сессии Live API не считается использованием. Если значение не указано, по умолчанию используется 1.

Более подробная информация о распространенных типах.

Для получения дополнительной информации о часто используемых типах ресурсов API: Blob , Content , FunctionCall , FunctionResponse , GenerationConfig , GroundingMetadata , ModalityTokenCount и Tool , см. раздел «Генерация контента» .