PromptTokenLimit 政策

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

PromptTokenLimit 政策會限制使用者提示中的權杖數量，防止大型語言模型 (LLM) 後端流量暴增。

PromptTokenLimit 政策與 SpikeArrest 政策類似，但 SpikeArrest 政策會限制要求數量，而 PromptTokenLimit 政策會限制這些要求中的權杖數量。這項政策專為 LLM 應用程式量身打造，因為這類應用程式的費用和效能與處理的權杖數量直接相關。

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

PromptTokenLimit 和 LLMTokenQuota 的差異

PromptTokenLimit 政策用於管理作業流量，可避免權杖用量突然暴增。相較之下，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>
      

預設政策

以下範例顯示在 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 代理的所有要求強制執行一項速率限制。

預設值	不適用
必填與否	選用
類型	字串
父項元素	<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>

設定每分鐘或每秒間隔允許的權杖數量，指定限制權杖尖峰 (或爆量) 的速率。您可以搭配 <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 (每秒的權杖數量，平滑處理為毫秒間隔)
• 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 個權杖。如果用戶端為 Proxy 上的所有用戶端傳遞 custom_rate 標頭 (值為 10ps)，系統會將所有用戶端視為 10ps，直到傳送沒有 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>

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

舉例來說，假設您輸入的速率為 30pm (每分鐘 30 個權杖)，在測試中，您可能會認為只要在 1 分鐘內傳送，就能在 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 或 false)。
ratelimit.POLICY_NAME.resolvedUserPrompt	字串	唯讀	傳回擷取的使用者提示。
ratelimit.POLICY_NAME.userPromptSource	字串	唯讀	傳回政策中指定的使用者提示訊息範本。
ratelimit.POLICY_NAME.userPromptTokenCount	字串	唯讀	傳回擷取的使用者提示權杖數。

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

錯誤參考資料

本節說明 Apigee 在這項政策觸發錯誤時傳回的錯誤代碼和錯誤訊息，以及設定的錯誤變數。您也可能會看到 SpikeArrest 政策錯誤。 如果您要開發用來處理錯誤的錯誤規則，就必須瞭解這項資訊。如要瞭解詳情，請參閱「 政策錯誤須知」和「 處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

提示：需要協助解決錯誤嗎？按一下「修正」欄中的 ，即可查看詳細的疑難排解資訊。

故障代碼	HTTP 狀態	Apigee 錯誤	原因	修正
policies.prompttokenlimit.FailedToExtractUserPrompt	400	FALSE	無法從 API 要求中擷取使用者提示。
policies.prompttokenlimit.PromptTokenLimitViolation	429	FALSE	違反 PromptTokenLimit。
policies.prompttokenlimit.FailedToCalculateUserPromptTokens	500	TRUE	無法計算使用者提示的權杖。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

提示：需要協助解決錯誤嗎？按一下「修正」欄中的 ，即可查看詳細的疑難排解資訊。

故障代碼	HTTP 狀態	Apigee 錯誤	原因	修正
policies.prompttokenlimit.MessageWeightNotSupported	500	FALSE	PromptTokenLimit 政策不支援 MessageWeight。

錯誤變數

發生執行階段錯誤時，系統會設定這些變數。詳情請參閱「 政策錯誤須知」。

變數	地點	範例
ratelimit.policy_name.fault.name	fault_name 是錯誤名稱，如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤代碼的最後一部分。	fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed	policy_name 是使用者指定的政策名稱，該政策擲回了錯誤。	ratelimit.PTL-PromptTokenLimitPolicy.failed = true

錯誤回應範例

以下是錯誤回應範例：

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為這些文字可能會變更。

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

錯誤規則範例

以下是處理 PromptTokenLimitViolation 錯誤的錯誤規則範例：

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "PromptTokenLimitViolation") </Condition>
        </Step>
        <Condition>ratelimit.PTL-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

目前，如果超過 LLMTokenQuota 或 PromptTokenLimit 政策設定的速率限制，系統會傳回 HTTP 狀態碼 429 (要求數超量)。

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。

相關主題

• LLMTokenQuota 政策：LLMTokenQuota 政策，可限制回覆詞元配額用量。
• 頻率限制：頻率限制總覽
• 比較頻率限制政策