PromptTokenLimit ポリシー

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

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

<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 は次のように平滑化されます。
  1000 ミリ秒（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 または 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	ユーザー プロンプトのトークンを計算できません。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

障害コード	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 ポリシー。
• レート制限: レート制限の概要
• レート制限ポリシーの比較