View a markdown version of this page

Praktik terbaik batas tarif - Batu Dasar Amazon AgentCore
Pola desainPanduan pemilihan kunci dimensiPertimbangan batas tarif tokenFAQ batas tarif tokenPertimbangan operasionalMemantauMembuat alarm dari rentang batas laju

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

Praktik terbaik batas tarif

Topik ini memberikan panduan tentang merancang, menerapkan, dan membatasi kecepatan operasi secara efektif di gateway Anda.

Pola desain

Akses berjenjang

Buat beberapa batas tarif dengan kunci dimensi yang sama ($.context.jwt.subatau$.context.jwt.tier) tetapi entri berbeda untuk setiap tingkat. Gunakan entri yang tepat untuk pengguna premium yang dikenal dan * entri sebagai tingkat default.

Pertahanan secara mendalam

Batas laju lapisan pada beberapa granularitas. Misalnya, gabungkan batas RPS per target (melindungi kapasitas backend) dengan batas RPM per penelepon (mencegah penyalahgunaan individu) dan batas token per alat (biaya kontrol).

Infrastruktur sebagai Kode dengan BatchPut

Gunakan BatchPutGatewayRateLimits untuk mengelola konfigurasi batas tarif secara deklaratif. Batch put menggunakan semantik upsert, membuatnya aman untuk dijalankan berulang kali dari CI/CD pipeline atau template infrastruktur.

Peluncuran bertahap

Mulailah dengan batas tarif yang besar dan kencangkan dari waktu ke waktu berdasarkan pola lalu lintas yang diamati. Pantau atribut rentang aws.agentcore.gateway.throttle.customer.decision OTEL dan tingkat respons 429 sebelum mengurangi batas.

Blok darurat

Gunakan rate: 0 entri untuk memblokir pemanggil, target, atau alat tertentu selama insiden. Blok mulai berlaku setelah propagasi selesai (hingga 30 detik).

Panduan pemilihan kunci dimensi

Pilih kunci dimensi yang menghasilkan jumlah bucket tarif yang dibatasi dan dapat diprediksi:

Kunci dimensi Kardinalitas Rekomendasi

targetName

Rendah (set yang diketahui)

Pilihan yang sangat baik. Gunakan untuk perlindungan per target.

toolName

Low-medium

Pilihan yang baik untuk gateway MCP dengan set alat yang dikenal.

qualifiedModelId

Rendah (set yang diketahui)

Sangat baik untuk gateway inferensi.

$.context.jwt.sub

Medium-high

Bagus untuk batas per pengguna. Kardinalitas dibatasi oleh basis pengguna Anda.

$.context.jwt.team

Rendah

Sangat baik untuk kuota per tim.

$.context.iam.principal

Sedang

Bagus untuk batas per peran dalam IAM-authenticated pengaturan.

$.context.jwt.jti

Tak terbatas

Jangan gunakan . Membuat bucket unik per token.

$.context.jwt.nonce

Tak terbatas

Jangan gunakan . Membuat bucket unik per permintaan.
Awas

Kunci dimensi tak terbatas (seperti $.context.jwt.jti atau klaim dengan cakupan permintaan) membuat bucket tarif dalam jumlah tak terbatas. Ini membuang memori, menurunkan kinerja, dan secara efektif menonaktifkan pembatasan kecepatan karena setiap permintaan mendapatkan bucket sendiri dan tidak pernah dibatasi.

Pertimbangan batas tarif token

Batas tarif token memerlukan pertimbangan khusus karena model penegakan berbasis anggaran mereka:

  • Pemanfaatan anggaran: Gateway memperkirakan token input sebelum meneruskan dan mencatat penggunaan aktual setelah respons. Short-lived semburan mungkin untuk sementara melebihi tingkat yang dikonfigurasi.

  • Opsi aliran: Untuk permintaan penyelesaian obrolan streaming (/v1/chat/completions), gateway secara otomatis menambahkan "stream_options": {"include_usage": true} ke badan permintaan saat batas tarif token aktif dan opsi belum ada. Ini memungkinkan penghitungan token yang akurat untuk penegakan TPM.

  • Jalur yang didukung: Batas tarif token hanya berlaku untuk permintaan pada jalur inferensi yang diketahui (/v1/chat/completions,/v1/messages,/v1/responses). Permintaan ke jalur lain tidak tunduk pada batas token.

  • Pass-through target: Jika proxy target Anda ke penyedia model tanpa menggunakan jalur inferensi yang diketahui, batas tarif token tidak berlaku. Pertimbangkan untuk menggunakan batas tarif permintaan atau merestrukturisasi target Anda untuk menggunakan jalur yang didukung.

FAQ batas tarif token

Bagian ini menjawab pertanyaan umum tentang bagaimana penegakan token-per-menit (TPM) bekerja dalam praktik.

Bagaimana cara kerja penegakan TPM?

Gateway menggunakan model penegakan berbasis anggaran. Saat permintaan tiba, gateway memperkirakan jumlah token input dan mencadangkan jumlah tersebut dari anggaran TPM yang dikonfigurasi. Jika perkiraan melebihi anggaran yang tersisa, permintaan ditolak dengan respons HTTP 429 sebelum mencapai model. Setelah permintaan berhasil diselesaikan, gateway mendamaikan anggaran dengan mengganti perkiraan awal dengan penggunaan token aktual (input + token keluaran) yang dilaporkan oleh penyedia model.

Bagaimana cara kerja TPM dengan prompt caching?

Gateway memperhitungkan token berdasarkan output_tokens nilai input_tokens dan yang dikembalikan penyedia model dalam respons inferensi. Gateway tidak melacak atau menyesuaikan secara independen untuk cache yang cepat. Apakah token yang di-cache disertakan input_tokens tergantung pada bagaimana penyedia model Anda melaporkan penggunaan — perilaku ini bervariasi antar penyedia. Konsultasikan dokumentasi penyedia model Anda untuk memahami bagaimana caching cepat memengaruhi jumlah token yang dilaporkan dan konsumsi TPM efektif Anda.

Jika batas TPM saya adalah 50 dan tokenizer memperkirakan 51 token input, apakah permintaan dibatasi?

Ya. Gateway mengevaluasi perkiraan tokenizer terhadap anggaran TPM yang tersisa sebelum meneruskan permintaan. Jika perkiraan melebihi anggaran yang tersedia, permintaan ditolak dengan respons HTTP 429. Tanggapan mencakup retryAfter bidang yang menunjukkan kapan anggaran yang cukup akan tersedia.

Jika permintaan yang berjalan lama menghabiskan lebih banyak token daripada yang diperkirakan semula, apakah respons dibatasi?

Tidak. Setelah gateway menerima dan meneruskan permintaan, tanggapan selalu disampaikan secara penuh. Gateway menyimpan perkiraan token pada waktu permintaan, dan permintaan lainnya terus dievaluasi terhadap anggaran yang tersisa saat permintaan sedang dalam penerbangan. Ketika respons selesai, gateway mendamaikan penggunaan aktual dengan perkiraan. Jika konsumsi aktual lebih tinggi, anggaran disesuaikan — ini dapat menyebabkan permintaan berikutnya dibatasi, tetapi respons asli tidak pernah terganggu.

Bagaimana cara kerja akuntansi token dengan respons streaming?

Gateway menggunakan potongan respons akhir sebagai sumber kebenaran untuk rekonsiliasi token. Tidak semua penyedia model melaporkan penggunaan token di setiap potongan yang dialirkan — beberapa memasukkannya hanya di bagian akhir. Gateway menunggu respons lengkap sebelum merekonsiliasi anggaran TPM. Untuk streaming Penyelesaian Obrolan OpenAI, gateway secara otomatis menambahkan "stream_options": {"include_usage": true} ke badan permintaan ketika batas tarif token aktif dan opsi ini belum ada, memastikan jumlah token yang akurat tersedia di bagian akhir.

Pertimbangan operasional

Waktu propagasi

Perubahan batas laju membutuhkan waktu hingga 30 detik untuk disebarkan. Rencanakan penundaan ini selama insiden — entri blok (rate: 0) tidak langsung.

Nilai perilaku nol

Tingkat 0 memblokir semua lalu lintas yang cocok. Gunakan ini dengan sengaja untuk pemblokiran darurat. Double-check nilai dimensi entri sebelum pengaturan rate: 0 untuk menghindari pemblokiran lalu lintas yang sah secara tidak sengaja.

Tombol dimensi yang tidak dapat diubah

Anda tidak dapat mengubah dimensionKeys batas tarif yang ada. Jika Anda membutuhkan dimensi yang berbeda, hapus batas tarif yang ada dan buat yang baru. Rencanakan struktur kunci dimensi Anda sebelum membuat batas tingkat produksi.

penting

Batas tarif menggunakan perilaku gagal buka. Jika layanan batas tarif sementara tidak tersedia, lalu lintas diizinkan lewat. Jangan gunakan batas tarif sebagai satu-satunya mekanisme keamanan Anda. Gabungkan mereka dengan otentikasi, otorisasi, aturan gateway, dan WAF untuk pertahanan secara mendalam.

Memantau

Gunakan sinyal berikut untuk memantau efektivitas batas laju:

Sinyal respons yang dibatasi:

  • Pantau tanggapan HTTP 429 dari gateway Anda.

  • Parsing limitKey bidang dalam respons yang dibatasi untuk mengidentifikasi batas laju mana yang dipicu.

  • Gunakan retryAfter nilai untuk memahami jendela penegakan.

OpenTelemetry atribut rentang:

Atribut Apa yang harus dipantau

aws.agentcore.gateway.throttle.customer.decision = throttled

Hitungan permintaan yang dibatasi. Peringatan tentang lonjakan yang tidak terduga.

aws.agentcore.gateway.throttle.customer.limit_key

Identifikasi batas tarif mana yang paling aktif. Carilah penegakan yang tidak seimbang.

aws.agentcore.gateway.throttle.customer.metric

Tentukan apakah permintaan, token, atau koneksi adalah hambatan.

aws.agentcore.gateway.throttle.customer.matched_entry

Identifikasi penelepon atau target mana yang paling sering mencapai batas.

aws.agentcore.gateway.throttle.customer.evaluated

Daftar yang diurutkan dari semua bucket yang diperiksa. Berguna untuk memahami batasan mana yang diterapkan pada permintaan tertentu.

Contoh kueri pemantauan:

Gunakan Amazon CloudWatch Logs Insights pada grup aws/spans log untuk menanyakan rentang OTEL gateway Anda. Contoh berikut membantu mengidentifikasi pola pelambatan.

Hitung permintaan yang dibatasi berdasarkan batas tarif:

filter attributes.`aws.agentcore.gateway.throttle.customer.decision` = "throttled"
| stats count(*) as throttle_count by attributes.`aws.agentcore.gateway.throttle.customer.limit_key`
| sort throttle_count desc

Identifikasi penelepon mana yang paling dibatasi:

filter attributes.`aws.agentcore.gateway.throttle.customer.decision` = "throttled"
| stats count(*) as throttle_count by attributes.`aws.agentcore.gateway.throttle.customer.matched_entry`
| sort throttle_count desc
| limit 20

Bandingkan permintaan yang diizinkan vs permintaan yang dibatasi dari waktu ke waktu:

filter ispresent(attributes.`aws.agentcore.gateway.throttle.customer.decision`)
| stats count(*) as total,
        sum(attributes.`aws.agentcore.gateway.throttle.customer.decision` = "throttled") as throttled
  by bin(5m)

Jika batas tarif tunggal memperhitungkan sebagian besar peristiwa throttle, pertimbangkan apakah tarif yang dikonfigurasi terlalu membatasi atau apakah pola lalu lintas menunjukkan penyalahgunaan.

Membuat alarm dari rentang batas laju

Anda dapat mengonversi atribut rentang OTEL batas tarif menjadi CloudWatch metrik dan alarm untuk secara proaktif memantau perilaku pelambatan. Ini membutuhkan pengaktifan observabilitas gateway (lihat Meng aktifkan observabilitas untuk sumber daya AgentCore gateway).

Langkah 1: Aktifkan rentang gateway

Pastikan gateway Anda mengaktifkan observabilitas. Rentang gateway diekspor ke CloudWatch dan dapat dilihat di Pencarian CloudWatch Transaksi dan halaman pengamatan AI generatif.

Langkah 2: Buat filter CloudWatch metrik

Buat filter metrik pada grup aws/spans log untuk mengekstrak peristiwa throttle sebagai metrik khusus. Contoh berikut membuat metrik yang menghitung permintaan yang dibatasi per batas tarif:

{
  "filterPattern": "{ $.attributes.aws\\.agentcore\\.gateway\\.throttle\\.customer\\.decision = \"throttled\" }",
  "metricTransformations": [
    {
      "metricName": "GatewayRateLimitThrottleCount",
      "metricNamespace": "AgentCore/Gateway/RateLimits",
      "metricValue": "1",
      "defaultValue": 0,
      "dimensions": {
        "LimitKey": "$.attributes.aws\\.agentcore\\.gateway\\.throttle\\.customer\\.limit_key"
      }
    }
  ]
}

Langkah 3: Buat CloudWatch alarm

Setelah filter metrik dipasang, buat alarm yang dipicu ketika kecepatan throttle melebihi ambang batas.

contoh
AWS CLI

  1. Jalankan perintah berikut:

    aws cloudwatch put-metric-alarm \
    --alarm-name "GatewayRateLimitThrottleSpike" \
    --namespace "AgentCore/Gateway/RateLimits" \
    --metric-name "GatewayRateLimitThrottleCount" \
    --statistic Sum \
    --period 300 \
    --evaluation-periods 1 \
    --threshold 100 \
    --comparison-operator GreaterThanThreshold \
    --alarm-description "Alert when rate limit throttles exceed 100 in 5 minutes" \
    --alarm-actions "arn:aws:sns:us-west-2:123456789012:my-alarm-topic"
AWS Python SDK (Boto3)

  1. import boto3

cloudwatch = boto3.client("cloudwatch", region_name="us-west-2")

cloudwatch.put_metric_alarm(
    AlarmName="GatewayRateLimitThrottleSpike",
    Namespace="AgentCore/Gateway/RateLimits",
    MetricName="GatewayRateLimitThrottleCount",
    Statistic="Sum",
    Period=300,
    EvaluationPeriods=1,
    Threshold=100,
    ComparisonOperator="GreaterThanThreshold",
    AlarmDescription="Alert when rate limit throttles exceed 100 in 5 minutes",
    AlarmActions=["arn:aws:sns:us-west-2:123456789012:my-alarm-topic"],
)

print("Alarm created successfully")

Langkah 4: Bangun dasbor

Buat CloudWatch dasbor untuk memvisualisasikan kecepatan throttle dari waktu ke waktu. Konfigurasi widget berikut menunjukkan jumlah throttle yang dikelompokkan berdasarkan batas laju:

{
  "metrics": [
    [
      "AgentCore/Gateway/RateLimits",
      "GatewayRateLimitThrottleCount",
      "LimitKey", "per-target-rps"
    ],
    [
      "AgentCore/Gateway/RateLimits",
      "GatewayRateLimitThrottleCount",
      "LimitKey", "per-caller-rpm"
    ]
  ],
  "period": 60,
  "stat": "Sum",
  "title": "Rate Limit Throttles by Limit"
}
Tip

Anda juga dapat menggunakan Throttles metrik bawaan (tersedia secara default di bawah metrik pemanggilan gateway) untuk jumlah throttle total tanpa perincian per batas. Gunakan filter metrik khusus pada atribut rentang saat Anda membutuhkan visibilitas per batas atau per penelepon.