跳至主要内容

消费跟踪

跟踪跨 100 多个大模型（LLM）的密钥、用户和团队的支出情况。

LiteLLM 会自动跟踪所有已知模型的支出。请参阅我们的 模型成本映射表

当响应包含层级元数据时，系统会自动应用特定于提供商的成本跟踪（例如：Vertex AI PayGo / 优先级定价、Bedrock 服务层级、Azure 基准模型映射）。

保持定价数据更新

从 GitHub 同步模型定价数据，以确保成本跟踪的准确性。

成本与提供商账单不符？

请使用 成本差异调试 中的分步工作流：校准时间范围，比较令牌类别（包括缓存），然后判断差异是源于摄入量、公式还是模型映射定价。

如何使用 LiteLLM 跟踪支出​

步骤 1

👉 设置 LiteLLM 数据库

步骤 2 发送 /chat/completions 请求

使用支出跟踪功能发送请求
import openai
client = openai.OpenAI(
    api_key="sk-1234",
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="llama3",
    messages = [
        {
            "role": "user",
            "content": "this is a test request, write a short poem"
        }
    ],
    user="palantir", # OPTIONAL: pass user to track spend by user
    extra_body={
        "metadata": {
            "tags": ["jobID:214590dsff09fds", "taskName:run_page_classification"] # ENTERPRISE: pass tags to track spend by tags
        }
    }
)

print(response)

步骤 3 - 验证支出跟踪 完成了。现在验证您的支出是否已被成功跟踪

预期的响应头中应包含 x-litellm-response-cost 以及计算出的成本

允许非代理管理员访问 /spend 终端点​

当您需要非代理管理员访问 /spend 终端点时使用此功能

信息

预约会议以获取企业许可证

创建密钥​

创建带有 permissions={"get_spend_routes": true} 的密钥

生成带有支出路由权限的密钥
curl --location 'http://0.0.0.0:4000/key/generate' \
        --header 'Authorization: Bearer sk-1234' \
        --header 'Content-Type: application/json' \
        --data '{
            "permissions": {"get_spend_routes": true}
    }'
在 /spend 终端点上使用生成的密钥​

使用新生成的密钥访问支出路由

curl -X GET 'https://:4000/global/spend/report?start_date=2024-04-01&end_date=2024-06-30' \
  -H 'Authorization: Bearer sk-H16BKvrSNConSsBYLGc_7A'

重置团队、API 密钥支出 - 仅限主密钥 (MASTER KEY)​

如果您希望执行以下操作，请使用 /global/spend/reset

  • 重置所有 API 密钥和团队的支出。LiteLLM_TeamTable 和 LiteLLM_VerificationToken 中所有团队和密钥的 spend 将被设置为 spend=0

  • LiteLLM 将保留 LiteLLMSpendLogs 中的所有日志以供审计使用

请求​

只有您设置的 LITELLM_MASTER_KEY 才能访问此路由

curl -X POST \
  'https://:4000/global/spend/reset' \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json'
预期响应​
{"message":"Spend for all API Keys and Teams reset successfully","status":"success"}

每个用户的总支出​

假设您一直在为终端用户颁发密钥，并已在密钥上设置了 user_id，您可以检查他们的使用情况。

获取用户支出 - API 请求
curl -L -X GET 'https://:4000/user/info?user_id=jane_smith' \
-H 'Authorization: Bearer sk-...'
用户总支出 API 响应
{
  "user_id": "jane_smith",
  "user_info": {
    "spend": 0.1
  },
  "keys": [
    {
      "token": "6e952b0efcafbb6350240db25ed534b4ec6011b3e1ba1006eb4f903461fd36f6",
      "key_name": "sk-...KE_A",
      "key_alias": "user-01882d6b-e090-776a-a587-21c63e502670-01983ddb-872f-71a3-8b3a-f9452c705483",
      "soft_budget_cooldown": false,
      "spend": 0.1,
      "expires": "2025-07-31T19:14:13.968000+00:00",
      "models": [],
      "aliases": {},
      "config": {},
      "user_id": "01982d6b-e090-776a-a587-21c63e502660",
      "team_id": "f2044fde-2293-482f-bf35-a8dab4e85c5f",
      "permissions": {},
      "max_parallel_requests": null,
      "metadata": {},
      "blocked": null,
      "tpm_limit": null,
      "rpm_limit": null,
      "max_budget": null,
      "budget_duration": null,
      "budget_reset_at": null,
      "allowed_cache_controls": [],
      "allowed_routes": [],
      "model_spend": {},
      "model_max_budget": {},
      "budget_id": null,
      "organization_id": null,
      "object_permission_id": null,
      "created_at": "2025-07-24T19:14:13.970000Z",
      "created_by": "582b168f-fc11-4e14-ad6a-cf4bb3656ddc",
      "updated_at": "2025-07-24T19:14:13.970000Z",
      "updated_by": "582b168f-fc11-4e14-ad6a-cf4bb3656ddc",
      "litellm_budget_table": null,
      "litellm_organization_table": null,
      "object_permission": null,
      "team_alias": null
    }
  ],
  "teams": []
}

警告 终端用户可以在其请求体中提供 user 参数，这样做会增加通过 /customer/info?end_user_id=self-declared-user 报告的成本，而不是该 API 报告的密钥所有者的成本。这意味着用户可以通过这种方式“规避”他们的支出跟踪。这意味着如果您需要跟踪用户支出，且正在向终端用户发放 API 密钥，您必须在创建 API 密钥时始终设置 user_id，并在后端服务代表他们进行 LLM 调用时始终使用为该用户发放的密钥。这样才能准确跟踪他们的支出。

每日支出明细 API​

通过单个终端点检索用户的细粒度每日使用数据（按模型、提供商和 API 密钥）。

示例请求

每日支出明细 API
curl -L -X GET 'https://:4000/user/daily/activity?start_date=2025-03-20&end_date=2025-03-27' \
-H 'Authorization: Bearer sk-...'
每日支出明细 API 响应
{
    "results": [
        {
            "date": "2025-03-27",
            "metrics": {
                "spend": 0.0177072,
                "prompt_tokens": 111,
                "completion_tokens": 1711,
                "total_tokens": 1822,
                "api_requests": 11
            },
            "breakdown": {
                "models": {
                    "gpt-4o-mini": {
                        "spend": 1.095e-05,
                        "prompt_tokens": 37,
                        "completion_tokens": 9,
                        "total_tokens": 46,
                        "api_requests": 1
                },
                "providers": { "openai": { ... }, "azure_ai": { ... } },
                "api_keys": { "3126b6eaf1...": { ... } }
            }
        }
    ],
    "metadata": {
        "total_spend": 0.7274667,
        "total_prompt_tokens": 280990,
        "total_completion_tokens": 376674,
        "total_api_requests": 14
    }
}

API 参考​

请参阅我们的 Swagger API，了解有关 /user/daily/activity 终端点的更多详细信息

自定义标签​

查看完整的请求标签文档

有关所有标签选项（包括 x-litellm-tags 请求头、请求体 tags 以及基于配置的标签）的完整文档，请参阅专门的 请求标签 (Request Tags) 页面。

要求

  • 应设置虚拟密钥和数据库，请参阅 虚拟密钥

注意： 默认情况下，LiteLLM 会将 User-Agent 作为成本跟踪的自定义标签。这使得您可以查看 Claude Code、Gemini CLI 等工具的使用情况。

客户端支出标签​

curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "metadata": {
        "tags": ["tag1", "tag2", "tag3"]
    }
}

'

为支出跟踪添加自定义请求头​

您可以向请求添加自定义标头，以跟踪支出和使用情况。

litellm_settings:
  extra_spend_tag_headers:
    - "x-custom-header"

禁用 User-Agent 跟踪​

您可以将 litellm_settings.disable_add_user_agent_to_request_tags 设置为 true 来禁用 User-Agent 跟踪。

litellm_settings:
  disable_add_user_agent_to_request_tags: true

✨ (企业版) 生成支出报告​

使用此功能向其他团队、客户和用户收费

使用 /global/spend/report 终端点获取支出报告

示例请求​

👉 关键更改：指定 group_by=team

curl -X GET 'https://:4000/global/spend/report?start_date=2024-04-01&end_date=2024-06-30&group_by=team' \
  -H 'Authorization: Bearer sk-1234'

响应示例​

[
    {
        "group_by_day": "2024-04-30T00:00:00+00:00",
        "teams": [
            {
                "team_name": "Prod Team",
                "total_spend": 0.0015265,
                "metadata": [ # see the spend by unique(key + model)
                    {
                        "model": "gpt-4",
                        "spend": 0.00123,
                        "total_tokens": 28,
                        "api_key": "88dc28.." # the hashed api key
                    },
                    {
                        "model": "gpt-4",
                        "spend": 0.00123,
                        "total_tokens": 28,
                        "api_key": "a73dc2.." # the hashed api key
                    },
                    {
                        "model": "chatgpt-v-2",
                        "spend": 0.000214,
                        "total_tokens": 122,
                        "api_key": "898c28.." # the hashed api key
                    },
                    {
                        "model": "gpt-3.5-turbo",
                        "spend": 0.0000825,
                        "total_tokens": 85,
                        "api_key": "84dc28.." # the hashed api key
                    }
                ]
            }
        ]
    }
]

📊 支出日志 API - 单笔交易日志​

/spend/logs 终端点现在支持 summarize 参数，以便在使用日期过滤器时控制数据格式。

关键参数​

参数描述
summarize新参数：true（默认）= 聚合数据，false = 单笔交易日志

示例​

获取单笔交易日志

获取单笔交易日志
curl -X GET "https://:4000/spend/logs?start_date=2024-01-01&end_date=2024-01-02&summarize=false" \
-H "Authorization: Bearer sk-1234"

获取摘要数据（默认）

获取摘要支出数据
curl -X GET "https://:4000/spend/logs?start_date=2024-01-01&end_date=2024-01-02" \
-H "Authorization: Bearer sk-1234"

用例

  • summarize=false：分析仪表板、ETL 流程、详细审计追踪
  • summarize=true：每日支出报告、高层级成本跟踪（旧版行为）

✨ 自定义支出日志元数据​

将特定的键值对作为支出日志元数据的一部分进行记录

信息

在支出日志元数据中记录特定键值对是一项企业级功能。

要求

  • 应设置虚拟密钥和数据库，请参阅 虚拟密钥

用法 - 带有特殊支出日志元数据的 /chat/completions 请求​

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

'

查看带有自定义元数据的支出​

/spend/logs 请求格式​

curl -X GET "http://0.0.0.0:4000/spend/logs?request_id=<your-call-id" \ # e.g.: chatcmpl-9ZKMURhVYSi9D6r6PJ9vLcayIK0Vm
-H "Authorization: Bearer sk-1234"

/spend/logs 响应格式​

[
    {
        "request_id": "chatcmpl-9ZKMURhVYSi9D6r6PJ9vLcayIK0Vm",
        "call_type": "acompletion",
        "metadata": {
            "user_api_key": "example-api-key-123",
            "user_api_key_alias": null,
            "spend_logs_metadata": { # 👈 LOGGED CUSTOM METADATA
                "hello": "world"
            },
            "user_api_key_team_id": null,
            "user_api_key_user_id": "116544810872468347480",
            "user_api_key_team_alias": null
        },
    }
]
🚅
LiteLLM 企业版
SSO/SAML、审计日志、支出跟踪、多团队管理和护栏 —— 专为生产环境构建。
了解更多 →