View a markdown version of this page

Menangani peristiwa masukan dengan API dua arah - Amazon Nova
IkhtisarRiwayat PercakapanStreaming AudioMenutup SesiMasukan Alur Acara

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menangani peristiwa masukan dengan API dua arah

API Stream dua arah menggunakan arsitektur berbasis peristiwa dengan peristiwa input dan output terstruktur. Memahami urutan acara yang benar sangat penting untuk menerapkan aplikasi percakapan yang sukses dan mempertahankan status percakapan yang tepat selama interaksi.

Ikhtisar

Percakapan Nova Sonic mengikuti urutan peristiwa terstruktur. Anda mulai dengan mengirimkan sessionStart peristiwa yang berisi parameter konfigurasi inferensi, seperti batas suhu dan token. Selanjutnya, Anda mengirim promptStart untuk menentukan format output audio dan konfigurasi alat, menetapkan promptName pengidentifikasi unik yang harus disertakan dalam semua acara berikutnya.

Untuk setiap jenis interaksi (prompt sistem, audio, dan sebagainya), Anda mengikuti pola tiga bagian: gunakan contentStart untuk menentukan jenis konten dan peran konten (SYSTEM,,,,SYSTEM_SPEECH) USER ASSISTANTTOOL, lalu berikan peristiwa konten yang sebenarnya, dan selesaikan dengan contentEnd untuk menutup segmen itu. contentStartAcara ini menentukan apakah Anda mengirim hasil alat, streaming audio, atau prompt sistem. contentStartAcara ini mencakup contentName pengenal unik.

Riwayat Percakapan

Riwayat percakapan hanya dapat disertakan sekali, setelah prompt sistem dan sebelum streaming audio dimulai. Ini mengikuti contentEnd polacontentStart/textInput/yang sama. ASSISTANTPeran USER dan harus didefinisikan dalam contentStart acara untuk setiap pesan historis. Ini memberikan konteks penting untuk percakapan saat ini tetapi harus diselesaikan sebelum masukan pengguna baru dimulai.

Streaming Audio

Streaming audio beroperasi dengan pengambilan sampel mikrofon kontinu. Setelah mengirim inisiasicontentStart, bingkai audio (masing-masing sekitar 32 ms) ditangkap langsung dari mikrofon dan segera dikirim sebagai audioInput acara menggunakan yang samacontentName. Sampel audio ini harus dialirkan secara real-time saat ditangkap, mempertahankan irama pengambilan sampel mikrofon alami selama percakapan. Semua bingkai audio berbagi satu wadah konten hingga percakapan berakhir dan ditutup secara eksplisit.

Menutup Sesi

Setelah percakapan berakhir atau perlu dihentikan, penting untuk menutup semua aliran terbuka dengan benar dan mengakhiri sesi dalam urutan yang benar. Untuk mengakhiri sesi dengan benar dan menghindari kebocoran sumber daya, Anda harus mengikuti urutan penutupan tertentu:

  • Tutup semua aliran audio yang terbuka dengan contentEnd acara tersebut.

  • Kirim promptEnd acara yang mereferensikan aslinyapromptName.

  • Kirim sessionEnd acara.

Melewatkan salah satu acara penutupan ini dapat mengakibatkan percakapan yang tidak lengkap atau sumber daya yatim piatu.

Pengidentifikasi ini membuat struktur hierarkis: promptName mengikat semua peristiwa percakapan bersama-sama, sementara masing-masing contentName menandai batas-batas blok konten tertentu. Hirarki ini memastikan bahwa model mempertahankan konteks yang tepat di seluruh interaksi.

Masukan Alur Acara

Struktur aliran peristiwa masukan disediakan di bagian ini.

Acara mulai sesi menginisialisasi percakapan dengan konfigurasi inferensi dan mengubah pengaturan deteksi.

Konfigurasi inferensi:

  • maxTokens: Jumlah maksimum token yang akan dihasilkan dalam respons

  • topP: Parameter pengambilan sampel nukleus (0,0 hingga 1,0) untuk mengendalikan keacakan

  • temperature: Mengontrol keacakan dalam generasi (0,0 hingga 1,0)

Turn Detection Configuration: endpointingSensitivity Parameter mengontrol seberapa cepat Nova Sonic mendeteksi ketika pengguna selesai berbicara:

  • HIGH: Mendeteksi jeda dengan cepat, memungkinkan respons yang lebih cepat tetapi dapat memotong speaker yang lebih lambat

  • MEDIUM: Sensitivitas seimbang untuk sebagian besar skenario percakapan (default yang disarankan)

  • LOW: Menunggu lebih lama sebelum mendeteksi akhir pembicaraan, lebih baik untuk pembicara yang bijaksana atau ragu-ragu

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

Contoh:

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

Acara mulai cepat mendefinisikan konfigurasi percakapan termasuk format output, pemilihan suara, dan alat yang tersedia.

Untuk daftar ID suara yang tersedia, lihat Dukungan bahasa dan kemampuan multibahasa

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

Teks

Acara mulai konten teks digunakan untuk prompt sistem, riwayat percakapan, dan input teks lintas modal.

Parameter Interaktif:

  • true: Mengaktifkan input lintas modal, memungkinkan pesan teks selama sesi suara aktif

  • false: Input teks standar untuk permintaan sistem dan riwayat percakapan

Jenis Peran:

  • SYSTEM: Instruksi dan petunjuk sistem

  • USER: Pesan pengguna dalam riwayat percakapan atau input lintas modal

  • ASSISTANT: Tanggapan asisten dalam riwayat percakapan

  • SYSTEM_SPEECH: Mengontrol pemformatan transkripsi untuk pengalihan kode Hindi (skrip) 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"
            }
        }
    }
}

Contoh - Prompt Sistem:

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

Contoh - Cross-modal Masukan:

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

Alat

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