Short sentence recognition API reference - Intelligent Speech Interaction

La reconnaissance de phrases courtes convertit des clips audio d'une durée maximale de 60 secondes en texte pour les conversations chat, les commandes vocales, la saisie vocale et la recherche vocale. Les clients envoient des flux audio via WebSocket et reçoivent des événements et des résultats de reconnaissance.

Remarques d'utilisation

L'encodage audio doit correspondre aux paramètres de la requête. Une incompatibilité peut entraîner l'échec de la reconnaissance ou le renvoi d'un résultat vide.

Canaux et profondeur de bits : mono, 16 bits.
Formats audio : PCM, WAV encodé en PCM, OPUS dans un conteneur OGG, SPEEX dans un conteneur OGG et AMR.
Fréquence d'échantillonnage : 8 000 Hz ou 16 000 Hz. Le modèle du projet doit prendre en charge la fréquence d'échantillonnage audio et la langue.
Durée audio : jusqu'à 60 secondes.
Taille audio : jusqu'à 2 Mo.

Les paramètres de requête contrôlent des fonctionnalités telles que les résultats intermédiaires, la ponctuation et la normalisation inverse du texte (ITN).

Sélectionner un modèle de reconnaissance

Les modèles de langue et de dialecte ne peuvent pas être spécifiés dans les paramètres de la requête. Sur la page Tous les projets de la console Intelligent Speech Interaction, localisez le projet puis cliquez sur Configurer les fonctionnalités du projetConfigure Project Features. Sélectionnez un modèle adapté à la langue audio et à la fréquence d'échantillonnage. Pour obtenir des instructions de configuration, consultez la rubrique Gérer les projets.

Les modèles disponibles sont répertoriés sur la page de configuration des fonctionnalités du projet. Sélectionnez une fréquence d'échantillonnage, puis choisissez un modèle de langue.

Endpoints

Utilisez l'endpoint WebSocket suivant via le réseau public : wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1.

Processus d'interaction

Le processus ci-dessous s'applique aux connexions WebSocket et aux SDK qui utilisent ce protocole. Pour les requêtes RESTful, consultez la rubrique API RESTful.

Chaque événement serveur inclut l'identifiant task_id de la tâche de reconnaissance dans son en-tête header. Utilisez cet ID pour corréler les requêtes et les réponses, ainsi que pour le dépannage.

1. Authentification

Le client utilise un jeton NLS pour s'authentifier lors de l'établissement de la connexion WebSocket.

Pour obtenir les instructions, consultez la rubrique Obtenir un jeton d'accès.

2. Démarrer la reconnaissance

Le client envoie une directive StartRecognition accompagnée des paramètres de reconnaissance. Le serveur valide la requête et renvoie un événement RecognitionStarted. Attendez la réception de cet événement avant d'envoyer les données audio.

3. Envoyer les données

Le client transmet l'audio binaire par blocs tout en recevant les événements du serveur.

Si enable_intermediate_result est défini sur true, le serveur peut renvoyer plusieurs événements RecognitionResultChanged contenant des résultats intermédiaires.
Si enable_intermediate_result est défini sur false, le serveur ne renvoie pas de résultats intermédiaires. Le client doit néanmoins gérer les événements tels que RecognitionCompleted et TaskFailed.

Important
Le dernier résultat intermédiaire peut différer du résultat final. Tenez compte uniquement du résultat fourni dans l'événement RecognitionCompleted comme résultat définitif.

4. Arrêter la reconnaissance

Une fois l'envoi de l'audio terminé, le client envoie une directive StopRecognition . En cas de succès, le serveur renvoie l'événement RecognitionCompleted avec le résultat final ; en cas d'échec, il renvoie TaskFailed. Attendez la réception de l'événement de fin ou d'échec avant de fermer la connexion.

Si la détection d'activité vocale est activée, le serveur peut terminer la reconnaissance lorsque le silence en fin de flux dépasse la valeur max_end_silence. Les données audio envoyées après la fin de la reconnaissance ne sont pas traitées.

Paramètres de requête

Dans un SDK, utilisez les méthodes de l'objet SpeechRecognizer pour définir ces paramètres. Pour les requêtes WebSocket directes, spécifiez appkey dans l'en-tête header de la requête, et placez les autres paramètres de reconnaissance dans le corps payload de la directive StartRecognition.

Paramètre	Type	Obligatoire	Description
appkey	String	Oui	Appkey du projet créé dans la console.
format	String	Non	Format audio : `pcm`, `wav`, `opus`, `speex` ou `amr`. Le format WAV doit utiliser l'encodage PCM. Les formats OPUS et SPEEX doivent utiliser des conteneurs OGG.
sample_rate	Integer	Non	Fréquence d'échantillonnage en Hz. Valeur par défaut : `16000`. Valeurs valides : `8000` et `16000`. La valeur doit correspondre à l'audio et au modèle du projet.
enable_intermediate_result	Boolean	Non	Indique s'il faut renvoyer les résultats de reconnaissance intermédiaires. Valeur par défaut : `false`.
enable_punctuation_prediction	Boolean	Non	Indique s'il faut ajouter la ponctuation lors du post-traitement. Valeur par défaut : `false`.
enable_inverse_text_normalization	Boolean	Non	Active ou désactive la normalisation inverse du texte (ITN). Si ce paramètre est défini sur `true`, les chiffres chinois sont convertis en chiffres arabes dans la sortie. Valeur par défaut : `false`.
disfluency	Boolean	Non	Indique s'il faut filtrer les mots de remplissage (lissage de la sortie). Valeur par défaut : `false`.
customization_id	String	Non	ID du modèle de langue personnalisé. Pour les instructions de configuration, consultez la rubrique Personnaliser les modèles de langue.
vocabulary_id	String	Non	ID de la liste de mots clés personnalisés. Pour les instructions de configuration, consultez la rubrique Personnaliser les mots clés.
enable_voice_detection	Boolean	Non	Active ou désactive la détection d'activité vocale (VAD). La VAD détecte le début et la fin de la parole et exclut le bruit. Valeur par défaut : `false`.
max_start_silence	Integer	Non	Prend effet uniquement si `enable_voice_detection` est défini sur `true`. Durée maximale du silence initial, en millisecondes. Plage recommandée : (0, 60000]. Si aucune parole n'est détectée durant cette période, le serveur renvoie `TaskFailed` et met fin à la reconnaissance.
max_end_silence	Integer	Non	Prend effet uniquement si `enable_voice_detection` est défini sur `true`. Durée maximale du silence final, en millisecondes. Plage valide : 200–6000. Lorsque le silence final dépasse cette valeur, le serveur renvoie `RecognitionCompleted` et met fin à la reconnaissance. L'audio ultérieur n'est pas reconnu.

Événements de réponse

L'en-tête header contient les champs communs suivants.

Paramètre

Type

Description

namespace

String

Espace de noms : SpeechRecognizer.

name

String

Nom de l'événement. Consultez les descriptions d'événements ci-dessous.

status

Integer

Code d'état. La valeur 20000000 indique un succès. Pour les autres valeurs, consultez la section Codes d'état.

status_text

String

Message d'état.

task_id

String

ID de tâche globalement unique, correspondant à l'ID de tâche de la requête client. Enregistrez cette valeur pour le dépannage.

message_id

String

ID de ce message de réponse du serveur.

RecognitionStarted

Le serveur a accepté la demande de démarrage et le client peut envoyer les données audio. Cet événement ne contient aucun résultat de reconnaissance.

RecognitionResultChanged

Le champ payload.result contient le résultat de reconnaissance intermédiaire sous forme de chaîne. Cet événement est renvoyé uniquement si enable_intermediate_result est défini sur true.

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionResultChanged",
    "status": 20000000,
    "message_id": "8b756a91809843619c920e176d26****",
    "task_id": "af41104b6806410e9d3f192532aa****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "hello today is a beautiful day i would like to buy for two apples thank you"
  }
}

RecognitionCompleted

La reconnaissance est terminée avec succès. Le champ payload.result contient le résultat de reconnaissance final sous forme de chaîne.

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionCompleted",
    "status": 20000000,
    "message_id": "25227a2a43a74259a45685fc1633****",
    "task_id": "af41104b6806410e9d3f192532aa****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "hello today is a beautiful day i would like to buy for two apples thank you"
  }
}

TaskFailed

La tâche de reconnaissance a échoué. Vérifiez header.status et header.status_text pour identifier la cause. Par exemple, l'arrêt d'une requête sans envoi d'audio renvoie le code 40000000 et le message Gateway:CLIENT_ERROR:Empty audio data!.

Codes d'état

Lors du dépannage, vérifiez à la fois les champs status et status_text. Un code d'état peut avoir plusieurs causes ; utilisez le message d'état spécifique pour identifier le problème.

Codes d'erreur courants

Code d'état

Message d'état

Cause

Solution

40000000

Code d'erreur client par défaut. Ce code correspond à plusieurs messages d'erreur.

Paramètres ou séquence d'appel non valides.

Vérifiez les paramètres de la requête, l'ordre des directives et le message d'état spécifique.

40000001

The token 'xxx' has expired.

The token 'xxx' is invalid

Le jeton a expiré ou n'est pas valide.

Obtenez un jeton NLS valide et réessayez.

40000002

Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!

Le message n'est pas valide ou n'est pas accepté dans l'état actuel de la tâche.

Vérifiez la structure du message et l'ordre des directives. Démarrez une nouvelle tâche de reconnaissance après l'échec d'une tâche.

40000003

PARAMETER_INVALID

Failed to decode url params

Paramètres non valides.

Vérifiez les noms, types et valeurs des paramètres par rapport aux exigences de l'API.

40000005

Gateway:TOO_MANY_REQUESTS:Too many requests!

Trop de requêtes simultanées.

Réduisez le nombre de requêtes simultanées et vérifiez le quota de simultanéité disponible.

40000009

Invalid wav header!

L'en-tête du message n'est pas valide.

Si vous envoyez un fichier audio WAV et définissez le paramètre format sur wav, vérifiez que l'en-tête WAV du fichier audio est correct. Si l'en-tête est incorrect, le serveur peut rejeter la requête.

40000009

Too large wav header!

L'en-tête WAV de l'audio transmis n'est pas valide.

Vous pouvez envoyer le flux audio dans un format tel que PCM ou OPUS. Si vous utilisez le format WAV, assurez-vous que l'en-tête WAV du fichier audio contient la longueur de données correcte.

40000010

Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!

L'essai gratuit a expiré sans mise à niveau commerciale, ou le compte présente des impayés.

Vérifiez le statut d'activation de la reconnaissance de phrases courtes et le solde du compte dans la console.

40010001

Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal

Une API ou un paramètre non pris en charge a été utilisé.

Vérifiez l'endpoint, le namespace et les paramètres par rapport aux exigences de l'API.

40010003

Gateway:DIRECTIVE_INVALID:[xxx]

Un paramètre ou une directive non valide a été envoyé.

Utilisez le message d'état spécifique pour vérifier les paramètres et la directive.

40010004

Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!

Le client s'est déconnecté avant la fin de la tâche.

Attendez l'événement de réussite ou d'échec du serveur avant de fermer la connexion.

40010005

Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!

La directive n'est pas prise en charge dans l'état actuel de la tâche.

Vérifiez l'ordre des directives et évitez d'envoyer des directives d'arrêt en double.

40020105

Meta:APPKEY_NOT_EXIST:Appkey not exist!

L'Appkey n'existe pas.

Vérifiez l'Appkey dans la configuration du projet dans la console.

40020106

Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!

L'Appkey et le jeton appartiennent à des comptes différents.

Utilisez une Appkey de projet et un jeton NLS provenant du même compte.

403

Forbidden

Le jeton n'existe pas, a expiré ou n'est pas valide.

Utilisez un jeton NLS valide et obtenez-en un nouveau avant son expiration.

41000003

MetaInfo doesn't have end point info

Les informations de routage pour l'Appkey n'ont pas pu être obtenues.

Vérifiez l'Appkey et assurez-vous qu'elle appartient au même compte que le jeton.

41010101

UNSUPPORTED_SAMPLE_RATE

La fréquence d'échantillonnage n'est pas prise en charge par la configuration actuelle.

Utilisez un audio de 8 000 Hz ou 16 000 Hz et assurez-vous que l'audio, le paramètre de requête et le modèle de projet correspondent.

50000000

GRPC_ERROR:Grpc error!

Un appel côté serveur a échoué, probablement en raison de la charge ou des conditions réseau.

Réessayez la requête. Si le problème persiste, contactez le support technique et fournissez le task_id.

50000001

GRPC_ERROR:Grpc error!

Un appel côté serveur a échoué, probablement en raison de la charge ou des conditions réseau.

Réessayez la requête. Si le problème persiste, contactez le support technique et fournissez le task_id.

52010001

GRPC_ERROR:Grpc error!

Un appel côté serveur a échoué, probablement en raison de la charge ou des conditions réseau.

Réessayez la requête. Si le problème persiste, contactez le support technique et fournissez le task_id.

Codes d'erreur de reconnaissance de phrases courtes

Code d'état

Message d'état

Cause

Solution

40000000

Gateway:CLIENT_ERROR:Empty audio data!

Aucune donnée audio n'a été envoyée.

Envoyez des données audio binaires non vides avant d'envoyer la directive d'arrêt.

40000004

Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time

Aucune donnée n'a été envoyée après l'établissement de la connexion WebSocket, et la connexion est restée inactive pendant plus de 10 secondes.

Envoyez rapidement les directives de reconnaissance et l'audio après la connexion. Envoyez la directive d'arrêt lorsque tout l'audio a été envoyé.

40010002

Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported!

Le serveur ne prend pas en charge la directive.

Vérifiez le nom de la directive et utilisez une directive prise en charge par la reconnaissance de phrases courtes.

40010003

Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173)

Trop de mots clés ont été spécifiés.

Réduisez le nombre de mots clés à la limite autorisée pour la méthode de configuration des mots clés utilisée.

40270002

NO_VALID_AUDIO_ERROR

L'audio n'est pas valide et aucun texte valide n'a été reconnu.

Vérifiez que l'audio contient une parole claire et que son encodage, sa fréquence d'échantillonnage et son modèle correspondent.

41010104

TOO_LONG_SPEECH

L'audio dépasse la limite de durée pour la reconnaissance de phrases courtes.

Utilisez un audio d'une durée maximale de 60 secondes. Pour un audio plus long, utilisez la reconnaissance vocale en temps réel.

41010105

SILENT_SPEECH

Aucune parole n'a été détectée dans un audio silencieux ou bruyant.

Vérifiez l'audio. Si la VAD est activée, vérifiez également le paramètre de silence initial.