Gestión de eventos de entrada con la API bidireccional - Amazon Nova
Flujo 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.

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 al 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), 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.

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.

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.

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:

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

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

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

Diagrama que explica el flujo de eventos de entrada de Amazon Nova Sonic.

Flujo de eventos de entrada

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

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