跳至主要内容

预算、速率限制

预算设置选项

个人预算：创建没有 team_id 的虚拟密钥，用于设置个人支出限额

团队预算：向虚拟密钥添加 team_id，以利用团队的共享预算

团队成员预算：在团队共享预算内设置个人的支出限额

代理（Agent）预算：为代理设置速率限制（tpm/rpm）和会话级上限（迭代次数、美元预算） 跳转

如果密钥属于某个团队，则应用团队预算，而不是用户的个人预算。

要求

设置预算​

全局代理​

在代理的所有调用中应用预算

第 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. 启动代理

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"
        }
    ],
}'

团队​

您可以

  • 向团队添加预算
信息

在此处获取关于在团队中设置、重置预算的分步教程（通过 API 或使用管理 UI）

向团队添加预算​

curl --location 'https://: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",
}'

团队成员​

当您想要限制团队内某个用户的支出时，请使用此功能

第 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 'https://:4000/chat/completions' \
    --header 'Authorization: Bearer sk-RV-l2BJEZ_LYNChSx2EueQ' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "llama3",
    "messages": [
        {
        "role": "user",
        "content": "tes4"
        }
    ]
}'

内部用户​

为内部用户（密钥所有者）在代理上可以进行的所有调用应用预算。

信息

对于设置了 'team_id' 的密钥，将使用团队预算而不是用户的个人预算。

要为团队内的用户应用预算，请使用团队成员预算。

LiteLLM 提供了一个 /user/new 端点来为此创建预算。

您可以

  • 向用户添加预算 跳转
  • 添加预算周期以重置支出 跳转

默认情况下，max_budget 设置为 null，且不会对密钥进行检查

向用户添加预算​

curl --location 'https://: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，并且

  • 预算检查：此密钥将检查 krrish3@berri.ai 的预算（例如 10 美元）
  • 支出跟踪：此密钥的支出也会更新 krrish3@berri.ai 的支出情况
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 的发布设置每日护栏（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 时间午夜

通过仪表板

打开 虚拟密钥 → 创建密钥 → 可选设置 → 预算窗口。

Step 1 - open key settings

点击 + 添加预算窗口 添加一行，从下拉菜单中选择周期，并输入支出上限。

Step 2 - add a window

添加第二行以设置不同的时间周期（例如，在每日 10 美元的基础上，每月 100 美元）。

Step 3 - add second window

每个窗口都会在输入框下方显示重置时间表，因此始终清楚支出何时重置。

Step 4 - reset hints

✨ 虚拟密钥（模型特定）​

在密钥上应用特定于模型的预算。示例

  • 对于 key = "sk-12345"，gpt-4o 在 1d 时间周期内的预算为 0.0000001 美元
  • 对于 key = "sk-12345"，gpt-4o-mini 在 30d 时间周期内的预算为 10 美元
信息

✨ 这是企业版专属功能 在此开始使用企业版

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"}}
}'

进行测试请求​

我们预计第一次请求会成功，而第二次请求会失败，因为我们超过了虚拟密钥上 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"
        }
      ]
    }
'

代理​

为在 LiteLLM 代理网关上注册的代理设置预算和速率限制。您可以控制

  • 每代理速率限制：代理本身的 tpm_limit 和 rpm_limit
  • 每会话速率限制：按会话应用的 session_tpm_limit 和 session_rpm_limit
  • 每会话迭代上限：代理 litellm_params 中的 max_iterations
  • 每会话预算上限：代理 litellm_params 中的 max_budget_per_session

在代理上设置 tpm_limit 和 rpm_limit 以限制所有会话的总吞吐量。

curl -X POST 'https://: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 'https://: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/completions 的 user 设置预算，无需为每个用户创建一个密钥

第 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_time 和 proxy_budget_rescheduler_max_time

例如：每 1 秒检查一次

general_settings: 
  proxy_budget_rescheduler_min_time: 1
  proxy_budget_rescheduler_max_time: 1

设置速率限制​

您可以设置

  • tpm 限制（每分钟 Token 数）
  • rpm 限制（每分钟请求数）
  • 最大并行请求数
  • 给定密钥或团队的每个模型的 rpm / tpm 限制

TPM 速率限制类型（输入/输出/总计）​

默认情况下，TPM（每分钟 Token 数）速率限制计算总 Token 数（输入 + 输出）。您可以将其配置为仅计算输入 Token 或仅计算输出 Token。

在您的 config.yaml 中设置 token_rate_limit_type

general_settings:
  master_key: sk-1234
  token_rate_limit_type: "output"  # Options: "input", "output", "total" (default)
值描述
total计算总 Token 数（提示词 + 完成词）。默认行为。
input仅计算提示词/输入 Token
output仅计算完成词/输出 Token

此设置全局适用于所有 TPM 速率限制检查（密钥、用户、团队等）。

使用 /team/new 或 /team/update，以便在团队的多个密钥中持久化速率限制。

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",
}

为所有内部用户设置默认预算​

使用此功能可为拥有密钥的用户设置默认预算。

当用户拥有 user_role="internal_user"（通过 /user/new 或 /user/update 设置）时，这将适用。

如果密钥有 team_id，则此设置不适用（此时适用团队预算）。告诉我们如何改进这一点！

  1. 在 config.yaml 中定义最大预算
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. 为用户创建密钥
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"
    }
}

多实例速率限制​

重要提示

  • 速率限制不适用于代理管理员用户。
  • 测试速率限制时，请使用内部用户角色（非管理员），以确保限制按预期执行。

变更

  • 这在更新当前请求/Token 时改为使用 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 'https://: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)：以美元为单位的最高预算金额
  • time_period (str)：指定预算时间周期的持续时间字符串。支持的格式
    • 秒："30s"
    • 分钟："30m"
    • 小时："30h"
    • 天："30d"

示例：​

{
  "budget_limit": "0.0001",
  "time_period": "1d"
}
🚅
LiteLLM 企业版
SSO/SAML、审计日志、支出跟踪、多团队管理和护栏 —— 专为生产环境构建。
了解更多 →