View a markdown version of this page

Gestión de eventos de entrada con la API bidireccional - Amazon Nova
Descripción generalHistorial de la conversaciónTransmisión de audioCierre de la sesiónFlujo de eventos de entrada

Gestión de eventos de entrada con la API bidireccional

La API de transmisión bidireccional utiliza una arquitectura basada en eventos con eventos de entrada y salida estructurados. Comprender el orden correcto de los eventos es fundamental para implementar aplicaciones conversacionales que funcionen y mantener el estado de conversación adecuado durante todas las interacciones.

Descripción general

La conversación de Nova Sonic sigue una secuencia de eventos estructurada. Se empieza por enviar un evento sessionStart que contenga los parámetros de configuración de la inferencia, como la temperatura y los límites de tokens. A continuación, se envía promptStart para definir el formato de salida de audio y las configuraciones de las herramientas, y se asigna un identificador único promptName que se debe incluir en todos los eventos posteriores.

Para cada tipo de interacción (petición del sistema, audio, etc.), se sigue un patrón de tres partes: se utiliza contentStart para definir el tipo de contenido y el rol del contenido (SYSTEM, USER, ASSISTANT, TOOL, SYSTEM_SPEECH), luego se proporciona el evento de contenido real y se termina con contentEnd para cerrar ese segmento. El evento contentStart especifica si se están enviando los resultados de la herramienta, si se está transmitiendo audio o una petición al sistema. El evento contentStart incluye un identificador único contentName.

Historial de la conversación

El historial de conversaciones solo se puede incluir una vez, después de darle la petición al sistema y antes de que comience la transmisión de audio. Sigue el mismo patrón contentStart/textInput/contentEnd. Los roles USER y ASSISTANT deben definirse en el evento contentStart para cada mensaje histórico. Esto proporciona un contexto esencial para la conversación actual, pero debe completarse antes de que comience cualquier nueva entrada del usuario.

Transmisión de audio

La transmisión de audio funciona con un muestreo continuo del micrófono. Tras enviar un contentStart inicial, se capturan las tramas del audio (aproximadamente de 32 ms cada una) directamente desde el micrófono y se envían inmediatamente como eventos audioInput utilizando el mismo contentName. Estas muestras de audio deben transmitirse en tiempo real a medida que se capturan, manteniendo la cadencia de muestreo natural del micrófono durante toda la conversación. Todas las tramas de audio comparten un único contenedor de contenido hasta que la conversación finaliza y se cierra explícitamente.

Cierre de la sesión

Una vez que la conversación finalice o deba terminarse, es esencial cerrar correctamente todas las transmisiones abiertas y finalizar la sesión en la secuencia correcta. Para finalizar correctamente una sesión y evitar la pérdida de recursos, se debe seguir una secuencia de cierre específica:

  • Cierre todas las transmisiones de audio abiertas con el evento contentEnd.

  • Envíe un evento promptEnd que haga referencia al promptName original.

  • Envíe el evento sessionEnd.

Omitir cualquiera de estos eventos de cierre puede provocar conversaciones incompletas o recursos huérfanos.

Estos identificadores crean una estructura jerárquica: el promptName une todos los eventos de la conversación, mientras que cada contentName marca los límites de bloques de contenido específicos. Esta jerarquía garantiza que el modelo mantenga el contexto adecuado durante toda la interacción.

Flujo de eventos de entrada

En esta sección, se proporciona la estructura del flujo de eventos de entrada.

El evento de inicio de la sesión inicializa la conversación con la configuración de inferencias y de detección de turnos.

Configuración de inferencias:

  • maxTokens: número máximo de tokens que se generarán en la respuesta

  • topP: parámetro de muestreo del núcleo (de 0,0 a 1,0) para el control de la aleatoriedad

  • temperature: control de la asignación al azar en la generación (de 0,0 a 1,0)

Configuración de detección de turnos: el parámetro endpointingSensitivity controla la rapidez con la que Nova Sonic detecta cuándo ha terminado de hablar un usuario.

  • HIGH: detecta las pausas rápidamente, lo que permite respuestas más rápidas, pero puede interrumpir a hablantes más lentos.

  • MEDIUM: tiene una sensibilidad equilibrada para la mayoría de los escenarios de conversación (se recomienda de forma predeterminada).

  • LOW: espera más tiempo antes de detectar el final del habla, lo que es mejor para hablantes reflexivos o indecisos.

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

Ejemplo:

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

El evento de inicio de la petición define la configuración de la conversación, lo que incluye los formatos de salida, la selección de voz y las herramientas disponibles.

Para obtener una lista de los ID de voz disponibles, consulte Soporte lingüístico y capacidades multilingües.

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

Texto

El evento de inicio del contenido de texto se utiliza para las peticiones del sistema, el historial de conversaciones y la entrada de texto multimodal.

Parámetro interactivo:

  • true: habilita la entrada multimodal, lo que permite enviar mensajes de texto durante una sesión de voz activa

  • false: entrada de texto estándar para las peticiones del sistema y el historial de conversaciones

Tipos de roles:

  • SYSTEM: peticiones e instrucciones del sistema

  • USER: mensajes del usuario en el historial de conversaciones o la entrada multimodal

  • ASSISTANT: respuestas del asistente en el historial de conversaciones

  • SYSTEM_SPEECH: controla el formato de transcripción para cambios de código en hindi (alfabetos latino, devanagari o mixto)

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

Ejemplo, petición del sistema:

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

Ejemplo, entrada multimodal:

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

Herramienta

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