共用方式為

限制 Azure OpenAI API 權杖使用量

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |Premium |進階 v2

此 azure-openai-token-limit 原則會藉由將語言模型令牌的耗用量限製為指定的速率（每分鐘數目）、指定期間或兩者中的配額，來防止 Foundry Models API 中的 Azure OpenAI 使用量尖峰。 超過指定的令牌速率限制時，呼叫端會收到 429 Too Many Requests 響應狀態代碼。 超過指定的配額時，呼叫端會收到 403 Forbidden 響應狀態代碼。

透過依賴來自 Azure OpenAI 端點回傳的代幣使用指標，該政策監控並根據實際代幣消耗量執行限制。 該政策也允許 API 管理提前估算提示令牌，減少對 Azure OpenAI 後端不必要的請求，若限制已超過。 然而，由於實際消耗的代幣數量取決於提示大小與完成大小（依請求而異），因此政策無法事先預測總代幣消耗量。 此設計允許在多個請求同時處理時暫時超過令牌限制。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 深入了解如何設定或編輯 APIM 原則。

Azure AI Foundry 模型中支援的 Azure OpenAI

原則會與下列類型的 AI Foundry 模型中從 Azure OpenAI 新增至 API 管理 的 API 搭配使用：

API 類型 支援的模型
聊天完成 gpt-3.5

gpt-4

gpt-4o

gpt-4o-mini

o1

o3
嵌入技術 text-embedding-3-large

text-embedding-3-small

text-embedding-ada-002
回應 （預覽） gpt-4o （版本： 2024-11-20、 2024-08-06、 2024-05-13）

gpt-4o-mini （版本： 2024-07-18）

gpt-4.1 （版本： 2025-04-14）

gpt-4.1-nano （版本： 2025-04-14）

gpt-4.1-mini （版本： 2025-04-14）

gpt-image-1 （版本： 2025-04-15）

o3 （版本： 2025-04-16）

o4-mini （版本： '2025-04-16）

注意

傳統完成 API 僅適用於舊版模型，且支援有限。

如需模型及其功能的目前資訊，請參閱 Foundry 模型中的 Azure OpenAI。

原則陳述式

<azure-openai-token-limit counter-key="key value"
        tokens-per-minute="number"
        token-quota="number"
        token-quota-period="Hourly | Daily | Weekly | Monthly | Yearly"
        estimate-prompt-tokens="true | false"    
        retry-after-header-name="custom header name, replaces default 'Retry-After'" 
        retry-after-variable-name="policy expression variable name"
        remaining-quota-tokens-header-name="header name"  
        remaining-quota-tokens-variable-name="policy expression variable name"
        remaining-tokens-header-name="header name"  
        remaining-tokens-variable-name="policy expression variable name"
        tokens-consumed-header-name="header name"
        tokens-consumed-variable-name="policy expression variable name" />

屬性

屬性 描述 是必要欄位 預設
counter-key 用於權杖限制原則的金鑰。 針對每個索引鍵值，會針對原則設定的所有範圍使用單一計數器。 允許使用原則運算式。 是的 N/A
token-per-minute 提示和完成每分鐘所取用的權杖數目上限。 必須指定速率限制 （tokens-per-minute）、配額 （token-quota 超過 ）， token-quota-period或兩者。 N/A
token-quota 在 中指定的 token-quota-period時間間隔期間允許的令牌數目上限。 不允許使用原則運算式。 必須指定速率限制 （tokens-per-minute）、配額 （token-quota 超過 ）， token-quota-period或兩者。 N/A
token-quota-period 固定窗口的長度，之後會 token-quota 重設。 這個值必須是下列其中一項：Hourly、DailyWeeklyMonthlyYearly 。 配額期間的開始時間是使用UTC時間戳截斷為期間所使用的單位（小時、日等）。計算。 必須指定速率限制 （tokens-per-minute）、配額 （token-quota 超過 ）， token-quota-period或兩者。 N/A
estimate-prompt-tokens 布林值，用以判斷是否要估計提示所需權杖數目：
- true：根據 API 中的提示結構描述估計權杖數目；可能降低效能。
- false：不要估計提示權杖。

當設定為 false 時，系統會使用模型回應中的實際權杖使用量來計算每個 counter-key 的剩餘權杖。 這可能會導致提示傳送至超過權杖限制的模型。 此時，回應會偵測到此情況，所有後續請求將被策略封鎖，直到令牌限制重置。		 是的 N/A
retry-after-header-name 自定義響應標頭的名稱，其值在指定或tokens-per-minute超過之後token-quota的秒內為建議的重試間隔。 不允許使用原則運算式。 否 Retry-After
retry-after-variable-name 變數的名稱，這個變數會將建議的重試間隔儲存在指定 tokens-per-minute 或 token-quota 超過后的秒內。 不允許使用原則運算式。 否 N/A
remaining-quota-tokens-header-name 回應標頭的名稱，其值在每次執行原則之後，是對應 token-quota 於 允許 token-quota-period的剩餘權杖數目的預估數目。 不允許使用原則運算式。 否 N/A
remaining-quota-tokens-variable-name 變數的名稱，在每次執行原則之後，儲存對應 token-quota 於 允許 token-quota-period的剩餘權杖預估數目。 不允許使用原則運算式。 否 N/A
remaining-tokens-header-name 響應標頭的名稱，其每個原則執行之後的值都是時間間隔所允許的剩餘令牌 tokens-per-minute 數目。 不允許使用原則運算式。 否 N/A
remaining-tokens-variable-name 每個原則執行之後的變數名稱會儲存時間間隔 tokens-per-minute 所允許的剩餘令牌數目。 不允許使用原則運算式。 否 N/A
tokens-consumed-header-name 回應標頭的名稱，其值為提示和完成所取用的權杖數目。 只有在從後端收到回應之後，才會將標頭新增至回應。 不允許使用原則運算式。 否 N/A
tokens-consumed-variable-name 變數的名稱，如果 backend 為 estimate-prompt-tokens，該變數會在管線的 true 區段中初始化為提示中的預估權杖數目，否則為零。 變數會在收到 outbound 區段中的回應時，以回報的計數進行更新。 否 N/A

使用方式

使用注意事項

  • 此政策可多次使用，且定義為
  • 此政策可在透過入口網站新增 Azure OpenAI API 時選擇性設定。
  • 當 設定為 estimate-prompt-tokens時false，會使用 Azure OpenAI API 回應使用量區段中的值來判斷令牌使用量。
  • 當多個請求同時或稍有延遲時，該政策可能允許代幣消耗超過設定限制。 這是因為政策無法確定實際消耗的代幣數量，直到後端收到回應。 一旦回應處理完且代幣限制超過，後續請求會被封鎖，直到限制重置。
  • 某些 Azure OpenAI 端點支持回應串流。 當 API 要求中 stream 設定為 true 以啟用串流時，不論 estimate-prompt-tokens 屬性的值為何，系統一律會估計提示權杖。 當回應經過串流處理時，也會預估完成權杖。
  • 或remaining-quota-tokens-variable-name的remaining-quota-tokens-header-name值是參考目的的估計值，但根據實際的代幣消耗量，可能大於預期。 隨著配額的接近，該值會更準確。
  • 對於接受影像輸入的模型，映像令牌通常會由後端語言模型計算，並包含在限制和配額計算中。 不過，使用串流或 estimate-prompt-tokens 設定為 true時，原則目前會將每個影像的計數過度計算為1200個令牌的最大計數。
  • APIM 會針對您在原則中指定的每個 counter-key 值使用單一計數器。 計數器會在使用該索引鍵值設定原則的所有範圍內更新。。 如果您想要在不同的範圍設定不同的計數器 (例如特定 API 或產品)，請在不同的範圍指定不同的索引鍵值。 例如，將識別範圍的字串附加至運算式的值。
  • v2 層級使用 代幣桶演算法來限制速率，這與經典層級的滑動視窗演算法不同。 基於此實作差異，當你在多個範圍內 counter-key設定 v2 層級的 token 限制時，請確保 tokens-per-minute 所有政策實例的值一致。 數值不一致會導致行為變得不可預測。
  • 此原則會在套用令牌的每個閘道上獨立追蹤令牌使用方式，包括多區域部署中的工作區閘道和區域閘道。 它不會匯總整個實例的令牌計數。

範例

令牌速率限制

在下列範例中，呼叫端IP位址會以每分鐘5000的令牌速率限制為索引鍵。 此原則不會估計提示所需的權杖數目。 在每個原則執行之後，時間週期內該呼叫者 IP 位址允許的其餘權杖會儲存在變數 remainingTokens 中。

<policies>
    <inbound>
        <base />
        <azure-openai-token-limit
            counter-key="@(context.Request.IpAddress)"
            tokens-per-minute="5000" estimate-prompt-tokens="false" remaining-tokens-variable-name="remainingTokens" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

令牌配額

在下列範例中，10000 的令牌配額會依訂用帳戶標識碼進行密鑰，並每月重設。 在每個原則執行之後，該訂用帳戶標識碼所允許的剩餘令牌數目會儲存在變數 remainingQuotaTokens中。

<policies>
    <inbound>
        <base />
        <azure-openai-token-limit
            counter-key="@(context.Subscription.Id)"
            token-quota="100000" token-quota-period="Monthly" remaining-quota-tokens-variable-name="remainingQuotaTokens" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

相關內容

如需使用原則的詳細資訊，請參閱：

  • Last updated on