跳至主要內容

預算、速率限制

預算設定選項

個人預算:建立不含 team_id 的虛擬金鑰,以設定個人支出上限

團隊預算:在虛擬金鑰中加入 team_id,以使用團隊共享預算

團隊成員預算:在團隊共享預算內,為個別成員設定支出上限

代理程式預算:為代理程式設定速率限制(tpm/rpm)與工作階段層級上限(迭代次數、美元預算) 跳轉

如果金鑰屬於某個團隊,則會套用團隊預算,而不是使用者的個人預算。

需求:

設定預算

全域 Proxy

在 proxy 上對所有請求套用預算

步驟 1. 修改 config.yaml

general_settings:
master_key: sk-1234

litellm_settings:
# other litellm settings
max_budget: 0 # (float) sets max budget as $0 USD
budget_duration: 30d # (str) frequency of reset - You can set duration as seconds ("30s"), minutes ("30m"), hours ("30h"), days ("30d").

步驟 2. 啟動 proxy

litellm /path/to/config.yaml

步驟 3. 傳送測試請求

curl --location 'http://0.0.0.0:4000/chat/completions' \
--header 'Autherization: Bearer sk-1234' \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "what llm are you"
}
],
}'

團隊

您可以:

  • 為 Teams 加入預算
資訊

逐步教學:在 Teams 上設定、重設預算(透過 API 或使用 Admin UI)

為團隊新增預算

curl --location 'http://localhost:4000/team/new' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"team_alias": "my-new-team_4",
"members_with_roles": [{"role": "admin", "user_id": "5c4a0aa3-a1e1-43dc-bd87-3c2da8382a3a"}],
"rpm_limit": 99
}'

查看 Swagger

範例回應

{
"team_alias": "my-new-team_4",
"team_id": "13e83b19-f851-43fe-8e93-f96e21033100",
"admins": [],
"members": [],
"members_with_roles": [
{
"role": "admin",
"user_id": "5c4a0aa3-a1e1-43dc-bd87-3c2da8382a3a"
}
],
"metadata": {},
"tpm_limit": null,
"rpm_limit": 99,
"max_budget": null,
"models": [],
"spend": 0.0,
"max_parallel_requests": null,
"budget_duration": null,
"budget_reset_at": null
}

為團隊新增預算期間

budget_duration:預算會在指定持續時間結束時重設。如果未設定,預算將永不重設。您可以將持續時間設定為秒("30s")、分鐘("30m")、小時("30h")、天("30d")。

curl 'http://0.0.0.0:4000/team/new' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"team_alias": "my-new-team_4",
"members_with_roles": [{"role": "admin", "user_id": "5c4a0aa3-a1e1-43dc-bd87-3c2da8382a3a"}],
"budget_duration": "30s",
}'

團隊成員

當您想要限制 Team 內使用者的支出預算時,請使用此功能

步驟 1. 建立使用者

使用 user_id=ishaan 建立使用者

curl --location 'http://0.0.0.0:4000/user/new' \
--header 'Authorization: Bearer sk-1234' \
--header 'Content-Type: application/json' \
--data '{
"user_id": "ishaan"
}'

步驟 2. 將使用者加入既有團隊 - 設定 max_budget_in_team

在將使用者加入團隊時,設定 max_budget_in_team。我們會使用在步驟 1 中設定的相同 user_id

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{"team_id": "e8d1460f-846c-45d7-9b43-55f3cc52ac32", "max_budget_in_team": 0.000000000001, "member": {"role": "user", "user_id": "ishaan"}}'

步驟 3. 為步驟 1 的團隊成員建立金鑰

設定步驟 1 中的 user_id=ishaan

curl --location 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer sk-1234' \
--header 'Content-Type: application/json' \
--data '{
"user_id": "ishaan",
"team_id": "e8d1460f-846c-45d7-9b43-55f3cc52ac32"
}'

來自 /key/generate 的回應

我們會在步驟 4 中使用此回應中的 key

{"key":"sk-RV-l2BJEZ_LYNChSx2EueQ", "models":[],"spend":0.0,"max_budget":null,"user_id":"ishaan","team_id":"e8d1460f-846c-45d7-9b43-55f3cc52ac32","max_parallel_requests":null,"metadata":{},"tpm_limit":null,"rpm_limit":null,"budget_duration":null,"allowed_cache_controls":[],"soft_budget":null,"key_alias":null,"duration":null,"aliases":{},"config":{},"permissions":{},"model_max_budget":{},"key_name":null,"expires":null,"token_id":null}% 

步驟 4. 對團隊成員發出 /chat/completions 請求

此請求請使用步驟 3 中的金鑰。執行 2-3 次請求後,預期會看到以下錯誤 ExceededBudget: Crossed spend within team

curl --location 'http://localhost:4000/chat/completions' \
--header 'Authorization: Bearer sk-RV-l2BJEZ_LYNChSx2EueQ' \
--header 'Content-Type: application/json' \
--data '{
"model": "llama3",
"messages": [
{
"role": "user",
"content": "tes4"
}
]
}'

內部使用者

在 proxy 上,對內部使用者(金鑰擁有者)可發出的所有請求套用預算。

資訊

對於設定了 'team_id' 的金鑰,會使用團隊預算,而不是使用者的個人預算。

若要對團隊內的使用者套用預算,請使用團隊成員預算。

LiteLLM 提供一個 /user/new 端點來建立這些預算。

您可以:

  • 將預算新增到使用者 跳轉
  • 新增預算持續時間,以重設支出 跳轉

預設情況下,max_budget 設為 null,且不會針對金鑰進行檢查

為使用者新增預算

curl --location 'http://localhost:4000/user/new' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{"models": ["azure-models"], "max_budget": 0, "user_id": "krrish3@berri.ai"}'

查看 Swagger

範例回應

{
"key": "sk-YF2OxDbrgd1y2KgwxmEA2w",
"expires": "2023-12-22T09:53:13.861000Z",
"user_id": "krrish3@berri.ai",
"max_budget": 0.0
}

為使用者新增預算期間

budget_duration:預算會在指定持續時間結束時重設。若未設定,預算永不重設。您可以將持續時間設定為秒("30s")、分鐘("30m")、小時("30h")、天("30d")。

curl 'http://0.0.0.0:4000/user/new' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"team_id": "core-infra", # [OPTIONAL]
"max_budget": 10,
"budget_duration": "30s",
}'

為既有使用者建立新金鑰

現在您只需使用該 user_id(例如 krrish3@berri.ai)呼叫 /key/generate,並且:

curl --location 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data '{"models": ["azure-models"], "user_id": "krrish3@berri.ai"}'

虛擬金鑰

對金鑰套用預算。

您可以:

  • 將預算新增到金鑰 跳轉
  • 新增預算持續時間,以重設支出 跳轉

預期行為

  • 每個金鑰的成本會自動填入 LiteLLM_VerificationToken 表格
  • 金鑰超過其 max_budget 後,請求會失敗
  • 若設定了持續時間,支出會在持續時間結束時重設

預設情況下,max_budget 設為 null,且不會針對金鑰進行檢查

為金鑰新增預算

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"team_id": "core-infra", # [OPTIONAL]
"max_budget": 10,
}'

金鑰超過預算時對 /chat/completions 的範例請求

curl --location 'http://0.0.0.0:4000/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <generated-key>' \
--data ' {
"model": "azure-gpt-3.5",
"user": "e09b4da8-ed80-4b05-ac93-e16d9eb56fca",
"messages": [
{
"role": "user",
"content": "respond in 50 lines"
}
],
}'

金鑰超過預算時來自 /chat/completions 的預期回應

{
"detail":"Authentication Error, ExceededTokenBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07"
}

為金鑰新增預算期間

budget_duration:預算會在指定持續時間結束時重設。若未設定,預算永不重設。您可以將持續時間設定為秒("30s")、分鐘("30m")、小時("30h")、天("30d")。

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"team_id": "core-infra", # [OPTIONAL]
"max_budget": 10,
"budget_duration": "30s",
}'

在金鑰上設定多個預算視窗

在同一個金鑰上於不同時間尺度套用多個並行預算限制——例如,將金鑰上限設為 $10/天$100/月

這在什麼情況下有用?

單一 budget_duration 視窗無法防止糟糕的一天燒掉您整個月份的額度。多個預算視窗可讓您:

  • 在一天內封鎖失控的用量暴增,同時仍允許正常的每月支出。
  • 為 Claude Code rollout 提供每日防護欄(24h)與每月上限(30d),避免單次大量使用的工作階段耗盡整個月份。
  • 在週上限之上,為突發型工作負載分層加入更細的每小時限制。
資訊

請參閱 使用者預算文件,以了解預算如何跨金鑰、團隊與使用者運作。

透過 API

budget_limits 作為 {budget_duration, max_budget} 物件的清單傳入:

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"budget_limits": [
{"budget_duration": "24h", "max_budget": 10},
{"budget_duration": "30d", "max_budget": 100}
]
}'

每個時間窗口都會獨立追蹤,並依各自的排程重設:

budget_duration重設
1h每小時
24h每天 UTC 午夜
7d每週日 UTC 午夜
30d每月 1 日 UTC 午夜

透過儀表板

開啟 Virtual Keys → Create Key → Optional Settings → Budget Windows

步驟 1 - 開啟金鑰設定

點擊 + Add Budget Window 新增一列,從下拉選單選擇期間,並輸入支出上限。

步驟 2 - 新增窗口

再新增第二列以設定不同時間區間(例如:在每日 10 美元之外,再加上每月 100 美元)。

步驟 3 - 新增第二個窗口

每個窗口都會在輸入欄位下方顯示重設排程,因此您可以清楚知道支出何時重設。

步驟 4 - 重設提示

✨ 虛擬金鑰(模型特定)

在金鑰上套用模型特定預算。範例:

  • gpt-4o 的預算為 $0.0000001,期間為 1d,適用於 key = "sk-12345"
  • gpt-4o-mini 的預算為 $10,期間為 30d,適用於 key = "sk-12345"
資訊

✨ 這是僅限 Enterprise 的功能 在此開始使用 Enterprise

model_max_budget 的規格為 Dict[str, GenericBudgetInfo]

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"model_max_budget": {"gpt-4o": {"budget_limit": "0.0000001", "time_period": "1d"}}
}'

發出測試請求

我們預期第一個請求會成功,而第二個請求會失敗,因為我們在 Virtual Key 上超過了 gpt-4o 的預算

Langchain、OpenAI SDK 使用範例

curl --location 'http://0.0.0.0:4000/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <sk-generated-key>' \
--data ' {
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": "testing request"
}
]
}
'

若要在超過每個模型的預算時,將請求重新路由到其他模型,而不是回傳 budget_exceeded,請參閱 預算備援

代理程式

在 LiteLLM 註冊的代理程式上設定預算與速率限制,Agent Gateway。您可以控制:

  • 每個代理程式的速率限制:套用在代理程式本身的 tpm_limitrpm_limit
  • 每個工作階段的速率限制:每個工作階段套用的 session_tpm_limitsession_rpm_limit
  • 每個工作階段的迭代上限:代理程式 litellm_params 中的 max_iterations
  • 每個工作階段的預算上限:代理程式 litellm_params 中的 max_budget_per_session

在代理程式上設定 tpm_limitrpm_limit,以限制所有工作階段的總吞吐量。

curl -X POST 'http://localhost:4000/v1/agents' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
"agent_name": "my-research-agent",
"agent_card_params": {
"name": "my-research-agent",
"description": "A research agent",
"url": "http://my-agent:8080",
"version": "1.0.0"
},
"tpm_limit": 100000,
"rpm_limit": 100
}'
資訊

您也可以使用 PATCH /v1/agents/{agent_id} 更新既有代理程式的速率限制:

curl -X PATCH 'http://localhost:4000/v1/agents/<agent_id>' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
"tpm_limit": 200000,
"rpm_limit": 200,
"session_tpm_limit": 50000,
"session_rpm_limit": 50
}'

客戶

這可用來為傳遞給 /chat/completionsuser 編列預算,而不需要為每位使用者建立一把金鑰

步驟 1. 修改 config.yaml 定義 litellm.max_end_user_budget

general_settings:
master_key: sk-1234

litellm_settings:
max_end_user_budget: 0.0001 # budget for 'user' passed to /chat/completions
  1. 發出 /chat/completions 請求,傳入 'user' - 第一次呼叫成功
curl --location 'http://0.0.0.0:4000/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-zi5onDRdHGD24v0Zdn7VBA' \
--data ' {
"model": "azure-gpt-3.5",
"user": "ishaan3",
"messages": [
{
"role": "user",
"content": "what time is it"
}
]
}'
  1. 發出 /chat/completions 請求,傳入 'user' - 呼叫失敗,因為 'ishaan3' 超出預算
curl --location 'http://0.0.0.0:4000/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-zi5onDRdHGD24v0Zdn7VBA' \
--data ' {
"model": "azure-gpt-3.5",
"user": "ishaan3",
"messages": [
{
"role": "user",
"content": "what time is it"
}
]
}'

錯誤

{"error":{"message":"Budget has been exceeded: User ishaan3 has exceeded their budget. Current spend: 0.0008869999999999999; Max Budget: 0.0001","type":"auth_error","param":"None","code":401}}%                

重設預算

重設跨金鑰/內部使用者/團隊/客戶的預算

budget_duration:預算會在指定期間結束時重設。如果未設定,預算永遠不會重設。您可以將期間設定為秒("30s")、分鐘("30m")、小時("30h")、天("30d")。

curl 'http://0.0.0.0:4000/user/new' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"max_budget": 10,
"budget_duration": "30s", # 👈 KEY CHANGE
}'

注意: 預設情況下,伺服器每 10 分鐘檢查一次是否需要重設,以減少資料庫呼叫。

若要變更此設定,請設定 proxy_budget_rescheduler_min_timeproxy_budget_rescheduler_max_time

例如:每 1 秒檢查一次

general_settings: 
proxy_budget_rescheduler_min_time: 1
proxy_budget_rescheduler_max_time: 1

備援到「free」模型

如果金鑰/使用者/團隊已達到其預算上限,對設定了 input_cost_per_token: 0output_cost_per_token: 0 的模型之請求仍會被允許。對零成本模型則會完全略過預算檢查。

這讓您可以將免費或自架模型設定為備援,即使預算已用盡的金鑰仍可存取。

若要將模型標記為免費,請在您的 config.yaml 中將這兩個成本欄位都明確設為 0

model_list:
- model_name: my-free-model
litellm_params:
model: ollama/llama3
input_cost_per_token: 0
output_cost_per_token: 0

注意: 成本欄位必須明確設為 0。如果未設定(null/缺失),模型不會被視為免費,預算檢查仍會套用。

硬性預算強制執行(失敗即封閉)

預算檢查會從 Redis 中的跨 pod 計數器讀取目前支出,這可讓強制執行在 workers 與 replicas 之間保持快速且一致。該計數器是熱路徑上的事實來源,而資料庫會在背景中進行協調。若 Redis 重新啟動並載入較舊的快照,計數器可能會回到低於資料庫中已記錄支出的值;在熱路徑上,系統會信任這個過時值,這可能讓金鑰持續花費超過其 max_budget,直到計數器被修正為止。

對於已設定的預算即使在 Redis 降級時也必須是硬上限的部署,請設定 fail_closed_budget_enforcement

general_settings:
fail_closed_budget_enforcement: true

啟用後,每個有預算的請求在被接受前都會先以權威資料庫驗證支出(涵蓋 key、team、user、organization、end-user、tag,以及 per-window 預算),因此過時或缺失的 Redis 計數器無法低估支出。資料庫讀取會在程序內合併並快取數秒,因此額外負載會被限制在每個 worker、每個快取視窗、每個有預算實體約一筆讀取,而不是每個請求一筆讀取。若目前支出無法同時由 Redis 與資料庫驗證,請求會以 503 被拒絕,而不是在無法驗證的預算上被接受。

保持此設定關閉(預設值)可讓健康且未超預算的流量完全不碰資料庫;在預設模式下,當計數器讀到低於呼叫者最後已知記錄支出時,仍會與資料庫交叉檢查,這能在不需要每個請求都讀取資料庫的情況下,攔截常見的過時計數器情境。

設定速率限制

您可以設定:

  • tpm 限制(每分鐘 tokens)
  • rpm 限制(每分鐘請求數)
  • 最大平行請求數
  • 針對特定 key 或 team、依模型設定的 rpm / tpm 限制

TPM 速率限制類型(輸入/輸出/總計)

預設情況下,TPM(每分鐘 tokens)速率限制會計算總 tokens(輸入 + 輸出)。您也可以將其設定為只計算輸入 tokens,或改為只計算輸出 tokens。

請在您的 config.yaml 中設定 token_rate_limit_type

general_settings:
master_key: sk-1234
token_rate_limit_type: "output" # Options: "input", "output", "total" (default)
說明
total計算總 tokens(prompt + completion)。預設行為。
input僅計算 prompt/input tokens
output僅計算 completion/output tokens

此設定會全域套用至所有 TPM 速率限制檢查(keys、users、teams 等)。

使用 /team/new/team/update,即可在 team 的多個 key 之間保留 rate limits。

curl --location 'http://0.0.0.0:4000/team/new' \
--header 'Authorization: Bearer sk-1234' \
--header 'Content-Type: application/json' \
--data '{"team_id": "my-prod-team", "max_parallel_requests": 10, "tpm_limit": 20, "rpm_limit": 4}'

查看 Swagger

預期回應

{
"key": "sk-sA7VDkyhlQ7m8Gt77Mbt3Q",
"expires": "2024-01-19T01:21:12.816168",
"team_id": "my-prod-team",
}

為所有內部使用者設定預設預算

可用來為您提供 key 的使用者設定預設 budget。

當使用者有 user_role="internal_user" 時,這會生效(可透過 /user/new/user/update 設定)。

如果 key 有 team_id,這將不會生效(屆時會套用 team budgets)。告訴我們如何改進!

  1. 在您的 config.yaml 中定義 max budget
model_list: 
- model_name: "gpt-3.5-turbo"
litellm_params:
model: gpt-3.5-turbo
api_key: os.environ/OPENAI_API_KEY

litellm_settings:
max_internal_user_budget: 0 # amount in USD
internal_user_budget_duration: "1mo" # reset every month
  1. 為使用者建立 key
curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{}'

預期回應:

{
...
"key": "sk-X53RdxnDhzamRwjKXR4IHg"
}
  1. 測試它!
curl -L -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-X53RdxnDhzamRwjKXR4IHg' \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "Hey, how's it going?"}]
}'

預期回應:

{
"error": {
"message": "ExceededBudget: User=<user_id> over budget. Spend=3.7e-05, Budget=0.0",
"type": "budget_exceeded",
"param": null,
"code": "400"
}
}

多實例速率限制

重要注意事項:

  • Rate limits 不適用於 proxy 管理員使用者。
  • 測試 rate limits 時,請使用內部使用者角色(非管理員),以確保限制如預期般生效。

變更:

  • 這會在更新目前請求/權杖時改用 async_increment,而不是 async_set_cache。
  • 內存快取會每 0.01 秒與 redis 同步一次,以避免每個請求都呼叫 redis。
  • 在測試中,這被發現比先前的實作快 2 倍,並將預期與實際失敗之間的偏差在高流量(3 個執行個體上每秒 100 RPS)下減少到最多 10 個請求。

授予新模型存取權限

使用模型存取群組來讓使用者可存取特定模型,並隨時間加入新的模型(例如 mistral、llama-2 等)。

使用 /key/generate/user/new 之間有什麼差異?如果您在 /user/new 上這麼做,它會在為該使用者產生的多個金鑰之間持續保留。

步驟 1. 在 config.yaml 中指定模型、存取群組

model_list:
- model_name: text-embedding-ada-002
litellm_params:
model: azure/azure-embedding-model
api_base: "os.environ/AZURE_API_BASE"
api_key: "os.environ/AZURE_API_KEY"
api_version: "2023-07-01-preview"
model_info:
access_groups: ["beta-models"] # 👈 Model Access Group

步驟 2. 建立具有存取群組的金鑰

curl --location 'http://localhost:4000/user/new' \
-H 'Authorization: Bearer <your-master-key>' \
-H 'Content-Type: application/json' \
-d '{"models": ["beta-models"], # 👈 Model Access Group
"max_budget": 0}'

為既有內部使用者建立新金鑰

只要在 /key/generate 請求中加入 user_id 即可。

curl --location 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data '{"models": ["azure-models"], "user_id": "krrish@berri.ai"}'

API 規格

GenericBudgetInfo

一個定義預算資訊、包含時間期間與上限的 Pydantic 模型。

class GenericBudgetInfo(BaseModel):
budget_limit: float # The maximum budget amount in USD
time_period: str # Duration string like "1d", "30d", etc.

欄位:

  • budget_limit(float):以 USD 表示的最大預算金額
  • time_period(str):指定預算時間期間的持續時間字串。支援的格式:
    • 秒:"30s"
    • 分鐘:"30m"
    • 小時:"30h"
    • 天:"30d"

範例:

{
"budget_limit": "0.0001",
"time_period": "1d"
}