가상 키

가상 키 (Virtual Keys)

여러 팀원이나 앱이 프록시를 쓰다 보면 "누가 얼마나 썼는지"와 "누가 어떤 모델에 접근할 수 있는지"를 관리하고 싶어져요. 가상 키(virtual key)가 바로 그 일을 해 주는 도구예요. 프록시에서 키를 발급하면 지출을 추적하고 모델 접근을 제어할 수 있어요.

출처: 공식문서

사전 요구사항

가상 키를 쓰려면 몇 가지가 준비돼 있어야 해요.

• PostgreSQL 데이터베이스 (Supabase, Neon 등)
• 환경 변수에 DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname> 설정
• 마스터 키(master key) 설정 — 이게 프록시 관리자 키로, 다른 키를 만드는 데 써요. 반드시 sk-로 시작해야 해요.
  • config.yaml의 general_settings:master_key에 설정하거나
  • 환경 변수 LITELLM_MASTER_KEY로 설정해요

export DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname>

키 생성 흐름

Step 1: 포스트그레스 URL 저장

model_list:
  - model_name: gpt-4
    litellm_params:
      model: ollama/llama2
  - model_name: gpt-3.5-turbo
    litellm_params:
      model: ollama/llama2

general_settings:
  master_key: sk-1234
  database_url: "postgresql://<user>:<password>@<host>:<port>/<dbname>"  # 👈 KEY CHANGE

Step 2: litellm 실행

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

Step 3: 키 생성

curl 'http://0.0.0.0:4000/key/generate' \
  --header 'Authorization: Bearer <your-master-key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{"models": ["gpt-3.5-turbo", "gpt-4"], "metadata": {"user": "[email protected]"}}'

키의 소유자와 상속 규칙

키의 소유자는 그 키의 user_id가 가리키는 사람이에요. 그런데 그게 항상 키를 만든 사람과 같지는 않아요. /key/generate는 호출자가 프록시 관리자가 아닐 때만 자동으로 호출자의 user_id를 새 키에 찍어요. 관리자가 만든 경우엔 user_id를 명시적으로 넘겨야 해서, user_id가 없는 관리자 생성 키는 소유자가 없고 관리자로부터 아무것도 상속받지 못해요. 관리자 UI에서 특정 사용자용으로 만든 키나 서비스 계정 키(항상 user_id가 null)도 같은 규칙을 따라요.

상속은 권한 영역마다 달라요. 모델 접근과 MCP 접근은 항상 키 행 자체 기준으로 평가되지만, 관리 라우트 접근은 소유 사용자의 역할(role) 로 결정돼요. 그래서 프록시 관리자가 소유한 키는 관리자 엔드포인트를 호출할 수 있어요.

지출 추적

지출을 보는 엔드포인트는 이렇게 나뉘어요.

• 키별: /key/info
• 사용자별: /user/info
• 팀별: /team/info
• 최종 사용자별: /end_user/info (진행 중)

비용은 어떻게 계산될까요? 모델별 비용은 model_prices_and_context_window.json에 저장돼 있고, completion_cost() 함수로 계산돼요.

어떻게 추적될까요? 지출은 키에 대해 LiteLLM_VerificationTokenTable에 자동 기록돼요. 키에 user_id나 team_id가 붙어 있으면 사용자 지출은 LiteLLM_UserTable, 팀 지출은 LiteLLM_TeamTable에 추적돼요.

키 지출 조회 예시:

curl 'http://0.0.0.0:4000/key/info?key=<user-key>' \
     -X GET \
     -H 'Authorization: Bearer <your-master-key>'

응답 예시:

{
    "key": "sk-tXL0wt5-lOOVK9sfY2UacA",
    "info": {
        "token": "sk-tXL0wt5-lOOVK9sfY2UacA",
        "spend": 0.0001065,
        "expires": "2023-11-24T23:19:11.131000Z",
        "models": ["gpt-3.5-turbo", "gpt-4", "claude-2"],
        "aliases": {"mistral-7b": "gpt-3.5-turbo"},
        "config": {}
    }
}

모델 업그레이드/다운그레이드 (Aliases)

사용자가 특정 모델(예: gpt-3.5-turbo)을 쓰도록 기대되는데, 그 요청을 업그레이드(GPT-4로)하거나 다운그레이드(Mistral로)하고 싶을 때가 있어요. config에서 모델 그룹을 만들고 키 생성 시 aliases로 매핑하면 돼요.

curl -X POST "https://0.0.0.0:4000/key/generate" \
  -H "Authorization: Bearer <your-master-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["my-free-tier"],
    "aliases": {"gpt-3.5-turbo": "my-free-tier"},  # 👈 KEY CHANGE
    "duration": "30min"
  }'

업그레이드/다운그레이드 방식을 바꾸려면 alias 매핑만 바꾸면 돼요.

커스텀 키 헤더

기본 Authorization 헤더 대신 커스텀 헤더에서 가상 키를 찾도록 하고 싶을 때가 있어요. litellm_key_header_name을 설정하면 됩니다.

general_settings:
  master_key: sk-1234
  litellm_key_header_name: "X-Litellm-Key"   # 👈 Key Change

키 차단/해제 (Disable/Enable Keys)

키를 즉시 차단하려면 /key/block, 다시 활성화하려면 /key/unblock을 써요.

curl -L -X POST 'http://0.0.0.0:4000/key/block' \
  -H 'Authorization: Bearer LITELL..._KEY' \
  -H 'Content-Type: application/json' \
  -d '{"key": "KEY-TO-BLOCK"}'

{"blocked": true}가 응답으로 오면 차단된 거예요.

키 순환 (Key Rotation · Regenerate)

기존 API 키를 순환(regenerate)하면서 파라미터도 함께 갱신할 수 있어요.

curl 'http://localhost:4000/key/sk-1234/regenerate' \
  -X POST \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "max_budget": 100,
    "metadata": {"team": "core-infra"},
    "models": ["gpt-4", "gpt-3.5-turbo"],
    "grace_period": "48h"
  }'

유예 기간(Grace period, 선택) — grace_period(예: "24h", "2d", "1w")를 설정하면 옛 키가 전환 기간 동안 계속 유효해요. 유예 기간이 지나기 전까지는 옛 키와 새 키가 모두 동작해서, 프로덕션 다운타임 없이 전환할 수 있어요. 생략하거나 비워 두면 즉시 폐기돼요.

자동 키 순환

LiteLLM은 정의한 시간 간격에 따라 가상 키를 자동으로 순환할 수도 있어요.

1. DB 연결 필요 — 순환 스케줄을 추적하려면 연결된 데이터베이스가 있어야 해요.
2. 순환 워커 활성화 — LITELLM_KEY_ROTATION_ENABLED=true 환경 변수 설정.
3. 검사 간격 설정(선택) — LITELLM_KEY_ROTATION_CHECK_INTERVAL_SECONDS(기본 86400초 = 24시간).

동작 방식: 가상 키 생성 시 auto_rotate: true와 rotation_interval(기간 문자열)을 지정하면, LiteLLM이 now + rotation_interval을 다음 순환 시각으로 계산해 DB에 저장해요. 백그라운드 잡이 주기적으로 순환 시각이 지난 키를 찾아, 순환이 되면 키를 재생성하고 옛 키 문자열을 무효화해요. 배포 시 자동 순환을 쓰고 싶다면 /key/generate에 "auto_rotate": true, "rotation_interval": "30d"를 넣으면 돼요.

더 알아보기

• 팀 예산 설정
• 요청이 프록시를 통과하는 전체 흐름
• 퀵 스타트