View a markdown version of this page

限速执行 - 亚马逊基岩 AgentCore
与网关规则的交互堆叠语义条目匹配和特异性评估顺序与服务管理限制的互动响应受限传播时间执法的准确性和最终一致性Fail-open 行为使用 OpenTelemetry 跨度进行跟踪

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

限速执行

本主题介绍网关如何在运行时评估和强制执行速率限制，包括与其他网关功能的交互、受限的响应格式和可观察性。

与网关规则的交互

网关在评估网关规则之前评估速率限制。如果速率限制限制了请求，则该请求永远不会进入规则评估阶段。

堆叠语义

当多个速率限制应用于一个请求时，网关使用 AND 逻辑，请求必须通过所有速率限制才能继续。如果任何单一速率限制拒绝请求，则网关会对其进行限制。

条目匹配和特异性

当速率限制有多个条目时，网关会为解析的维度值选择最具体的匹配条目：

  • 精确值匹配优先于*条目。

  • 该*值表示 “将此比率应用于该维度的所有值”，它用作默认条目。

  • 对于多维速率限制，网关使用渐进式追踪回退：它首先尝试完全精确匹配，然后*一次用一个维度替换尾随维度，直到找到匹配项。

以下示例显示速率限制的条目与解析值为dimensionKeys: ["targetName", "toolName"]时如何匹配["my-target", "readData"]：

入口尺寸 火柴？ 为什么

{"targetName": "my-target", "toolName": "readData"}

是（先勾选）

两个维度完全匹配。最具体的。

{"targetName": "my-target", "toolName": "*"}

是（第二次勾选）

在第一个维度上精确匹配，*在第二个维度上完全匹配。

{"targetName": "", "toolName": ""}

是（上次勾选）

默认条目。最不具体。

第一个匹配的参赛者获胜。如果没有匹配的条目（也不存在*默认值），则跳过该请求的速率限制。

评估顺序

网关按以下顺序评估速率限制：

  1. 网关首先使用更多维度键来评估速率限制（更具体的限制优先）。

  2. 在相同数量的维度内，网关首先使用更严格（更低）的速率评估速率限制。

  3. 第一次拒绝时评估会短路 — 网关不评估剩余的速率限制。

与服务管理限制的互动

网关强制执行客户定义的速率限制和服务管理的限制。任何请求的有效费率是两者中的最低值：

  • 网关首先评估客户定义的速率限制。

  • 如果请求超过客户限制，则会评估服务管理限制。

  • 任一来源的拒绝都会导致节流。

响应受限

当请求受到限制时，网关会返回特定于协议的错误响应，其中包含响应正文中的retryAfter值。

HTTP 协议：

{
    "error": "Rate limit exceeded",
    "success": false,
    "limitKey": "rl-abc123/targetName=my-target",
    "metric": "requests",
    "retryAfter": 1
}

MCP 协议 (JSON-RPC): 

{
    "jsonrpc": "2.0",
    "id": "request-1",
    "error": {
        "code": -32003,
        "message": "Rate limit exceeded",
        "data": {
            "limitKey": "rl-abc123/targetName=my-target",
            "metric": "requests",
            "retryAfter": 1
        }
    }
}

OpenAI-compatible 协议: 

{
    "error": {
        "message": "Rate limit exceeded",
        "type": "rate_limit_error",
        "code": "429",
        "limitKey": "rl-abc123/qualifiedModelId=anthropic.claude-3-sonnet",
        "metric": "tokens",
        "retryAfter": 60
    }
}

Anthropic-compatible 协议: 

{
    "type": "error",
    "error": {
        "type": "rate_limit_error",
        "message": "Rate limit exceeded",
        "limitKey": "rl-abc123/qualifiedModelId=anthropic.claude-3-sonnet",
        "metric": "tokens",
        "retryAfter": 60
    }
}

该retryAfter字段表示呼叫者在重试之前应等待多少秒。直接在客户端重试逻辑中使用此值。

传播时间

速率限制更改（创建、更新、删除）将在 30 秒内传播到数据平面。传播期间：

  • 在传播完成之前，不会强制执行新的速率限制。

  • 更新后的速率限制会继续强制执行先前的配置，直到更新传播为止。

  • 删除的速率限制会继续执行，直到删除传播开来。

执法的准确性和最终一致性

速率限制的执行最终是一致的，而不是精确的。执法精度是限额开始接收流量后的近似值，并且随着流量的持续而提高。因此，您观察到的准确性取决于您的交通模式。

预计会出现以下行为：

  • 起初，寒冷极限过度承认。冷限制是指新设的或最近没有流量的限制。在较短的初始时间内，网关可能会过度允许（允许的请求数量超过配置的速率），然后再进行强制执行。一旦限制处于持续流量下，精度就会提高，观察到的油门速率就会稳定到接近配置的速率。

  • 持续的流量可以准确执行，但短暂的突发可能不是。短暂突破寒冷极限可以在不受到限制的情况下通过。强制执行与持续流量相同的发送速率，因为精度会随着限制的升高而提高。要观察或演示执法情况，请将流量持续发送到限制数分钟，而不是一次短暂的突发。例如，对于每秒 4 个请求的限制，网关可能不会在第一秒内限制第 5 个请求。如果您每秒连续发送 5 个请求，则在限制预热后，您会持续看到额外的请求受到限制。

  • 极低的费率不太准确。低于大约 1 个请求的速率（例如，每分钟请求数的较小限制）更难精确执行，而且会显示出更大的可变性。在精确的执法至关重要的情况下，倾向于更高的税率，将非常低的限额视为近似值。

  • 代币限额趋于缓慢。 Token-per-minute 仅在模型响应后限制更新（协调）跟踪的总使用量。正在运行几秒钟或几分钟的请求在完成之前，其估计费用仅占预算的比例。相对于请求限制，这延长了网关可能过度批准请求的期限。有关详细信息，请参阅代币速率限制常见问题解答。

围绕合理使用和后端保护设计您的限制。这意味着在持续的窗口内平滑突发并保护目标免受邻居的噪音侵害，而不是在超过阈值的那一刻就屏蔽确切的请求数。速率限制不是一个精确的、准确的请求门槛。速率限制也不是安全边界，如下节所述。

Fail-open 行为

网关使用失效开放语义进行速率限制评估。下表描述了速率限制系统遇到错误时的行为：

场景 决策 理由

速率限制服务超时

允许

可用性优先于强制执行。

无法从请求中解析维度密钥

跳过（允许）

速率限制不适用于此请求类型。

速率限制缓存刷新失败

使用陈旧的数据重试

在缓存恢复之前，将使用最新的已知配置。
重要

由于失效开放行为，不要仅仅依赖速率限制作为安全边界。使用速率限制进行流量管理和服务质量，并使用身份验证、授权和 WAF 规则进行安全强制执行。

使用 OpenTelemetry 跨度进行跟踪

对于评估客户速率限制的每个请求，网关都会在服务器跨度上发出 OpenTelemetry (OTEL) 跨度属性。使用这些属性进行调试和监控。

属性 说明 示例

aws.agentcore.gateway.throttle.customer.decision

此请求的执行决定。

allowed 或 throttled

aws.agentcore.gateway.throttle.customer.limit_key

拒绝请求rateLimitId的速率限制的值。只有在做出决定时才出现throttled。

per-target-rps

aws.agentcore.gateway.throttle.customer.metric

已用尽的指标类型。只有在做出决定时才出现throttled。

requests

aws.agentcore.gateway.throttle.customer.matched_entry

Comma-separated 解析了触发油门的条目的维度值。只有在做出决定时才出现throttled。

my-target,alice

aws.agentcore.gateway.throttle.customer.evaluated

为该请求检查的所有速率限制存储桶的订购列表。每个条目都显示速率限制 ID、指标和已解析的维度值。为双方都出席allowed，并throttled作出决定。

["per-target-rps:requests:my-target", "per-caller-rpm:requests:alice"]

该evaluated属性对于了解对请求应用了哪些速率限制非常有用，即使请求是允许的。列表中的每个条目都遵循格式{rateLimitId}:{metric}:{resolvedDimVal1,dimVal2,…​}。