动态 TPM/RPM 分配

防止项目消耗过多的 tpm/rpm。

另请参阅： 请求优先级排序 - 通过将高流量下的 LLM API 请求添加到优先级队列中来设置其优先级。

根据每一分钟内的活跃密钥，为 API 密钥动态分配 TPM/RPM 配额。查看代码

快速入门用法

设置 config.yaml

config.yaml
model_list: 
  - model_name: my-fake-model
    litellm_params:
      model: gpt-3.5-turbo
      api_key: my-fake-key
      mock_response: hello-world
      tpm: 60

litellm_settings: 
  callbacks: ["dynamic_rate_limiter_v3"]

general_settings:
  master_key: sk-1234 # OR set `LITELLM_MASTER_KEY=".."` in your .env
  database_url: postgres://.. # OR set `DATABASE_URL=".."` in your .env

启动代理

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

测试它！

test.py
"""
- Run 2 concurrent teams calling same model
- model has 60 TPM
- Mock response returns 30 total tokens / request
- Each team will only be able to make 1 request per minute
"""

import requests
from openai import OpenAI, RateLimitError

def create_key(api_key: str, base_url: str): 
    response = requests.post(
        url="{}/key/generate".format(base_url), 
        json={},
        headers={
            "Authorization": "Bearer {}".format(api_key)
        }
    )

    _response = response.json()

    return _response["key"]

key_1 = create_key(api_key="sk-1234", base_url="http://0.0.0.0:4000")
key_2 = create_key(api_key="sk-1234", base_url="http://0.0.0.0:4000")

# call proxy with key 1 - works
openai_client_1 = OpenAI(api_key=key_1, base_url="http://0.0.0.0:4000")

response = openai_client_1.chat.completions.with_raw_response.create(
    model="my-fake-model", messages=[{"role": "user", "content": "Hello world!"}],
)

print("Headers for call 1 - {}".format(response.headers))
_response = response.parse()
print("Total tokens for call - {}".format(_response.usage.total_tokens))


# call proxy with key 2 -  works 
openai_client_2 = OpenAI(api_key=key_2, base_url="http://0.0.0.0:4000")

response = openai_client_2.chat.completions.with_raw_response.create(
    model="my-fake-model", messages=[{"role": "user", "content": "Hello world!"}],
)

print("Headers for call 2 - {}".format(response.headers))
_response = response.parse()
print("Total tokens for call - {}".format(_response.usage.total_tokens))
# call proxy with key 2 -  fails
try:  
    openai_client_2.chat.completions.with_raw_response.create(model="my-fake-model", messages=[{"role": "user", "content": "Hey, how's it going?"}])
    raise Exception("This should have failed!")
except RateLimitError as e: 
    print("This was rate limited b/c - {}".format(str(e)))

预期响应

This was rate limited b/c - Error code: 429 - {'error': {'message': {'error': 'Key=<hashed_token> over available TPM=0. Model TPM=0, Active keys=2'}, 'type': 'None', 'param': 'None', 'code': 429}}

[测试版] 设置优先级 / 预留配额

为不同的环境或用例预留 TPM/RPM 容量。这可以确保关键的生产工作负载始终拥有保证的容量，而开发任务或低优先级任务则使用剩余的配额。

用例

生产环境 vs 开发环境
实时应用程序 vs 批处理
关键服务 vs 实验性功能

提示

基于优先级预留密钥的 TPM/RPM 是一项高级功能。请获取企业许可证以使用此功能。

优先级预留的工作原理

优先级预留将模型总 TPM/RPM 的一部分分配给特定的优先级级别。具有更高优先级的密钥将优先获得其预留配额的保证访问权。

示例场景

模型总容量为 10 RPM
优先级预留：{"prod": 0.9, "dev": 0.1}
结果：生产密钥获得 9 RPM 的保证，开发密钥获得 1 RPM 的保证

配置

1. 设置 config.yaml

config.yaml
model_list:
  - model_name: gpt-3.5-turbo             
    litellm_params:
      model: "gpt-3.5-turbo"       
      api_key: os.environ/OPENAI_API_KEY 
      rpm: 10   # Total model capacity

litellm_settings:
  callbacks: ["dynamic_rate_limiter_v3"]
  priority_reservation:
    "prod": 0.9 # 90% reserved for production (9 RPM)
    "dev": 0.1 # 10% reserved for development (1 RPM)
    # Alternative format:
    # "prod":
    #   type: "rpm"    # Reserve based on requests per minute
    #   value: 9       # 9 RPM = 90% of 10 RPM capacity
    # "dev":
    #   type: "tpm"    # Reserve based on tokens per minute
    #   value: 100     # 100 TPM
  priority_reservation_settings:
    default_priority: 0  # Weight (0%) assigned to keys without explicit priority metadata
    saturation_threshold: 0.50 #  A model is saturated if it has hit 50% of its RPM limit
    saturation_check_cache_ttl: 60 # How long (seconds) saturation values are cached locally

general_settings:
  master_key: sk-1234 # OR set `LITELLM_MASTER_KEY=".."` in your .env
  database_url: postgres://.. # OR set `DATABASE_URL=".."` in your.env

配置详情

priority_reservation: Dict[str, Union[float, PriorityReservationDict]]

键 (str): 优先级级别名称（可以是任何字符串，如 "prod", "dev", "critical" 等）
值: 浮点数 (0.0-1.0) 或包含 type 和 value 的字典
- 浮点数: 0.9 = 容量的 90%
- 字典: {"type": "rpm", "value": 9} = 9 次请求/分钟
- 支持的类型: "percent", "rpm", "tpm"

priority_reservation_settings: 对象 (可选)

default_priority (float): 分配给未设置优先级元数据的 API 密钥的权重/百分比（0.0 到 1.0，默认为 0.5）
saturation_threshold (float): 模型开始执行严格优先级限制的饱和度水平（0.0 到 1.0）。饱和度计算公式为 max(current_rpm/max_rpm, current_tpm/max_tpm)。在此阈值以下，宽容模式允许优先级借用未使用的容量。在此阈值以上，严格模式强制执行标准化的优先级限制。
- 示例：当模型使用率较低时，密钥可以使用超过其分配的份额。当模型使用率较高时，密钥会被严格限制在其分配的份额内。
saturation_check_cache_ttl (int): 从 Redis 读取饱和度值时的本地缓存 TTL（以秒为单位，默认为 60）。在多节点部署中，这控制了节点收敛到相同饱和状态的速度。较低的值意味着更快的收敛速度，但会增加 Redis 读取次数。
- 示例：设置为 5 以获得更快的跨节点一致性，或设置为 0 以始终直接从 Redis 读取。

启动 Proxy

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

在团队或密钥上设置优先级

可以在团队级别或密钥级别设置优先级。团队级优先级优先于密钥级优先级。

选项 A：在团队上设置优先级（推荐）

团队内的所有密钥都将继承该团队的优先级。当你希望特定环境或项目的所有密钥具有相同优先级时，这非常有用。

curl -X POST 'http://0.0.0.0:4000/team/new' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
  "team_alias": "production-team",
  "metadata": {"priority": "prod"}
}'

为该团队创建密钥

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
  "team_id": "team-id-from-previous-response"
}'

选项 B：在单个密钥上设置优先级

直接在密钥上设置优先级。当需要对每个密钥进行精细控制时，这非常有用。

生产密钥

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
  "metadata": {"priority": "prod"}
}'

开发密钥

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
  "metadata": {"priority": "dev"}
}'

无优先级的密钥（使用 default_priority 权重）

curl -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{}'

预期响应

{
  "key": "sk-...",
  "metadata": {"priority": "prod"}, // or "dev"
  ...
}

优先级解析顺序

如果密钥属于设置了 metadata.priority 的团队 → 使用团队优先级
否则，如果密钥设置了 metadata.priority → 使用密钥优先级
否则 → 使用配置中的 default_priority

3. 测试优先级分配

测试生产密钥（应获得 9 RPM）

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-prod-key' \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello from prod"}]
  }'

测试开发密钥（应获得 1 RPM）

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-dev-key' \
  -d '{
    "model": "gpt-3.5-turbo", 
    "messages": [{"role": "user", "content": "Hello from dev"}]
  }'

预期行为

使用上述配置

生产密钥每分钟最多可进行 9 次请求（10 RPM 的 90%）
开发密钥每分钟最多可进行 1 次请求（10 RPM 的 10%）
未明确指定优先级的密钥将获得 default_priority 权重（0 = 0%），即每分钟分配 0 次请求（10 RPM 的 0%）
priority_reservation 中的命名优先级与带有 default_priority 的密钥是独立运行的

速率限制错误示例

{
  "error": {
    "message": "Key=sk-dev-... over available RPM=0. Model RPM=10, Reserved RPM for priority 'dev'=1, Active keys=1",
    "type": "rate_limit_exceeded",
    "code": 429
  }
}

演示视频

此视频介绍了如何通过优先级预留和 locust 测试来设置动态速率限制，以验证该行为。

快速入门用法​

[测试版] 设置优先级 / 预留配额​

优先级预留的工作原理​

配置​

1. 设置 config.yaml​

在团队或密钥上设置优先级​

3. 测试优先级分配​

预期行为​

演示视频​