このページの内容は Apigee に適用されます。Apigee ハイブリッドには適用されません。
Apigee Edge のドキュメントを表示する。
概要
LLMTokenQuota ポリシーは、AI/LLM ワークロードのトークン使用量を管理および制御するように設計されています。大規模言語モデル（LLM）のインタラクションはトークンベースであるため、費用管理、パフォーマンスの最適化、プラットフォームの安定性を確保するには、効果的な管理が不可欠です。
割り当ては、API プロキシが一定の期間（分、時間、日、週、月単位）に消費できる LLM トークン（入力または出力）の割り当て量です。LLMTokenQuota ポリシーは、API プロキシで使用されたトークンの数を集計するカウンタを維持します。この機能により、API プロバイダは一定の時間内にアプリが消費するトークン数に上限を適用できます。
このポリシーでは、<LLMTokenUsageSource> 要素と <LLMModelSource> 要素を使用して、LLM のレスポンスからトークン数を抽出し、リクエストまたはレスポンスからモデル名を抽出します。これにより、正確なリアルタイムの割り当て適用が可能になります。
このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
LLMTokenQuota の適用方法
LLMTokenQuota ポリシーの機能は次のとおりです。
-
トークン カウント（
<CountOnly>）: LLMTokenQuota ポリシーは、API プロキシを通過する LLM レスポンスによって消費されるトークンの数を追跡するカウンタを維持します。 -
上限の適用（
<EnforceOnly>）: この機能により、API プロバイダは、定義された期間にアプリケーションが消費するトークンの数に厳格な上限を設定できます。たとえば、アプリケーションを 1 分あたり 1,000 個のトークンまたは 1 か月あたり 10,000,000 個のトークンに制限できます。 - 割り当て超過: API プロキシが定義されたトークン割り当て上限に達すると、Apigee は後続のトークン消費リクエストを拒否します。指定された時間間隔の終了時に LLMTokenQuota カウンタが自動的にリセットされるまで、エラー メッセージが返されます。たとえば、割り当てが 1 か月あたり 10,000 個のトークンに設定されている場合、その上限に達したのが月のどの時点であっても、10,000 個目のトークンがカウントされた時点でトークン制限が開始されます。
LLMTokenQuota が API プロダクトと連携する仕組み
LLMTokenQuota ポリシーが API プロダクトと連携する仕組みは次のとおりです。
-
API プロキシのリクエストで
LLMTokenQuota適用ポリシーとともにVerifyAPIKeyポリシーまたはVerifyAccessTokenポリシーを適用します（プロキシまたはターゲットは関係ありません）。 -
API プロキシ（プロキシまたはターゲットは関係ありません）へのレスポンスで
LLMTokenQuotaカウント ポリシーを適用します。 - VerifyAPIKey ポリシーまたは VerifyAccessToken ポリシーは、キーまたはトークンを API プロダクト、オペレーション セット、デベロッパー、アプリと照合します。照合された LLM オペレーション セットのすべてのモデルの LLM 割り当てのフロー変数を公開します。
- 割り当て適用ポリシー内で、指定されたメッセージ テンプレートに従ってモデルを抽出します。
- 次に、モデルの LLM 割り当て変数が照合されます。一致するものが見つかった場合、参照が挿入されます。
- 参照が挿入されると、これらの値が割り当てオペレーションの実行に使用されます。
LLMTokenQuota と SSE レスポンスの連携の仕組み
LLMTokenQuota を SSE レスポンスで動作させるには、次のようにイベント フローの一部としてポリシーを追加します。
<EventFlow content-type="text/event-stream"> <Response> <Step> <Name>LLM_TOKEN_QUOTA_COUNT_POLICY_NAME</Name> </Step> </Response> </EventFlow>
イベント ストリームの処理中に、トークン数のカウントは、LLM レスポンスのトークン使用量メタデータがイベントで見つかった場合にのみ実行されます。トークン使用状況のメタデータが検出されると、メタデータが抽出され、ポリシーが実行されます。他のすべてのイベントでは、ポリシーの結果は NO-OP になります。
LLMTokenQuota ポリシーのタイプ
LLMTokenQuota ポリシーは、割り当てカウンタの開始とリセットの方法を複数サポートしています。どの方法を使用するかは、次の例に示すように、<LLMTokenQuota> 要素の type 属性で定義できます。
<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar"> ... </LLMTokenQuota>
type の有効な値は、次のとおりです。
calendar: 開始時刻を明示して割り当てを構成します。各アプリの LLMTokenQuota カウンタは、<StartTime>、<Interval>、<TimeUnit>に設定した値に基づいて更新されます。rollingwindow: 割り当て使用量を決定するために、ローリング ウィンドウを使用する割り当てを構成します。rollingwindowでは、<Interval>要素と<TimeUnit>要素を使用してウィンドウのサイズを指定します（例: 1 日）。リクエストを受け取ると、Apigee はリクエストの正確な時刻（たとえば、午後 5 時 1 分）を確認して、前日の午後 5 時 1 分からそれまでに（1 日）に消費されたトークン数をカウントし、そのウィンドウの間に割り当てを超過したかどうかを判断します。flexi: アプリから最初のリクエスト メッセージを受信したときにカウンタを開始し、<Interval>と<TimeUnit>の値に基づいてリセットする割り当てを構成します。
次の表は、各タイプの割り当てのリセットについて説明したものです。
| 時間単位 | 型 | ||
|---|---|---|---|
default（または null） |
calendar |
flexi |
|
| 分 | 次の 1 分間の開始 | <StartTime> から 1 分後 |
最初のリクエストの 1 分後 |
| 時間 | 次の 1 時間の開始 | <StartTime> から 1 時間後 |
最初のリクエストの 1 時間後 |
| 日 | 現在の日付の深夜（GMT） | <StartTime> から 24 時間後 |
最初のリクエストの 24 時間後 |
| 週 | 週の終わりの日曜日の深夜（GMT） | <StartTime> から 1 週間後 |
最初のリクエストの 1 週間後 |
| 月 | 月の最終日の深夜（GMT） | <StartTime> の 1 か月（28 日）後 |
最初のリクエストの 1 か月（28 日）後 |
type="calendar" には、<StartTime> の値を指定する必要があります。
この表には、rollingwindow タイプのカウントがリセットされるタイミングは記載されていません。これは、ローリング ウィンドウ割り当ては、1 時間や 1 日などのルックバック ウィンドウに基づいて、少し異なる仕組みで機能するためです。rollingwindow タイプの場合、カウンタはリセットされませんが、リクエストごとに再計算されます。新しいリクエストを受信すると、過去の時間枠内で割り当てを超過したかどうかがポリシーによって判断されます。
たとえば、1,000 個のトークンを許可する 2 時間のウィンドウを定義します。過去 2 時間のウィンドウで割り当てカウントが計算されるので、新しいリクエストを午後 4 時 45 分に受信した場合、午後 2 時 45 分以降に消費されたトークン数が計算されます。この 2 時間のウィンドウで割り当て上限を超えていない場合、リクエストは許可されます。
1 分後の午後 4 時 46 分に別のリクエストを受信した場合、午後 2 時 46 分以降の割り当てカウントが計算され、上限の超過がないかどうか確認されます。
割り当てカウンタについて
API プロキシフローで LLMTokenQuota ポリシーが実行されると、割り当てカウンタが増加します。カウンタが上限に達すると、そのカウンタに関連付けられた API 呼び出しはそれ以上できなくなります。API プロダクトに使用する構成によっては、LLMTokenQuota ポリシーで単一のカウンタを使用する場合もあれば、複数の独立したカウンタを使用する場合もあります。複数のカウンタを使用する状況と、その動作を理解することが重要です。
API プロダクトの割り当て設定を構成する
API プロダクトは、プロダクト レベルまたは個々のオペレーション レベル、あるいはその両方で割り当て設定を指定できます。API プロキシが API プロダクトに含まれている場合、そのプロダクトで定義されている割り当て設定（許可カウント、時間単位、間隔）を使用するように、LLMTokenQuota ポリシーを構成できます。最も簡単な方法は、useQuotaConfigInAPIProduct 要素を使用することです。あるいは、個々の変数参照で LLMTokenQuota ポリシーのこれらの設定を参照することもできます。
割り当てのカウント方法
デフォルトでは、Apigee は API プロダクトで定義されたオペレーションごとに個別の割り当てカウンタを保持しており、次のルールが適用されます。
- オペレーションに割り当てが定義されている場合、そのオペレーションの割り当て設定は、プロダクト レベルで定義された割り当て設定よりも優先されます。
- オペレーションに割り当てが定義されていない場合、プロダクト レベルの割り当て設定が適用されます。
- API プロダクトに割り当て設定が（プロダクト レベルとオペレーション レベルの両方で）含まれていない場合、LLMTokenQuota ポリシーで指定された許可数、時間単位、間隔の割り当て設定が適用されます。
いずれの場合も、Apigee は API プロダクトで定義されたオペレーションごとに個別の割り当てカウンタを保持します。オペレーションに一致する API 呼び出しを行うと、カウンタが加算されます。
API プロキシレベルのカウンタの構成
API プロキシ スコープで割り当てカウントを維持するように API プロダクトを構成できます。この場合、API プロダクト レベルで指定された割り当て構成は、独自の割り当てが指定されていないすべてのオペレーションで共有されます。この構成の効果は、この API プロダクトの API プロキシレベルでカウンタを作成することです。
この構成を行うには、/apiproducts Apigee API を使ってプロダクトを作成または更新し、quotaCounterScope属性を作成リクエストまたは更新リクエストで PROXY に設定します。PROXY 構成では、同じプロキシに関連付けられて独自の割り当て設定を持たない API プロダクトに定義されたオペレーションのいずれかに一致するリクエストは、そのプロキシの共通割り当てカウンタを共有することになります。
図 1 では、オペレーション 1 と 2 は Proxy1 に関連付けられており、オペレーション 4 と 5 は Proxy3 に関連付けられています。quotaCounterScope=PROXY が API プロダクトに設定されているため、これらの各オペレーションは API プロダクト レベルの割り当て設定を使用します。Proxy1 に関連付けられているオペレーション 1 と 2 は共有カウンタを使用し、Proxy3 に関連付けられているオペレーション 4 と 5 は別の共有カウンタを使用します。オペレーション 3 には独自の割り当て構成設定があります。このため、quotaCounterScope 属性の値に関係なく、独自のカウンタを使用します。
図 1: quotaCounterScope フラグの使用
使用中の API プロダクトがない場合の割り当てのカウント方法
API プロキシに関連付けられた API プロダクトがない場合、LLMTokenQuota ポリシーは、API プロキシ内での参照回数に関係なく、1 つのカウンタを保持します。割り当てカウンタの名前は、ポリシーの name 属性に基づいています。
たとえば、MyLLMTokenQuotaPolicy という名前の LLMTokenQuota ポリシーを作成し、トークンを 5 つに制限して、API プロキシで複数のフロー（フロー A、B、C）に配置します。複数のフローで使用されていても、維持されるカウンタは 1 つだけです。このカウンタは、ポリシーのすべてのインスタンスで更新されます。LLM レスポンスが毎回 1 トークンを使用すると仮定します。
- フロー A が実行される -> MyLLMTokenQuotaPolicy が実行され、カウンタが 1 に設定される
- フロー B が実行される -> MyLLMTokenQuotaPolicy が実行され、カウンタが 2 に設定される
- フロー A が実行される -> MyLLMTokenQuotaPolicy が実行され、カウンタが 3 に設定される
- フロー C が実行される -> MyLLMTokenQuotaPolicy が実行され、カウンタが 4 に設定される
- フロー A が実行される -> MyLLMTokenQuotaPolicy が実行され、カウンタが 5 に設定される
割り当てカウンタが上限に達したため、この 3 つのフローのいずれかに対する次のリクエストは拒否されます。
API プロキシフローの複数の場所で同じ LLMTokenQuota ポリシーを使用すると、意図せずに予想よりも早く LLMTokenQuota を使い切る場合があります。これは、アンチパターンの概要で説明されているアンチパターンです。
API プロキシで複数の LLMTokenQuota ポリシーを定義し、フローごとに異なるポリシーを使用することもできます。各 LLMTokenQuota ポリシーは、ポリシーの name 属性に基づいて独自のカウンタを維持します。
ポリシー構成で複数のカウンタを作成する
LLMTokenQuota ポリシーで <Class> 要素または <Identifier> 要素を使用すると、1 つのポリシーで複数の一意のカウンタを定義できます。これらの要素を使用すると、リクエストを行ったアプリ、リクエストを行ったアプリのデベロッパー、クライアント ID などのクライアント識別子に基づいて、1 つのポリシー内で異なるカウンタを維持できます。<Class> 要素や <Identifier> 要素の使用方法については、前述の例をご覧ください。
時間の表記
すべての LLMTokenQuota の時間は、協定世界時（UTC）タイムゾーンに設定されます。
LLMTokenQuota の時間表記は、国際標準 ISO 8601 で定義されている国際標準の日付表記に準拠しています。
日付は、年、月、日で定義され、YYYY-MM-DD の形式で記述します。たとえば、2025-02-04 は 2025 年 2 月 4 日を表します。
時刻は、hours:minutes:seconds の形式で時間、分、秒で定義されます。たとえば、23:59:59 は深夜 0 時の 1 秒前を表します。
1 つの日付に関連付けられる可能性のある 2 つの深夜を区別するために、00:00:00 と 24:00:00 という 2 つの表記を使用できます。したがって、2025-02-04
24:00:00 は 2025-02-05 00:00:00 と同じ日時になります。後者のほうがよく利用されています。
API プロダクトの構成から割り当て設定を取得する
API プロダクトの構成から割り当て上限を設定できます。この場合、制限は自動的に適用されません。代わりに、LLMTokenQuota ポリシーでプロダクトの割り当て設定を参照します。次に、LLMTokenQuota ポリシーが参照する割り当てをプロダクトに設定する利点をいくつか示します。
- LLMTokenQuota ポリシーでは、API プロダクトのすべての API プロキシで統一された設定を使用できます。
- API プロダクトの割り当て設定は実行時に変更でき、その値を参照する LLMTokenQuota ポリシーには、更新された割り当て値が自動的に設定されます。
API プロダクトの割り当て設定の使用について詳しくは、動的割り当ての例をご覧ください。
割り当て上限のある API プロダクトの構成については、API プロダクトを管理するをご覧ください。
共有割り当てカウンタの構成
単純なケースでは、LLMTokenQuota ポリシーは、最初のリクエスト処理中に API プロキシに送信されたトークンごとにカウンタを 1 回インクリメントします。受信リクエストの初期処理で割り当てが超過しているかどうかを確認しながら、レスポンス処理中にのみカウンタをインクリメントする場合もあります。
3 つの LLMTokenQuota ポリシー要素（<SharedName>、<CountOnly>、<EnforceOnly>）を一緒に使用すると、LLMTokenQuota ポリシーをカスタマイズして、受信リクエストに割り当てを適用できますが、レスポンス フローでのみカウンタを増分できます。
たとえば、LLM をターゲットとして使用する API プロキシがあり、1 時間あたり 100,000 トークンの割り当てを適用するとします。LLM レスポンスは totalTokenCount 値を提供します。これを行う手順は以下のとおりです。
<SharedName>要素を名前の値に設定し、<EnforceOnly>要素をtrueに設定して、ProxyEndpoint リクエスト フローに LLMTokenQuota ポリシーを追加します。- LLMTokenQuota ポリシーの
<LLMTokenUsageSource>要素を使用してトークン数を取得する
共有カウンタの使用方法を示す例については、サンプル セクションの共有カウンタをご覧ください。
サンプル
割り当て期間を開始または終了するポリシーコードのサンプルを紹介します。
その他の動的 LLMTokenQuota
<LLMTokenQuota name="CheckLLMTokenQuota"> <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.llmquota.interval">1</Interval> <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.llmquota.timeunit">hour</TimeUnit> <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.llmquota.limit"/> </LLMTokenQuota>
動的割り当てを使用すると、単一の LLMTokenQuota ポリシーで LLMTokenQuota ポリシーに渡される情報に基づいてさまざまな割り当て設定を適用するように構成できます。このコンテキストでの LLMTokenQuota 設定は、サービスプランとも呼ばれます。動的 LLMTokenQuota は、アプリのサービスプランを確認してから、これらの設定を適用します。
たとえば、API プロダクトを作成するときに、許可される割り当て制限、時間単位、間隔を設定できます。ただし、これらの値を API プロダクトに設定しただけでは、API プロキシで使用されません。これらの値を読み取る API プロキシに LLMTokenQuota ポリシーを追加する必要があります。詳しくは、API プロダクトを作成するをご覧ください。
上記の例では、LLMTokenQuota ポリシーを含む API プロキシは、verify-api-key という名前の VerifyAPIKey ポリシーを使用して、リクエストで渡された API キーを検証します。次に、LLMTokenQuota ポリシーは、VerifyAPIKey ポリシーのフロー変数にアクセスして、API プロダクトに設定された割り当て値を読み取ります。
別の方法としては、個々のデベロッパーまたはアプリに対してカスタム属性を設定し、それらの値を LLMTokenQuota ポリシーで読み取ることです。たとえば、デベロッパーごとに異なる割り当て値を設定するには、上限、時間単位、間隔を含むカスタム属性をデベロッパーごとに設定します。次に、LLMTokenQuota ポリシーでこれらの値を以下のように参照します。
<LLMTokenQuota name="DeveloperLLMTokenQuota"> <Identifier ref="verifyapikey.verify-api-key.client_id"/> <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> </LLMTokenQuota>
この例では、VerifyAPIKey フロー変数を使用して、デベロッパーに設定されたカスタム属性を参照しています。
LLMTokenQuota ポリシーのパラメータを設定する場合は、任意の変数を使用できます。これらの変数は次のものから取得できます。
- フロー変数
- API プロダクト、アプリまたはデベロッパーのプロパティ
- Key-Value マップ（KVM）
- ヘッダー、クエリ パラメータ、フォーム パラメータなど
各 API プロキシについて、他のすべてのプロキシの他のすべての LLMTokenQuota ポリシーと同じ変数を参照する LLMTokenQuota ポリシーを追加することも、LLMTokenQuota ポリシーでそのポリシーとプロキシに固有の変数を参照することもできます。
開始時刻
<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar"> <StartTime>2025-02-18 10:30:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </LLMTokenQuota>
type が calendar に設定された LLMTokenQuota の場合は、明示的な <StartTime> 値を定義する必要があります。時刻の値は現地時間ではなく、GMT です。calendar タイプのポリシーに <StartTime> 値を指定しない場合、Apigee によってエラーが発行されます。
各アプリの LLMTokenQuota カウンタは、<StartTime>、<Interval>、<TimeUnit> の値に基づいて更新されます。この例では、LLMTokenQuota で 2025 年 2 月 18 日午前 10 時 30 分（GMT）にカウントを開始し、5 時間ごとに更新されます。したがって、次の更新は 2025 年 2 月 18 日午後 3 時 30 分（GMT）に行われます。
アクセス カウンタ
<LLMTokenQuota name="LLMTokenQuotaPolicy"> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </LLMTokenQuota>
API プロキシは、LLMTokenQuota ポリシーが設定したフロー変数にアクセスします。API プロキシでこれらのフロー変数にアクセスすると、条件付きの処理や、割り当て上限に近いポリシーのモニタリングを行うことができます。また、現在の割り当てカウンタをアプリに返すこともできます。
ポリシーのフロー変数へのアクセスはポリシーの name 属性に基づいているため、上記の <LLMTokenQuota> というポリシーの場合、次の形式でフロー変数にアクセスします。
ratelimit.LLMTokenQuotaPolicy.allowed.count: 許可された数。ratelimit.LLMTokenQuotaPolicy.used.count: 現在のカウンタ値。ratelimit.LLMTokenQuotaPolicy.expiry.time: カウンタがリセットされる UTC 時間。
以下で説明するように、この他にもアクセスできるフロー変数が多数あります。
たとえば、次の AssignMessage ポリシーを使用すると、LLMTokenQuota フロー変数の値をレスポンス ヘッダーとして返すことができます。
<AssignMessage continueOnError="false" enabled="true" name="ReturnQuotaVars"> <AssignTo createNew="false" type="response"/> <Set> <Headers> <Header name="LLMTokenQuotaLimit">{ratelimit.LLMTokenQuotaPolicy.allowed.count}</Header> <Header name="LLMTokenQuotaUsed">{ratelimit.LLMTokenQuotaPolicy.used.count}</Header> <Header name="LLMTokenQuotaResetUTC">{ratelimit.LLMTokenQuotaPolicy.expiry.time}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
共有カウンタ
次の例は、API プロキシの共有カウンタを構成する方法を示しています。ここでは、ターゲット レスポンスが HTTP ステータス 200 の場合に、割り当てカウンタも増分されます。両方の LLMTokenQuota ポリシーで同じ <SharedName> 値が使用されるため、両方の LLMTokenQuota ポリシーが同じ割り当てカウンタを共有します。詳細については、共有割り当てカウンタの構成をご覧ください。
ProxyEndpoint 構成の例:
<ProxyEndpoint name="default">
<PreFlow name="PreFlow">
<Request>
<Step>
<Name>LLMTokenQuota-Enforce-Only</Name>
</Step>
</Request>
<Response>
<Step>
<Name>LLMTokenQuota-Count-Only</Name>
</Step>
</Response>
<Response/>
</PreFlow>
<Flows/>
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<HTTPProxyConnection>
<BasePath>/quota-shared-name</BasePath>
</HTTPProxyConnection>
<RouteRule name="noroute"/>
</ProxyEndpoint>最初の LLMTokenQuota ポリシーの例:
<LLMTokenQuota name="LLMTokenQuota-Enforce-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <EnforceOnly>true</EnforceOnly> <Allow count="15000"/> <Interval>30</Interval> <TimeUnit>minute</TimeUnit> <Distributed>true</Distributed> </LLMTokenQuota>
2 番目の LLMTokenQuota ポリシーの例:
<LLMTokenQuota name="LLMTokenQuota-Count-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <!-- Same name as the first LLMTokenQuota policy --> <CountOnly>true</CountOnly> <Allow count="15000"/> <Interval>30</Interval> <TimeUnit>minute</TimeUnit> <Distributed>true</Distributed> <LLMTokenUsageSource> {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)} </LLMTokenUsageSource> <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource> </LLMTokenQuota>
最初のリクエスト
<LLMTokenQuota name="MyLLMTokenQuota"> <Interval>1</Interval> <TimeUnit>hour</TimeUnit> <Allow count="10000"/> </LLMTokenQuota>
このサンプルコードを使用して、「1 時間あたり 10,000 トークン」という割り当てを適用します。このポリシーでは、1 時間ごとに割り当てカウンタをリセットします。1 時間が経過する前にカウンタが 10,000 トークンの割り当てに達すると、10,000 を超えるトークンを消費する API 呼び出しは拒否されます。
たとえば、カウンタが 2025-07-08 07:00:00 に開始された場合、2025-07-08 08:00:00 （開始時刻から 1 時間後）になると 0 にリセットされます。最初のリクエストが 2025-07-08 07:35:28 で受信され、2025-07-08 08:00:00 より前にトークン数が 10,000 に達した場合、その数を超えるトークンを消費するリクエストは、正時にカウントがリセットされるまで拒否されます。
カウンタのリセット時間は、<Interval> と <TimeUnit> の組み合わせで決まります。たとえば、<Interval> を 12、<TimeUnit> を時間に設定すると、カウンタは 12 時間ごとにリセットされます。<TimeUnit> には、分、時間、日、週、月を設定できます。
このポリシーは、API プロキシの複数の場所で参照できます。たとえば、プロキシの PreFlow に配置すると、リクエストを受信するたびに実行されます。また、API プロキシの複数のフローに配置することもできます。このポリシーをプロキシの複数の場所で使用すると、ポリシーのすべてのインスタンスで更新される単一のカウンタが維持されます。
また、API プロキシで複数の LLMTokenQuota ポリシーを定義することもできます。各 LLMTokenQuota ポリシーは、ポリシーの name 属性に基づいて独自のカウンタを維持します。
ID の設定
<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar"> <Identifier ref="request.header.clientId"/> <StartTime>2025-02-18 10:00:00</StartTime> <Interval>5</Interval> <TimeUnit>hour</TimeUnit> <Allow count="99"/> </LLMTokenQuota>
デフォルトでは、LLMTokenQuota ポリシーは、リクエストの送信元に関係なく、API プロキシのカウンタを 1 つ定義します。また、LLMTokenQuota ポリシーで <Identifier> 属性を使用して、<Identifier> 属性の値に基づいて個別のカウンタを維持することもできます。
たとえば、クライアント ID ごとに個別のカウンタを定義するには、<Identifier> タグを使用します。プロキシへのリクエストでは、クライアント アプリは上記の例のように clientID を含むヘッダーを渡します。
<Identifier> 属性には任意のフロー変数を指定できます。たとえば、id という名前のクエリ パラメータに一意の識別子が含まれるように指定できます。
<Identifier ref="request.queryparam.id"/>
VerifyAPIKey ポリシーを使用して API キーを検証するか、または OAuth トークンで OAuthV2 ポリシーを使用する場合、API キーまたはトークンの情報を使用して、同じ LLMTokenQuota ポリシーに対して個々のカウンタを定義できます。たとえば、次の <Identifier> 要素では、verify-api-key という名前の VerifyAPIKey ポリシーの client_id フロー変数を使用しています。
<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>
一意の各 client_id 値により、LLMTokenQuota ポリシーで独自のカウンタを定義できるようになりました。
クラス
<LLMTokenQuota name="LLMTokenQuotaPolicy">
<Interval>1</Interval>
<TimeUnit>day</TimeUnit>
<Allow>
<Class ref="request.header.developer_segment">
<Allow class="platinum" count="10000"/>
<Allow class="silver" count="1000" />
</Class>
</Allow>
</LLMTokenQuota>クラスベースの LLMTokenQuota カウントを使用すると、LLMTokenQuota 上限を動的に設定できます。この例では、割り当て上限は各リクエストで渡される developer_segment ヘッダーの値によって決まります。この変数は、platinum または silver の値にすることができます。ヘッダーに無効な値がある場合、割り当て違反エラーが返されます。
次の例は、LLMTokenQuota ポリシーのさまざまな構成を示しています。
トークンを計算する
この例では、トークンを計算する方法を示します。
<LLMTokenQuota name="LTQ-Count-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <CountOnly>true</CountOnly> <Allow count="15000"/> <Interval>30</Interval> <TimeUnit>minute</TimeUnit> <Distributed>true</Distributed> <LLMTokenUsageSource> {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)} </LLMTokenUsageSource> <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource> </LLMTokenQuota>
API プロダクト、デベロッパー、アプリを使用して割り当ての動的変数をカウントする
この例では、API プロダクト、デベロッパー、アプリを使用して割り当ての動的変数をカウントする方法を示します。
<LLMTokenQuota name="LTQ-Count-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <CountOnly>true</CountOnly> <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.interval">1</Interval> <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.timeunit">hour</TimeUnit> <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.limit"/> <Distributed>true</Distributed> <LLMTokenUsageSource> {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)} </LLMTokenUsageSource> <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource> </LLMTokenQuota>
API プロダクトなしで割り当てを適用する
この例では、API プロダクトを使用せずに割り当てを適用する方法を示します。
<LLMTokenQuota name="Quota-Enforce-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <EnforceOnly>true</EnforceOnly> <Allow count="15000"/> <Interval>30</Interval> <TimeUnit>minute</TimeUnit> <Distributed>true</Distributed> </LLMTokenQuota>
API プロダクト、デベロッパー、アプリで割り当てを適用する
この例では、API プロダクト、デベロッパー、アプリを使用して割り当てを適用する方法を示します。
<LLMTokenQuota name="Quota-Enforce-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <EnforceOnly>true</EnforceOnly> <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.interval">1</Interval> <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.timeunit">hour</TimeUnit> <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.limit"/> <Distributed>true</Distributed> </LLMTokenQuota>
SSE ストリームを使用する場合
この例では、SSE ストリームで LLMTokenQuota を使用する方法を示します。
トークンの割り当て数ポリシー:
<LLMTokenQuota name="LTQ-Count-Only" type="rollingwindow"> <SharedName>common-counter</SharedName> <CountOnly>true</CountOnly> <Allow count="15000"/> <Interval>30</Interval> <TimeUnit>minute</TimeUnit> <Distributed>true</Distributed> <LLMTokenUsageSource> {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)} </LLMTokenUsageSource> <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource> </LLMTokenQuota>
イベントフロー:
<EventFlow content-type="text/event-stream"> <Response> <Step> <Name>LTQ-Count-Only</Name> </Step> </Response> </EventFlow>
<LLMTokenQuota> 要素
以下は、<LLMTokenQuota> の属性と子要素です。一部の要素の組み合わせは相互に排他的か、必須ではありません。具体的な使用方法については、サンプルをご覧ください。
下の verifyapikey.my-verify-key-policy.apiproduct.* 変数は、リクエスト内でアプリの API キーを確認するために、my-verify-key-policy という VerifyAPIKey ポリシーを使用する際に、デフォルトで使用できます。API プロダクト構成から割り当て設定を取得するで説明されているとおり、変数の値は、キーが関連付けられている API プロダクトの割り当て設定から取得されます。
<LLMTokenQuota continueOnError="false" enabled="true" name="LTQ-TokenQuota-1" type="calendar"> <DisplayName>Quota 3</DisplayName> <LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}</LLMTokenUsageSource> <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource> <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.limit"/> <Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/> <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/> </Class> </Allow> <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.interval"> 1 </Interval> <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.timeunit"> month </TimeUnit> <StartTime>2025-7-16 12:00:00</StartTime> <Distributed>false</Distributed> <Synchronous>false</Synchronous> <AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration> <Identifier/> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <UseQuotaConfigInAPIProduct> <DefaultConfig> <Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow> <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.interval"> 1 </Interval> <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.timeunit"> month </TimeUnit> </DefaultConfig> </UseQuotaConfigInAPIProduct> <SharedName/> <EnforceOnly>true</EnforceOnly> </LLMTokenQuota>
以下の属性は、このポリシーに固有のものです。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
type |
LLMTokenQuota ポリシータイプを設定します。これにより、割り当てカウンタで割り当て使用量を確認するタイミングと方法、リセット方法が決まります。
有効な値は次のとおりです。
各タイプの詳細については、LLMTokenQuota ポリシーのタイプをご覧ください。 |
なし | 省略可 |
次の表に、すべてのポリシーの親要素に共通する属性を示します。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
name |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
| デフォルト |
なし この要素を省略した場合、ポリシーの |
|---|---|
| 要否 | 省略可 |
| タイプ | 文字列 |
<Allow>
指定した時間間隔で許可されるトークンの合計数を指定します。ポリシーのカウンタがこの上限の値に達すると、カウンタをリセットするまで後続の API 呼び出しは拒否されます。
フロー変数に基づいて <Allow> 要素に条件付けする <Class> 要素を含めることもできます。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 整数型または複合型 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 |
<Class> |
<Allow> 要素を設定するには、次の 3 つの方法があります。
<Allow count="2000"/>
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.limit"/>
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.limit"/>
count と countRef の両方を指定すると、countRef が優先されます。ランタイム時に countRef が解決されない場合は、count の値が使用されます。
また、<Class> 要素を <Allow> の子として指定すると、フロー変数に基づいてポリシーの許可数を決定できます。Apigee は、次に示すように、フロー変数の値と <Allow> 要素の class 属性を照合します。
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
次の表は、<Allow> の属性を示したものです。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
count |
割り当てのトークン数を指定します。 たとえば、 |
2000 | 省略可 |
countRef |
割り当てのトークン数を含むフロー変数を指定します。 |
なし | 省略可 |
<Class>
フロー変数の値に基づいて、<Allow> 要素の値に条件付けできます。<Class> の異なる <Allow> 子タグごとに、ポリシーによって異なるカウンタが維持されます。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 複合型 |
| 親要素 |
<Allow>
|
| 子要素 |
<Allow>（<Class> の子） |
<Class> 要素を使用するには、<Class> 要素に ref 属性を使用してフロー変数を指定します。Apigee は、フロー変数の値を使用して <Allow> 子要素のいずれかを選択し、ポリシーの許可数を決定します。Apigee は、次に示すように、フロー変数の値と <Allow> 要素の class 属性を照合します。
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
この例では、現在の割り当てカウンタは、各リクエストで渡される time_variable クエリ パラメータの値によって決まります。この変数は、peak_time または off_peak_time の値にすることができます。クエリ パラメータに無効な値が含まれている場合、ポリシーは割り当て違反エラーを返します。
次の表は、<Class> の属性を示したものです。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
ref |
割り当ての割り当てクラスを含むフロー変数を指定します。 | なし | 必須 |
<Allow>（<Class> の子）
<Class> 要素で定義された割り当てカウンタの上限を指定します。<Class> の各 <Allow> 子タグによって、ポリシーで複数のカウンタを維持します。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 複合型 |
| 親要素 |
<Class>
|
| 子要素 | なし |
次に例を示します。
<Allow> <Class ref="request.queryparam.time_variable"> <Allow class="peak_time" count="5000"/> <Allow class="off_peak_time" count="1000"/> </Class> </Allow>
この例では、LLMTokenQuota ポリシーで、peak_time と off_peak_time という名前の 2 つの割り当てカウンタを維持します。どちらを使用するかは、<Class> の例に示すように、渡されたクエリ パラメータによって異なります。
次の表は、<Allow> の属性を示したものです。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
class |
割り当てカウンタの名前を定義します。 | なし | 必須 |
count |
カウンタの割り当て制限を指定します。 | なし | 必須 |
<IgnoreUnresolvedVariables>
Apigee がポリシーの ref 属性で参照されている変数を解決できない場合に、LLMTokenQuota ポリシーの処理を停止するかどうかを指定します。
| デフォルト値 | false |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
true を設定すると、未解決の変数を無視して処理を続行できます。それ以外の場合は false を設定します。デフォルト値は false です。
<IgnoreUnresolvedVariables> が true に設定され、ref 属性で指定された変数を解決できない場合、Apigee は ref 属性を無視します。ref 属性を含む要素に <Allow count="2000"/> などの値も含まれている場合、Apigee はその値を使用します。値がない場合、Apigee は要素の値を null として扱い、デフォルト値（存在する場合）または空の文字列に置き換えます。
<IgnoreUnresolvedVariables> が false で、ref 属性で指定された変数を解決できない場合、Apigee はエラーを返します。
<Interval>
割り当てが計算される期間を指定します。
| デフォルト値 | なし |
| 必須かどうか | 必須 |
| 型 | 整数 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
整数（1、2、5、60 など）を、指定した <TimeUnit> 要素（分、時間、日、週、月）と組み合わせて指定し、Apigee で割り当ての使用量を計算する期間を決定します。
たとえば、間隔が 24 で <TimeUnit> が hour の場合、割り当ては 24 時間にわたって計算されます。
<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.interval">1</Interval>
次の表は、<Interval> の属性を示したものです。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
ref |
割り当ての間隔を含むフロー変数を指定します。 |
なし | 省略可 |
<TimeUnit>
割り当てに適用される時間の単位を指定します。
| デフォルト値 | なし |
| 必須かどうか | 必須 |
| 型 | 文字列 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
minute、hour、day、week、month、year から選択します。
たとえば、Interval が 24 で TimeUnit が hour の場合、割り当ては 24 時間にわたって計算されます。
<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.timeunit">month</TimeUnit>
次の表は、<TimeUnit> の属性を示したものです。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
ref |
割り当ての時間単位を含むフロー変数を指定します。ref は明示的な間隔の値よりも優先されます。ランタイムに ref が解決されない場合、間隔値が使用されます。 |
なし | 省略可 |
<StartTime>
type が calendar に設定されている場合に、割り当てカウンタのカウントを開始する日時を指定します。アプリからリクエストを受信しているかどうかは関係ありません。
| デフォルト値 | なし |
| 必須かどうか | 省略可（type が calendar に設定されている場合は必須） |
| 型 | ISO 8601 の日時形式の文字列。 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
次に例を示します。
<StartTime>2025-7-16 12:00:00</StartTime>
<Distributed>
Apigee がリクエストの処理に 1 つのノードを使用するか、それ以上のノードを使用するかを決定します。
| デフォルト値 | false |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
ポリシーが中央カウンタを維持し、すべてのノードで継続的にカウンタを同期するように指定するには、true に設定します。ノードはアベイラビリティ ゾーンやリージョンにわたって存在できます。
デフォルト値である false を使用する場合、各ノードの数が共有されないため、割り当てを超過する可能性があります。
<Distributed>false</Distributed>
カウンタが同期され、リクエストごとに更新されることを保証するには、<Distributed> と <Synchronous> を true に設定します。
<Distributed>true</Distributed> <Synchronous>true</Synchronous>
<Synchronous>
分散割り当てカウンタを同時に更新するかどうかを決定します。
| デフォルト値 | false |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
分散割り当てカウンタを同時に更新するには、true に設定します。つまり、API に対するリクエストで割り当てが確認されるのと同時に、カウンタの更新が行われます。割り当てを超える API 呼び出しを許可しないことが重要な場合は、true に設定します。
割り当てカウンタを非同期で更新するには、false に設定します。この場合、中央のリポジトリにある割り当てカウンタが非同期で更新されるため、一部の API 呼び出しで割り当てを超過する可能性があります。ただし、同期更新にみられるパフォーマンスの低下が起きることはありません。
非同期更新のデフォルトの間隔は 10 秒です。この非同期動作は、<AsynchronousConfiguration> 要素を使用して構成します。
<Synchronous>false</Synchronous>
<AsynchronousConfiguration>
ポリシー構成要素 <Synchronous> が存在しないか、存在しているものの、false に設定されている場合、分散割り当てカウンタの同期間隔を構成します。<Synchronous> が true に設定されている場合、Apigee によってこの要素が無視されます。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 複合型 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 |
<SyncIntervalInSeconds><SyncMessageCount> |
同期動作は、<SyncIntervalInSeconds> 子要素または <SyncMessageCount> 子要素を使用して指定できます。いずれか、または両方の要素を使用します。たとえば、
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
または
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
<SyncIntervalInSeconds>のみが存在する場合、割り当ては N 秒ごとに同期されます。ここで、N は要素で指定された値です。処理されたメッセージの数は関係ありません。<SyncMessageCount>のみが存在する場合、割り当ては M 件のメッセージごと（M は要素で指定された値）、または 10 秒ごと（どちらか早い方）に同期されます。- 両方の要素が存在する場合、割り当ては M 件のメッセージごと、または N 秒ごと（どちらか早い方）に同期されます。
<AsynchronousConfiguration>が存在しない場合、またはどちらの子要素も存在しない場合、処理されたメッセージの数に関係なく、割り当ては 10 秒ごとに同期されます。
<SyncIntervalInSeconds>
10 秒経過した後に非同期更新を行うデフォルトの動作をオーバーライドします。
| デフォルト値 | 10 秒 |
| 必須かどうか | 省略可 |
| 型 | 整数 |
| 親要素 |
<AsynchronousConfiguration>
|
| 子要素 | なし |
<AsynchronousConfiguration> <SyncIntervalInSeconds>20</SyncIntervalInSeconds> </AsynchronousConfiguration>
同期間隔は、上限で説明しているように 10 秒以上にする必要があります。
<SyncMessageCount>
割り当てカウンタを同期する前に処理するリクエスト数を指定します。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 整数 |
| 親要素 |
<AsynchronousConfiguration>
|
| 子要素 | なし |
<AsynchronousConfiguration> <SyncMessageCount>5</SyncMessageCount> </AsynchronousConfiguration>
この例の構成を使用すると、各ノードで、5 回のリクエストごとに、または 10 秒ごとに、どちらか早い方で割り当て数が同期されます。
<LLMTokenUsageSource>
LLM の回答からのトークン使用のソースを提供します。これは、単一のトークン使用量値に解決されるメッセージ テンプレートである必要があります。ポリシーがイベントフローの一部ではなく、指定されたソースからトークン数を抽出できない場合、policies.ratelimit.FailedToResolveTokenUsageCount ランタイム エラーがスローされます。
| デフォルト値 | {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)} |
| 必須かどうか | 省略可 |
| 型 | 文字列 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
次の例は、トークンの使用状況のソースを指定する方法を示しています。
<LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount', response.content, true)}</LLMTokenUsageSource><LLMModelSource>
LLM の回答または LLM リクエストからモデル名のソースを提供します。これは、単一のモデル名値を指定するメッセージ テンプレートである必要があります。
| デフォルト値 | |
| 要否 | 省略可 |
| 型 | 文字列 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
次の例は、リクエストからモデルソースを指定する方法を示しています。
<LLMModelSource>{jsonPath('$.model', request.content, true)}</LLMModelSource><Identifier>
フロー変数に基づいて一意のカウンタが作成されるようにポリシーを構成します。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 文字列 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
ID 要素を使用すると、フロー変数の値で定義された複数のバケットにトークン数を割り当てることができます。たとえば、VerifyAPIKey ポリシーの後に入力される developer.id 変数を使用して、特定のデベロッパーによって作成されたすべてのアプリのインスタンスに対して 1 つの割り当て上限を適用できます。また、client_id を使用して、特定のアプリごとに割り当て制限を適用することもできます。後者の構成は次のようになります。
<Identifier ref="client_id"/>
AssignMessage ポリシーや JavaScript ポリシーで設定するカスタム変数、または VerifyAPIKey ポリシーや VerifyJWT ポリシーで設定されるような、暗黙的に設定される変数のいずれかを参照できます。変数の詳細については、フロー変数の使用をご覧ください。Apigee によって定義されるよく知られた変数のリストについては、フロー変数のリファレンスをご覧ください。
この要素を使用しない場合、ポリシーはすべてのトークン数を特定の LLMTokenQuota ポリシーの 1 つのカウンタに割り当てます。
次の表に、<Identifier> 属性を示します。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
ref |
リクエストに使用するカウンタを特定するフロー変数を指定します。この変数は、HTTP ヘッダー、クエリ パラメータ、フォーム パラメータ、メッセージ コンテンツの要素、あるいはトークン数の割り当て方法を特定する他の値を参照できます。
|
なし | 省略可 |
<UseQuotaConfigInAPIProduct>
時間単位、間隔、許容される最大値など、API プロダクトの割り当て設定を定義します。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 複合型 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 |
<DefaultConfig> |
LLMTokenQuota ポリシーに <UseQuotaConfigInAPIProduct> 要素を追加すると、LLMTokenQuotaPolicy の <Allow>、<Interval>、<TimeUnit> の子要素は Apigee によって無視されます。
次の例に示すように、<UseQuotaConfigInAPIProduct> 要素は、デフォルト設定の単純な入れ物で、<DefaultConfig> 要素を使用して定義します。
<UseQuotaConfigInAPIProduct stepName="POLICY_NAME"> <DefaultConfig>...</DefaultConfig> </UseQuotaConfigInAPIProduct>
stepName 属性を使用して、フロー内で OAuthv2 ポリシーの VerifyAPIKey ポリシー オペレーションまたは ValidateToken ポリシー オペレーションを参照できます。
次の表に、<UseQuotaConfigInAPIProduct> の属性を示します。
| 属性 | 説明 | デフォルト | 要否 |
|---|---|---|---|
stepName |
フロー内の認証ポリシーの名前を識別します。対象は、VerifyAPIKey ポリシーまたは OAuthv2 ポリシーのいずれかです。 | なし | 必須 |
詳しくは以下をご覧ください。
<DefaultConfig>
API プロダクトの割り当てのデフォルト値が含まれます。<DefaultConfig> を定義する場合は、3 つの子要素がすべて必要です。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 複合型 |
| 親要素 |
<UseQuotaConfigInAPIProduct>
|
| 子要素 |
<Allow><Interval><TimeUnit> |
これらの値は、API プロダクトのオペレーション（UI または API プロダクト API のいずれか）と LLMTokenQuota ポリシーの両方で定義できます。ただし、このように設定した場合、API プロダクトの設定が優先され、LLMTokenQuota ポリシーの設定は無視されます。
この要素の構文は次のとおりです。
<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
<DefaultConfig>
<Allow>allow_count</Allow>
<Interval>interval</Interval>
<TimeUnit>[minute|hour|day|week|month]</TimeUnit>
</DefaultConfig>
</UseQuotaConfigInAPIProduct>次の例では、毎週 10,000 の割り当てが指定されています。
<DefaultConfig> <Allow>10000</Allow> <Interval>1</Interval> <TimeUnit>week</TimeUnit> </DefaultConfig>
詳しくは以下をご覧ください。
<SharedName>
この LLMTokenQuota ポリシーを共有と識別します。同じ <SharedName> 値を持つ API プロキシのすべての LLMTokenQuota ポリシーは、同じ基盤となる割り当てカウンタを共有します。
詳細および例については、共有割り当てカウンタの構成を参照してください。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 文字列 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
<CountOnly>
ProxyEndpoint レスポンス フローのステップにこの要素を true に設定した LLMTokenQuota ポリシーを配置し、トークン割り当て上限を超えたときにクライアントにエラーを返さずにトークン数を追跡します。この要素が存在する場合、<SharedName> 要素も存在する必要があります。<EnforceOnly> 要素は存在しない必要があります。
詳細と例については、共有割り当てカウンタの構成をご覧ください。
| デフォルト値 | false |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
<EnforceOnly>
この要素を true に設定した LLMTokenQuota ポリシーを API プロキシのリクエスト フローに配置して、割り当てカウンタを増やさずにトークン上限を適用します。この要素が存在する場合、<SharedName> も存在する必要があります。<CountOnly> 要素は存在しない必要があります。
詳細および例については、共有割り当てカウンタの構成を参照してください。
| デフォルト値 | false |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<LLMTokenQuota>
|
| 子要素 | なし |
フロー変数
LLMTokenQuota ポリシーが実行されると、次の事前定義されたフロー変数が自動的に入力されます。詳細については、フロー変数のリファレンスをご覧ください。
| 変数 | 型 | 権限 | 説明 |
|---|---|---|---|
| ratelimit.{policy_name}.allowed.count | Long | 読み取り専用 | 許容される割り当て数を返します |
| ratelimit.{policy_name}.used.count | Long | 読み取り専用 | 割り当て間隔内で使用された現在の割り当てを返します |
| ratelimit.{policy_name}.available.count | Long | 読み取り専用 | 割り当て間隔で使用可能な割り当て数を返します |
| ratelimit.{policy_name}.exceed.count | Long | 読み取り専用 | 割り当てを超過すると、1 を返します。 |
| ratelimit.{policy_name}.total.exceed.count | Long | 読み取り専用 | 割り当てを超過すると、1 を返します。 |
| ratelimit.{policy_name}.expiry.time | Long | 読み取り専用 |
UTC 時間（ミリ秒）を返します。この時間が経過すると、割り当てが期限切れになり、新しい割り当て期間が開始されます。
LLMTokenQuota ポリシーのタイプが |
| ratelimit.{policy_name}.identifier | 文字列 | 読み取り専用 | ポリシーに追加された（クライアントの）ID 参照を返します。 |
| ratelimit.{policy_name}.class | 文字列 | 読み取り専用 | クラス ID に関連するクラスを返します。 |
| ratelimit.{policy_name}.class.allowed.count | Long | 読み取り専用 | クラスに定義された割り当ての許可数を返します。 |
| ratelimit.{policy_name}.class.used.count | Long | 読み取り専用 | クラスで使用されている割り当てを返します。 |
| ratelimit.{policy_name}.class.available.count | Long | 読み取り専用 | クラスで使用可能な割り当て数を返します。 |
| ratelimit.{policy_name}.class.exceed.count | Long | 読み取り専用 | 現在の割り当て間隔でクラスの制限を超過したトークンの数を返します。 |
| ratelimit.{policy_name}.class.total.exceed.count | Long | 読み取り専用 | すべての割り当て間隔でクラスの制限を超えるトークンの合計数を返します。つまり、すべての割り当て間隔の class.exceed.count の合計になります。 |
| ratelimit.{policy_name}.failed | ブール値 | 読み取り専用 |
ポリシーが失敗したかどうかを表します（true または false）。 |
| llmtokenquota.{policy_name}.model | 文字列 | 読み取り専用 | 抽出されたモデルを返します。 |
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 原因 | 修正 |
|---|---|---|---|
policies.llmtokenquota.FailedToResolveModelName |
400 |
モデル名を解決できませんでした。 | なし |
policies.llmtokenquota.FailedToResolveTokenUsageCount |
500 |
トークン使用回数を解決できませんでした。 | なし |
policies.llmtokenquota.MessageTemplateExtractionFailed |
400 |
メッセージ テンプレートの抽出に失敗しました。 | なし |
policies.llmtokenquota.LLMTokenQuotaViolation |
429 |
LLM トークンの割り当て上限を超えました。 | なし |
policies.ratelimit.FailedToResolveQuotaIntervalReference |
500 |
<Interval> 要素が LLMTokenQuota ポリシー内で定義されていない場合に発生します。この要素は必須であり、LLM トークン割り当てに適用される間隔を指定するために使用されます。間隔は、<TimeUnit> 要素で定義された分、時、日、週、月で指定できます。 |
build |
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference |
500 |
<TimeUnit> 要素が LLMTokenQuota ポリシー内で定義されていない場合に発生します。この要素は必須であり、LLM トークン割り当てに適用される時間単位を指定するために使用されます。間隔は、分、時間、日、週、月で指定できます。 |
build |
デプロイエラー
| エラー名 | 原因 | 修正 |
|---|---|---|
policies.llmtokenquota.MessageWeightNotSupported |
「MessageWeight」要素はサポートされていないため、使用するとエラーが発生します。 | なし |
policies.llmtokenquota.InvalidConfiguration |
<CountOnly> または <EnforceOnly> のいずれか 1 つのみを true に設定する必要があります。 | なし |
InvalidQuotaInterval |
<Interval> 要素で指定された LLM トークン割り当て間隔が整数でない場合、API プロキシのデプロイは失敗します。たとえば、<Interval> 要素で指定された割り当て間隔が 0.1 の場合、API プロキシのデプロイが失敗します。 |
build |
InvalidQuotaTimeUnit |
<TimeUnit> 要素で指定された時間単位がサポートされていない場合、API プロキシのデプロイは失敗します。サポートされている時間単位は minute、hour、day、week、month です。 |
build |
InvalidQuotaType |
<LLMTokenQuota> 要素の type 属性で指定された LLM トークン割り当てのタイプが無効な場合、API プロキシのデプロイは失敗します。サポートされている割り当てのタイプは、default、calendar、flexi、rollingwindow です。 |
build |
InvalidStartTime |
<StartTime> 要素で指定された時刻の形式が無効な場合、API プロキシのデプロイは失敗します。有効な形式は yyyy-MM-dd HH:mm:ss です。これは ISO 8601 の日付と時刻の形式です。たとえば、<StartTime> 要素で指定された時間が 7-16-2017 12:00:00 の場合、API プロキシのデプロイは失敗します。
|
build |
StartTimeNotSupported |
割り当てのタイプが calendar タイプ以外の <StartTime> 要素が指定されている場合、API プロキシのデプロイは失敗します。<StartTime> 要素は、calendar 割り当てタイプでのみサポートされています。たとえば、<LLMTokenQuota> 要素の type 属性が flexi または rolling window に設定されている場合、API プロキシのデプロイが失敗します。 |
build |
InvalidSynchronizeIntervalForAsyncConfiguration |
LLMTokenQuota ポリシーの <AsynchronousConfiguration> 要素内の <SyncIntervalInSeconds> 要素に指定された値が 0 未満の場合、API プロキシのデプロイが失敗します。 |
build |
InvalidAsynchronizeConfigurationForSynchronousQuota |
LLMTokenQuota ポリシーで <AsynchronousConfiguration> 要素の値が true に設定されていて、<AsynchronousConfiguration> 要素を使用して非同期構成が定義されている場合、API プロキシのデプロイが失敗します。 |
build |
障害変数
このポリシーがエラーをトリガーした場合は、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
| 変数 | 説明 | 例 |
|---|---|---|
fault.name="fault_name" |
fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 | fault.name Matches "LLMTokenQuotaViolation" |
ratelimit.policy_name.failed |
policy_name は、障害をスローしたポリシーのユーザー指定の名前です。 | ratelimit.QT-LLMTokenQuotaPolicy.failed = true |
エラー レスポンスの例
{ "fault":{ "detail":{ "errorcode":"policies.llmtokenquota.LLMTokenQuotaViolation" }, "faultstring":"Rate limit LLM Token quota violation. Quota limit exceeded. Identifier : _default" } }
障害ルールの例
<FaultRules>
<FaultRule name="LLMTokenQuota Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "LLMTokenQuotaViolation") </Condition>
</Step>
<Condition>ratelimit.LLMTokenQuota-1.failed=true</Condition>
</FaultRule>
</FaultRules>