Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

PromptTokenLimit 政策

可擴充政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

PromptTokenLimit 政策會限制使用者提示詞中的詞元數，防止大型語言模型 (LLM) 後端受流量遽增影響。

PromptTokenLimit 政策與 SpikeArrest 政策類似，但 SpikeArrest 政策限制的是要求數量，PromptTokenLimit 政策限制的是這些要求中的詞元數量。這項政策專為 LLM 應用程式設計，其費用和效能與所處理的詞元數直接相關。

這項政策屬於可擴充政策，使用這項政策可能會產生費用或影響使用率，具體取決於您的 Apigee 授權。如要瞭解政策類型和使用影響，請參閱「政策類型」。

PromptTokenLimit 和 LLMTokenQuota 的差異

PromptTokenLimit 政策用於管理營運流量，可防止詞元用量突然暴增。相較之下，LLMTokenQuota 政策則用於對用戶端應用程式強制執行長期 (例如數小時、數天或數個月) 的用量限制，以控管成本並落實業務協議。

`PromptTokenLimit` 元素

定義 PromptTokenLimit 政策。

預設值	請參閱下方的「預設政策」分頁
必填與否	選用
類型	Complex 物件
父項元素	不適用
子元素	`<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>

預設政策

以下範例說明在 UI 中將 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>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

範例

以下範例說明 PromptTokenLimit 政策的部分使用方式：

範例 1

單一副本中的提示詞元限制。

在這個範例中，提示詞元限制發生在單一副本內，不會分散到區域內的多個訊息處理器。

<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

限制發放的權杖數量。

在這個範例中，提示詞元限制會分散在區域內的多個副本，並採用「滑動視窗」頻率限制演算法。

<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

每個要求的脈絡窗口大小詞元限制。

在這個範例中，提示詞元限制發生在單一副本內，不會分散到區域內的多個訊息處理器。這項特定設定用於限制每個要求的脈絡窗口大小權杖。

<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

使用預設值的分散式權杖限制。

在這個範例中，提示詞元限制發生在單一副本內，不會分散到區域內的多個訊息處理器。系統會使用使用者提示來源預設值：{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 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<DisplayName> 元素適用於所有政策。

預設值	不適用
是否必要？	(非必要) 如果省略 `<DisplayName>`，系統會使用政策的 `name` 屬性值。
類型	字串
上層元素	<`PolicyElement`>
子元素	無

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

語法

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

範例

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

<DisplayName> 元素沒有屬性或子項元素。

`<Identifier>`

可讓您選擇要求的分組方式，以便根據用戶端套用 PromptTokenLimit 政策。舉例來說，您可以依開發人員 ID 將要求分組，這樣每位開發人員的要求都會計入自己的 PromptTokenLimit 費率，而不是計入所有傳送至 Proxy 的要求。

如果將 <Identifier> 元素留空，系統會對傳入該 API Proxy 的所有要求強制執行一項頻率限制。

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<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 用來將傳入要求分組的變數。您可以使用任何流程變數來指出不重複的用戶端，例如驗證 API 金鑰政策提供的變數。您也可以使用 JavaScript 政策或 AssignMessage 政策設定自訂變數。	不適用	必填

`<Rate>`

指定每分鐘或每秒等時間單位內允許的詞元數，以限制詞元量遽增的情形。您可以將這個元素與 <Identifier> 搭配使用，在執行階段接受用戶端的值，順暢地調節流量。使用 <UseEffectiveCount> 元素設定政策使用的頻率限制演算法。

注意：任何 Apigee 機構或執行生產工作負載的 Apigee Hybrid 機構，都不支援使用值或 false 的 <UseEffectiveCount>。詳情請參閱「<UseEffectiveCount>」一文。

預設值	不適用
必填與否	必填
類型	整數
父項元素	`<PromptTokenLimit>`
子元素	無

語法

您可以透過下列其中一種方式指定費率：

您指定為 <Rate> 元素主體的靜態費率
可由用戶端傳遞的變數值；使用 ref 屬性識別流程變數的名稱

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

有效的費率值 (定義為變數值或在元素主體中) 必須符合下列格式：

intps (每秒權杖數量，平滑至毫秒間隔)
intpm (每分鐘詞元數，平滑至秒數間隔)

int 的值必須是非零的正整數。

範例 1

以下範例將速率設為每秒五個權杖：

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

這項政策會將速率調整為每 200 毫秒允許一個權杖 (1000/5)。

範例 2

以下範例將速率設為每分鐘 12 個權杖：

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

這項政策範例會將速率平滑化，每五秒允許一個權杖 (60/12)。

下表說明 <Rate> 的屬性：

屬性說明狀態預設

屬性	說明	狀態	預設
`ref`	識別指定費率的流程變數。這可以是任何流程變數，例如 HTTP 查詢參數、標頭或訊息內文內容，也可以是 KVM 等值。詳情請參閱「流程變數參考資料」。您也可以使用 JavaScript 政策或 AssignMessage 政策，自訂變數。如果您同時定義 `ref` 和這個元素的主體，當流程變數在要求中設定時，系統會套用 `ref` 的值，並優先採用該值。(如果要求中「未」設定 `ref` 中指定的變數，則情況相反)。例如： <Rate ref="request.header.custom_rate">1pm</Rate> 在這個範例中，如果用戶端未傳遞 `custom_rate` 標頭，所有用戶端的 API Proxy 速率都是每分鐘 1 個權杖。如果用戶端傳遞 `custom_rate` 標頭，其值為 10ps，則 Proxy 上的所有用戶端都會套用這個值，直到傳送不含 `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 Proxy 速率都是每分鐘 1 個權杖。如果用戶端傳遞 custom_rate 標頭，其值為 10ps，則 Proxy 上的所有用戶端都會套用這個值，直到傳送不含 custom_rate 標頭的要求為止。

您可以使用 <Identifier> 將要求分組，為不同類型的用戶端強制執行自訂費率。

如果您為 ref 指定值，但未在 <Rate> 元素的主體中設定速率，且用戶端未傳遞值，則 PromptTokenLimit 政策會擲回錯誤。

選用

不適用

下表說明定義流量調節行為的 Rate 屬性：

屬性	說明
`messagesPerPeriod`	指定在定義的時間範圍內允許的權杖數量。舉例來說，如果政策設定為「10ps」(每秒 10 個權杖)，則 `messagesPerPeriod` 值為 10。
`periodInMicroseconds`	定義計算 `messagesPerPeriod` 的時間範圍 (以微秒為單位)。如果是「10ps」設定，這個值會是 1,000,000，相當於一秒。
`maxBurstMessageCount`	代表新間隔開始時，可立即或在短時間內允許的權杖數量上限。

注意：這些屬性的值和計算結果可能會受到 MP 數量和是否啟用UseEffectiveCount設定的影響。舉例來說，如果您將速率設為「10ps」，並啟用 10 個 MP 和 UseEffectiveCount，則每個 MP 的有效速率為 1ps。個別 MP 的內部屬性會隨之調整。舉例來說，messagesPerPeriod 屬性可以設為 1，periodInMicroseconds 則設為 1,000,000。

`<UseEffectiveCount>`

這項元素可讓您選擇不同的 PromptTokenLimit 演算法，只要將值設為 true 或 false 即可，詳情如下：

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 政策會使用「權杖 bucket」演算法，將您指定的頻率限制劃分為較小的間隔，藉此平緩詞元尖峰。這種做法的缺點是，在短時間內傳入的多個合法權杖可能會遭到拒絕。

舉例來說，假設您輸入的速率為 30pm (每分鐘 30 個權杖)，在測試中，您可能會認為只要在 1 分鐘內傳送 30 個權杖，就能在 1 秒內傳送 30 個權杖。但政策並非以這種方式強制執行設定。如果仔細想想，在 1 秒內有 30 個權杖，在某些環境中可能算是迷你尖峰。

每分鐘費率會平滑化為秒間隔內允許的完整要求。

舉例來說，30pm 的平滑處理方式如下：
60 秒 (1 分鐘)/30pm = 2 秒間隔，或每 2 秒允許 1 個權杖。如果在 2 秒內產生第二個權杖，則會失敗。此外，一分鐘內的第 31 個權杖會失敗。
每秒速率會平滑化，轉換為以毫秒為間隔允許的完整要求數。

舉例來說，10ps 的平滑處理方式如下：
1000 毫秒 (1 秒) / 10ps = 100 毫秒間隔，或每 100 毫秒允許 1 個權杖。100 毫秒內產生的第二個權杖會失敗。此外，一秒內第 11 個權杖會失敗。

預設值	否
必填與否	選用
類型	布林值
父項元素	`<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。

預設值	否
必填與否	選用
類型	布林值
父項元素	`<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`	字串	唯讀	傳回擷取的使用者提示權杖數量。

詳情請參閱「流程變數參考資料」。

錯誤參考資料

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>`