Package google.assistant.embedded.v1alpha1

Indeks

EmbeddedAssistant

Usługa, która korzysta z interfejsu Google Assistant API.

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

Rozpoczyna lub kontynuuje rozmowę za pomocą wbudowanej usługi asystenta. Każde połączenie jest wysyłane w obie strony, wysyłane do usługi żądanie dźwiękowe i odbierane w odpowiedzi audio. Używa dwukierunkowego przesyłania strumieniowego do odbierania wyników, np. zdarzenia END_OF_UTTERANCE, podczas wysyłania dźwięku.

Rozmowa to co najmniej jedno połączenie gRPC, z których każde składa się z kilku przesyłanych strumieniowo żądań i odpowiedzi. Na przykład użytkownik powie Dodaj do mojej listy zakupów, a Asystent odpowie Co chcesz dodać?. Sekwencja przesyłanych strumieniowo żądań i odpowiedzi w pierwszym komunikacie gRPC mogłaby wyglądać tak:

  • 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

Użytkownik mówi bajgle, a asystent odpowiada OK, dodałem bajgle do listy zakupów. Jest ono wysyłane jako kolejne wywołanie połączenia gRPC do metody Converse, ponownie ze strumieniowymi żądaniami i odpowiedziami, takimi jak:

  • 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

Chociaż dokładna kolejność odpowiedzi nie jest gwarantowana, kolejne komunikaty ConverseResponse.audio_out zawsze zawierają sekwencyjne fragmenty dźwięku.

Upoważnienie

Wymaga następującego zakresu OAuth:

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

Więcej informacji znajdziesz w przewodniku uwierzytelniania.

AudioInConfig

Określa, jak przetwarzać dane audio_in przekazywane w kolejnych żądaniach. Zalecane ustawienia znajdziesz w artykule o sprawdzonych metodach dotyczących interfejsu gRPC API Asystenta Google.

Pola
encoding

Encoding

Wymagane kodowanie danych dźwiękowych wysyłanych we wszystkich wiadomościach typu audio_in.

sample_rate_hertz

int32

Wymagane – częstotliwość próbkowania (w hercach) danych dźwiękowych wysłanych we wszystkich wiadomościach typu audio_in. Prawidłowe wartości mieszczą się w przedziale od 16 000 do 24 000, ale optymalna to 16 000. Aby uzyskać najlepsze wyniki, ustaw częstotliwość próbkowania dla źródła dźwięku na 16 000 Hz. Jeśli jest to niemożliwe, użyj natywnej częstotliwości próbkowania ze źródła audio (zamiast ponownego próbkowania).

Kodowanie

Kodowanie dźwięku danych wysłanych w wiadomości głosowej. Dźwięk musi być jednokanałowy (mono). Jedyny obsługiwany język to „en-US”.

Wartości w polu enum
ENCODING_UNSPECIFIED Nie określono. Zwrócony wynik to google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Nieskompresowane, podpisane 16-bitowe próbki little-endian (Linear PCM). Kodowanie nie obejmuje nagłówka, a jedynie nieprzetworzone bajty audio.
FLAC Zalecane jest kodowanie FLAC (Free Lossless Audio Codec), ponieważ jest ono bezstratne, dzięki czemu rozpoznawanie nie jest zagrożone i wymaga tylko około połowy przepustowości LINEAR16. To kodowanie obejmuje nagłówek strumienia FLAC, po którym następuje dane audio. Obsługuje on 16- i 24-bitowe próbki, ale nie wszystkie pola w STREAMINFO są obsługiwane.

AudioOut

Nagranie z odpowiedzią asystenta na pytanie. Kolejne fragmenty danych dźwiękowych są odbierane w sekwencji komunikatów ConverseResponse.

Pola
audio_data

bytes

Tylko dane wyjściowe – dane dźwiękowe zawierające odpowiedź asystenta na zapytanie. Kolejne fragmenty danych dźwiękowych są odbierane w sekwencji komunikatów ConverseResponse.

AudioOutConfig

Określa format, który ma być używany przez serwer przy zwracaniu wiadomości audio_out.

Pola
encoding

Encoding

Wymagane kodowanie danych dźwiękowych, które mają być zwracane we wszystkich wiadomościach typu audio_out.

sample_rate_hertz

int32

Wymagane: częstotliwość próbkowania danych audio zwracanych w wiadomościach (audio_out) w hercach danych dźwiękowych. Prawidłowe wartości to: 16 000–24 000.

volume_percentage

int32

Wymagane: bieżące ustawienie głośności wyjścia audio urządzenia. Prawidłowe wartości to od 1 do 100 (odpowiadające 1%–100%).

Kodowanie

Kodowanie dźwięku danych zwróconych w wiadomości głosowej. Wszystkie kodowanie są nieprzetworzonymi bajtami audio bez nagłówka, z wyjątkiem sytuacji opisanych poniżej.

Wartości w polu enum
ENCODING_UNSPECIFIED Nie określono. Zwrócony wynik to google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Nieskompresowane, podpisane 16-bitowe próbki little-endian (Linear PCM).
MP3 Kodowanie audio MP3. Częstotliwość próbkowania jest kodowana w ładunku.
OPUS_IN_OGG Dźwięk w kodowaniu opus zapakowany w kontenerze Ogg. Powstanie plik, który można natywnie odtwarzać na Androidzie i w niektórych przeglądarkach (np. Chrome). Jakość kodowania jest znacznie wyższa niż jakość MP3 przy tej samej szybkości transmisji bitów. Częstotliwość próbkowania jest kodowana w ładunku.

ConverseConfig

Określa sposób przetwarzania wiadomości ConverseRequest.

Pola
audio_in_config

AudioInConfig

Wymagane – określa sposób przetwarzania następnego dźwięku przychodzącego.

audio_out_config

AudioOutConfig

Wymagane – określa sposób formatowania dźwięku, który ma być zwracany.

converse_state

ConverseState

Wymagane Reprezentuje bieżący stan okna.

ConverseRequest

Wiadomość najwyższego poziomu wysłana przez klienta. Klienci muszą wysłać co najmniej dwie (zwykle dużą liczbę wiadomości) wiadomości ConverseRequest. Pierwsza wiadomość musi zawierać wiadomość config i nie może zawierać danych audio_in. Wszystkie kolejne wiadomości muszą zawierać dane audio_in i nie mogą zawierać wiadomości config.

Pola
Pole sumy converse_request. W każdym polu ConverseRequest musisz podać dokładnie jedno z tych pól. converse_request może mieć tylko jedną z tych wartości:
config

ConverseConfig

Komunikat config przekazuje modułowi rozpoznawania informacje określające sposób przetworzenia żądania. Pierwsza wiadomość ConverseRequest musi zawierać wiadomość config.

audio_in

bytes

Dane dźwiękowe do rozpoznania. Kolejne fragmenty danych dźwiękowych są wysyłane w formie kolejnych komunikatów w trybie ConverseRequest. Pierwsza wiadomość ConverseRequest nie może zawierać danych audio_in, a wszystkie kolejne wiadomości ConverseRequest muszą zawierać dane audio_in. Bajty audio muszą być zakodowane w sposób określony w zasadzie AudioInConfig. Dźwięk musi być wysyłany w czasie zbliżonym do rzeczywistego (16 000 próbek na sekundę). Jeśli dźwięk jest przesyłany znacznie szybciej lub wolniej, zwracany jest błąd.

ConverseResponse

Wiadomość najwyższego poziomu odebrana przez klienta. Seria co najmniej jednej wiadomości w usłudze ConverseResponse jest przesyłana z powrotem do klienta.

Pola
Pole sumy converse_response. W każdym polu ConverseResponse pojawi się tylko 1 z tych pól. converse_response może mieć tylko jedną z tych wartości:
error

Status

Tylko dane wyjściowe Jeśli zasada jest ustawiona, zwraca komunikat google.rpc.Status określający błąd operacji. Jeśli podczas przetwarzania wystąpi błąd, wiadomość zostanie ustawiona i nie będą wysyłane żadne kolejne wiadomości.

event_type

EventType

Tylko dane wyjściowe Wskazuje typ zdarzenia.

audio_out

AudioOut

Tylko dane wyjściowe – dźwięk zawierający odpowiedź asystenta na zapytanie.

result

ConverseResult

Tylko dane wyjściowe – semantyczny wynik zapytania wypowiedzianego przez użytkownika.

EventType

Wskazuje typ zdarzenia.

Wartości w polu enum
EVENT_TYPE_UNSPECIFIED Nie określono zdarzenia.
END_OF_UTTERANCE To zdarzenie oznacza, że serwer wykrył koniec wypowiedzi użytkownika i nie oczekuje żadnej dodatkowej mowy. Dlatego serwer nie przetwarza dodatkowego dźwięku (chociaż może później zwracać dodatkowe wyniki). Klient powinien przestać wysyłać dodatkowe dane audio, zamknąć do połowy połączenie gRPC i poczekać na dodatkowe wyniki, aż serwer zamknie połączenie gRPC.

ConverseResult

Wynik semantyczny zapytania wypowiedzianego przez użytkownika.

Pola
spoken_request_text

string

Tylko dane wyjściowe – rozpoznawana transkrypcja wypowiedzi użytkownika.

spoken_response_text

string

Tylko dane wyjściowe – tekst odpowiedzi Asystenta. Zwracana jest tylko w przypadku działania IFTTT.

conversation_state

bytes

Tylko dane wyjściowe – informacje o stanie dla kolejnych zdarzeń typu ConverseRequest. Ta wartość powinna zostać zapisana w kliencie i zwrócona w elemencie conversation_state z następnym elementem typu ConverseRequest. (Klient nie musi interpretować ani w inny sposób używać tej wartości). Nie trzeba zapisywać tych informacji przy ponownym uruchomieniu urządzenia.

microphone_mode

MicrophoneMode

Tylko dane wyjściowe – określa tryb mikrofonu po przetworzeniu tego wywołania RPC Converse.

volume_percentage

int32

Tylko na wyjściu Zaktualizowano poziom głośności. Wartość może być równa 0 lub pomijana (co oznacza brak zmian), chyba że rozpoznano polecenie głosowe, np. „Zwiększ głośność” lub „Ustaw poziom głośności 4”. W takim przypadku wartość mieści się w zakresie od 1 do 100 (odpowiada nowemu poziomowi głośności od 1% do 100%). Zazwyczaj klient powinien używać tego poziomu głośności podczas odtwarzania danych audio_out. Zachowaj tę wartość na bieżącym poziomie głośności i dostarczaj ją w AudioOutConfig nast. ConverseRequest. (Niektórzy klienci mogą też wdrażać inne sposoby umożliwiające zmianę bieżącego poziomu głośności, na przykład dostarczając pokrętło, które użytkownik może obrócić).

MicrophoneMode

Możliwe stany mikrofonu po zakończeniu RPC Converse.

Wartości w polu enum
MICROPHONE_MODE_UNSPECIFIED Nie określono trybu.
CLOSE_MICROPHONE Usługa nie oczekuje od użytkownika kolejnego pytania. Mikrofon powinien pozostać wyłączony, dopóki użytkownik go ponownie nie aktywuje.
DIALOG_FOLLOW_ON Usługa oczekuje od użytkownika kolejnego pytania. Mikrofon powinien zostać ponownie włączony po zakończeniu odtwarzania elementu AudioOut (przez rozpoczęcie nowego wywołania RPC Converse w celu wysłania nowego dźwięku).

ConverseState

Zawiera informacje o bieżącym stanie okna dialogowego.

Pola
conversation_state

bytes

Wymagane – wartość conversation_state zwrócona w poprzedniej wartości ConverseResponse. Pomiń (nie ustawiaj pola), jeśli nie było poprzedniego elementu ConverseResponse. Jeśli była już dostępna poprzednia ConverseResponse, nie pomijaj tego pola. Spowoduje to zakończenie tej rozmowy (a nowa prośba spowoduje rozpoczęcie nowej rozmowy).