[Beta] 分離 ITPM / OTPM 速率限制

在路由器部署上分別強制執行 每分鐘輸入 token 數（ITPM） 與 每分鐘輸出 token 數（OTPM）。

當提供者公布分開的輸入／輸出吞吐量限制時（例如 Bedrock Mantle model cards），請使用此功能，而不是單一合併的 TPM。

資訊

這使用與 合併 TPM/RPM 強制執行 相同的 enforce_model_rate_limits 請求前檢查。請在部署上設定 itpm / otpm，而不是 tpm / rpm。

快速開始

config.yaml

model_list:
  - model_name: gpt-oss-120b
    litellm_params:
      model: bedrock_mantle/openai.gpt-oss-120b
      aws_region_name: us-east-1
      itpm: 500000   # 500K input tokens per minute
      otpm: 100000   # 100K output tokens per minute

router_settings:
  optional_pre_call_checks:
    - enforce_model_rate_limits

啟動 proxy：

litellm --config /path/to/config.yaml

將 itpm / otpm 設為您提供者配額或 model card 中的值（Bedrock Mantle 的 Service Quotas console，或您內部的容量規劃）。

Mantle 風格保留

LiteLLM 遵循與 Bedrock Mantle endpoint 相同的保留模型：token 限制會在上游請求前強制執行，然後在回應後重新對帳。

請求前（准入）

在請求送出給提供者之前：

1. 估算輸入 token 數，來源為請求本文（messages、prompt，或 Responses input）。
2. 決定有效的輸出上限——在檢查配額時，作為 max_tokens 的替代值：

優先順序	來源	範例 (openai.gpt-oss-120b)
1	請求 max_tokens 或 max_completion_tokens	用戶端送出 max_tokens: 1024 → 使用 1024
2	Model map max_output_tokens（fallback max_tokens）	用戶端未指定上限 → 使用 model card 中的 32768
3	硬性預設值	未知模型 → 4096

3. ITPM 檢查： 針對部署 ITPM 限制保留 estimated_input + effective_output_cap。若准入會超出限制，則以 429 阻擋。
4. OTPM 檢查： 確保 current_otpm + effective_output_cap 符合 OTPM 限制。若會超出 OTPM，則回滾 ITPM 保留並回傳 429。

這與 Mantle 相同：當用戶端省略 max_tokens 時，LiteLLM 會假設 model 的最大輸出容量，而不是其輸入 context window。這就是為什麼在大型模型上缺少 max_tokens，可能會保留大量 ITPM/OTPM 餘裕。

提示

將 max_tokens（或 Responses 上的 max_output_tokens）設得接近您預期的 completion 大小。Mantle 和 LiteLLM 都會在回應後向下重新對帳，但過高的預設上限仍會在請求完成前阻擋並行請求。

請求後（重新對帳）

在成功回應後：

計數器	記錄內容
ITPM	以 billable_input + completion_tokens 取代請求前的保留，其中 billable_input = prompt_tokens - cached_tokens
OTPM	加上實際 completion_tokens

如果請求在完成前失敗，ITPM 保留會退還；OTPM 不會計費。

具體範例

對 max_tokens（bedrock_mantle/openai.gpt-oss-120b）的請求，未提供 max_output_tokens: 32768，itpm: 500000：

步驟	計算	ITPM 使用量
請求前保留	12 輸入估算 + 32768 輸出上限	保留 32780
回應	prompt_tokens=10、completion_tokens=150、無快取	—
請求後重新對帳	10 + 150	160 最終

若沒有明確的 max_tokens，預先請求保留量會遠大於最終扣款，這與 Mantle 文件中對配額保留的行為相同。

運作方式

階段	ITPM	OTPM
請求前	保留 estimated_input + effective_output_cap	檢查 current_otpm + effective_output_cap
請求後	重新對帳為 billable_input + completion_tokens	加上實際 completion_tokens
失敗	退還 ITPM 保留	不收取 OTPM

已快取的 prompt tokens（prompt_tokens_details.cached_tokens）在回應後會自 ITPM 計費中排除。

回應標頭

當某個 model group 已設定 itpm 或 otpm 時，LiteLLM 會回傳：

標頭	說明
x-ratelimit-limit-input-tokens	該 model group 的 ITPM 限制
x-ratelimit-remaining-input-tokens	本分鐘剩餘的 ITPM 容量
x-ratelimit-reset-input-tokens	直到分鐘視窗重設還有幾秒
x-ratelimit-limit-output-tokens	該 model group 的 OTPM 限制
x-ratelimit-remaining-output-tokens	本分鐘剩餘的 OTPM 容量
x-ratelimit-reset-output-tokens	直到分鐘視窗重設還有幾秒

錯誤回應

當上游請求前超出限制時：

{
  "error": {
    "message": "Model rate limit exceeded. ITPM limit=500000, current usage=500120",
    "type": "rate_limit_error",
    "code": 429
  }
}

回應會包含 retry-after 標頭（距離目前分鐘視窗重設還有幾秒）。

專案層級限制

在 proxy 上為 project 強制執行每個模型的 ITPM / OTPM 配額。建立或更新專案時，設定 model_itpm_limit 和 model_otpm_limit：每一項都會將模型名稱（model_name 用戶端請求的名稱）對應到每分鐘 token 限制。

curl -X POST 'http://localhost:4000/project/new' \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_alias": "my-project",
    "team_id": "<team-id>",
    "models": ["claude-fable-5"],
    "model_itpm_limit": {"claude-fable-5": 300000},
    "model_otpm_limit": {"claude-fable-5": 100000}
  }'

使用專案金鑰發出的請求會計入這些限制。強制執行遵循與部署限制相同的保留模型：LiteLLM 會在上游請求前先保留輸入估算值加上有效的輸出上限，然後在回應後與實際用量對帳。不需要 router 設定。proxy 的速率限制器會自動強制執行專案中繼資料。這需要資料庫，因為專案儲存在 proxy DB 中。

專案回應標頭

對具有專案限制的模型，成功回應會包含：

標頭	說明
x-ratelimit-model_per_project_itpm-limit-tokens	該模型的專案 ITPM 限制
x-ratelimit-model_per_project_itpm-remaining-tokens	這一分鐘剩餘的專案 ITPM
x-ratelimit-model_per_project_otpm-limit-tokens	該模型的專案 OTPM 限制
x-ratelimit-model_per_project_otpm-remaining-tokens	這一分鐘剩餘的專案 OTPM

專案錯誤回應

任何會超出專案限制的請求都會在上游請求前被 429 阻擋：

{
  "error": {
    "message": "Rate limit exceeded for model_per_project_itpm: <project-id>:claude-fable-5. Limit type: tokens. Current limit: 300000, Remaining: 300000. Limit resets at: 2026-08-18 14:48:49 UTC",
    "type": "throttling_error",
    "code": "429"
  }
}

ITPM 與 TPM

設定	限制內容	使用時機
tpm	每分鐘總 token 數（單一計數器）	舊版合併吞吐量限制
itpm + otpm	分別限制輸入與輸出	具有明確輸入／輸出 TPM 的提供者文件（Bedrock Mantle）

請不要在同一個部署上同時設定兩種模式。如果存在 itpm 或 otpm，LiteLLM 會使用 ITPM/OTPM 路徑，並忽略該部署的合併 TPM 追蹤。

多實例部署

使用 Redis 在 proxy 複本之間共享計數器：

config.yaml

router_settings:
  optional_pre_call_checks:
    - enforce_model_rate_limits
  redis_host: redis.example.com
  redis_port: 6379
  redis_password: your-password

SDK 使用方式

example.py

from litellm import Router

router = Router(
    model_list=[
        {
            "model_name": "gpt-oss-120b",
            "litellm_params": {
                "model": "bedrock_mantle/openai.gpt-oss-120b",
                "itpm": 500_000,
                "otpm": 100_000,
            },
        }
    ],
    optional_pre_call_checks=["enforce_model_rate_limits"],
)

response = await router.acompletion(
    model="gpt-oss-120b",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=1024,  # explicit cap avoids over-reserving model max_output_tokens
)

相關內容

• 負載平衡 + 合併 TPM/RPM 強制執行
• 動態 TPM/RPM 配置
• Bedrock Mantle 配額（AWS）