Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Gestion des événements d’entrée avec l’API bidirectionnelle
L’API Stream bidirectionnelle utilise une architecture événementielle avec des événements d’entrée et de sortie structurés. Il est essentiel de comprendre l’ordre correct des événements pour implémenter des applications conversationnelles efficaces et maintenir un état de conversation approprié tout au long des interactions.
## Présentation de
La conversation Nova Sonic suit une séquence d’événements structurée. Vous commencez par envoyer un événement `sessionStart` qui contient les paramètres de configuration de l’inférence, tels que la température et les limites de jetons. Ensuite, vous envoyez `promptStart` pour définir le format de sortie audio et les configurations des outils, en attribuant un identifiant `promptName` unique qui doit être inclus dans tous les événements suivants.
Pour chaque type d'interaction (invite système, audio, etc.), vous suivez un schéma en trois parties : utilisez `contentStart` pour définir le type de contenu et le rôle du contenu (`SYSTEM`,,`USER`, `ASSISTANT``TOOL`,`SYSTEM_SPEECH`), puis indiquez l'événement de contenu réel et terminez par `contentEnd` pour fermer ce segment. L’événement `contentStart` spécifie si vous envoyez les résultats d’un outil, un flux audio ou une invite système. L’événement `contentStart` comprend un identifiant `contentName` unique.
## Historique des conversations
Un historique de conversation ne peut être inclus qu’une seule fois, après l’invite système et avant le début du flux audio. Il suit le même modèle `contentStart`/`textInput`/`contentEnd`. Les rôles `USER` et `ASSISTANT` doivent être définis dans l’événement `contentStart` pour chaque message historique. Cela fournit un contexte essentiel pour la conversation en cours, mais doit être effectué avant que toute nouvelle entrée utilisateur ne commence.
## Diffusion audio
Le streaming audio fonctionne avec un échantillonnage continu du microphone. Après l’envoi d’un `contentStart` initial, les trames audio (environ 32 ms chacune) sont capturées directement à partir du microphone et immédiatement envoyées en tant qu’événements `audioInput` en utilisant le même `contentName`. Ces échantillons audio doivent être diffusés en temps réel au fur et à mesure qu’ils sont capturés, en conservant la cadence naturelle d’échantillonnage du microphone tout au long de la conversation. Toutes les trames audio partagent un seul conteneur de contenu jusqu’à la fin de la conversation et sa fermeture explicite.
## Clôture de la session
Une fois la conversation terminée ou lorsqu’il est nécessaire d’y mettre fin, il est essentiel de fermer correctement tous les flux ouverts et de terminer la session dans le bon ordre. Pour terminer correctement une session et éviter les fuites de ressources, vous devez suivre une séquence de fermeture spécifique :
+ Fermez tous les flux audio ouverts avec l’événement `contentEnd`.
+ Envoyez un événement `promptEnd` qui fait référence au `promptName` d’origine.
+ Envoyez l’événement `sessionEnd`.
Le fait d’ignorer l’un de ces événements de fermeture peut entraîner des conversations incomplètes ou des ressources orphelines.
Ces identifiants créent une structure hiérarchique : le `promptName` relie tous les événements de conversation, tandis que chaque `contentName` marque les limites de blocs de contenu spécifiques. Cette hiérarchie garantit que le modèle conserve un contexte approprié tout au long de l’interaction.
## Flux d'événements d'entrée
La structure du flux d’événements d’entrée est présentée dans cette section.
### 1. RequestStartEvent (Début de session)
L'événement de démarrage de session initialise la conversation avec les paramètres de configuration d'inférence et de détection des virages.
**Configuration d'inférence :**
+ `maxTokens`: nombre maximum de jetons à générer dans la réponse
+ `topP`: paramètre d'échantillonnage du noyau (0,0 à 1,0) pour contrôler le caractère aléatoire
+ `temperature`: Contrôle le caractère aléatoire de la génération (0,0 à 1,0)
**Configuration de la détection des virages :** le `endpointingSensitivity` paramètre contrôle la rapidité avec laquelle Nova Sonic détecte lorsqu'un utilisateur a fini de parler :
+ `HIGH`: détecte rapidement les pauses, permettant des réponses plus rapides mais peut interrompre les haut-parleurs plus lents
+ `MEDIUM`: sensibilité équilibrée pour la plupart des scénarios de conversation (valeur par défaut recommandée)
+ `LOW`: attend plus longtemps avant de détecter la fin du discours, ce qui est préférable pour les orateurs attentionnés ou hésitants
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": "int",
"topP": "float",
"temperature": "float"
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "HIGH" | "MEDIUM" | "LOW"
}
}
}
}
```
**Exemple :**
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": 2048,
"topP": 0.9,
"temperature": 0.7
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "MEDIUM"
}
}
}
}
```
### 2. PromptStartEvent
L'événement de démarrage rapide définit la configuration de la conversation, notamment les formats de sortie, la sélection vocale et les outils disponibles.
Pour obtenir la liste des identifiants vocaux disponibles, reportez-vous à la section Prise en [charge linguistique et fonctionnalités multilingues](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-language-support.html)
```
{
"event": {
"promptStart": {
"promptName": "string", // unique identifier same across all events i.e. UUID
"textOutputConfiguration": {
"mediaType": "text/plain"
},
"audioOutputConfiguration": {
"mediaType": "audio/lpcm",
"sampleRateHertz": 8000 | 16000 | 24000,
"sampleSizeBits": 16,
"channelCount": 1,
"voiceId": "matthew" | "tiffany" | "amy" | "olivia" | "lupe" | "carlos" | "ambre" | "florian" | "lennart" | "beatrice" | "lorenzo" |
"tina" | "carolina" | "leo" | "kiara" | "arjun",
"encoding": "base64",
"audioType": "SPEECH"
},
"toolUseOutputConfiguration": {
"mediaType": "application/json"
},
"toolConfiguration": {
"tools": [
{
"toolSpec": {
"name": "string",
"description": "string",
"inputSchema": {
"json": "{}"
}
}
}
]
}
}
}
}
```
### 3. InputContentStartEvent
#### Texte
L'événement de démarrage du contenu textuel est utilisé pour les instructions du système, l'historique des conversations et la saisie de texte intermodale.
**Paramètre interactif :**
+ `true`: permet la saisie intermodale, autorisant les messages texte pendant une session vocale active
+ `false`: saisie de texte standard pour les instructions du système et l'historique des conversations
**Types de rôles :**
+ `SYSTEM`: instructions et instructions du système
+ `USER`: messages utilisateur dans l'historique des conversations ou saisie intermodale
+ `ASSISTANT`: réponses de l'assistant dans l'historique des conversations
+ `SYSTEM_SPEECH`: Contrôle le formatage de la transcription pour le changement de code en hindi (scripts) Latin/Devanagari/mixed
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"type": "TEXT",
"interactive": "boolean", // true for cross-modal input
"role": "SYSTEM" | "USER" | "ASSISTANT" | "TOOL" | "SYSTEM_SPEECH",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**Exemple - Invite système :**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "system-prompt-1",
"type": "TEXT",
"interactive": false,
"role": "SYSTEM",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**Exemple - Cross-modal Saisie :**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "user-text-1",
"type": "TEXT",
"interactive": true,
"role": "USER",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
#### Audio
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"type": "AUDIO",
"interactive": true,
"role": "USER",
"audioInputConfiguration": {
"mediaType": "audio/lpcm",
"sampleRateHertz": 8000 | 16000 | 24000,
"sampleSizeBits": 16,
"channelCount": 1,
"audioType": "SPEECH",
"encoding": "base64"
}
}
}
}
```
#### Outil
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"interactive": false,
"type": "TOOL",
"role": "TOOL",
"toolResultInputConfiguration": {
"toolUseId": "string", // existing tool use id
"type": "TEXT",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
}
```
### 4. TextInputContent
```
{
"event": {
"textInput": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"content": "string"
}
}
}
```
### 5. AudioInputContent
```
{
"event": {
"audioInput": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // same unique identifier from its contentStart
"content": "base64EncodedAudioData"
}
}
}
```
### 6. ToolResultContentEvent
```
"event": {
"toolResult": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // same unique identifier from its contentStart
"content": "{\"key\": \"value\"}" // stringified JSON object as a tool result
}
}
```
### 7. InputContentEndEvent
```
{
"event": {
"contentEnd": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string" // same unique identifier from its contentStart
}
}
}
```
### 8. PromptEndEvent
```
{
"event": {
"promptEnd": {
"promptName": "string" // same unique identifier from promptStart event
}
}
}
```
### 9. RequestEndEvent
```
{
"event": {
"sessionEnd": {}
}
}
```