View a markdown version of this page

Perutean model dan fallback - Batu Dasar Amazon AgentCore

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

Perutean model dan fallback

Saat Anda merutekan lalu lintas inferensi melalui gateway, permintaan dapat gagal ketika target yang melayani model yang diminta dibatasi, kehabisan kapasitas, atau tidak dapat dijangkau. Dengan model fallback, Anda menentukan rantai tujuan alternatif yang teratur, dan gateway secara otomatis mencoba yang berikutnya ketika utama gagal. Fallback memberi Anda ketersediaan yang lebih tinggi dan kontrol lebih besar atas biaya dan cakupan model, tanpa setiap klien yang menelepon menerapkan logika fallback-nya sendiri.

Anda mengonfigurasi perutean model dan fallback pada aturan gateway, dan mereka berlaku untuk target inferensi. Topik ini dimulai dengan aturan routing, lalu menambahkan rantai fallback ke dalamnya.

Merutekan model ke target

Mulailah dengan aturan yang merutekan model ke target tertentu, tanpa fallback. Gunakan a routeToTarget aturan untuk mengganti default gateway perutean berbasis model untuk model yang cocok. SEBUAH matchModels kondisi menentukan permintaan mana yang berlaku untuk aturan, dan a routeToTarget tindakan dengan a staticRoute menentukan target yang melayani permintaan yang cocok. Ketika beberapa target cocok dengan model yang sama, perutean default dapat mengirim permintaan ke salah satu dari mereka; aturan menyematkannya ke target yang Anda pilih.

Berikut ini AWS Perintah CLI membuat aturan yang merutekan gpt-5.5 ke bedrock-mantle sasaran:

aws bedrock-agentcore-control create-gateway-rule \ --gateway-identifier my-gateway-abc1234567 \ --priority 100 \ --description "Route gpt-5.5 to bedrock-mantle" \ --conditions '[ { "matchModels": { "anyOf": [ {"value": "gpt-5.5"} ] } } ]' \ --actions '[ { "routeToTarget": { "staticRoute": { "targetName": "bedrock-mantle" } } } ]'

staticRoute bisa juga menyematkan yang disajikan model, jadi target melayani model yang berbeda dari yang diminta penelepon; hilangkan model untuk melayani model yang diminta. Untuk selengkapnya matchModels dan routeToTarget referensi, lihat Menambahkan aturan ke gateway.

Tambahkan rantai fallback

Untuk melindungi rute itu, tambahkan fallback memblokir ke routeToTarget tindakan. Blok tersebut menyatakan daftar tujuan alternatif yang diurutkan dan kondisi untuk meninggalkan tujuan. Tujuan adalah target, opsional dengan model tertentu.

  • Primer — Yang staticRoute (atau masing-masing weightedRoute kaki). Secara opsional menyematkan a model, sehingga model yang dilayani dapat berbeda dari yang diminta; hilangkan model untuk melayani model yang diminta pada target itu. Kondisi cuti primer sendiri berada di fallback blok.

  • targetFallback — Daftar terurutan dari 1 hingga 2 tujuan alternatif untuk dicoba, secara berurutan, ketika utama gagal. Setiap entri menamai a targetName dan opsional model, dan membawa kondisi cuti opsionalnya sendiri.

  • triggerOn — Kondisi di mana gateway meninggalkan tujuan dan mencoba yang berikutnya. Respons yang tidak cocok dengan tidak satu pun dari mereka kembali ke penelepon tidak berubah.

  • firstByteTimeoutMilliseconds — Berapa lama menunggu byte respons pertama tujuan sebelum menyerah dan pindah ke tujuan berikutnya. Ini membuat fallback berfungsi ketika penyedia berhenti alih-alih mengembalikan kesalahan bersih.

  • circuitBreaker — Menghidupkan atau mematikan pemutus sirkuit untuk rute ini (ENABLED secara default). Pemutus sirkuit melewatkan tujuan yang saat ini gagal sehingga permintaan langsung menuju tujuan yang sehat. Untuk informasi selengkapnya, lihat Pemutus sirkuit.

Gerbang berjalan rantai secara berurutan. Untuk setiap tujuan, ia memeriksa pemutus sirkuit, mencoba tujuan sekali, dan mengembalikan respons ke penelepon atau, jika pemicu menyala, maju ke tujuan berikutnya. Jika setiap tujuan gagal, penelepon menerima kesalahan terakhir.

Setelah respons streaming dimulai, gateway tidak dapat lagi mundur; penelepon menerima respons paruh dan kesalahan, dan harus mencoba lagi.

Berikut ini AWS Perintah CLI membuat aturan yang merutekan gpt-5.5 kepada bedrock-mantle dan menambahkan rantai fallback. Ia mencoba gpt-5.5 di atas bedrock-mantle pertama. Jika gagal, ia mencoba gpt-5.5 di atas openai. Hanya jika tidak ada yang dapat melayani permintaan, itu akan menurun menjadi gpt-5.4 di atas bedrock-mantle. Yang utama jatuh kembali pada 429 dan 5XX, pada kesalahan koneksi atau batas waktu byte pertama, dan pada target yang tidak dapat dirutekan, dengan batas waktu byte pertama 5 detik. Dua tujuan fallback mengambil default layanan.

aws bedrock-agentcore-control create-gateway-rule \ --gateway-identifier my-gateway-abc1234567 \ --priority 100 \ --description "Prefer gpt-5.5 on bedrock-mantle, fall back to OpenAI, then degrade to gpt-5.4" \ --conditions '[ { "matchModels": { "anyOf": [ {"value": "gpt-5.5"} ] } } ]' \ --actions '[ { "routeToTarget": { "staticRoute": { "targetName": "bedrock-mantle", "model": "gpt-5.5", "fallback": { "circuitBreaker": {"mode": "ENABLED"}, "triggerOn": { "statusCodes": ["5XX", "429"], "errors": ["CONNECTION_ERROR", "FIRST_BYTE_TIMEOUT", "UNROUTABLE"] }, "firstByteTimeoutMilliseconds": 5000, "targetFallback": [ {"targetName": "openai"}, {"targetName": "bedrock-mantle", "model": "gpt-5.4"} ] } } } } ]'
catatan

Nama target dan model dalam contoh ini bersifat ilustratif. Gunakan nama target yang dikonfigurasi pada gateway dan ID model yang dilayani target Anda. Untuk membuat target inferensi yang dirujuk aturan, lihat Target inferensi. Penyedia model mungkin menghentikan atau menghapus model dari waktu ke waktu.

Pemicu fallback

triggerOn objek mencantumkan kondisi yang menyebabkan fallback. Anda dapat mengaturnya di fallback blok (untuk primer) dan pada masing-masing targetFallback entri (untuk tujuan itu). Ini memiliki dua bidang:

Kode Status

1 hingga 10 kode status kesalahan HTTP atau pola kelas. Setiap nilai adalah kode yang tepat atau kelas dalam bentuk NXX, dibatasi pada rentang 4xx dan 5xx - misalnya, 429, 503, atau 5XX. Fallback hanya berlaku untuk respons kesalahan; 2xx dan 3xx tanggapan tidak pernah memenuhi syarat untuk fallback.

kesalahan

1 hingga 3 tingkat koneksi atau kondisi routing, dari nilai-nilai berikut:

  • CONNECTION_ERROR - Gateway tidak dapat membuat koneksi ke tujuan (koneksi ditolak, diatur ulang, atau batas waktu). Upaya itu tidak pernah mencapai penyedia.

  • FIRST_BYTE_TIMEOUT - Tujuan menerima koneksi tetapi tidak mengembalikan byte respons pertama di dalamnya firstByteTimeoutMilliseconds.

  • UNROUTABLE — Gateway tidak dapat merutekan ke target penayangan (target hilang, atau tidak mendukung jalur API permintaan). Ini adalah kondisi deterministik di sisi gerbang: ia memajukan rantai tetapi tidak memberi makan pemutus sirkuit.

Pemutus sirkuit

Pemutus sirkuit melewatkan tujuan yang saat ini gagal, jadi permintaan langsung menuju tujuan yang sehat alih-alih membayar upaya yang gagal terlebih dahulu. Ini menurunkan latensi dan biaya selama pemadaman. Pemutus aktif secara default. Untuk mematikannya, atur circuitBreaker.mode kepada DISABLED Misalnya, untuk terus menggunakan primer yang lebih murah daripada gagal cepat ke sekunder yang lebih mahal. Dengan pemutus mati, rantai masih berjalan sesuai urutan yang Anda nyatakan.

Pemutus bergerak melalui tiga keadaan secara otomatis. Tabel berikut menunjukkan bagaimana setiap negara mempengaruhi permintaan dan apa yang ditagih Anda. Setiap upaya keluar yang dilakukan gateway ditagih sebagai satu pemanggilan gateway (lihat Pengamatan dan penagihan).

Status pemecah Apa yang terjadi pada permintaan Penagihan

Tutup (sehat)

Gateway mengirimkan permintaan ke primer. Jika primer mengembalikan pemicu fallback (misalnya, a 500 respon), gateway jatuh kembali ke tujuan berikutnya dalam rantai.

Setiap upaya ditagih sebagai pemanggilan gateway, termasuk upaya utama yang gagal sebelum fallback.

Terbuka (gagal)

Gateway melewatkan yang utama dan mengirimkan permintaan langsung ke tujuan berikutnya dalam rantai, sehingga permintaan menghindari upaya yang gagal dan kembali lebih cepat.

Gateway tidak menagih utama yang dilewati. Setiap tujuan yang dicoba gateway ditagih sebagai pemanggilan gateway.

Half-open (pulih)

Gateway memungkinkan sebagian kecil permintaan masuk ke primer untuk memeriksa apakah telah pulih; sisanya melewati primer dan pergi ke tujuan berikutnya. Jika permintaan yang diizinkan berhasil, pemutus ditutup dan semua lalu lintas kembali ke primer. Jika gagal, pemutus tetap terbuka.

Permintaan yang diizinkan masuk ke utama ditagih sebagai pemanggilan gateway untuk upaya tersebut. Permintaan lain ditagih seperti dalam keadaan terbuka.

Fallback dengan rute tertimbang

Ketika yang utama adalah weightedRoute, Anda mengonfigurasi fallback untuk setiap leg: setiap entri split lalu lintas membawa opsionalnya sendiri fallback blok, dan weightedRoute itu sendiri tidak memiliki fallback tingkat rute. Kaki tanpa fallback mengembalikan kesalahan ke penelepon ketika gagal. Pemutus sirkuit adalah per tujuan dan tidak tergantung pada bobot.

Aturan validasi untuk rantai fallback

  • Setiap tujuan dalam aturan harus berbeda. Tujuan utama dan setiap tujuan fallback harus memberi nama kombinasi target dan model yang berbeda; gateway menolak aturan yang mengulanginya.

  • SEBUAH fallback blok harus mencantumkan setidaknya satu targetFallback entri.

  • SEBUAH matchModels kondisi harus mencantumkan setidaknya satu entri, dan setiap entri value tidak boleh kosong.

  • Fallback berlaku untuk target inferensi.

Pengamatan dan penagihan

Gateway mencatat keputusan fallback dan routing dalam log routing yang dijualnya. Log ini mengaitkan tujuan yang benar-benar melayani setiap permintaan dan mencatat ketika pemutus sirkuit melewatkan tujuan, sehingga Anda dapat mengonfirmasi perutean dan melihat mengapa tujuan dilewati.

penting

Setiap upaya keluar yang dilakukan gateway dihitung sebagai pemanggilan gateway dan ditagih dengan tarif gateway. Oleh karena itu, permintaan yang jatuh kembali ke beberapa tujuan dihitung sebagai satu pemanggilan gateway untuk setiap upaya, dan pemutus sirkuit mengurangi biaya ini dengan melewatkan tujuan yang sudah gagal. Biaya model dan inferensi dari setiap upaya ditagih secara terpisah oleh Amazon Bedrock atau penyedia model, bukan oleh gateway.

Dari perspektif klien yang menelepon, fallback transparan: klien mengirim satu permintaan dan menerima satu respons, dari tujuan mana pun yang dilayani. Gateway tidak menambahkan indikator yang menghadap ke penelepon dari tujuan mana yang digunakan.