设置标签预算

通过标签跟踪支出并为您的 API 请求设置预算。标签允许您跨不同的成本中心、项目和部门对成本进行分类和监控。

先决条件

• 您必须设置一个 Postgres 数据库（例如 Supabase、Neon 等）

什么是标签？

标签是您可以附加到 LLM 请求上的标记，用于按类别跟踪和限制支出。

常见用例

• 成本中心跟踪：将 LLM 成本分配给特定部门或业务单元（例如：“工程”、“市场营销”、“客户支持”）
• 基于项目的预算：为不同的项目或计划设置预算（例如：“project-alpha”、“chatbot-v2”）
• 客户归属：按客户或委托方跟踪支出（例如：“customer-acme”、“customer-techcorp”）
• 功能监控：监控特定功能的成本（例如：“feature-chat”、“feature-summarization”）

标签被添加到每个请求的 metadata 字段中，以跟踪和强制执行预算限制。

设置标签预算

1. 创建带预算的标签

创建一个标签以代表成本中心、项目或任何预算类别。设置 max_budget（允许的美元金额）和 budget_duration（预算重置的频率）。

示例：为您的工程部门创建一个每月 500 美元预算的标签

API

创建一个新标签并设置 max_budget 和 budget_duration

curl -X POST 'http://0.0.0.0:4000/tag/new' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
            "name": "engineering", 
            "description": "Engineering department cost center",
            "max_budget": 500.0, 
            "budget_duration": "30d"
        }' 

请求体参数

参数	类型	必需	描述
name	string	是	标签的唯一名称（例如：成本中心名称）
description	string	否	此标签跟踪内容的描述
models	list[string]	否	将标签限制为特定模型
max_budget	float	否	最高预算（美元）
budget_duration	string	否	预算重置的频率（例如：“30d”、“1d”）
soft_budget	float	否	用于警告的软预算限制

响应

{
  "name": "engineering",
  "description": "Engineering department cost center",
  "max_budget": 500.0,
  "budget_duration": "30d",
  "budget_reset_at": "2025-11-10T00:00:00Z",
  "created_at": "2025-10-11T00:00:00Z"
}  

LiteLLM 管理 UI

导航至标签管理页面并点击创建新标签。填写标签详细信息并设置您的预算

budget_duration 的可选值

budget_duration	预算重置时间
budget_duration="1s"	每 1 秒
budget_duration="1m"	每 1 分钟
budget_duration="1h"	每 1 小时
budget_duration="1d"	每 1 天
budget_duration="7d"	每 1 周
budget_duration="30d"	每 1 个月

2. 在请求中使用标签

将标签添加到 API 请求的 metadata 字段中

API 密钥上的标签预算

目前，标签预算强制执行仅支持按请求进行。如果您希望在 API 密钥上设置标签，以便所有请求自动继承标签预算，请在 GitHub 上提交功能请求。

OpenAI SDK

import openai

client = openai.OpenAI(
    api_key="sk-1234",  # Your LiteLLM proxy key
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "metadata": {
            "tags": ["engineering"]
        }
    }
)

cURL

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "model": "gpt-4",
           "messages": [{"role": "user", "content": "Hello"}],
           "metadata": {
               "tags": ["engineering"]
           }
         }'

3. 测试它

持续发起请求直到超过预算

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "model": "gpt-4",
           "messages": [{"role": "user", "content": "Hello"}],
           "metadata": {
               "tags": ["engineering"]
           }
         }'

当超过预算时，您将看到

{
  "error": {
    "message": "Budget has been exceeded! Tag=engineering Current cost: 505.50, Max budget: 500.0",
    "type": "budget_exceeded",
    "param": null,
    "code": "400"
  }
}

管理标签

查看标签信息

获取有关特定标签的信息

curl -X POST 'http://0.0.0.0:4000/tag/info' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "names": ["engineering", "marketing"]
         }'

响应

{
  "engineering": {
    "name": "engineering",
    "description": "Engineering department cost center",
    "spend": 245.50,
    "max_budget": 500.0,
    "budget_duration": "30d",
    "budget_reset_at": "2025-11-10T00:00:00Z",
    "created_at": "2025-10-11T00:00:00Z",
    "updated_at": "2025-10-11T12:30:00Z"
  },
  "marketing": {
    "name": "marketing",
    "description": "Marketing department cost center",
    "spend": 89.20,
    "max_budget": 300.0,
    "budget_duration": "30d",
    "budget_reset_at": "2025-11-10T00:00:00Z",
    "created_at": "2025-10-11T00:00:00Z",
    "updated_at": "2025-10-11T12:30:00Z"
  }
}

更新标签预算

更新现有标签的预算

curl -X POST 'http://0.0.0.0:4000/tag/update' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "engineering",
           "max_budget": 750.0,
           "budget_duration": "30d"
         }'

删除标签

curl -X POST 'http://0.0.0.0:4000/tag/delete' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "engineering"
         }'

每个请求支持多个标签

您可以将多个标签应用于单个请求，以同时跨不同维度跟踪成本。例如，同时跟踪成本中心和特定项目

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "metadata": {
            "tags": ["engineering", "project-alpha", "customer-acme"]
        }
    }
)

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "model": "gpt-4",
           "messages": [{"role": "user", "content": "Hello"}],
           "metadata": {
               "tags": ["engineering", "project-alpha", "customer-acme"]
           }
         }'

预算强制执行：如果任何标签超过其预算，请求将被拒绝。