Package google.assistant.embedded.v1alpha1

Index

EmbeddedAssistant

Service mettant en œuvre l'API Assistant Google.

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

Lance ou poursuit une conversation avec le service d'assistant intégré. Chaque appel effectue un aller-retour, en envoyant une requête audio au service et en recevant la réponse audio. Utilise le streaming bidirectionnel pour recevoir des résultats, tels que l'événement END_OF_UTTERANCE, tout en envoyant du contenu audio.

Une conversation correspond à une ou plusieurs connexions gRPC, chacune composée de plusieurs requêtes et réponses diffusées. Par exemple, il dit Ajouter à ma liste de courses et l'Assistant répond Que voulez-vous ajouter ? La séquence de requêtes et de réponses diffusées dans le premier message gRPC peut se présenter comme suit:

  • 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'utilisateur dit ensuite bagels, et l'assistant répond OK, j'ai ajouté des bagels à votre liste de courses. Il est envoyé via un autre appel de connexion gRPC à la méthode Converse, là encore avec des requêtes et des réponses diffusées en streaming, par exemple:

  • 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

Bien que l'ordre précis des réponses ne soit pas garanti, les messages ConverseResponse.audio_out séquentiels contiendront toujours des parties audio séquentielles.

Autorisation

Requiert le niveau d'accès OAuth suivant :

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

Pour en savoir plus, consultez le guide d'authentification.

AudioInConfig

Spécifie comment traiter les données audio_in qui seront fournies dans les requêtes ultérieures. Pour connaître les paramètres recommandés, consultez les bonnes pratiques concernant l'API gRPC de l'Assistant Google.

Champs
encoding

Encoding

Obligatoire : encodage des données audio envoyées dans tous les messages audio_in.

sample_rate_hertz

int32

Obligatoire : Taux d'échantillonnage (en Hertz) des données audio envoyées dans tous les messages audio_in. Les valeurs valides sont comprises entre 16 000 et 24 000, mais 16 000 est optimal. Pour de meilleurs résultats, définissez le taux d'échantillonnage de la source audio sur 16 000 Hz. Si ce n'est pas possible, utilisez le taux d'échantillonnage natif de la source audio (plutôt que d'effectuer un ré-échantillonnage).

Encodage

Encodage audio des données envoyées dans le message audio. L'audio doit être à un seul canal (mono). La seule langue acceptée est "en-US".

Enums
ENCODING_UNSPECIFIED Non spécifié. Renvoie le résultat google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Échantillons little-endian de 16 bits signés et non compressés (LPCM). Cet encodage n'inclut pas d'en-tête, mais uniquement les octets audio bruts.
FLAC L'encodage FLAC (Free Lossless Audio Codec, codec audio sans perte sans frais) est recommandé, car il est sans perte. De ce fait, la reconnaissance n'est pas compromise et ne nécessite qu'environ la moitié de la bande passante par rapport à LINEAR16. Cet encodage inclut l'en-tête de flux FLAC suivi des données audio. Il accepte les échantillons 16 bits et 24 bits. Toutefois, tous les champs de STREAMINFO ne sont pas acceptés.

AudioOut

Audio contenant la réponse de l'assistant à la requête. Des fragments séquentiels de données audio sont reçus dans des messages ConverseResponse séquentiels.

Champs
audio_data

bytes

Sortie uniquement : données audio contenant la réponse de l'assistant à la requête. Des fragments séquentiels de données audio sont reçus dans des messages ConverseResponse séquentiels.

AudioOutConfig

Spécifie le format que le serveur doit utiliser lorsqu'il renvoie des messages audio_out.

Champs
encoding

Encoding

Obligatoire. Encodage des données audio à renvoyer dans tous les messages audio_out.

sample_rate_hertz

int32

Obligatoire. Taux d'échantillonnage en Hertz des données audio renvoyées dans les messages audio_out. Les valeurs possibles sont comprises entre 16 000 et 24 000.

volume_percentage

int32

Obligatoire. Paramètre de volume actuel de la sortie audio de l'appareil. Les valeurs valides sont comprises entre 1 et 100 (correspondant à 1% et 100%).

Encodage

Encodage audio des données renvoyées dans le message audio. Tous les encodages sont des octets audio bruts sans en-tête, sauf indication contraire ci-dessous.

Enums
ENCODING_UNSPECIFIED Non spécifié. Renvoie le résultat google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Échantillons little-endian de 16 bits signés et non compressés (LPCM).
MP3 Encodage audio MP3. Le taux d'échantillonnage est encodé dans la charge utile.
OPUS_IN_OGG Audio encodé au format Opus et encapsulé dans un conteneur Ogg. Vous obtiendrez un fichier qui pourra être lu de manière native sur Android et dans certains navigateurs (comme Chrome). La qualité de l'encodage est considérablement supérieure à celle du format MP3 tout en utilisant le même débit. Le taux d'échantillonnage est encodé dans la charge utile.

ConverseConfig

Indique comment traiter les messages ConverseRequest.

Champs
audio_in_config

AudioInConfig

Obligatoire Spécifie comment traiter le contenu audio entrant qui suit.

audio_out_config

AudioOutConfig

Obligatoire : spécifie le format du contenu audio renvoyé.

converse_state

ConverseState

Obligatoire. Représente l'état actuel de la boîte de dialogue.

ConverseRequest

Message de premier niveau envoyé par le client. Les clients doivent envoyer au moins deux messages ConverseRequest, et généralement de nombreux. Le premier message doit contenir un message config et ne doit pas contenir de données audio_in. Tous les messages suivants doivent contenir des données audio_in et pas de message config.

Champs
Champ d'union converse_request. Un seul de ces champs doit être spécifié dans chaque ConverseRequest. La converse_request ne peut être qu'un des éléments suivants :
config

ConverseConfig

Le message config fournit à l'outil de reconnaissance des informations qui spécifient comment traiter la requête. Le premier message ConverseRequest doit contenir un message config.

audio_in

bytes

Données audio à reconnaître. Des blocs séquentiels de données audio sont envoyés dans des messages ConverseRequest séquentiels. Le premier message ConverseRequest ne doit pas contenir de données audio_in et tous les messages ConverseRequest suivants doivent contenir des données audio_in. Les octets de données audio doivent être encodés comme spécifié dans AudioInConfig. Le son doit être envoyé en temps quasi réel (16 000 échantillons par seconde). Une erreur est renvoyée si le contenu audio est envoyé beaucoup plus rapidement ou plus lentement.

ConverseResponse

Message de premier niveau reçu par le client. Une série d'un ou de plusieurs messages ConverseResponse est diffusée en streaming vers le client.

Champs
Champ d'union converse_response. Un seul de ces champs sera renseigné dans chaque ConverseResponse. La converse_response ne peut être qu'un des éléments suivants :
error

Status

Uniquement en sortie Si cette valeur est définie, elle renvoie un message google.rpc.Status spécifiant l'erreur pour l'opération. Si une erreur survient pendant le traitement, ce message sera défini et plus aucun message ne sera envoyé.

event_type

EventType

Uniquement en sortie : indique le type d'événement.

audio_out

AudioOut

Sortie uniquement : contenu audio contenant la réponse de l'assistant à la requête.

result

ConverseResult

Sortie uniquement : résultat sémantique de la requête vocale de l'utilisateur.

EventType

Indique le type d'événement.

Enums
EVENT_TYPE_UNSPECIFIED Aucun événement spécifié.
END_OF_UTTERANCE Cet événement indique que le serveur a détecté la fin de l'énoncé de l'utilisateur et ne s'attend plus à aucune entrée vocale. Le serveur ne traite donc pas de nouvelles données audio (bien qu'il puisse par la suite renvoyer des résultats supplémentaires). Le client doit arrêter d'envoyer des données audio, interrompre à moitié la connexion gRPC, et attendre les résultats supplémentaires jusqu'à ce que le serveur stoppe cette connexion.

ConverseResult

Résultat sémantique de la requête vocale de l'utilisateur.

Champs
spoken_request_text

string

Sortie uniquement : transcription reconnue de ce que l'utilisateur a dit.

spoken_response_text

string

Sortie uniquement : texte de la réponse vocale de l'Assistant. Cette valeur n'est renvoyée que pour une action IFTTT.

conversation_state

bytes

Informations d'état en sortie uniquement pour les ConverseRequest suivantes. Cette valeur doit être enregistrée dans le client et renvoyée dans conversation_state avec la valeur ConverseRequest suivante. (Le client n'a pas besoin d'interpréter ni d'utiliser cette valeur.) Il n'est pas nécessaire d'enregistrer ces informations à chaque redémarrage de l'appareil.

microphone_mode

MicrophoneMode

Sortie uniquement Spécifie le mode du micro après le traitement de ce RPC Converse.

volume_percentage

int32

Sortie uniquement Mise à jour du niveau de volume. La valeur est égale à 0 ou omise (indiquant qu'elle ne change pas), sauf si une commande vocale telle que "Augmenter le volume" ou "Régler le niveau de volume 4" a été reconnue, auquel cas la valeur est comprise entre 1 et 100 (correspondant au nouveau niveau de volume compris entre 1% et 100%). En règle générale, le client doit utiliser ce niveau de volume lors de la lecture des données audio_out, conserver cette valeur comme niveau de volume actuel et la fournir dans la AudioOutConfig du ConverseRequest suivant. (Certains clients peuvent également mettre en œuvre d'autres moyens pour permettre la modification du niveau de volume actuel, par exemple en fournissant un bouton que l'utilisateur peut tourner.)

MicrophoneMode

États possibles du micro une fois un RPC Converse terminé.

Enums
MICROPHONE_MODE_UNSPECIFIED Aucun mode spécifié.
CLOSE_MICROPHONE Le service n'attend pas de question complémentaire de la part de l'utilisateur. Le micro doit rester désactivé jusqu'à ce que l'utilisateur le réactive.
DIALOG_FOLLOW_ON Le service attend une question complémentaire de la part de l'utilisateur. Le micro doit être rouvert à la fin de la lecture du AudioOut (en démarrant un nouvel appel RPC Converse pour envoyer le nouveau contenu audio).

ConverseState

Fournit des informations sur l'état actuel de la boîte de dialogue.

Champs
conversation_state

bytes

Obligatoire : valeur conversation_state renvoyée dans le ConverseResponse précédent. Omettez le champ (ne définissez pas le champ) s'il n'existe aucun ConverseResponse antérieur. S'il y avait un ConverseResponse antérieur, n'omettez pas ce champ, car cela mettra fin à cette conversation (et cette nouvelle requête lancera une nouvelle conversation).