跳至主要內容

客戶／終端使用者

追蹤花費、為您的客戶設定預算與權限。

追蹤客戶花費 + 權限​

1. 使用客戶 ID 發出 LLM API 請求​

LiteLLM 依照以下順序檢查客戶／終端使用者 ID（以第一個符合者為準）：

優先順序方法位置備註
1x-litellm-customer-id 標頭請求標頭標準標頭，一律檢查
2x-litellm-end-user-id 標頭請求標頭標準標頭，一律檢查
3透過 user_header_mappings 的自訂標頭請求標頭在 general_settings 中設定
4透過 user_header_name 的自訂標頭請求標頭已棄用 — 請改用 user_header_mappings
5user 欄位請求主體標準 OpenAI 欄位
6litellm_metadata.user 欄位請求主體Anthropic 風格的中繼資料
7metadata.user_id 欄位請求主體通用中繼資料模式
8safety_identifier 欄位請求主體Responses API

選項 1：標準標頭（建議 — 不需要修改請求主體）

Make request with customer ID in header
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer sk-1234' \
        --header 'x-litellm-end-user-id: ishaan3' \
        --data '{
        "model": "azure-gpt-3.5",
        "messages": [{"role": "user", "content": "what time is it"}]
        }'

x-litellm-customer-id 和 x-litellm-end-user-id 都受支援，且一律會在不需任何設定的情況下檢查。

選項 2：請求主體中的 user 欄位（相容 OpenAI）

Make request with customer ID in body
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer sk-1234' \
        --data '{
        "model": "azure-gpt-3.5",
        "user": "ishaan3",
        "messages": [{"role": "user", "content": "what time is it"}]
        }'

選項 3：透過 user_header_mappings 的自訂標頭（可設定）

config.yaml
general_settings:
  user_header_mappings:
    - header_name: "x-my-app-user-id"
      litellm_user_role: "customer"
Make request with custom header
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer sk-1234' \
        --header 'x-my-app-user-id: ishaan3' \
        --data '{
        "model": "azure-gpt-3.5",
        "messages": [{"role": "user", "content": "what time is it"}]
        }'

選項 4：litellm_metadata.user（Anthropic 風格）

Make request with litellm_metadata.user
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer sk-1234' \
        --data '{
        "model": "claude-3-5-sonnet",
        "messages": [{"role": "user", "content": "what time is it"}],
        "litellm_metadata": {"user": "ishaan3"}
        }'

選項 5：metadata.user_id

Make request with metadata.user_id
curl -X POST 'http://0.0.0.0:4000/chat/completions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer sk-1234' \
        --data '{
        "model": "azure-gpt-3.5",
        "messages": [{"role": "user", "content": "what time is it"}],
        "metadata": {"user_id": "ishaan3"}
        }'

customer_id 會隨著新的花費 upsert 到資料庫中。

如果 customer_id 已存在，花費將會累加。

2. 取得客戶花費​

呼叫 /customer/info 以取得客戶的總花費

Get customer spend
curl -X GET 'http://0.0.0.0:4000/customer/info?end_user_id=ishaan3' \ # 👈 CUSTOMER ID
        -H 'Authorization: Bearer sk-1234' \ # 👈 YOUR PROXY KEY

預期回應：

Response
{
    "user_id": "ishaan3",
    "blocked": false,
    "alias": null,
    "spend": 0.001413,
    "allowed_model_region": null,
    "default_model": null,
    "litellm_budget_table": null
}

設定客戶物件權限​

控制客戶可存取哪些資源（MCP 伺服器、向量儲存、代理程式）。

什麼是物件權限？​

物件權限可讓您限制客戶對特定項目的存取：

  • MCP 伺服器：限制客戶可呼叫哪些 MCP 伺服器
  • MCP 存取群組：將客戶指派至預先定義的 MCP 伺服器群組
  • MCP 工具權限：細緻控制客戶可在 MCP 伺服器中使用哪些工具
  • 向量儲存：控制客戶可查詢哪些向量儲存
  • 代理程式：限制客戶可互動的代理程式
  • 代理程式存取群組：將客戶指派至預先定義的代理程式群組

建立具有物件權限的客戶​

Create customer with object permissions
curl -L -X POST 'http://localhost:4000/customer/new' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "user_1",
    "object_permission": {
      "mcp_servers": ["server_1", "server_2"],
      "mcp_access_groups": ["public_group"],
      "mcp_tool_permissions": {
        "server_1": ["tool_a", "tool_b"]
      },
      "vector_stores": ["vector_store_1"],
      "agents": ["agent_1"],
      "agent_access_groups": ["basic_agents"]
    }
  }'

參數：

  • mcp_servers (Optional[List[str]]): 允許的 MCP 伺服器 ID 清單
  • mcp_access_groups (Optional[List[str]]): MCP 存取群組名稱清單
  • mcp_tool_permissions (Optional[Dict[str, List[str]]]): 伺服器 ID 對允許工具名稱的對應
  • vector_stores (Optional[List[str]]): 允許的向量儲存 ID 清單
  • agents (Optional[List[str]]): 允許的代理程式 ID 清單
  • agent_access_groups (Optional[List[str]]): 代理程式存取群組名稱清單

**注意：**如果 object_permission 是 null 或 {}，則該客戶沒有物件層級限制。

更新客戶物件權限​

您可以更新既有客戶的物件權限：

Update customer object permissions
curl -L -X POST 'http://localhost:4000/customer/update' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "user_1",
    "object_permission": {
      "mcp_servers": ["server_3"],
      "vector_stores": ["vector_store_2", "vector_store_3"]
    }
  }'

檢視客戶物件權限​

當您查詢客戶資訊時，回應中會包含物件權限：

Get customer info with object permissions
curl -X GET 'http://0.0.0.0:4000/customer/info?end_user_id=user_1' \
    -H 'Authorization: Bearer sk-1234'

回應：

Response with object permissions
{
  "user_id": "user_1",
  "blocked": false,
  "alias": "John Doe",
  "spend": 0.0,
  "object_permission": {
    "object_permission_id": "perm_abc123",
    "mcp_servers": ["server_1", "server_2"],
    "mcp_access_groups": ["public_group"],
    "mcp_tool_permissions": {
      "server_1": ["tool_a", "tool_b"]
    },
    "vector_stores": ["vector_store_1"],
    "agents": ["agent_1"],
    "agent_access_groups": ["basic_agents"]
  },
  "litellm_budget_table": null
}

使用案例​

1. 分級存取控制 為您的客戶建立不同的權限等級：

Free tier customer
# Free tier - limited access
curl -L -X POST 'http://localhost:4000/customer/new' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "free_user",
    "budget_id": "free_tier",
    "object_permission": {
      "mcp_access_groups": ["public_group"],
      "agent_access_groups": ["basic_agents"]
    }
  }'
Premium tier customer
# Premium tier - full access
curl -L -X POST 'http://localhost:4000/customer/new' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "premium_user",
    "budget_id": "premium_tier",
    "object_permission": {
      "mcp_servers": ["server_1", "server_2", "server_3"],
      "vector_stores": ["vector_store_1", "vector_store_2"],
      "agents": ["agent_1", "agent_2", "agent_3"]
    }
  }'

2. 部門專屬存取 將客戶限制在與其部門相關的資源：

Sales team customer
curl -L -X POST 'http://localhost:4000/customer/new' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "sales_user",
    "object_permission": {
      "mcp_servers": ["crm_server", "email_server"],
      "agents": ["sales_assistant"],
      "vector_stores": ["sales_knowledge_base"]
    }
  }'

3. 工具層級限制 授予對 MCP 伺服器內特定工具的存取：

Limited tool access
curl -L -X POST 'http://localhost:4000/customer/new' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "user_id": "restricted_user",
    "object_permission": {
      "mcp_servers": ["database_server"],
      "mcp_tool_permissions": {
        "database_server": ["read_only_query", "get_table_schema"]
      }
    }
  }'

設定客戶預算​

在 LiteLLM Proxy 上設定客戶預算（例如每月預算、tpm/rpm 限制）

所有客戶的預設預算​

將預算限制套用至所有沒有明確預算的客戶。這對於在所有終端使用者之間進行速率限制與花費控制很有用。

步驟 1：建立預設預算

Create default budget
curl -X POST 'http://localhost:4000/budget/new' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-1234' \
-d '{
    "max_budget": 10,
    "rpm_limit": 2,
    "tpm_limit": 1000
}'

步驟 2：設定預設預算 ID

config.yaml
litellm_settings:
  max_end_user_budget_id: "budget_id_from_step_1"

步驟 3：測試它

Make request with customer ID
curl -X POST 'http://localhost:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-1234' \
-d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "user": "my-customer-id"
}'

客戶將受到預設預算限制（RPM、TPM 和 $ 預算）的約束。具有明確預算的客戶不受影響。

快速入門​

建立／更新具有預算的客戶

建立新客戶並附加預算

Create customer with budget
curl -X POST 'http://0.0.0.0:4000/customer/new'         
    -H 'Authorization: Bearer sk-1234'         
    -H 'Content-Type: application/json'         
    -d '{
        "user_id" : "my-customer-id",
        "max_budget": "0", # 👈 CAN BE FLOAT
    }'

測試它！

Test customer budget
curl -X POST 'http://localhost:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-1234' \
-D '{
    "model": "mistral",
    "messages": [
        {
        "role": "user",
        "content": "What'\''s the weather like in Boston today?"
        }
    ],
    "user": "ishaan-jaff-48"
}

指派定價層級​

建立並將客戶指派至定價層級。

1. 建立預算​

  • 前往 UI 上的 'Budgets' 分頁。
  • 點選 '+ Create Budget'。
  • 建立您的定價層級（例如，'my-free-tier'，預算為 $4）。這表示此定價層級上的每位使用者最高預算為 $4。

2. 將預算指派給客戶​

在您的應用程式程式碼中，於建立新客戶時指派預算。

只要使用建立預算時所用的 budget_id。在我們的範例中，這是 my-free-tier。

Assign budget to customer
curl -X POST 'http://localhost:4000/customer/new' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-1234' \
-D '{
    "user_id": "my-customer-id",
    "budget_id": "my-free-tier" # 👈 KEY CHANGE
}

3. 測試它！​

Test with curl
curl -X POST 'http://localhost:4000/customer/new' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-1234' \
-D '{
    "user_id": "my-customer-id",
    "budget_id": "my-free-tier" # 👈 KEY CHANGE
}
🚅
LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →