Multimodal Live API

Мультимодальный Live API обеспечивает двунаправленное голосовое и видео взаимодействие с Gemini с малой задержкой. Используя Multimodal Live API, вы можете предоставить конечным пользователям возможность естественного, человеческого голосового общения, а также возможность прерывать ответы модели с помощью голосовых команд. Модель может обрабатывать ввод текста, аудио и видео, а также обеспечивать вывод текста и звука.

Возможности

Мультимодальный Live API включает в себя следующие ключевые возможности:

• Мультимодальность: модель может видеть, слышать и говорить.
• Взаимодействие в реальном времени с малой задержкой: обеспечивает быструю реакцию.
• Память сеанса: модель сохраняет память обо всех взаимодействиях в течение одного сеанса, вспоминая ранее услышанную или увиденную информацию.
• Поддержка вызова функций, выполнения кода и поиска как инструмента: обеспечивает интеграцию с внешними службами и источниками данных.
• Автоматическое обнаружение голосовой активности (VAD). Модель может точно распознавать, когда пользователь начинает и прекращает говорить. Это обеспечивает естественное диалоговое взаимодействие и дает пользователям возможность прервать работу модели в любой момент.

Вы можете попробовать Multimodal Live API в Google AI Studio .

Начать

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

В этом разделе показан пример использования Multimodal Live API для преобразования текста в текст с использованием Python 3.9+.

Установите библиотеку Gemini API.

Чтобы установить пакет google-genai , используйте следующую команду pip :

!pip3 install google-genai

Импортировать зависимости

Чтобы импортировать зависимости:

from google import genai

Отправка и получение текстового сообщения

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Руководство по интеграции

В этом разделе описывается, как работает интеграция с Multimodal Live API.

Сессии

Сеанс представляет собой одно соединение WebSocket между клиентом и сервером Gemini.

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

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

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

См. следующий пример конфигурации:

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

Дополнительные сведения см. в разделе BidiGenerateContentSetup .

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

Сообщения представляют собой строки в формате JSON, которыми обмениваются через соединение WebSocket.

Чтобы отправить сообщение, клиент должен отправить поддерживаемое клиентское сообщение в строке в формате JSON с помощью одного из открытых соединений WebSocket.

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

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

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

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

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

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

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

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

Дополнительные обновления контента

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

См. следующий пример контекстного сообщения:

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

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

Потоковое аудио и видео

Вызов функции

Все функции должны быть объявлены в начале сеанса путем отправки определений инструментов как часть сообщения BidiGenerateContentSetup .

Дополнительную информацию о вызове функций см. в руководстве по вызову функций .

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

Клиент должен ответить BidiGenerateContentToolResponse .

Аудиовходы и аудиовыходы отрицательно влияют на способность модели использовать вызов функций.

Аудио форматы

Мультимодальный Live API поддерживает следующие аудиоформаты:

• Формат входного аудио: необработанный 16-битный звук PCM с частотой 16 кГц с прямым порядком байтов.
• Выходной аудиоформат: необработанный 16-битный звук PCM с частотой 24 кГц с прямым порядком байтов.

Системные инструкции

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

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

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

Перебои

Пользователи могут прервать вывод модели в любой момент. Когда обнаружение голосовой активности (VAD) обнаруживает прерывание, текущая генерация отменяется и отменяется. В истории сеанса сохраняется только информация, уже отправленная клиенту. Затем сервер отправляет сообщение BidiGenerateContentServerContent чтобы сообщить о прерывании.

Кроме того, сервер Gemini отбрасывает все ожидающие вызовы функций и отправляет сообщение BidiGenerateContentServerContent с идентификаторами отмененных вызовов.

Голоса

Мультимодальный Live API поддерживает следующие голоса: Aoede, Charon, Fenrir, Kore и Puck.

Чтобы указать голос, задайте voice_name в объекте speech_config как часть конфигурации сеанса .

См. следующее JSON-представление объекта speech_config :

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

Ограничения

При планировании проекта учитывайте следующие ограничения Multimodal Live API и Gemini 2.0.

Аутентификация клиента

Мультимодальный Live API обеспечивает только аутентификацию между серверами и не рекомендуется для прямого использования клиентом. Ввод клиента должен направляться через промежуточный сервер приложений для безопасной аутентификации с помощью Multimodal Live API.

Для веб-приложений и мобильных приложений мы рекомендуем использовать интеграцию от наших партнеров Daily .

История разговоров

Хотя модель отслеживает взаимодействия во время сеанса, история разговоров не сохраняется. Когда сеанс завершается, соответствующий контекст удаляется.

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

Максимальная продолжительность сеанса

Продолжительность сеанса ограничена до 15 минут для аудио или до 2 минут для аудио и видео. Когда продолжительность сеанса превышает лимит, соединение разрывается.

Модель также ограничена размером контекста. Отправка больших фрагментов контента вместе с видео- и аудиопотоками может привести к более раннему завершению сеанса.

Обнаружение голосовой активности (VAD)

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

Количество токенов

Подсчет токенов не поддерживается.

Ограничения ставок

Применяются следующие ограничения по ставкам:

• 3 одновременных сеанса на каждый ключ API
• 4 миллиона токенов в минуту

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

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

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