本頁面由 Cloud Translation API 翻譯而成。

LLMTokenQuota 政策

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

查看 Apigee Edge 說明文件。

總覽

LLMTokenQuota 政策旨在管理及控管 AI/LLM 工作負載的權杖用量。由於大型語言模型 (LLM) 互動是以權杖為基礎，因此有效管理對於控管成本、提升成效和確保平台穩定性至關重要。

配額是指 API 代理程式在一段時間內 (例如每分鐘、每小時、每天、每週或每月) 可使用的 LLM 權杖 (輸入或輸出) 分配量。LLMTokenQuota 政策會維護計數器，計算 API Proxy 耗用的權杖數量。這項功能可讓 API 供應商在一段時間內，對應用程式的權杖用量強制設下限制。

這項政策會使用 <LLMTokenUsageSource> 和 <LLMModelSource> 元素，從 LLM 的回應中擷取權杖數量，並從要求或回應中擷取模型名稱，以便精確地即時強制執行配額。

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

LLMTokenQuota 違規處置的運作方式

以下說明 LLMTokenQuota 政策的功能：

詞元計數 (<CountOnly>)： LLMTokenQuota 政策會維護計數器，追蹤通過 API 代理的 LLM 回應所使用的詞元數量。
強制執行限制 (<EnforceOnly>)： API 供應商可透過這項功能，嚴格限制應用程式在特定時間間隔內可使用的權杖數量。舉例來說，您可以將應用程式限制為每分鐘 1,000 個權杖，或每月 1,000 萬個權杖。
超出配額：當 API Proxy 達到定義的權杖配額上限時，Apigee 會拒絕後續耗用權杖的要求。在指定時間間隔結束前，LLMTokenQuota 計數器會自動重設，期間系統會傳回錯誤訊息。舉例來說，如果配額設為每月 10,000 個權杖，系統會在計算到第 10,000 個權杖時開始限制權杖，無論該月何時達到上限。

LLMTokenQuota 如何與 API 產品搭配運作

以下說明 LLMTokenQuota 政策如何搭配 API 產品運作：

在 API Proxy 的要求中，一併套用 VerifyAPIKey 或 VerifyAccessToken 政策和 LLMTokenQuota 強制執行政策 (Proxy 或 Target 皆可)。
在回應 API Proxy 時套用 LLMTokenQuota 計數政策 (Proxy 或目標皆可)。
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：根據明確的開始時間設定配額。系統會根據您設定的 <StartTime>、<Interval> 和 <TimeUnit> 值，重新整理每個應用程式的 LLMTokenQuota 計數器。
rollingwindow：設定配額，使用滾動視窗判斷配額用量。使用 rollingwindow，透過 <Interval> 和 <TimeUnit> 元素決定時間範圍大小，例如 1 天。收到要求時，Apigee 會查看要求的確切時間 (例如下午 5:01)，計算從前一天下午 5:01 到收到要求期間 (1 天) 消耗的權杖數量，並判斷該時間範圍內是否超出配額。
flexi：設定配額，讓計數器在收到應用程式的第一個要求訊息時開始計數，並根據 <Interval> 和 <TimeUnit> 值重設。

下表說明各類配額的重設時間：

時間單位	類型
時間單位	`default` (或空值)	`calendar`	`flexi`
分鐘	下一分鐘的開頭	`<StartTime>` 過後 1 分鐘	第一次要求後一分鐘
小時	下一個小時的整點	`<StartTime>`後一小時	發出第一項要求後一小時
天	當天格林威治標準時間午夜	`<StartTime>`後 24 小時	首次要求後 24 小時
週	每週結束時的週日格林威治標準時間午夜	`<StartTime>`過後一週	首次要求後一週
個月	當月最後一天的格林威治標準時間午夜	`<StartTime>`過後一個月 (28 天)	首次要求後一個月 (28 天)

您必須為 type="calendar" 指定 <StartTime> 的值。

下表未說明 rollingwindow 類型的計數何時會重設。這是因為滾動式時間範圍配額的運作方式略有不同，會根據回溯時間範圍 (例如一小時或一天) 計算。如果是 rollingwindow 類型，計數器不會重設，但每次請求都會重新計算。收到新要求時，政策會判斷過去一段時間是否已超出配額。

舉例來說，您可以定義兩小時的時段，允許 1,000 個權杖。下午 4:45 收到新要求。政策會計算過去兩小時的配額數，也就是自下午 2:45 起消耗的權杖數。如果兩小時內未超過配額上限，系統就會允許要求。

一分鐘後，也就是下午 4:46，系統收到另一項要求。現在政策會計算下午 2:46 以來的配額計數，判斷是否超過上限。

瞭解配額計數器

在 API Proxy 流程中執行 LLMTokenQuota 政策時，配額計數器會遞增。當計數器達到上限時，系統會禁止與該計數器相關聯的 API 呼叫。視您為 API 產品使用的設定而定，LLMTokenQuota 政策可能會採用單一計數器或多個獨立計數器。請務必瞭解使用多個計數器的情境，以及這些計數器的行為。

設定 API 產品的配額設定

API 產品可以在產品層級或個別作業層級指定配額設定，也可以同時在兩個層級指定。如果 API Proxy 包含在 API 產品中，您可以設定 LLMTokenQuota 政策，使用該產品中定義的配額設定 (允許數量、時間單位和間隔)。最簡單的方法是透過 useQuotaConfigInAPIProduct 元素。或者，您也可以透過個別變數參照，在 LLMTokenQuota 政策中參照這些設定。

配額的計算方式

根據預設，Apigee 會為 API 產品中定義的每個作業維護個別配額計數器，並遵守下列規則：

如果作業已定義配額，作業的配額設定會優先於產品層級定義的配額設定。
如果作業未定義配額，系統會套用產品層級的配額設定。
如果 API 產品未包含任何配額設定 (產品或作業層級皆無)，系統會套用 LLMTokenQuota 政策中指定的允許計數、時間單位和間隔配額設定。

在所有情況下，Apigee 都會為 API 產品中定義的每項作業，維護個別的配額計數器。只要 API 呼叫符合作業，系統就會增加計數器。

設定 API Proxy 層級的計數器

您可以設定 API 產品，在 API Proxy 範圍內維持配額計數。在這種情況下，API 產品層級指定的配額設定會套用至所有未指定配額的作業。這項設定的效果是在這個 API 產品的 API Proxy 層級建立計數器。

如要進行這項設定，您必須使用 /apiproducts Apigee API 建立或更新產品，並在建立或更新要求中，將 quotaCounterScope 屬性設為 PROXY。透過 PROXY 設定，凡是與相同 Proxy 相關聯，且沒有專屬配額設定的 API 產品，只要要求符合為該產品定義的任何作業，就會共用該 Proxy 的配額計數器。

在圖 1 中，作業 1 和 2 與 Proxy1 相關聯，作業 4 和 5 則與 Proxy3 相關聯。由於 API 產品中已設定 quotaCounterScope=PROXY，因此這些作業都會使用 API 產品層級的配額設定。與 Proxy1 相關聯的作業 1 和 2 使用共用計數器，與 Proxy3 相關聯的作業 4 和 5 則使用個別的共用計數器。作業 3 有自己的配額設定，因此無論 quotaCounterScope 屬性的值為何，都會使用自己的計數器。

圖 1：使用 quotaCounterScope 標記

如果未使用任何 API 產品，配額會如何計算？

如果 API Proxy 沒有相關聯的 API 產品，無論您在 API Proxy 中參照 LLMTokenQuota 政策的次數為何，該政策都會維持單一計數器。配額計數器名稱是以政策的 name 屬性為準。

舉例來說，您建立名為 MyLLMTokenQuotaPolicy 的 LLMTokenQuota 政策，並將權杖限制設為 5 個，然後將這項政策放在 API Proxy 的多個流程 (流程 A、B 和 C) 中。即使在多個流程中使用，系統仍會維護單一計數器，並由所有政策執行個體更新。假設 LLM 回覆每次都使用 1 個權杖：

執行流程 A -> 執行 MyLLMTokenQuotaPolicy，計數器 = 1
執行流程 B -> 執行 MyLLMTokenQuotaPolicy，計數器 = 2
執行流程 A -> 執行 MyLLMTokenQuotaPolicy，計數器 = 3
執行流程 C -> 執行 MyLLMTokenQuotaPolicy，計數器 = 4
執行流程 A -> 執行 MyLLMTokenQuotaPolicy，計數器 = 5

由於配額計數器已達上限，因此系統會拒絕下一個對任一流程提出的要求。

在 API Proxy 流程的多個位置使用相同的 LLMTokenQuota 政策，可能會導致 LLMTokenQuota 意外快速用盡，這是「反模式簡介」中說明的反模式。

或者，您也可以在 API Proxy 中定義多項 LLMTokenQuota 政策，並在每個流程中使用不同的政策。每項 LLMTokenQuota 政策都會根據政策的 name 屬性，維護自己的計數器。

透過政策設定建立多個計數器

您可以在 LLMTokenQuota 政策中使用 <Class> 或 <Identifier> 元素，在單一政策中定義多個不重複的計數器。使用這些元素後，單一政策就能根據發出要求的應用程式、發出要求的應用程式開發人員、用戶端 ID 或其他用戶端 ID 等，維護不同的計數器。如要進一步瞭解如何使用 <Class> 或 <Identifier> 元素，請參閱上方的範例。

時間標記

所有 LLMTokenQuota 時間都設為世界標準時間 (UTC) 時區。

LLMTokenQuota 時間標記遵循國際標準日期標記，如國際標準 ISO 8601 所定義。

日期定義為年、月和日，格式如下：YYYY-MM-DD。例如，2025-02-04 代表 2025 年 2 月 4 日。

一天中的時間定義為小時、分鐘和秒數，格式如下： hours:minutes:seconds。舉例來說，23:59:59 代表午夜前一秒。

請注意，有兩種標記方式 (00:00:00 和 24:00:00) 可用來區分與同一日期相關聯的兩個午夜。因此 2025-02-04 24:00:00 與 2025-02-05 00:00:00 的日期和時間相同。後者通常是偏好的標記方式。

從 API 產品設定取得配額設定

您可以在 API 產品設定中設定配額上限。這些限制不會自動強制執行配額。您可以改為在 LLMTokenQuota 政策中參照產品配額設定。以下是針對 LLMTokenQuota 政策設定產品配額的優點：

LLMTokenQuota 政策可以在 API 產品的所有 API Proxy 中使用統一設定。
您可以對 API 產品的配額設定進行執行階段變更，而參照該值的 LLMTokenQuota 政策會自動更新配額值。

如要進一步瞭解如何使用 API 產品的配額設定，請參閱動態配額範例。

如要瞭解如何設定配額限制的 API 產品，請參閱「管理 API 產品」。

設定共用配額計數器

在簡單的情況下，LLMTokenQuota 政策會在初始要求處理期間，針對傳送至 API 代理的每個權杖，將計數器遞增一次。在某些情況下，您可能想在初始處理傳入要求時檢查是否超出配額，但只在處理回應時遞增計數器。

三個 LLMTokenQuota 政策元素 (<SharedName>、<CountOnly> 和 <EnforceOnly>) 搭配使用時，可讓您自訂 LLMTokenQuota 政策，對傳入要求強制執行配額，但只會在回應流程中遞增計數器。

舉例來說，假設您有一個以 LLM 做為目標的 API Proxy，並希望每小時強制執行 100,000 個權杖的配額。LLM 回覆會提供 totalTokenCount 值。如要達成這個目標，請按照下列步驟操作：

將 LLMTokenQuota 政策附加至 ProxyEndpoint 要求流程，並將 <SharedName> 元素設為名稱值，以及將 <EnforceOnly> 元素設為 true。
在 LLMTokenQuota 政策中使用 <LLMTokenUsageSource> 元素，擷取權杖數量

如需共用計數器的使用範例，請參閱「範例」一節中的「共用計數器」。

範例

這些政策程式碼範例說明如何透過下列方式開始和結束配額週期：

開始時間

<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar">
  <StartTime>2025-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

如果 LLMTokenQuota 的 type 設為 calendar，您必須定義明確的 <StartTime> 值。時間值為 GMT 時間，而非當地時間。如果未提供 <StartTime> 值給 calendar 類型的政策，Apigee 會發出錯誤。

系統會根據 <StartTime>、<Interval> 和 <TimeUnit> 值，重新整理每個應用程式的 LLMTokenQuota 計數器。以這個範例來說，LLMTokenQuota 會在 2025 年 2 月 18 日格林威治標準時間上午 10:30 開始計算，並每 5 小時重新整理一次。因此，下次重新整理時間為 2025 年 2 月 18 日下午 3:30 (格林威治標準時間)。

存取計數器

<LLMTokenQuota name="LLMTokenQuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

API Proxy 可存取 LLMTokenQuota 政策設定的流程變數。您可以在 API Proxy 中存取這些流程變數，執行條件式處理、監控政策是否即將達到配額限制、將目前的配額計數器傳回應用程式，或是基於其他原因。

由於存取政策的流程變數是根據政策的 name 屬性，因此對於上述名為 <LLMTokenQuota> 的政策，您會以以下形式存取其流程變數：

ratelimit.LLMTokenQuotaPolicy.allowed.count：允許的金額。
ratelimit.LLMTokenQuotaPolicy.used.count：目前的計數器值。
ratelimit.LLMTokenQuotaPolicy.expiry.time：計數器重設時的世界協調時間。

如要存取其他流程變數，請參閱下文。

舉例來說，您可以使用下列 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 Proxy 設定共用計數器，其中配額計數器也會在目標回應為 HTTP 狀態 200 時遞增。由於兩個 LLMTokenQuota 政策都使用相同的 <SharedName> 值，因此這兩個政策會共用同一個配額計數器。詳情請參閱「設定共用配額計數器」。

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>

第二個 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>

使用這個範例程式碼，強制每小時配額為 10,000 個權杖。這項政策會在每個整點重設配額計數器。如果計數器在一小時結束前達到 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 (以小時為單位)，則計數器每 12 小時就會重設一次。<TimeUnit>您可以將 <TimeUnit> 設為分鐘、小時、天、週或月。

您可以在 API Proxy 的多個位置參照這項政策。舉例來說，您可以將其放在 Proxy PreFlow 中，以便在每個要求上執行。或者，您也可以將其放在 API Proxy 中的多個流程。如果您在 Proxy 中的多個位置使用這項政策，系統會維護單一計數器，並由政策的所有執行個體更新。

或者，您也可以在 API Proxy 中定義多個 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 Proxy 定義單一計數器。或者，您也可以搭配使用 <Identifier> 屬性和 LLMTokenQuota 政策，根據 <Identifier> 屬性的值維護個別計數器。

舉例來說，您可以使用 <Identifier> 標記，為每個用戶端 ID 定義個別計數器。在對 Proxy 的要求中，用戶端應用程式會傳遞包含 clientID 的標頭，如上例所示。

您可以為 <Identifier> 屬性指定任何流程變數。舉例來說，您可以指定名為 id 的查詢參數包含專屬 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> 的屬性和子項元素。請注意，部分元素組合互斥或非必要。如需特定用途的範例，請參閱相關說明。

使用名為 my-verify-key-policy 的 VerifyAPIKey 政策檢查要求中的應用程式 API 金鑰時，預設會提供下列 verifyapikey.my-verify-key-policy.apiproduct.* 變數。變數值來自與金鑰相關聯的 API 產品配額設定，如「從 API 產品設定取得配額設定」一文所述。

注意：<LLMTokenQuota> 與標準 <Quota> 政策不同，因為前者是依據權杖使用情形和模型識別來源，而非 <MessageWeight> 元素。此外，必須指定 <CountOnly> 或 <EnforceOnly> 元素，並設為 true。您無法在同一項政策中同時指定這兩個元素。

<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 政策類型，決定配額計數器檢查配額用量的時間和方式，以及重設方式。如果未設定 `type`，計數器會從分鐘/小時/天/週/月的第一個時間點開始計數。有效值包括： `calendar` `rollingwindow` `flexi` 如需各類型的完整說明，請參閱「LLMTokenQuota 政策類型」。	不適用	選用

type

設定 LLMTokenQuota 政策類型，決定配額計數器檢查配額用量的時間和方式，以及重設方式。

如果未設定 type，計數器會從分鐘/小時/天/週/月的第一個時間點開始計數。

有效值包括：

calendar
rollingwindow
flexi

如需各類型的完整說明，請參閱「LLMTokenQuota 政策類型」。

不適用

選用

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
`name`	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
`continueOnError`	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
存在必要性	選用
類型	字串

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。

存在必要性選用

類型字串

`<Allow>`

指定指定時間間隔內允許的權杖總數。如果政策的計數器達到這個限制值，後續的 API 呼叫都會遭到拒絕，直到計數器重設為止。

也可以包含 <Class> 元素，根據流程變數設定 <Allow> 元素的條件。

預設值	不適用
必填與否	選用
類型	整數或複數類型
父項元素	`<LLMTokenQuota>`
子元素	`<Class>`

以下三種方式可設定 <Allow> 元素：

<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`	用來指定配額的權杖數量。舉例來說，如果 `count` 屬性值為 100、`Interval` 為 1，且 `TimeUnit` 為「month」，則表示每月配額為 100 個權杖。	2000	選用
`countRef`	用於指定含有配額權杖計數的流程變數。 `countRef` 的優先順序高於 `count` 屬性。	無	選用

count

用來指定配額的權杖數量。

舉例來說，如果 count 屬性值為 100、Interval 為 1，且 TimeUnit 為「month」，則表示每月配額為 100 個權杖。

2000

選用

countRef

用於指定含有配額權杖計數的流程變數。 countRef 的優先順序高於 count 屬性。

無

選用

`<Class>`

根據流程變數的值，有條件地設定 <Allow> 元素的值。對於 <Class> 的每個不同 <Allow> 子項標記，政策會維持不同的計數器。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<Allow>`
子元素	`<Allow>` (`<Class>` 的子項)

如要使用 <Class> 元素，請使用 ref 屬性，為 <Class> 元素指定流程變數。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。如果查詢參數含有無效值，政策會傳回配額違規錯誤。

注意：您無法在同一個 LLMTokenQuota 政策中同時使用 <Class> 和 <Identifier> 元素。

下表列出 <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 的配額計數器。使用哪個參數取決於傳遞的查詢參數，如 <Class> 範例所示。

下表列出 <Allow> 的屬性：

屬性	說明	預設	狀態
`class`	定義配額計數器的名稱。	無	必填
`count`	指定計數器的配額限制。	無	必填

<IgnoreUnresolvedVariables>

決定 Apigee 無法解析政策中 ref 屬性參照的變數時，是否停止處理 LLMTokenQuota 政策。

預設值	false
必填與否	選用
類型	布林值
父項元素	`<LLMTokenQuota>`
子元素	無

設為 true 可忽略未解析的變數並繼續處理；否則設為 false。預設值為 false。

如果 <IgnoreUnresolvedVariables> 設為 true，且無法解析 ref 屬性中指定的變數，Apigee 就會忽略 ref 屬性。如果包含 ref 屬性的元素也包含值 (例如 <Allow count="2000"/>)，Apigee 就會使用該值。如果沒有值，Apigee 會將元素的值視為空值，並代入預設值 (如有) 或空白字串。

如果 <IgnoreUnresolvedVariables> 為 false，且無法解析 ref 屬性中指定的變數，Apigee 會傳回錯誤。

`<Interval>`

指定計算配額的時間間隔。

預設值	不適用
必填與否	必填
類型	整數
父項元素	`<LLMTokenQuota>`
子元素	無

指定與您指定的 <TimeUnit> 元素 (分鐘、小時、天、週或月) 配對的整數 (例如 1、2、5、60 等)，藉此決定 Apigee 計算配額用量的時間範圍。

舉例來說，間隔為 24，且 <TimeUnit> 為 hour，表示系統會在 24 小時內計算配額。

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.interval">1</Interval>

下表列出 <Interval> 的屬性：

屬性	說明	預設	狀態
`ref`	用於指定包含配額間隔的流程變數。`ref` 的優先順序高於明確間隔值。如果同時指定參照和值，系統會優先採用參照。如果 `ref` 無法在執行階段解析，則會使用該值。	無	選用

`<TimeUnit>`

指定配額適用的時間單位。

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<LLMTokenQuota>`
子元素	無

選取 minute、hour、day、week、month 或 year。

注意：LLMTokenQuota 政策也支援以 second 做為時間單位。不過，second 僅適用於非分散式計數器 (當 <Distributed> 設為 false 時)。Google 建議您使用 PromptTokenLimit 政策，在第二層級限制要求流量尖峰，而非在此使用 second 值。

舉例來說，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 是否使用一或多個節點處理要求。

預設值	false
必填與否	選用
類型	布林值
父項元素	`<LLMTokenQuota>`
子元素	無

設為 true，指定政策應維護中央計數器，並在所有節點間持續同步處理。節點可跨可用區和/或區域。

如果您使用預設值 false，則可能會超出配額，因為每個節點的計數不會共用：

<Distributed>false</Distributed>

如要確保計數器同步處理，並在每次要求時更新，請將 <Distributed> 和 <Synchronous> 設為 true：

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

`<Synchronous>`

判斷是否要同步更新分散式配額計數器。

預設值	false
必填與否	選用
類型	布林值
父項元素	`<LLMTokenQuota>`
子元素	無

設為 true 可同步更新分散式配額計數器。也就是說，系統會在檢查 API 要求配額的同時，更新計數器。如果絕對不能允許任何超出配額的 API 呼叫，請設為 true。

注意：對計數器實作同步更新時，可能會影響效能並降低輸送量。在某些情況下，使用 <Synchronous>true</Synchronous> 可能會導致 LLMTokenQuota 政策無法處理部分交易。

設為 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」元素，您可以根據流程變數中的值，將權杖數量分配給不同的 bucket。舉例來說，您可以使用 developer.id 變數 (在 VerifyAPIKey 政策之後填入)，對每個特定開發人員建立的所有應用程式執行配額限制，也可以使用 client_id 對每個特定應用程式執行配額限制。後者的設定如下：

<Identifier ref="client_id"/>

您可以參照您可能使用 AssignMessage 政策或 JavaScript 政策設定的自訂變數，也可以參照隱含設定的變數，例如 VerifyAPIKey 政策或 VerifyJWT 政策設定的變數。如要進一步瞭解變數，請參閱「使用流程變數」；如需 Apigee 定義的知名變數清單，請參閱「流程變數參考資料」。

如果您未使用這個元素，政策會將所有權杖計數分配到特定 LLMTokenQuota 政策的單一計數器中。

下表說明 <Identifier> 的屬性：

屬性說明預設狀態

屬性	說明	預設	狀態
`ref`	指定用於識別要求計數器的流程變數。變數可以參照 HTTP 標頭、查詢參數、表單參數、訊息內容元素，或是其他值，以識別如何分配權杖計數。 `client_id` 通常用做變數。`client_id` 也稱為 API 金鑰或消費者金鑰，是在應用程式於 Apigee 上的機構中註冊時產生。如果已為 API 啟用 API 金鑰或 OAuth 授權政策，即可使用這個 ID。	不適用	選用

ref

指定用於識別要求計數器的流程變數。變數可以參照 HTTP 標頭、查詢參數、表單參數、訊息內容元素，或是其他值，以識別如何分配權杖計數。

client_id 通常用做變數。client_id 也稱為 API 金鑰或消費者金鑰，是在應用程式於 Apigee 上的機構中註冊時產生。如果已為 API 啟用 API 金鑰或 OAuth 授權政策，即可使用這個 ID。

不適用

選用

`<UseQuotaConfigInAPIProduct>`

定義 API 產品的配額設定，例如時間單位、間隔和允許上限。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<LLMTokenQuota>`
子元素	`<DefaultConfig>`

如果將 <UseQuotaConfigInAPIProduct> 元素新增至 LLMTokenQuota 政策，Apigee 會忽略 LLMTokenQuotaPolicy 的任何 <Allow>、<Interval> 和 <TimeUnit> 子元素。

<UseQuotaConfigInAPIProduct> 元素只是預設設定的容器，您可以使用 <DefaultConfig> 元素定義預設設定，如下列範例所示：

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

您可以使用 stepName 屬性，在流程中參照 VerifyAPIKey 政策或 OAuthv2 政策的 ValidateToken 政策作業。

下表說明 <UseQuotaConfigInAPIProduct> 的屬性：

屬性	說明	預設	狀態
`stepName`	識別流程中的驗證政策名稱。目標可以是 VerifyAPIKey 政策或 OAuthv2 政策。	不適用	必填

如要瞭解詳情，請參考下列資源：

`<DefaultConfig>`

包含 API 產品配額的預設值。定義 <DefaultConfig> 時，必須提供所有三個子項元素。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<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 政策識別為共用。API Proxy 中具有相同 <SharedName> 值的 LLMTokenQuota 政策，會共用相同的基礎配額計數器。

如需更多資訊和範例，請參閱「設定共用配額計數器」。

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<LLMTokenQuota>`
子元素	無

`<CountOnly>`

在 ProxyEndpoint 回應流程的步驟中，將這個元素設為 true，然後放置 LLMTokenQuota 政策，即可追蹤權杖數量，且在超出權杖配額限制時，不會將錯誤傳回用戶端。如果存在這個元素，則 <SharedName> 元素也必須存在，且 <EnforceOnly> 元素不得存在。

如需更多資訊和範例，請參閱「設定共用配額計數器」。

預設值	false
必填與否	選用
類型	布林值
父項元素	`<LLMTokenQuota>`
子元素	無

`<EnforceOnly>`

在 API Proxy 的要求流程中，將這個元素設為 true，並放置 LLMTokenQuota 政策，即可強制執行權杖限制，且不會遞增配額計數器。如果存在這個元素，就必須一併提供 <SharedName>，且不得提供 <CountOnly> 元素。

如需更多資訊和範例，請參閱「設定共用配額計數器」。

預設值	false
必填與否	選用
類型	布林值
父項元素	`<LLMTokenQuota>`
子元素	無

流程變數

執行 LLMTokenQuota 政策時，系統會自動填入下列預先定義的 Flow 變數。詳情請參閱流程變數參考資料。

變數	類型	權限	說明
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	唯讀	傳回世界標準時間 (以毫秒為單位)，用於判斷配額到期時間和新配額間隔的開始時間。如果 LLMTokenQuota 政策的類型為 `rollingwindow`，這個值無效，因為配額間隔永不過期。
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>` 元素所定義。
`policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference`	`500`	如果 `<TimeUnit>` 元素未在 `LLMTokenQuota` 政策中定義，就會發生這種情況。這個元素為必填，用於指定適用於 LLM 權杖配額的時間單位。時間間隔可以分鐘、小時、天、週或月為單位。

部署錯誤

錯誤名稱	原因	修正
`policies.llmtokenquota.MessageWeightNotSupported`	使用「MessageWeight」元素時發生錯誤，因為系統不支援該元素。	不適用
`policies.llmtokenquota.InvalidConfiguration`	<CountOnly> 或 <EnforceOnly> 必須設為 true，且只能設定其中一個。	不適用
`InvalidQuotaInterval`	如果 `<Interval>` 元素中指定的 LLM 權杖配額間隔不是整數，API 代理項目的部署作業就會失敗。舉例來說，如果 `<Interval>` 元素中指定的配額間隔為 0.1，API Proxy 的部署作業就會失敗。
`InvalidQuotaTimeUnit`	如果 `<TimeUnit>` 元素中指定的時間單位不受支援，API Proxy 部署作業就會失敗。支援的時間單位為 `minute`、`hour`、`day`、`week` 和 `month`。
`InvalidQuotaType`	如果 `<LLMTokenQuota>` 元素中 `type` 屬性指定的 LLM 權杖配額類型無效，API Proxy 部署作業就會失敗。支援的配額類型為 `default`、`calendar`、`flexi` 和 `rollingwindow`。
`InvalidStartTime`	如果 `<StartTime>` 元素中指定的時間格式無效，API Proxy 的部署作業就會失敗。有效格式為 `yyyy-MM-dd HH:mm:ss`，這是 ISO 8601 日期和時間格式。舉例來說，如果 `<StartTime>` 元素中指定的時間是 `7-16-2017 12:00:00`，API Proxy 的部署作業就會失敗。
`StartTimeNotSupported`	如果指定的 `<StartTime>` 元素配額類型不是 `calendar` 類型，API Proxy 部署作業就會失敗。`<StartTime>` 元素僅支援 `calendar` 配額類型。舉例來說，如果 `type` 屬性在 `<LLMTokenQuota>` 元素中設為 `flexi` 或 `rolling window`，API Proxy 的部署作業就會失敗。
`InvalidSynchronizeIntervalForAsyncConfiguration`	如果 `LLMTokenQuota` 政策中 `<AsynchronousConfiguration>` 元素內的 `<SyncIntervalInSeconds>` 元素指定值小於零，API Proxy 部署作業就會失敗。
`InvalidAsynchronizeConfigurationForSynchronousQuota`	如果 `LLMTokenQuota` 政策中的 `<AsynchronousConfiguration>` 元素值設為 `true`，且該政策也使用 `<AsynchronousConfiguration>` 元素定義非同步設定，則 API 代理伺服器部署作業會失敗。

錯誤變數

這項政策觸發錯誤時，系統會設定這些變數。詳情請參閱「政策錯誤須知」。

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

錯誤回應範例

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

{  
   "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>

注意：當傳入要求率超過 LLMTokenQuota 或 PromptTokenLimit 政策設定的門檻時，系統會傳回 HTTP 狀態碼 429 Too Many Requests。

LLMTokenQuota 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

LLMTokenQuota 違規處置的運作方式

LLMTokenQuota 如何與 API 產品搭配運作

LLMTokenQuota 如何搭配 SSE 回應運作

LLMTokenQuota 政策類型

瞭解配額計數器

設定 API 產品的配額設定

配額的計算方式

設定 API Proxy 層級的計數器

如果未使用任何 API 產品，配額會如何計算？

透過政策設定建立多個計數器

時間標記

從 API 產品設定取得配額設定

設定共用配額計數器

範例

更多 Dynamic LLMTokenQuota

開始時間

存取計數器

共用計數器

首次要求

設定 ID

類別

計算權杖

使用 API 產品、開發人員和應用程式計算配額動態變數

強制執行配額 (不使用 API 產品)

透過 API 產品、開發人員和應用程式強制執行配額

使用 SSE 串流

<LLMTokenQuota> 元素

<DisplayName> 元素

<Allow>

<Class>

<Allow> (<Class> 的子項)

<IgnoreUnresolvedVariables>

<Interval>

<TimeUnit>

<StartTime>

<Distributed>

<Synchronous>

<AsynchronousConfiguration>

<SyncIntervalInSeconds>

<SyncMessageCount>

<LLMTokenUsageSource>

<LLMModelSource>

<Identifier>

<UseQuotaConfigInAPIProduct>

<DefaultConfig>

<SharedName>

<CountOnly>

<EnforceOnly>

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

LLMTokenQuota 政策

`<LLMTokenQuota>` 元素

`<Allow>`

`<Class>`

`<Allow>` (`<Class>` 的子項)

`<Interval>`

`<TimeUnit>`

`<StartTime>`

`<Distributed>`

`<Synchronous>`

`<AsynchronousConfiguration>`

`<SyncIntervalInSeconds>`

`<SyncMessageCount>`

`<LLMTokenUsageSource>`

`<LLMModelSource>`

`<Identifier>`

`<UseQuotaConfigInAPIProduct>`

`<DefaultConfig>`

`<SharedName>`

`<CountOnly>`

`<EnforceOnly>`