本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

速率限制最佳實務

本主題提供在閘道上有效設計、部署和操作速率限制的指引。

設計模式

維度鍵選擇指引

選擇產生限制、可預測的速率儲存貯體數量的維度索引鍵：

字符速率限制考量事項

由於以預算為基礎的強制執行模式，字符率限制需要特殊考量：

字符速率限制常見問答集

本節回答有關token-per-minute(TPM) 強制執行如何實際運作的常見問題。

營運考量事項

監控

使用下列訊號來監控速率限制有效性：

調節回應訊號：

OpenTelemetry 跨度屬性：

監控查詢範例：

在aws/spans日誌群組上使用 Amazon CloudWatch Logs Insights 來查詢閘道的 OTEL 範圍。下列範例有助於識別限流模式。

依速率限制計算限流請求數：

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

識別哪些呼叫者受到節制：

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

比較一段時間內允許的請求與限流請求：

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)

如果單一速率限制考慮大多數調節事件，請考慮設定的速率是否太嚴格，或流量模式是否指出濫用。

從速率限制範圍建立警示

您可以將速率限制 OTEL 跨度屬性轉換為 CloudWatch 指標和警示，以主動監控限流行為。這需要啟用閘道可觀測性 （請參閱啟用 AgentCore 閘道資源的可觀測性)。

步驟 1：啟用閘道範圍

確保您的閘道已啟用可觀測性。閘道範圍會匯出至 CloudWatch，並可在 CloudWatch 交易搜尋和生成式 AI 可觀測性頁面中檢視。

步驟 2：建立 CloudWatch 指標篩選條件

在aws/spans日誌群組上建立指標篩選條件，以擷取節流事件做為自訂指標。下列範例會建立 指標，以計算每個速率限制的限流請求數：

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

步驟 3：建立 CloudWatch 警示

指標篩選條件到位後，請建立警示，在調節速率超過閾值時觸發。

步驟 4：建置儀表板

建立 CloudWatch 儀表板，將一段時間內的調節速率視覺化。下列小工具組態顯示依速率限制分組的調節計數：

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