速率限制

速率限制是我們的 API 對使用者或用戶端在指定期間內可存取服務的次數所設的限制。

為什麼需要速率限制？

設定速率限制是 API 的常見做法，主要有以下幾個原因：

• 有助於防止 API 遭到濫用或誤用。 例如，惡意人士可能向 API 傳送大量請求，企圖使其超載或中斷服務。設定速率限制可讓 OpenAI 防止這類行為。
• 速率限制有助於確保每個人都能公平地存取 API。 如果某個人或組織傳送過多請求，可能會拖慢其他所有人的 API 使用速度。透過限制單一使用者可傳送的請求數量，OpenAI 能確保盡可能多的人有機會使用 API，而不會遇到速度變慢的情況。
• 速率限制可協助 OpenAI 管理基礎設施的整體負載。 如果 API 請求量大幅增加，可能會加重伺服器負擔並造成效能問題。設定速率限制有助於 OpenAI 為所有使用者維持流暢且一致的體驗。

這些速率限制如何運作？

速率限制採用的指標包括 RPM （每分鐘請求數）、 RPD （每日請求數）、 TPM （每分鐘 Token 數）、 TPD （每日 Token 數）、 IPM （每分鐘圖像數），以及部分串流音訊模型每分鐘可處理的音訊分鐘數。任何一項指標先達到上限，就會觸發速率限制。例如，您可能向 ChatCompletions 端點傳送了 20 個請求，只使用了 100 個 Token，但如果 RPM 上限為 20，就已達到限制，即使這 20 個請求的 Token 總數尚未達到 150k 的 TPM 上限也是如此。

Batch API 的佇列限制是根據特定模型佇列中的輸入 Token 總數計算。尚未完成的批次作業所含的 Token 會計入佇列限制。批次作業完成後，其 Token 就不再計入該模型的限制。

其他需要注意的重點：

• 速率限制是在組織層級和專案層級設定，而非使用者層級。
• 速率限制會因使用的模型而異。
• 對於 GPT-5.5 等長上下文模型，長上下文請求有獨立的速率限制。您可以在開發者控制台查看這些限制。
• OpenAI 會為每個組織設定核准的每月使用上限。這與您可以自行為組織或專案設定的支出上限不同。
• 部分模型系列共用速率限制。在組織限制頁面中，列於同一個「共用限制」下的模型會共用一個速率限制。例如，如果列出的共用 TPM 為 3.5M，對該「共用限制」清單中任何模型的所有呼叫，都會計入這個 3.5M 上限。
• 向量儲存庫的資料匯入也會依各向量儲存庫 ID 設定速率限制。對每個向量儲存庫而言，/vector_stores/{vector_store_id}/files 和 /vector_stores/{vector_store_id}/file_batches 共用每分鐘 300 個請求的上限。匯入較大量的資料時，建議優先使用 /vector_stores/{vector_store_id}/file_batches。

使用層級

您可以在帳戶設定的限制區段查看組織的速率限制與使用上限。隨著您在我們 API 上的支出增加，我們會自動將您提升至下一個使用層級。這通常也會提高大多數模型的速率限制。

如需查看各模型的速率限制概覽，請前往模型頁面。

標頭中的速率限制資訊

除了在帳戶頁面查看速率限制外，您也可以在 HTTP 回應標頭中查看相關重要資訊，例如剩餘請求數、Token 數及其他中繼資料。

回應可能包含以下標頭欄位：

套用專案層級的 Token 限制時，回應可能包含專案 Token 標頭。因暫時性速率限制而傳回的 429 回應，以及因模型暫時過載而傳回的 503 回應，都可能包含 Retry-After。這並不表示配額、帳務或其他需要使用者採取行動的錯誤，也能透過重試解決。

微調速率限制

你也可以在儀表板中查看組織的微調速率限制，或透過 API 取得：

curl https://api.openai.com/v1/fine_tuning/model_limits \
  -H "Authorization: Bearer $OPENAI_API_KEY"

減少錯誤的影響

處理流量快速增加與模型過載

當請求速率增加過快時，API 可能傳回 slow_down；當請求使用的模型暫時過載時，則可能傳回 server_is_overloaded。請檢查 HTTP 狀態和 error.code，以區分這兩種情況：

若沒有 Retry-After，請延長重試間隔，並加入一小段隨機延遲。

即使流量未超過每分鐘請求數和每分鐘 Token 數的限制，仍可能發生 slow_down 錯誤。這反映的是流量增加的速度，而不是是否已達到這些限制。

一般建議是，當流量達到每分鐘 100 萬個輸入 Token（TPM）後，每 15 分鐘的增幅不要超過 50%。流量增長速率限制的實際觸發門檻，可能因模型和流量狀況而異。

若企業客戶的隨用隨付流量經常觸及流量增長速率限制，可以考慮使用規模層級，為符合資格的模型取得更可預期的容量。若使用 GPT-5.6 及後續模型，請參閱保留層級。容量層級不會改變 slow_down 回應的處理方式：若有 Retry-After，請依其指定的時間等待，降低流量，再逐步增加。

更新現有的錯誤處理常式

如果你的應用程式已針對先前的流量限制與過載回應進行處理，請同時檢查 HTTP 狀態和 error.code：

• 部分端點先前會針對這兩種情況傳回 503，並使用 slow_down 錯誤代碼；現在，流量快速增加時會傳回 429，並使用 slow_down。模型過載時仍傳回 503，但改用 server_is_overloaded。
• 先前，影片請求若因這些情況而在建立作業前遭到拒絕，會傳回 429，錯誤類型為 invalid_request_error，錯誤代碼為 rate_limit_exceeded。現在，流量快速增加時會傳回 429，並使用 rate_limit_error 和 slow_down；模型過載時則傳回 503，並使用 service_unavailable_error 和 server_is_overloaded。影片作業狀態中回報的錯誤屬於另一種情況。

請在 SDK 錯誤處理常式中同時處理 429 和 503。例如，Python、TypeScript 和 Ruby 使用 RateLimitError 處理 429，並使用 InternalServerError 處理 503；Java 則使用 RateLimitException 和 InternalServerException。只要應用程式仍可能收到舊有的回應代碼，就應保留對這些代碼的支援。其他錯誤也可能使用相同的 HTTP 狀態，因此請先檢查錯誤回應本文，再決定如何恢復運作。

對於串流請求，這些 HTTP 錯誤回應適用於串流開始之前。串流開始後發生的錯誤，可能會以串流事件的形式傳回；在已讀取輸出後，請勿自動重新傳送請求。

我可以採取哪些措施來減少影響？

OpenAI Cookbook 提供一份 Python 筆記本，說明如何避免速率限制錯誤，另有一份 Python 指令碼範例，示範如何在批次處理 API 請求時維持在速率限制內。

提供程式化存取、大量處理功能，以及社群媒體自動發文功能時，也應謹慎行事。請考慮只向可信任的客戶開放這些功能。

為防止自動化與大量濫用，請為個別使用者設定指定期間內（每日、每週或每月）的用量上限。可考慮強制執行上限，或對超過上限的使用者啟動人工審查流程。

使用指數退避重試

當請求超過暫時性速率限制時，API 會傳回 429 錯誤。回應可能包含 Retry-After 標頭，告知你重試前需等待多少秒。請將此值視為最短等待時間：至少等待這麼久，再加上一小段隨機延遲，避免多個用戶端同時重試。

每個官方 OpenAI SDK 都會依其重試設定，自動重試符合條件的 429 和 503 回應。Retry-After 的處理方式會因 SDK 版本與組態而異，尤其是在等待時間較長時。請確認已安裝版本的重試行為，不要假設它支援伺服器指定的所有等待時間。

如果伺服器指定的有效等待時間超過支援或設定的最長重試等待時間，請停止重試並延後處理請求，不要提早重試。當 SDK 不接受超過其上限的等待時間時，可能會傳回原始 HTTP 錯誤。請繼續分別處理取消與逾時錯誤：請求遭取消或超過截止時間時，重試可能會停止，而不會傳回該 HTTP 錯誤。每次嘗試的逾時設定，不一定就是整個操作的時間上限。

如果你使用自己的 HTTP 用戶端，當 Retry-After 標頭存在且值有效時，請遵循其指定的等待時間。如果標頭缺失或值無效，則改用加入隨機抖動的指數退避。請同時限制嘗試次數與重試所花費的總時間。如果你在應用程式中管理重試，請停用 SDK 重試，或將其納入這些限制，避免巢狀重試迴圈讓請求數成倍增加。遇到配額、帳務或其他需要你採取行動的錯誤時，請勿重試。

指數退避是指在請求失敗後稍作等待，並在每次重試失敗後延長等待時間，直到請求成功或達到設定的重試上限。

這種做法有許多優點：

• 自動重試可讓程式從速率限制錯誤中恢復運作，避免當機或資料遺失
• 指數退避讓你能迅速進行最初的重試；如果前幾次重試失敗，也能透過延長等待時間提高成功機會
• 在延遲時間中加入隨機抖動，有助於避免所有重試同時發生。

請注意，失敗的請求也會計入每分鐘的限制，因此持續重新傳送請求並無法解決問題。

以下 Python 範例示範備用的退避機制。這些範例不會檢查 Retry-After：使用前，請加入處理有效伺服器提示的邏輯，避免包裝函式在指定的等待時間結束前重試。請停用 SDK 重試，或將其納入應用程式的重試限制。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19from openai import OpenAI
from tenacity import (
    retry,
    stop_after_attempt,
    wait_random_exponential,
)  # for exponential backoff

client = OpenAI()


@retry(wait=wait_random_exponential(min=1, max=60), stop=stop_after_attempt(6))
def completion_with_backoff(**kwargs):
    return client.completions.create(**kwargs)


completion_with_backoff(
    model="gpt-3.5-turbo-instruct",
    prompt="Once upon a time,",
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import backoff
import openai
from openai import OpenAI

client = OpenAI()


@backoff.on_exception(backoff.expo, openai.RateLimitError)
def completions_with_backoff(**kwargs):
    return client.completions.create(**kwargs)


completions_with_backoff(
    model="gpt-3.5-turbo-instruct",
    prompt="Once upon a time,",
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59# imports
import random
import time

import openai
from openai import OpenAI

client = OpenAI()

# define a retry decorator


def retry_with_exponential_backoff(
    func,
    initial_delay: float = 1,
    exponential_base: float = 2,
    jitter: bool = True,
    max_retries: int = 10,
    errors: tuple = (openai.RateLimitError,),
):
    """Retry a function with exponential backoff."""

    def wrapper(*args, **kwargs):
        # Initialize variables
        num_retries = 0
        delay = initial_delay

        # Loop until a successful response or max_retries is hit or an exception is raised
        while True:
            try:
                return func(*args, **kwargs)

            # Retry on specific errors
            except errors:
                # Increment retries
                num_retries += 1

                # Check if max retries has been reached
                if num_retries > max_retries:
                    raise Exception(
                        f"Maximum number of retries ({max_retries}) exceeded."
                    )

                # Increment the delay
                delay *= exponential_base * (1 + jitter * random.random())

                # Sleep for the delay
                time.sleep(delay)

            # Raise exceptions for any errors not specified
            except Exception:
                raise

    return wrapper


@retry_with_exponential_backoff
def completions_with_backoff(**kwargs):
    return client.completions.create(**kwargs)

調低 max_tokens，使其符合生成內容的長度

計算速率限制時，會取 max_tokens 與根據請求字元數估算的 Token 數兩者中的較大值。請盡量將 max_tokens 設為接近預期回應長度的值。

批次處理請求

如果你的使用案例不需要立即回應，可以使用 Batch API，更輕鬆地提交並執行大量請求，而不影響同步請求的速率限制。

對於 確實 需要同步回應的使用案例，OpenAI API 分別對 每分鐘請求數 和 每分鐘 Token 數設有限制。

如果你的每分鐘請求數已達上限，但每分鐘 Token 數仍有餘裕，可以將多個任務合併到每個請求中，以提高吞吐量。這樣就能每分鐘處理更多 Token，尤其是在使用我們較小的模型時。

傳送一批提示詞的方式與一般 API 呼叫完全相同，唯一的差別是傳入 prompt 參數的是字串清單，而非單一字串。請參閱 Batch API 指南以瞭解詳情。