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

Конфигурация сеанса

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

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

См. следующий пример конфигурации. Обратите внимание, что регистр имен в 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, поэтому поле будет отображаться на верхнем уровне сообщения.)

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

ActivityEnd

Этот тип не имеет полей.

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

ActivityHandling

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

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

ActivityStart

Этот тип не имеет полей.

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

АудиоТранскрипцияКонфигурация

Этот тип не имеет полей.

Конфигурация аудиотранскрипции.

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

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

Поля
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 .

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

Поля
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

Оставшееся время до завершения соединения будет отмечено как ABORTED.

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

ProactivityConfig

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

Поля
proactiveAudio

bool

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

RealtimeInputConfig

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

Поля
automaticActivityDetection

AutomaticActivityDetection

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

activityHandling

ActivityHandling

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

turnCoverage

TurnCoverage

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

SessionResumptionConfig

Конфигурация возобновления сеанса.

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

Поля
handle

string

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

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

SessionResumptionUpdate

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

Отправляется только если установлен BidiGenerateContentSetup.sessionResumption .

Поля
newHandle

string

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

resumable

bool

True, если текущий сеанс может быть возобновлен в этой точке.

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

Раздвижное окно

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

Поля
targetTokens

int64

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

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

StartSensitivity

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

Перечисления
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.

ИспользованиеМетаданных

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

Поля
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.

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

BidiGenerateContentSetup

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

uses

int32

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

Дополнительная информация о распространенных типах

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