Présentation de Historique des conversations Diffusion audio Clôture de la session Flux d'événements d'entrée

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, ASSISTANTTOOL,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.

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"
            }
        }
    }
}

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


{
    "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": "{}"
                            }
                        }
                    }
                ]
            }
        }
    }
}

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"
                }
            }
        }
    }
}


{
    "event": {
        "textInput": {
            "promptName": "string", // same unique identifier from promptStart event
            "contentName": "string", // unique identifier for the content block
            "content": "string"
        }
    }
}


{
    "event": {
        "audioInput": {
            "promptName": "string", // same unique identifier from promptStart event
            "contentName": "string", // same unique identifier from its contentStart
            "content": "base64EncodedAudioData"
        }
    }
}


"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 
    }
}


{
    "event": {
        "contentEnd": {
            "promptName": "string", // same unique identifier from promptStart event
            "contentName": "string" // same unique identifier from its contentStart
        }
    }
}


{
    "event": {
        "promptEnd": {
            "promptName": "string" // same unique identifier from promptStart event
        }
    }
}


{
    "event": {
        "sessionEnd": {}
    }
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Séquence du flux d'événements

Gestion des événements de sortie avec l’API bidirectionnelle