PromptTokenLimit ポリシー

拡張可能なポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する

注: このポリシーは、Apigee と Apigee ハイブリッドバージョン 1.16.1 以降でサポートされています。

概要

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 文字を超えることはできません。 管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError	false	省略可	ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理
enabled	true	省略可	ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async	false	非推奨	この属性は非推奨となりました。

例

次の例は、PromptTokenLimit ポリシーの使用方法を示しています。

例 1

単一のレプリカ内のプロンプト トークンの制限。

この例では、プロンプト トークンの制限は単一のレプリカ内で発生し、リージョン内の複数の Message Processor に分散されません。

<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

リクエストあたりのコンテキスト ウィンドウ サイズのトークン制限。

この例では、プロンプト トークンの制限は単一のレプリカ内で発生し、リージョン内の複数の Message Processor に分散されません。この特定の構成は、リクエストあたりのコンテキスト ウィンドウ サイズのトークン制限に使用されます。

<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

デフォルト値による分散トークンの制限。

この例では、プロンプト トークンの制限は単一のレプリカ内で発生し、リージョン内の複数の Message Processor に分散されません。ユーザー プロンプト ソースのデフォルト値が使用されます。 {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 レートにカウントされます。

<Identifier> 要素を空のままにすると、その API プロキシに対するすべてのリクエストに 1 つのレート制限が適用されます。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	<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>

1 分間隔または 1 秒間隔で許可するトークン数を指定することによって、トークンの急増（バースト）を制限するレートを指定します。この要素を <Identifier> と組み合わせて使用すると、クライアントからの値を受け入れ、ランタイムにおけるトラフィックの絞り込みがスムーズになります。<UseEffectiveCount> 要素を使用して、ポリシーで使用されるレート制限アルゴリズムを設定します。

注: 値または false を指定して <UseEffectiveCount> を使用することは、すべての Apigee 組織または本番環境ワークロードを実行している Apigee ハイブリッド組織ではサポートされていません。 詳細については、<UseEffectiveCount> をご覧ください。

デフォルト値	なし
必須かどうか	必須
型	整数
親要素	<PromptTokenLimit>
子要素	なし

構文

次のいずれかの方法でレートを指定できます。

• <Rate> 要素の本体に指定する静的レート
• クライアントが渡すことが可能な変数値。ref 属性を使用してフロー変数の名前を特定する

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

有効なレート値（変数値で定義されるか、要素の本文で定義される）は、次の形式に従う必要があります。

• intps（1 秒あたりのトークン数、ミリ秒単位の間隔に平滑化）
• intpm（1 分あたりのトークン数、秒単位の間隔に平滑化）

int の値は、0 以外の正の整数にする必要があります。

例 1

次の例では、レートを 1 秒あたり 5 トークンに設定します。

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

このポリシーでは、200 ミリ秒につき 1 個のトークン（1000÷5）が許可されるように、レートが平滑化されます。

例 2

次の例では、レートを 1 分あたり 12 トークンに設定します。

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

この例のポリシーでは、5 秒ごとに 1 個のトークン（60÷12）が許可されるように、レートが平滑化されます。

次の表に、<Rate> 属性を示します。

属性	説明	要否	デフォルト
ref	レートを指定するフロー変数を識別します。これは、HTTP クエリ パラメータ、ヘッダー、メッセージ本文の内容などの任意のフロー変数、または KVM などの値にできます。詳細については、フロー変数のリファレンスをご覧ください。 また、JavaScript ポリシーまたは AssignMessage ポリシーを使用して、カスタム変数を使用することもできます。 ref とこの要素の本文の両方を定義する場合は、ref の値が適用され、フロー変数がリクエストで設定されている場合にその値が優先されます。リクエストで ref に変数が設定されていない場合は、その逆になります）。 次に例を示します。 <Rate ref="request.header.custom_rate">1pm</Rate> この例の場合、クライアントが custom_rate ヘッダーを渡さない場合、すべてのクライアントの API プロキシのレートが 1 分あたり 1 トークンになります。クライアントが custom_rate ヘッダー（値は 10ps）を渡すと、custom_rate ヘッダーのないリクエストが送信されない限り、プロキシ上のすべてのクライアントのレート制限が 1 秒あたり 10 件のリクエストになります。 <Identifier> を使用してリクエストをグループ化し、さまざまなタイプのクライアントに対してカスタムレートを適用できます。 ref の値は設定し、<Rate> 要素の本文でレートを設定せず、クライアントが値を渡さない場合、PromptTokenLimit ポリシーでエラーがスローされます。	省略可	なし

次の表に、トラフィック スロットリングの動作を定義する Rate の属性を示します。

属性	説明
messagesPerPeriod	定義された期間内に許可されるトークン数を指定します。たとえば、ポリシーが「10ps」（1 秒あたり 10 トークン）に構成されている場合、messagesPerPeriod の値は 10 になります。
periodInMicroseconds	messagesPerPeriod が計算される期間をマイクロ秒単位で定義します。「10ps」構成の場合、この値は 1,000,000（1 秒に相当）になります。
maxBurstMessageCount	新しい間隔の開始時に瞬時に、または短時間で許可できるトークンの最大数を表します。

注: これらの属性の値と計算は、MP の数と UseEffectiveCount 設定が有効になっているかどうかによって影響を受ける可能性があります。たとえば、10 個の MP でレートを「10ps」に設定し、UseEffectiveCount が有効になっている場合、各 MP の有効レートは 1ps になります。これに合わせて、個々の MP の内部属性が調整されます。たとえば、messagesPerPeriod 属性を 1 に、periodInMicroseconds を 1,000,000 に設定できます。

<UseEffectiveCount>

この要素を使用すると、以下で説明するように、値を true または false に設定することで、PromptTokenLimit アルゴリズムを選択できます。

true

true に設定すると、PromptTokenLimit がリージョンに分散されます。つまり、リクエスト数はリージョン内の Message Processor（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 ポリシーでは「トークン バケット」アルゴリズムが使用されます。このアルゴリズムは、指定したレート制限を短い間隔に分割することで、トークンの急増を緩和します。このアプローチの欠点は、短い間隔で受信された正当なトークンが拒否される可能性があることです。

たとえば、レートに 30 pm（1 分あたり 30 トークン）を入力したとします。テストでは、1 分以内の範囲であれば、30 個のトークンを 1 秒間で送信してもよいと思われるかもしれません。しかし、これはポリシーにより適用される設定とは異なります。1 秒の間に 30 個のトークンというのは、環境によっては小規模な急増と見なされることがあります。

• 1 分あたりのレートは、秒間隔で許可される完全なリクエスト数に平滑化されます。

  たとえば、30pm は次のように平滑化されます。
  60 秒（1 分）÷ 30pm = 2 秒間隔、または 2 秒ごとに 1 つのトークンが許可されます。2 秒以内の 2 つ目のトークンは失敗します。また、1 分以内の 31 個目のトークンも失敗します。

• 1 秒あたりのレートは、ミリ秒間隔で許可される完全なリクエスト数に平滑化されます。

  たとえば、10ps は次のように平滑化されます。
  1,000 ミリ秒（1 秒）÷ 10ps = 100 ミリ秒間隔、または 100 ミリ秒ごとに 1 つのトークンが許可されます。100 ミリ秒以内の 2 つ目のトークンは失敗します。また、1 秒以内の 11 個目のトークンも失敗します。

注: レートの平滑化では、トークン数は常に 1 以上の整数になります。平滑化では、部分的なトークンは計算されません。

デフォルト値	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	文字列	読み取り専用	抽出されたユーザー プロンプトのトークン数を返します。

詳細については、フロー変数のリファレンスをご覧ください。

エラー リファレンス

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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Apigee fault	Cause	Fix
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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

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 から入手できます。

関連トピック

• LLMTokenQuota ポリシー: LLMTokenQuota ポリシー。レスポンス トークンの割り当て使用量を制限します。
• レート制限: レート制限の概要
• レート制限ポリシーの比較