Gestion des événements d’entrée avec l’API bidirectionnelle - Amazon Nova
Flux d’événement en entrée

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

Note

Cette documentation concerne la version 1 d'Amazon Nova. Pour consulter le guide Amazon Nova 2 Sonic, consultez l'article Gérer les é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.

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 modèle en trois parties : utilisez contentStart pour définir le type de contenu et le rôle du contenu (SYSTEM, USER, ASSISTANT, TOOL), puis fournissez l’événement de contenu réel et terminez par contentEnd pour clôturer 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.

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.

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.

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 :

  1. Fermez tous les flux audio ouverts avec l’événement contentEnd.

  2. Envoyez un événement promptEnd qui fait référence au promptName d’origine.

  3. 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.

Schéma expliquant le flux d’événements d’entrée Amazon Nova Sonic.

Flux d’événement en entrée

La structure du flux d’événements d’entrée est présentée dans cette section.

  1. RequestStartEvent

    {
    "event": {
        "sessionStart": {
            "inferenceConfiguration": {
                "maxTokens": "int",
                "topP": "float",
                "temperature": "float"
            }
        }
    }
}

  2. PromptStartEvent

    {
    "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" |
                        "lupe" | "carlos" | "ambre" | "florian" |
                        "greta" | "lennart" | "beatrice" | "lorenzo",
                "encoding": "base64",
                "audioType": "SPEECH",
            },
            "toolUseOutputConfiguration": {
                "mediaType": "application/json"
            },
            "toolConfiguration": {
                "tools": [{
                    "toolSpec": {
                        "name": "string",
                        "description": "string",
                        "inputSchema": {
                            "json": "{}"
                        }
                    }
                }]
            }
        }
    }
}

  3. InputContentStartEvent

    • Text

      {
    "event": {
        "contentStart": {
            "promptName": "string", // same unique identifier from promptStart event
            "contentName": "string", // unique identifier for the content block
            "type": "TEXT",
            "interactive": false,
            "role": "SYSTEM" | "USER" | "ASSISTANT",
            "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"
            }
        }
    }
}

    • Tool

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