Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

PromptTokenLimit 政策

可扩展政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

PromptTokenLimit 政策通过限制用户提示中的 token 数量来保护大语言模型 (LLM) 后端免受流量激增的影响。

PromptTokenLimit 政策与 SpikeArrest 政策类似；不过，SpikeArrest 政策限制的是请求数量，而 PromptTokenLimit 政策限制的是这些请求中的 token 数量。此政策专门针对 LLM 应用，因为在这类应用中，成本和性能与处理的 token 数量直接相关。

此政策是一项 可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

PromptTokenLimit 与 LLMTokenQuota 的区别

PromptTokenLimit 政策用于运营流量管理，以防止 token 使用量突然激增。相比之下， LLMTokenQuota 政策用于在较长时间段（例如数小时、数天或数月）内对客户端应用强制执行消耗限制，以管理成本并执行业务协议。

`PromptTokenLimit` 元素

定义 PromptTokenLimit 政策。

默认值	请参阅下面的默认政策标签页
是否必需？	可选
类型	复杂对象
父元素	不适用
子元素	`<Identifier>` `<Rate>`（必需） `<UseEffectiveCount>` `<UserPromptSource>` `<IgnoreUnresolvedVariables>`

语法

PromptTokenLimit 元素使用以下语法：

<PromptTokenLimit continueOnError="false" enabled="true" name="POLICY_NAME">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

默认政策

以下示例展示了在界面中将 PromptTokenLimit 政策添加到您的流时的默认设置：

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

此元素具有所有政策中常见的以下属性：

属性	默认	是否必需？	说明
`name`	不适用	必需	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
`continueOnError`	false	可选	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障
`enabled`	true	可选	设置为 `true` 可实施政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
`async`	false	已弃用	此属性已弃用。

示例

以下示例展示了使用 PromptTokenLimit 政策的一些方式：

示例 1

在单个副本中限制提示 token。

在此示例中，提示 token 限制发生在单个副本中，不会分布在区域中的多个消息处理器之间。

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

示例 2

分布式 token 限制。

在此示例中，提示 token 限制分布在区域中的多个副本之间，并且采用了“滑动窗口”速率限制算法。

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

示例 3

每个请求的上下文窗口大小 token 限制。

在此示例中，提示 token 限制发生在单个副本中，不会分布在区域中的多个消息处理器之间。此特定配置用于每个请求的上下文窗口大小 token 限制。

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.messages',request.content,true)}</UserPromptSource>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

示例 4

具有默认值的分布式 token 限制。

在此示例中，提示 token 限制发生在单个副本中，不会分布在区域中的多个消息处理器之间。使用了用户提示来源默认值： {jsonPath('$.messages',request.content,true)}

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

子元素参考

本部分介绍 <PromptTokenLimit> 的子元素。

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 `<DisplayName>`，则会使用政策的 `name` 属性的值
类型	字符串
父元素	<`PolicyElement`>
子元素	无

<DisplayName> 元素使用以下语法：

语法

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

示例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素没有属性或子元素。

`<Identifier>`

让您可以选择如何对请求进行分组，以便可以根据客户端应用 PromptTokenLimit 政策。例如，您可以按开发者 ID 对请求进行分组，在这种情况下，每个开发者的请求将计入其自己的 PromptTokenLimit 速率，而不是代理的所有请求。

如果您将 <Identifier> 元素留空，系统会对发送到该 API 代理的所有请求强制执行一个速率限制。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<PromptTokenLimit>`
子元素	无

语法

<PromptTokenLimit
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="POLICY_NAME"
>
  <Identifier ref="FLOW_VARIABLE"/>
</PromptTokenLimit>

示例 1

以下示例按开发者 ID 应用 PromptTokenLimit 政策：

<PromptTokenLimit name="PTL-limitTokens-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

下表介绍 <Identifier> 的属性：

属性	说明	默认值	状态
`ref`	标识 PromptTokenLimit 对传入请求进行分组所依据的变量。您可以使用任何流变量来指示唯一客户端，例如 VerifyAPIKey 政策提供的变量。您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。	不适用	必填

`<Rate>`

通过设置每分钟或每秒允许的 token 数量来指定用于限制 token 高峰（或爆发）的速率。您可以将此元素与 <Identifier> 结合使用，以平稳地限制流量，方法是接受来自客户端的值。使用 <UseEffectiveCount> 元素设置政策使用的速率限制算法。

注意：任何 Apigee 组织或运行生产工作负载的 Apigee Hybrid 组织均不支持使用值为 <UseEffectiveCount> 或 false 的。如需了解详情，请参阅 <UseEffectiveCount>.

默认值	不适用
是否必需？	必需
类型	整数
父元素	`<PromptTokenLimit>`
子元素	无

语法

您可以通过以下某种方式指定速率：

指定为 <Rate> 元素的正文的静态速率
变量值，可由客户端传递；使用 ref 属性标识流变量的名称

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

有效的速率值（定义为变量值或在元素的正文中）必须遵循以下格式：

intps（每秒的 token 数量，平滑处理为毫秒间隔）
intpm（每分钟的 token 数量，平滑处理为秒间隔）

int 的值必须是非零正整数。

示例 1

以下示例将速率设置为每秒 5 个 token：

<PromptTokenLimit name="PTL-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

该政策将速率平滑处理为每 200 毫秒 (1000/5)。

示例 2

以下示例将速率设置为每分钟 12 个 token：

<PromptTokenLimit name="PTL-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

此示例政策将速率平滑处理为每 5 秒允许 1 个 token (60/12)。

下表介绍 <Rate> 的属性：

属性说明状态默认值

属性	说明	状态	默认值
`ref`	标识用于指定速率的流变量。这可以是任何流程变量（例如 HTTP 查询参数、标头或消息正文内容），也可以是 KVM 等值。如需了解详情，请参阅流变量参考文档。您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。如果您同时定义 `ref` 和此元素的正文，则在请求中设置流变量时，系统会应用 `ref` 的值。（如果在请求中未设置 `ref` 中标识的变量，则正好相反）。例如： <Rate ref="request.header.custom_rate">1pm</Rate> 在此示例中，如果客户端未传递 `custom_rate` 标头，则所有客户端的 API 代理的速率均为每分钟 1 个 token。如果客户端传递了 `custom_rate` 标头（其值为 10ps），则代理上的所有客户端的速率均为 10ps，直到发送不带 `custom_rate` 标头的请求为止。您可以使用 `<Identifier>` 对请求类型进行分组，以便对不同类型的客户端强制执行自定义速率。如果您为 `ref` 指定了值，但未在 `<Rate>` 元素的正文中设置速率，并且客户端未传递值，则 PromptTokenLimit 政策会抛出错误。	可选	不适用

ref

标识用于指定速率的流变量。这可以是任何流程变量（例如 HTTP 查询参数、标头或消息正文内容），也可以是 KVM 等值。如需了解详情，请参阅流变量参考文档。

您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。

如果您同时定义 ref 和此元素的正文，则在请求中设置流变量时，系统会应用 ref 的值。（如果在请求中未设置 ref 中标识的变量，则正好相反）。

例如：

<Rate ref="request.header.custom_rate">1pm</Rate>

在此示例中，如果客户端未传递 custom_rate 标头，则所有客户端的 API 代理的速率均为每分钟 1 个 token。如果客户端传递了 custom_rate 标头（其值为 10ps），则代理上的所有客户端的速率均为 10ps，直到发送不带 custom_rate 标头的请求为止。

您可以使用 <Identifier> 对请求类型进行分组，以便对不同类型的客户端强制执行自定义速率。

如果您为 ref 指定了值，但未在 <Rate> 元素的正文中设置速率，并且客户端未传递值，则 PromptTokenLimit 政策会抛出错误。

可选

不适用

下表介绍了 Rate 的属性，这些属性用于定义流量限制行为：

属性	说明
`messagesPerPeriod`	指定在定义的时间段内允许的 token 数量。例如，如果某项政策配置为“10ps”（每秒 10 个 token），则 `messagesPerPeriod` 值为 10。
`periodInMicroseconds`	定义计算 `messagesPerPeriod` 的时间段（以微秒为单位）。对于“10ps”配置，此值为 1,000,000，相当于 1 秒。
`maxBurstMessageCount`	表示在新的时间间隔开始时可以立即或在短时间内允许的 token 数上限。

注意：这些属性的值和计算结果可能会受到媒体计划数量以及是否启用 UseEffectiveCount设置的影响。例如，如果您将费率设置为“10ps”，并启用 10 个 MP 和 UseEffectiveCount，则每个 MP 的有效费率为 1ps。相应地调整各个 MP 的内部属性。例如，messagesPerPeriod 属性可以设置为 1，periodInMicroseconds 属性可以设置为 1,000,000。

`<UseEffectiveCount>`

借助该元素，您可以将值设为 true 或 false，从而在不同的 PromptTokenLimit 算法之间进行选择，如下所述：

true

如果设置为 true，则 PromptTokenLimit 会在区域中分布。这意味着请求计数在该区域内的消息处理器 (MP) 之间同步。此外，系统还将采用“滑动窗口”速率限制算法。此算法提供一致的速率限制行为，并且无法“平滑”发送到后端的传入请求数。如果在很短的时间间隔内发送突发的大量请求，只要这些请求不超过 <Rate> 元素中配置的速率限制，系统就会允许这些请求通过。例如：

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

false（默认）

注意：虽然默认值为 false，但 Apigee 组织应将此元素设置为 true。

Apigee 组织不支持速率平滑。

如果设置为 false（默认），PromptTokenLimit 政策使用 “令牌桶” 算法，通过将指定的速率限制划分为更小的时间间隔来平滑令牌高峰。这种方法的缺点是，在很短的时间间隔内传入的多个合法 token 可能会被拒绝。

例如，假设您输入的速率为 30pm（每分钟 30 个 token）。在测试中，您可能会认为只要在 1 分钟内，您就可以在 1 秒内发送 30 个 token。但政策并非以这种方式强制执行设置。仔细想想，在某些环境中，1 秒内 30 个 token 可以被视为微型高峰。

每分钟 的速率会平滑处理为以秒为间隔允许的完整请求。

例如，30pm 的平滑处理方式如下：
60 秒（1 分钟）/ 30pm = 2 秒间隔，或每 2 秒允许 1 个 token。2 秒内的第二个 token 将失败。此外，1 分钟内的第 31 个 token 将失败。将失败。
每秒的速率会平滑处理为以毫秒为间隔允许的完整请求。

例如，10ps 的平滑处理方式如下：
1000 毫秒（1 秒）/ 10ps = 100 毫秒间隔，或每 100 毫秒允许 1 个 token。100 毫秒内的第二个 token 将失败。此外，1 秒内的第 11 个 token 将失败。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<PromptTokenLimit>`
子元素	无

下表说明了 <UseEffectiveCount> 元素的属性：

属性	说明	默认值	状态
`ref`	标识包含 `<UseEffectiveCount>` 值的变量。这可以是任何流变量，例如 HTTP 查询参数、标头或消息正文内容。如需了解详情，请参阅流变量参考文档。您还可以通过 JavaScript 政策或 AssignMessage 政策使用自定义变量。	不适用	可选

`<UserPromptSource>`

提供用于检索用户提示文本的来源。使用消息模板。

消息模板应提供用户提示文本的单个值。

例如，{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<PromptTokenLimit>`
子元素	无

语法

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

示例 1

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

`<IgnoreUnresolvedVariables>`

确定在遇到无法解析的变量时处理是否停止。

设置为 true 可忽略无法解析的变量并继续处理；否则 false。默认值为 false。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<PromptTokenLimit>`
子元素	无

语法

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

示例

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>10ps</Rate>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PromptTokenLimit>

流变量

PromptTokenLimit 政策执行时，系统会填充以下流变量：

变量	类型	权限	说明
`ratelimit.POLICY_NAME.failed`	布尔值	只读	如果政策遇到内部执行失败，此变量为 `true`。请勿使用此变量检查是否超出速率限制。由于政策的 "故障开放"设计，在高负载下可能会设置为 `true`。
`ratelimit.POLICY_NAME.resolvedUserPrompt`	字符串	只读	返回提取的用户提示。
`ratelimit.POLICY_NAME.userPromptSource`	字符串	只读	返回政策中指定的用户提示的消息模板。
`ratelimit.POLICY_NAME.userPromptTokenCount`	字符串	只读	返回提取的用户提示的 token 数量。

如需了解详情，请参阅流变量参考文档。

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. You may also see SpikeArrest policy errors. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Apigee fault	Cause
`policies.prompttokenlimit.FailedToExtractUserPrompt`	`400`	FALSE	Unable to extract the user prompt from the API request.
`policies.prompttokenlimit.PromptTokenLimitViolation`	`429`	FALSE	PromptTokenLimit violation.
`policies.prompttokenlimit.FailedToCalculateUserPromptTokens`	`500`	TRUE	Tokens cannot be calculated for the user prompt.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault code	HTTP status	Apigee fault	Cause	Fix
`policies.prompttokenlimit.MessageWeightNotSupported`	500	FALSE	MessageWeight is not supported for the PromptTokenLimit policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`ratelimit.policy_name.fault.name`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "PromptTokenLimitViolation"`
`ratelimit.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`ratelimit.PTL-PromptTokenLimitPolicy.failed = true`

Example error response

Shown below is an example error response:

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.prompttokenlimit.PromptTokenLimitViolation"
      },
      "faultstring":"Prompt Token Limit Violation. Allowed rate : MessageRate{capacity=10, period=Minutes}"
   }
}

Example fault rule

Shown below is an example fault rule to handle a PromptTokenLimitViolation fault:

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>Assign-Message-1</Name>
        </Step>
        <Condition>(fault.name Matches "PromptTokenLimitViolation")</Condition>
    </FaultRule>
</FaultRules>

超出 LLMTokenQuota 或 PromptTokenLimit 政策设置的速率限制的当前 HTTP 状态代码为 429（请求过多）。

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

PromptTokenLimit 政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

PromptTokenLimit 与 LLMTokenQuota 的区别

PromptTokenLimit 元素

语法

默认政策

示例

示例 1

示例 2

示例 3

示例 4

子元素参考

<DisplayName>

语法

示例

<Identifier>

语法

示例 1

<Rate>

语法

示例 1

示例 2

<UseEffectiveCount>

true

false（默认）

<UserPromptSource>

语法

示例 1

<IgnoreUnresolvedVariables>

语法

示例

流变量

错误参考信息

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

架构

相关主题

PromptTokenLimit 政策

`PromptTokenLimit` 元素

`<DisplayName>`

`<Identifier>`

`<Rate>`

`<UseEffectiveCount>`

`<UserPromptSource>`

`<IgnoreUnresolvedVariables>`