Processamento de eventos de entrada com a API bidirecional

A API de streaming bidirecional usa uma arquitetura orientada por eventos com eventos estruturados de entrada e saída. Compreender a ordem correta dos eventos é crucial para implementar aplicações de conversação bem-sucedidas e manter o estado adequado da conversa durante as interações.

A conversa do Nova Sonic segue uma sequência estruturada de eventos. Você começa enviando um evento sessionStart que contém os parâmetros de configuração de inferência, como temperatura e limites de token. Em seguida, você envia promptStart para definir o formato de saída de áudio e as configurações de ferramentas, atribuindo um identificador promptName exclusivo que deve ser incluído em todos os eventos subsequentes.

Para cada tipo de interação (prompt do sistema, áudio etc.), você segue um padrão de três partes: use contentStart para definir o tipo de conteúdo e o perfil do conteúdo (SYSTEM, USER, ASSISTANT, TOOL), depois forneça o evento de conteúdo real e finalize com contentEnd para concluir o segmento. O evento contentStart especifica se você está enviando resultados de ferramentas, transmitindo áudio ou se é um prompt do sistema. O evento contentStart inclui um identificador contentName exclusivo.

Um histórico de conversa pode ser incluído apenas uma vez, após o prompt do sistema e antes do início do streaming de áudio. Ele segue o mesmo padrão contentStart/textInput/contentEnd. Os perfis USER e ASSISTANT devem ser definidos no evento contentStart para cada mensagem histórica. Isso fornece um contexto essencial para a conversa atual, mas deve ser concluído antes que qualquer nova entrada do usuário comece.

O streaming de áudio opera com amostragem contínua de microfone. Depois de enviar um contentStart inicial, os quadros de áudio (aproximadamente 32 ms cada) são capturados diretamente do microfone e enviados imediatamente como eventos audioInput usando o mesmo contentName. Essas amostras de áudio devem ser transmitidas em tempo real à medida que são capturadas, mantendo a cadência natural de amostragem do microfone durante toda a conversa. Todos os quadros de áudio compartilham um único contêiner de conteúdo até que a conversa termine e seja explicitamente concluída.

Depois que a conversa terminar ou precisar ser encerrada, é essencial fechar adequadamente todos os streamings abertos e encerrar a sessão na sequência correta. Para encerrar adequadamente uma sessão e evitar vazamentos de recursos, você deve seguir uma sequência de fechamento específica:

1. Feche todos os streamings de áudio abertos com o evento contentEnd.

2. Envie um evento promptEnd que faça referência ao promptName original.

3. Envie o evento sessionEnd.

Ignorar qualquer um desses eventos de encerramento pode resultar em conversas incompletas ou em recursos órfãos.

Esses identificadores criam uma estrutura hierárquica: o promptName une todos os eventos da conversa, enquanto cada contentName marca os limites de blocos de conteúdo específicos. Essa hierarquia garante que o modelo mantenha o contexto adequado durante toda a interação.

Fluxo de eventos de entrada

A estrutura do fluxo de eventos de entrada é fornecida nesta seção.

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