Live API - WebSockets API reference

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

Сессии

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

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

Веб-сокет-соединение

Чтобы начать сеанс, подключитесь к этой конечной точке веб-сокета:

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, а затем проанализируйте результат в соответствии с определением поддерживаемых сообщений сервера.

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

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 Реакция модели не будет прервана.

Начало активности

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

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

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

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

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

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

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

Поля
disabled

bool

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

startOfSpeechSensitivity

StartSensitivity

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

prefixPaddingMs

int32

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

endOfSpeechSensitivity

EndSensitivity

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

silenceDurationMs

int32

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

BidiGenerateContentClientContent

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

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

Поля
turns[]

Content

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

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

turnComplete

bool

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

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

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

Когда модель прерывается во время генерации, в прерванном ходу не будет сообщения «Generation_complete», оно будет проходить через «interrupted >turn_complete».

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

turnComplete

bool

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

interrupted

bool

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

groundingMetadata

GroundingMetadata

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

outputTranscription

BidiGenerateContentTranscription

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

modelTurn

Content

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

BidiGenerateContentServerMessage

Ответное сообщение на вызов BidiGenerateContent.

Поля
usageMetadata

UsageMetadata

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

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

BidiGenerateContentSetupComplete

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

serverContent

BidiGenerateContentServerContent

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

toolCall

BidiGenerateContentToolCall

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

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

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

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

outputAudioTranscription

AudioTranscriptionConfig

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

BidiGenerateContentSetupComplete

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

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

BidiGenerateContentToolCall

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

Поля
functionCalls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

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

Поля
ids[]

string

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

BidiGenerateContentToolResponse

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

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

Поля
functionResponses[]

FunctionResponse

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

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

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

Поля
text

string

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

Контекствиндовкомпрессионконфиг

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

Поля
compressionMechanism полей объединения. Используемый механизм сжатия контекстного окна. compressionMechanism может быть только одним из следующих:
slidingWindow

SlidingWindow

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

triggerTokens

int64

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

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

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

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

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

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

Уходите

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

Поля
timeLeft

Duration

Оставшееся время до того, как соединение будет прервано как ABORTED.

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

RealtimeInputConfig

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

Поля
automaticActivityDetection

AutomaticActivityDetection

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

activityHandling

ActivityHandling

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

turnCoverage

TurnCoverage

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

сессионресумпментконфиг

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

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

Поля
handle

string

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

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

сессионрезумминтепдате

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

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

Поля
newHandle

string

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

resumable

bool

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

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

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

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

Поля
targetTokens

int64

Целевое количество токенов, которое нужно сохранить. Значение по умолчанию — триггер_токены/2.

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

СтартЧувствительность

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

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

Покрытие оборотов

Опции о том, какой ввод включен в ход пользователя.

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

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

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

Поля
promptTokenCount

int32

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

cachedContentTokenCount

int32

Количество токенов в кэшированной части приглашения (кэшированный контент)

responseTokenCount

int32

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

toolUsePromptTokenCount

int32

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

thoughtsTokenCount

int32

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

totalTokenCount

int32

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

promptTokensDetails[]

ModalityTokenCount

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

cacheTokensDetails[]

ModalityTokenCount

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

responseTokensDetails[]

ModalityTokenCount

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

toolUsePromptTokensDetails[]

ModalityTokenCount

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

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

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