Package google.assistant.embedded.v1alpha1

Индекс

Встроенный помощник

Сервис, реализующий API Google Assistant.

Конверсы

rpc Converse( ConverseRequest ) returns ( ConverseResponse )

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

Разговор — это одно или несколько соединений gRPC, каждое из которых состоит из нескольких потоковых запросов и ответов. Например, пользователь говорит «Добавить в мой список покупок» , а помощник отвечает : «Что вы хотите добавить?» . Последовательность потоковых запросов и ответов в первом сообщении gRPC может быть следующей:

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

Затем пользователь говорит «бублики» , и помощник отвечает : «ОК, я добавил бублики в ваш список покупок» . Это отправляется как еще один вызов соединения gRPC к методу Converse , опять же с потоковыми запросами и ответами, например:

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

Хотя точный порядок ответов не гарантируется, последовательные сообщения ConverseResponse.audio_out всегда будут содержать последовательные части аудио.

Авторизация

Требуется следующая область действия OAuth:

  • https://www.googleapis.com/auth/assistant-sdk-prototype

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

Аудиоинконфиг

Указывает, как обрабатывать данные audio_in , которые будут предоставлены в последующих запросах. Рекомендуемые настройки см. в рекомендациях по API gRPC Google Assistant.

Поля
encoding

Encoding

Обязательное Кодирование аудиоданных, отправляемых во всех сообщениях audio_in .

sample_rate_hertz

int32

Требуемая частота дискретизации (в герцах) аудиоданных, отправляемых во всех сообщениях audio_in . Допустимые значения: 16000–24000, но оптимальное значение — 16000. Для достижения наилучших результатов установите частоту дискретизации источника звука на 16 000 Гц. Если это невозможно, используйте собственную частоту дискретизации источника звука (вместо повторной выборки).

Кодирование

Аудиокодирование данных, передаваемых в аудиосообщении. Звук должен быть одноканальным (моно). Единственный поддерживаемый язык — «en-US».

Перечисления
ENCODING_UNSPECIFIED Не указан. Вернет результат google.rpc.Code.INVALID_ARGUMENT .
LINEAR16 Несжатые 16-битные образцы с прямым порядком байтов (Linear PCM). Эта кодировка не включает заголовок, а только необработанные аудиобайты.
FLAC FLAC (бесплатный аудиокодек без потерь) — рекомендуемая кодировка, поскольку она не имеет потерь (поэтому распознавание не подвергается риску) и требует лишь примерно половины пропускной способности LINEAR16 . Эта кодировка включает заголовок потока FLAC , за которым следуют аудиоданные. Он поддерживает 16-битные и 24-битные выборки, однако не все поля в STREAMINFO поддерживаются.

Аудио выход

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

Поля
audio_data

bytes

Только для вывода Аудиоданные, содержащие ответ помощника на запрос. Последовательные фрагменты аудиоданных принимаются в последовательных сообщениях ConverseResponse .

АудиоВыходКонфиг

Указывает желаемый формат, который сервер будет использовать при возврате сообщений audio_out .

Поля
encoding

Encoding

Обязательное Кодирование аудиоданных, возвращаемых во всех сообщениях audio_out .

sample_rate_hertz

int32

Обязательно. Частота дискретизации аудиоданных, возвращаемых в сообщениях audio_out в герцах. Допустимые значения: 16000–24000.

volume_percentage

int32

Обязательно Текущая настройка громкости аудиовыхода устройства. Допустимые значения: от 1 до 100 (что соответствует от 1% до 100%).

Кодирование

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

Перечисления
ENCODING_UNSPECIFIED Не указан. Вернет результат google.rpc.Code.INVALID_ARGUMENT .
LINEAR16 Несжатые 16-битные образцы с прямым порядком байтов (Linear PCM).
MP3 Кодирование звука в формате MP3. Частота дискретизации закодирована в полезных данных.
OPUS_IN_OGG Звук в кодировке Opus, завернутый в контейнер ogg. Результатом будет файл, который можно будет воспроизводить на Android и в некоторых браузерах (например, Chrome). Качество кодирования значительно выше, чем у MP3 при использовании того же битрейта. Частота дискретизации закодирована в полезных данных.

ConverseConfig

Указывает, как обрабатывать сообщения ConverseRequest .

Поля
audio_in_config

AudioInConfig

Обязательно Указывает, как обрабатывать последующий входящий звук.

audio_out_config

AudioOutConfig

Обязательно Указывает, как форматировать возвращаемый аудиофайл.

converse_state

ConverseState

Обязательное Представляет текущее состояние диалога.

Конверсзапрос

Сообщение верхнего уровня, отправленное клиентом. Клиенты должны отправить как минимум два, а обычно множество сообщений ConverseRequest . Первое сообщение должно содержать сообщение config и не должно содержать данные audio_in . Все последующие сообщения должны содержать данные audio_in и не должны содержать сообщение config .

Поля
Поле объединения converse_request . В каждом ConverseRequest должно быть указано ровно одно из этих полей. converse_request может быть только одним из следующих:
config

ConverseConfig

Сообщение config предоставляет распознавателю информацию, указывающую, как обрабатывать запрос. Первое сообщение ConverseRequest должно содержать сообщение config .

audio_in

bytes

Аудиоданные, которые необходимо распознать. Последовательные фрагменты аудиоданных отправляются в последовательных сообщениях ConverseRequest . Первое сообщение ConverseRequest не должно содержать данные audio_in , а все последующие сообщения ConverseRequest должны содержать данные audio_in . Аудиобайты должны быть закодированы, как указано в AudioInConfig . Аудио должно отправляться примерно в реальном времени (16 000 выборок в секунду). Ошибка будет возвращена, если звук будет передаваться значительно быстрее или медленнее.

КонверсОтклик

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

Поля
Поле объединения converse_response . В каждом ConverseResponse будет заполнено ровно одно из этих полей. converse_response может быть только одним из следующих:
error

Status

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

event_type

EventType

Только вывод Указывает тип события.

audio_out

AudioOut

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

result

ConverseResult

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

Тип события

Указывает тип события.

Перечисления
EVENT_TYPE_UNSPECIFIED Событие не указано.
END_OF_UTTERANCE Это событие указывает на то, что сервер обнаружил окончание речевого высказывания пользователя и не ожидает дополнительной речи. Поэтому сервер не будет обрабатывать дополнительный звук (хотя впоследствии может вернуть дополнительные результаты). Клиенту следует прекратить отправку дополнительных аудиоданных, наполовину закрыть соединение gRPC и дождаться дополнительных результатов, пока сервер не закроет соединение gRPC.

КонверсРезультат

Семантический результат речевого запроса пользователя.

Поля
spoken_request_text

string

Только вывод Распознанная расшифровка того, что сказал пользователь.

spoken_response_text

string

Только вывод Текст устного ответа помощника. Это возвращается только для действия IFTTT.

conversation_state

bytes

Информация о состоянии только для вывода для последующего ConverseRequest . Это значение должно быть сохранено в клиенте и возвращено в conversation_state со следующим ConverseRequest . (Клиенту не нужно интерпретировать или иным образом использовать это значение.) Нет необходимости сохранять эту информацию при перезагрузке устройства.

microphone_mode

MicrophoneMode

Только выход Указывает режим микрофона после обработки этого Converse RPC.

volume_percentage

int32

Только вывод Обновленный уровень громкости. Значение будет равно 0 или опущено (что указывает на отсутствие изменений), если не была распознана голосовая команда, такая как «Увеличить громкость» или «Установить уровень громкости 4». В этом случае значение будет находиться в диапазоне от 1 до 100 (соответствует новому уровню громкости). уровень от 1% до 100%). Как правило, клиент должен использовать этот уровень громкости при воспроизведении данных audio_out , сохранять это значение в качестве текущего уровня громкости и указывать его в AudioOutConfig следующего ConverseRequest . (Некоторые клиенты могут также реализовать другие способы изменения текущего уровня громкости, например, путем предоставления ручки, которую пользователь может повернуть.)

Режим микрофона

Возможные состояния микрофона после завершения Converse RPC.

Перечисления
MICROPHONE_MODE_UNSPECIFIED Режим не указан.
CLOSE_MICROPHONE Сервис не ожидает дополнительного вопроса от пользователя. Микрофон должен оставаться выключенным до тех пор, пока пользователь не активирует его повторно.
DIALOG_FOLLOW_ON Служба ожидает ответного вопроса от пользователя. Микрофон следует снова открыть после завершения воспроизведения AudioOut (путем запуска нового вызова Converse RPC для отправки нового звука).

Конверсстате

Предоставляет информацию о текущем состоянии диалога.

Поля
conversation_state

bytes

Обязательный. Значение conversation_state , возвращенное в предыдущем ConverseResponse . Пропустите (не задавайте поле), если ранее не было ConverseResponse . Если ранее был ConverseResponse , не пропускайте это поле; это завершит этот разговор (и этот новый запрос начнет новый разговор).