Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

LLMTokenQuota 政策

可擴充政策

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

查看 Apigee Edge 說明文件。

總覽

LLMTokenQuota 政策旨在管理及控管 AI/LLM 工作負載的詞元用量。大型語言模型 (LLM) 互動是以詞元為基礎，因此有效管理對於控制成本、最佳化效能和穩定平台至關重要。

配額是指 API Proxy 在一段時間範圍內 (例如每分鐘、每小時、每天、每週或每月) 可使用的 LLM 輸入或輸出詞元數。LLMTokenQuota 政策會使用計數器統計 API Proxy 的詞元用量。API 供應商可透過這項功能，限制應用程式在一段時間內的權杖用量。

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

這項政策是可擴充政策，視您的 Apigee 授權而定，使用這項政策可能會影響費用或用量。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

LLMTokenQuota 強制執行機制的運作方式

以下說明 LLMTokenQuota 政策的功能：

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

LLMTokenQuota 如何與 API 產品搭配運作

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

在 API Proxy 的要求中，套用 VerifyAPIKey 或 VerifyAccessToken 政策，以及 LLMTokenQuota 違規處置政策 (Proxy 或目標皆可)。
在 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 設定時，如果要求符合為 API 產品定義的任何作業，且該產品與同一個 Proxy 相關聯，且沒有自己的配額設定，則會共用該 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 Proxy 的每個權杖，將計數器遞增一次。在某些情況下，您可能想在初步處理傳入要求時，檢查是否超出配額，但只在處理回應時增加計數。

搭配使用 <SharedName>、<CountOnly> 和 <EnforceOnly> 這三個 LLMTokenQuota 政策元素，即可自訂 LLMTokenQuota 政策，對傳入的要求強制執行配額限制，但只在回應流程中增加計數。

舉例來說，假設您有一個 API Proxy 使用 LLM 做為目標，並希望強制執行每小時 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> 值。時間值為格林威治標準時間，而非當地時間。如果未提供 <StartTime> 值給 calendar 類型的政策，Apigee 會發出錯誤。

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

存取計數器

<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> 的組合。舉例來說，如果將 <TimeUnit> 設為小時，並將 <Interval> 設為 12，計數器就會每十二小時重設一次。你可以將 <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 定義單一計數器，無論要求來源為何。或者，您也可以搭配 LLMTokenQuota 政策使用 <Identifier> 屬性，根據 <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.event.current.data,false)}
  </LLMTokenUsageSource>
  <LLMModelSource>{jsonPath('$.modelVersion',response.event.current.data,false)}</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',request.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> 元素，請使用 <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。如果查詢參數包含無效值，政策會傳回配額違規錯誤。

注意：您無法在同一個 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>`
子元素	無

用於指定整數 (例如 1、2、5、60 等)，並與您指定的 <TimeUnit> 元素 (分鐘、小時、天、週或月) 配對，以決定 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>

如果政策是處理伺服器傳送事件 (SSE) 串流的事件流程一部分，系統會從目前事件的資料 (而非完整的回應內容) 擷取權杖用量。使用 response.event.current.data 做為來源，並將 jsonPath 函式的第三個引數 (want-array) 設為 false，這樣就會傳回單一權杖用量值，而非陣列。如要進一步瞭解這個引數，請參閱 JSON 路徑函式。以下範例顯示 SSE 設定：

<LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount',response.event.current.data,false)}</LLMTokenUsageSource>

`<LLMModelSource>`

提供 LLM 回覆或 LLM 要求的模型名稱來源。這必須是提供單一型號名稱值的訊息範本。

預設值	{jsonPath('$.model',request.content,true)}
必填與否	選用
類型	字串
父項元素	`<LLMTokenQuota>`
子元素	無

注意：<LLMModelSource> 元素為選用項目。如未指定，LLMTokenQuota 政策預設會從要求主體的 model 欄位解析模型名稱。如果省略 <LLMModelSource>，且要求主體不含 model 欄位，政策會從在 API 產品中設定的 LLM 作業解析模型。

以下範例說明如何從要求中指定模型來源：

<LLMModelSource>{jsonPath('$.model', request.content, true)}</LLMModelSource>

如果政策是處理伺服器推送事件 (SSE) 串流的事件流程之一，系統會從目前事件的資料中擷取模型名稱，而非完整的回應內容。使用 response.event.current.data 做為來源，並將 jsonPath 函式的第三個引數 (want-array) 設為 false，這樣系統就會傳回單一模型名稱值，而不是陣列。如要進一步瞭解這個引數，請參閱 JSON 路徑函式。以下範例顯示 SSE 設定：

<LLMModelSource>{jsonPath('$.modelVersion',response.event.current.data,false)}</LLMModelSource>

`<Identifier>`

設定政策，根據流程變數建立專屬計數器。

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

透過「ID」元素，您可以根據流程變數中的值，將權杖計數分配給不同的儲存區。舉例來說，您可以使用 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 回應流程的步驟中，加入 LLMTokenQuota 政策，並將這個元素設為 true，即可在超出詞元配額上限時，追蹤詞元數量，但不會將錯誤傳回用戶端。如果這個元素存在，則 <SharedName> 元素也必須存在，且 <EnforceOnly> 元素不得存在。

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

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

`<EnforceOnly>`

在 API Proxy 的要求流程中，將 LLMTokenQuota 政策的這項元素設為 true，即可強制執行詞元限制，但不會增加配額計數。如果存在這個元素，則也必須存在 <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	唯讀	傳回世界標準時間 (以毫秒為單位)，決定配額何時到期，以及新配額間隔何時開始。如果 LLMTokenQuota 政策的類型為 `rollingwindow`，這個值會無效，因為配額間隔不會到期。
ratelimit.{policy_name}.identifier	字串	唯讀	傳回附加至政策的 (用戶端) 識別資訊參照
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 產品設定取得配額設定

設定共用配額計數器

範例

更多動態 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>`