Package google.assistant.embedded.v1alpha1

Indice

EmbeddedAssistant

Servizio che implementa l'API Google Assistant.

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

Avvia o continua una conversazione con il servizio di assistente incorporato. Ogni chiamata esegue un round trip, inviando una richiesta audio al servizio e ricevendo la risposta audio. Utilizza lo streaming bidirezionale per ricevere risultati, ad esempio l'evento END_OF_UTTERANCE, durante l'invio dell'audio.

Una conversazione consiste in una o più connessioni gRPC, ciascuna composta da diverse richieste e risposte in modalità flusso. Ad esempio, l'utente dice Aggiungi alla mia lista della spesa e l'assistente risponde Cosa vuoi aggiungere?. La sequenza di richieste e risposte in modalità flusso nel primo messaggio gRPC potrebbe essere:

  • 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

L'utente dice poi bagel e l'assistente risponde Ok, ho aggiunto i bagel alla tua lista della spesa. Viene inviata come un'altra chiamata di connessione gRPC al metodo Converse, sempre con richieste e risposte in streaming, ad esempio:

  • 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

Sebbene l'ordine esatto delle risposte non sia garantito, i messaggi ConverseResponse.audio_out sequenziali conterranno sempre parti sequenziali di audio.

Autorizzazione

Richiede il seguente ambito OAuth:

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

Per ulteriori informazioni, consulta la Guida all'autenticazione.

AudioInConfig

Specifica come elaborare i dati di audio_in che verranno forniti nelle richieste successive. Per le impostazioni consigliate, consulta le best practice relative all'API gRPC dell'Assistente Google.

Campi
encoding

Encoding

Obbligatorio Codifica dei dati audio inviati in tutti i messaggi audio_in.

sample_rate_hertz

int32

Obbligatorio Frequenza di campionamento (in Hertz) dei dati audio inviati in tutti i messaggi audio_in. I valori validi sono compresi tra 16.000 e 24.000, ma 16.000 è ottimale. Per ottenere risultati ottimali, imposta la frequenza di campionamento della sorgente audio su 16.000 Hz. Se non è possibile, utilizza la frequenza di campionamento nativa della sorgente audio (anziché il ricampionamento).

Codifica

Codifica audio dei dati inviati nel messaggio audio. L'audio deve essere monocanale (mono). L'unica lingua supportata è "en-US".

Enum
ENCODING_UNSPECIFIED Non specificato. Verrà restituito il risultato google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Campioni L-endian firmati a 16 bit non compressi (PCM lineare). Questa codifica non include intestazioni, ma solo byte audio non elaborati.
FLAC FLAC (Free Lossless Audio Codec) è la codifica consigliata perché è senza perdita di dati, pertanto il riconoscimento non è compromesso, e richiede solo circa la metà della larghezza di banda di LINEAR16. Questa codifica include l'intestazione stream FLAC seguita dai dati audio. Supporta campioni a 16 e 24 bit, ma non tutti i campi in STREAMINFO sono supportati.

AudioOut

L'audio contenente la risposta dell'assistente alla query. I blocchi sequenziali di dati audio vengono ricevuti in messaggi ConverseResponse sequenziali.

Campi
audio_data

bytes

Solo output I dati audio contenenti la risposta dell'assistente alla query. I blocchi sequenziali di dati audio vengono ricevuti in messaggi ConverseResponse sequenziali.

AudioOutConfig

Specifica il formato che il server deve utilizzare per la restituzione dei messaggi audio_out.

Campi
encoding

Encoding

Obbligatorio La codifica dei dati audio da restituire in tutti i messaggi audio_out.

sample_rate_hertz

int32

Obbligatorio La frequenza di campionamento in Hertz dei dati audio restituiti nei messaggi audio_out. I valori validi sono: 16000-24000.

volume_percentage

int32

Obbligatorio Impostazione del volume attuale dell'uscita audio del dispositivo. I valori validi sono compresi tra 1 e 100 (corrispondenti all'1%-100%).

Codifica

Codifica audio dei dati restituiti nel messaggio audio. Tutte le codifiche sono byte audio non elaborati senza intestazione, ad eccezione di quanto indicato di seguito.

Enum
ENCODING_UNSPECIFIED Non specificato. Verrà restituito il risultato google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Campioni L-endian firmati a 16 bit non compressi (PCM lineare).
MP3 Codifica audio MP3. La frequenza di campionamento è codificata nel payload.
OPUS_IN_OGG Audio con codifica Opus racchiuso in un container ogg. Il risultato sarà un file che può essere riprodotto in modo nativo su Android e in alcuni browser (come Chrome). La qualità della codifica è notevolmente superiore a quella del formato MP3, pur utilizzando la stessa velocità in bit. La frequenza di campionamento è codificata nel payload.

ConverseConfig

Specifica come elaborare i messaggi ConverseRequest.

Campi
audio_in_config

AudioInConfig

Obbligatorio Specifica come elaborare il successivo audio in arrivo.

audio_out_config

AudioOutConfig

Obbligatorio Specifica la formattazione dell'audio che verrà restituito.

converse_state

ConverseState

Obbligatorio Rappresenta lo stato corrente della finestra di dialogo.

ConverseRequest

Il messaggio di primo livello inviato dal client. I client devono inviare almeno due messaggi ConverseRequest, di solito numerosi. Il primo messaggio deve contenere un messaggio config e non deve contenere dati audio_in. Tutti i messaggi successivi devono contenere i dati audio_in e non un messaggio config.

Campi
Campo di unione converse_request. È necessario specificare esattamente uno di questi campi in ogni ConverseRequest. converse_request può essere solo uno dei seguenti:
config

ConverseConfig

Il messaggio config fornisce informazioni al riconoscimento che specificano come elaborare la richiesta. Il primo messaggio ConverseRequest deve contenere un messaggio config.

audio_in

bytes

I dati audio da riconoscere. Pezzi sequenziali di dati audio vengono inviati in messaggi ConverseRequest sequenziali. Il primo messaggio ConverseRequest non deve contenere dati audio_in e tutti i messaggi ConverseRequest successivi devono contenere dati audio_in. I byte audio devono essere codificati come specificato in AudioInConfig. L'audio deve essere inviato approssimativamente in tempo reale (16.000 campioni al secondo). Se l'audio viene inviato molto più velocemente o più lentamente, verrà restituito un errore.

ConverseResponse

Il messaggio di primo livello ricevuto dal client. Una serie di uno o più messaggi ConverseResponse viene riprodotta in streaming al client.

Campi
Campo di unione converse_response. Esattamente uno di questi campi verrà completato in ogni ConverseResponse. converse_response può essere solo uno dei seguenti:
error

Status

Output-only Se impostato, restituisce un messaggio google.rpc.Status che specifica l'errore dell'operazione. Se si verifica un errore durante l'elaborazione, questo messaggio viene impostato e non vengono inviati ulteriori messaggi.

event_type

EventType

Solo output Indica il tipo di evento.

audio_out

AudioOut

Solo output: l'audio contenente la risposta dell'assistente alla query.

result

ConverseResult

Solo output Il risultato semantico della query pronunciata dall'utente.

EventType

Indica il tipo di evento.

Enum
EVENT_TYPE_UNSPECIFIED Nessun evento specificato.
END_OF_UTTERANCE Questo evento indica che il server ha rilevato la fine dell'espressione vocale dell'utente e non prevede comandi vocali aggiuntivi. Di conseguenza, il server non elaborerà audio aggiuntivo (anche se in seguito potrebbe restituire risultati aggiuntivi). Il client dovrebbe interrompere l'invio di dati audio aggiuntivi, chiudere a metà la connessione gRPC e attendere eventuali risultati aggiuntivi finché il server non chiude la connessione gRPC.

ConverseResult

Il risultato semantico della query pronunciata dall'utente.

Campi
spoken_request_text

string

Solo output La trascrizione riconosciuta di ciò che ha detto l'utente.

spoken_response_text

string

Solo output Il testo della risposta vocale dell'assistente. Questo viene restituito solo per un'azione IFTTT.

conversation_state

bytes

Solo output Informazioni sullo stato per i ConverseRequest successivi. Questo valore deve essere salvato nel client e restituito nel conversation_state con i successivi ConverseRequest. Il cliente non deve interpretare né utilizzare in altro modo questo valore. Non è necessario salvare queste informazioni tra i riavvii del dispositivo.

microphone_mode

MicrophoneMode

Output-only Specifica la modalità del microfono dopo l'elaborazione di questa Converse RPC.

volume_percentage

int32

Solo output Livello del volume aggiornato. Il valore sarà 0 o omesso (che non indica alcuna modifica) a meno che non venga riconosciuto un comando vocale come "Alza il volume" o "Imposta il livello del volume 4", nel qual caso il valore sarà compreso tra 1 e 100 (corrispondente al nuovo livello del volume dall'1% al 100%). In genere, un client dovrebbe utilizzare questo livello di volume durante la riproduzione dei dati audio_out, mantenere questo valore come livello di volume attuale e fornirlo nella AudioOutConfig del ConverseRequest successivo. Alcuni client potrebbero anche implementare altri metodi per modificare il livello del volume corrente, ad esempio fornendo una manopola che l'utente può ruotare.

MicrophoneMode

Possibili stati del microfono dopo il completamento di una RPC Converse.

Enum
MICROPHONE_MODE_UNSPECIFIED Nessuna modalità specificata.
CLOSE_MICROPHONE Il servizio non si aspetta una domanda successiva da parte dell'utente. Il microfono dovrebbe rimanere disattivato finché l'utente non lo riattiva.
DIALOG_FOLLOW_ON Il servizio attende una domanda successiva da parte dell'utente. Il microfono dovrebbe essere riaperto al termine della riproduzione AudioOut (avviando una nuova chiamata RPC Converse per inviare il nuovo audio).

ConverseState

Fornisce informazioni sullo stato attuale della finestra di dialogo.

Campi
conversation_state

bytes

Obbligatorio Il valore conversation_state restituito nell'intervallo ConverseResponse precedente. Ometti (non impostare il campo) se non esistevano ConverseResponse precedenti. Se esiste un valore ConverseResponse precedente, non omettere questo campo; in questo modo, la conversazione verrà terminata e la nuova richiesta avvierà una nuova conversazione.