服务账户

如果您想创建不归属于特定用户，而是为生产环境项目创建的虚拟密钥，请使用此功能

为什么要使用服务账户密钥？

• 防止在删除用户时密钥被删除。
• 对密钥应用团队限制，而非团队成员限制。

服务账户与常规密钥的区别

功能	常规密钥	服务账户密钥
user_id	可选	始终为 null
team_id（团队 ID）	可选	必需
应用的限制	用户 + 团队限制	仅限团队限制
用户被删除时是否删除密钥？	是	否 — 保留
元数据中的 service_account_id	未设置	设置后不可更改
team_member_key_duration	继承	不继承

预算与限制

服务账户密钥在团队级别应用预算和速率限制，而不是按用户或按密钥成员应用。

• 在密钥本身上设置 max_budget、tpm_limit、rpm_limit，或者从团队继承它们。
• team_member_key_duration（一种控制团队成员密钥有效期的企业功能）不适用于服务账户密钥。

用法

使用 /key/service-account/generate 端点生成服务账户密钥。

curl -L -X POST 'https://:4000/key/service-account/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "team_id": "my-unique-team"
}'

service_account_id 字段

您可以选择在 metadata 中提供一个 service_account_id，为密钥赋予一个稳定的、人类可读的标识符

curl -L -X POST 'https://:4000/key/service-account/generate' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{
    "team_id": "my-unique-team",
    "metadata": {
        "service_account_id": "my-ci-pipeline"
    }
}'

不可变性规则 — 一旦设置了 service_account_id，就无法更改

操作	结果
覆盖为不同值	400 错误
显式设置为 null	400 错误
发送 metadata: null（将会清除它）	400 错误
在更新时完全省略 metadata	安全 — 保留现有值
重新发送相同的值	允许（无操作）

示例 - 要求所有服务账户请求包含 user 参数

1. 设置服务账户的配置

如果您想创建仅适用于服务账户密钥的设置，请配置 service_account_settings

general_settings:
    service_account_settings: 
        enforced_params: ["user"] # this means the "user" param is enforced for all requests made through any service account keys

2. 在 LiteLLM Proxy 管理界面创建服务账户密钥

3. 测试服务账户密钥

失败调用

curl --location 'https://:4000/chat/completions' \
    --header 'Authorization: Bearer <sk-your-service-account>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-3.5-turbo",
    "messages": [
        {
        "role": "user",
        "content": "hello"
        }
    ]
}'

预期响应

{
  "error": {
    "message": "BadRequest please pass param=user in request body. This is a required param for service account",
    "type": "bad_request_error",
    "param": "user",
    "code": "400"
  }
}

调用成功

curl --location 'https://:4000/chat/completions' \
    --header 'Authorization: Bearer <sk-your-service-account>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-3.5-turbo",
    "messages": [
        {
        "role": "user",
        "content": "hello"
        }
    ],
    "user": "test-user"
}'

预期响应

{
  "id": "chatcmpl-ad9595c7e3784a6783b469218d92d95c",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "\n\nHello there, how may I assist you today?",
        "role": "assistant",
        "tool_calls": null,
        "function_call": null
      }
    }
  ],
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0125",
  "object": "chat.completion",
  "system_fingerprint": "fp_44709d6fcb",
  "usage": {
    "completion_tokens": 12,
    "prompt_tokens": 9,
    "total_tokens": 21,
    "completion_tokens_details": null
  },
  "service_tier": null
}