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.
### 1. RequestStartEvent (Inizio sessione)
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"
}
}
}
}
```
### 2. PromptStartEvent
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](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
#### 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"
}
}
}
}
}
```
### 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": {}
}
}
```