PromptTokenLimit 政策

可擴充政策

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

查看 Apigee Edge 說明文件。

注意：這項政策適用於 Apigee 和 Apigee Hybrid 1.16.1 以上版本。

總覽

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 政策會擲回錯誤。	選用	不適用

下表說明定義流量調節行為的 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	字串	唯讀	傳回擷取的使用者提示權杖數量。

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

錯誤參考資料

本節說明 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>Assign-Message-1</Name>
        </Step>
        <Condition>(fault.name Matches "PromptTokenLimitViolation")</Condition>
    </FaultRule>
</FaultRules>

如果超過 LLMTokenQuota 或 PromptTokenLimit 政策設定的頻率限制，目前的 HTTP 狀態碼為 429 (要求數超量)。

結構定義

每種政策類型都是由 XML 結構定義 (.xsd) 定義。如需參考資料，請前往 GitHub 取得政策結構定義。

相關主題

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