View a markdown version of this page

Gestione degli eventi di input con l’API bidirezionale - Amazon Nova
Panoramica diCronologia delle conversazioniStreaming audioChiusura della sessioneFlusso di eventi di input

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Gestione degli eventi di input con l’API bidirezionale

L’API di streaming bidirezionale utilizza un’architettura basata sugli eventi con eventi di input e output strutturati. La comprensione del corretto ordine degli eventi è fondamentale per implementare applicazioni conversazionali di successo e mantenere lo stato di conversazione corretto durante le interazioni.

Panoramica di

La conversazione di Nova Sonic segue una sequenza di eventi strutturata. Si inizia inviando un evento sessionStart che contiene i parametri di configurazione dell’inferenza, come i limiti di temperatura e token. Successivamente, si invia promptStart per definire il formato dell’output audio e le configurazioni degli strumenti, assegnando un identificatore promptName univoco che deve essere incluso in tutti gli eventi successivi.

Per ogni tipo di interazione (prompt di sistema, audio e così via), seguite uno schema in tre parti: contentStart da utilizzare per definire il tipo di contenuto e il ruolo del contenuto (SYSTEM,,USER,ASSISTANT,SYSTEM_SPEECH)TOOL, quindi fornite l'evento di contenuto effettivo e terminate con contentEnd la chiusura del segmento. L’evento contentStart specifica se stai inviando i risultati dello strumento, lo streaming audio o un prompt di sistema. L’evento contentStart include un identificatore contentName univoco.

Cronologia delle conversazioni

Una cronologia delle conversazioni può essere inclusa una sola volta, dopo il prompt di sistema e prima dell’inizio dello streaming audio. Segue lo stesso schema contentStart/textInput/contentEnd. I ruoli USER e ASSISTANT devono essere definiti nell’evento contentStart per ogni messaggio storico. Ciò fornisce un contesto essenziale per la conversazione attuale, ma deve essere completato prima che inizi qualsiasi nuovo input da parte dell’utente.

Streaming audio

Lo streaming audio funziona con un campionamento continuo del microfono. Dopo l’invio di un contentStart iniziale, i frame audio (circa 32 ms ciascuno) vengono acquisiti direttamente dal microfono e inviati immediatamente come eventi audioInput utilizzando lo stesso contentName. Questi campioni audio devono essere trasmessi in streaming in tempo reale man mano che vengono acquisiti, mantenendo la naturale cadenza di campionamento del microfono per tutta la conversazione. Tutti i frame audio condividono un singolo container di contenuti fino al termine della conversazione e alla sua chiusura esplicita.

Chiusura della sessione

Dopo che la conversazione è terminata o deve essere interrotta, è fondamentale chiudere correttamente tutti gli stream aperti e terminare la sessione nella sequenza corretta. Per terminare correttamente una sessione ed evitare perdite di risorse, devi seguire una sequenza di chiusura specifica:

  • Chiudi tutti gli streaming flussi audio aperti con l’evento contentEnd.

  • Invia un evento promptEnd che fa riferimento al promptName originale.

  • Invia l’evento sessionEnd.

Saltare uno qualsiasi di questi eventi di chiusura può portare a conversazioni incomplete o alla creazione di risorse orfane.

Questi identificatori creano una struttura gerarchica: i promptName collegano tutti gli eventi di conversazione, mentre ciascun contentName segna i confini di blocchi di contenuto specifici. Questa gerarchia garantisce che il modello mantenga il contesto corretto durante l’interazione.

Flusso di eventi di input

La struttura del flusso di eventi di input è riportata in questa sezione.

L'evento di inizio della sessione inizializza la conversazione con la configurazione dell'inferenza e le impostazioni di rilevamento dei turni.

Configurazione dell'inferenza:

  • maxTokens: numero massimo di token da generare nella risposta

  • topP: Parametro di campionamento del nucleo (da 0,0 a 1,0) per il controllo della casualità

  • temperature: Controlla la casualità nella generazione (da 0,0 a 1,0)

Configurazione Turn Detection: il endpointingSensitivity parametro controlla la velocità con cui Nova Sonic rileva quando un utente ha finito di parlare:

  • HIGH: Rileva rapidamente le pause, permettendo risposte più rapide, ma può spegnere gli altoparlanti più lenti

  • MEDIUM: sensibilità bilanciata per la maggior parte degli scenari di conversazione (impostazione predefinita consigliata)

  • LOW: Attende più a lungo prima di rilevare la fine del discorso, preferibile per chi parla in modo riflessivo o titubante

{
    "event": {
        "sessionStart": {
            "inferenceConfiguration": {
                "maxTokens": "int",
                "topP": "float",
                "temperature": "float"
            },
            "turnDetectionConfiguration": {
                "endpointingSensitivity": "HIGH" | "MEDIUM" | "LOW"
            }
        }
    }
}

Esempio:

{
    "event": {
        "sessionStart": {
            "inferenceConfiguration": {
                "maxTokens": 2048,
                "topP": 0.9,
                "temperature": 0.7
            },
            "turnDetectionConfiguration": {
                "endpointingSensitivity": "MEDIUM"
            }
        }
    }
}

L'evento prompt start definisce la configurazione della conversazione, inclusi i formati di output, la selezione vocale e gli strumenti disponibili.

Per un elenco degli ID vocali disponibili, consulta Supporto linguistico e funzionalità multilingue

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

Testo

L'evento di avvio del contenuto testuale viene utilizzato per i prompt di sistema, la cronologia delle conversazioni e l'immissione di testo intermodale.

Parametro interattivo:

  • true: Abilita l'input intermodale, permettendo l'invio di messaggi di testo durante una sessione vocale attiva

  • false: immissione di testo standard per le istruzioni di sistema e la cronologia delle conversazioni

Tipi di ruolo:

  • SYSTEM: istruzioni e istruzioni di sistema

  • USER: messaggi utente nella cronologia delle conversazioni o nell'input intermodale

  • ASSISTANT: risposte dell'assistente nella cronologia delle conversazioni

  • SYSTEM_SPEECH: controlla la formattazione della trascrizione per la commutazione di codice in hindi (script) 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"
            }
        }
    }
}

Esempio - System Prompt:

{
    "event": {
        "contentStart": {
            "promptName": "conv-12345",
            "contentName": "system-prompt-1",
            "type": "TEXT",
            "interactive": false,
            "role": "SYSTEM",
            "textInputConfiguration": {
                "mediaType": "text/plain"
            }
        }
    }
}

Esempio - Cross-modal Input:

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

Strumento

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