모델 접근 그룹

모델 접근 그룹 (Model Access Groups)

여러 모델을 하나의 이름으로 묶은 뒤, 키나 팀에 그 그룹 전체 접근을 부여하는 기능이에요. 개별 키를 일일이 수정하지 않고도 그룹에서 모델을 추가·제거할 수 있어요.

생산과 개발 모델 분리, 고가 모델을 특정 팀으로 제한, 공급자나 기능별 모델 정리, 와일드카드(예: openai/*)로 모델 계열 접근 제어 등에 유용해요.

출처: 문서

본문

개요 (Overview)

여러 모델을 하나의 이름으로 묶은 뒤, 키나 팀에 그 그룹 전체 접근을 부여해요. 개별 키를 업데이트하지 않고도 그룹에서 모델을 추가·제거할 수 있어요.

사용 사례:

생산 모델과 개발 모델 분리
고가 모델을 특정 팀으로 제한
공급자 또는 기능별로 모델 정리
와일드카드로 모델 계열 접근 제어 (예: openai/*)

동작 방식 (How It Works)

핵심 개념: 모델을 그룹으로 묶기 → 키에 그룹 연결하기 → 키가 그룹의 모든 모델에 접근 가능

1단계: config.yaml에서 모델에 접근 그룹 지정하기

    model_list:
      - model_name: gpt-5.6-terra
        litellm_params:
          model: openai/fake
          api_key: fake-key
          api_base: https://exampleopenaiendpoint-production.up.railway.app/
        model_info:
          access_groups: ["beta-models"] # 👈 Model Access Group
      - model_name: fireworks-llama-v3-70b-instruct
        litellm_params:
          model: fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct
          api_key: "os.environ/FIREWORKS"
        model_info:
          access_groups: ["beta-models"] # 👈 Model Access Group

키 접근 그룹 (Key Access Groups)
팀 접근 그룹 (Team Access Groups)

접근 그룹이 있는 키 만들기

    curl --location 'http://localhost:4000/key/generate' \
    -H 'Authorization: Bearer ***' \
    -H 'Content-Type: application/json' \
    -d '{"models": ["beta-models"], # 👈 Model Access Group
    			"max_budget": 0,}'

키 테스트하기

허용 접근 (Allowed Access)
거부 접근 (Disallowed Access)

허용 접근:

    curl -i http://localhost:4000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-<ke...tep>" \
      -d '{
        "model": "gpt-5.6-terra",
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      }'

info

gpt-5.6-luna가 beta-models 접근 그룹에 없으므로 실패할 것으로 예상해요.

거부 접근:

    curl -i http://localhost:4000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-<ke...tep>" \
      -d '{
        "model": "gpt-5.6-luna",
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      }'

팀 만들기:

    curl --location 'http://localhost:4000/team/new' \
    -H 'Authorization: Bearer sk-<ke...tep>' \
    -H 'Content-Type: application/json' \
    -d '{"models": ["beta-models"]}'

팀용 키 만들기:

    curl --location 'http://0.0.0.0:4000/key/generate' \
    --header 'Authorization: Bearer sk-<ke...tep>' \
    --header 'Content-Type: application/json' \
    --data '{"team_id": "0ac97648-c194-4c90-8cd6-40af7b0d2d2a"}'

키 테스트하기

허용 접근 (Allowed Access)
거부 접근 (Disallowed Access)

팀 키 - 허용 접근:

    curl -i http://localhost:4000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-<ke...tep>" \
      -d '{
        "model": "gpt-5.6-terra",
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      }'

info

gpt-5.6-luna가 beta-models 접근 그룹에 없으므로 실패할 것으로 예상해요.

팀 키 - 거부 접근:

    curl -i http://localhost:4000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-<ke...tep>" \
      -d '{
        "model": "gpt-5.6-luna",
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      }'

✨ 와일드카드 모델 접근 제어하기

특정 접두사가 있는 모든 모델(예: openai/*)에 대한 접근을 제어해요.

이를 이용해 사용자가 못 쓰게 하고 싶은 일부 모델(예: openai/o1-*)을 제외한 모든 모델에 접근을 줄 수도 있어요.

Enterprise 기능이에요.

와일드카드 모델에 모델 접근 그룹을 설정하려면 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험을 시작하거나 데모를 예약하세요. Enterprise가 포함하는 것을 확인하세요.

config.yaml 설정하기

    model_list:
      - model_name: openai/*
        litellm_params:
          model: openai/*
          api_key: os.environ/OPENAI_API_KEY
        model_info:
          access_groups: ["default-models"]
      - model_name: openai/o1-*
        litellm_params:
          model: openai/o1-*
          api_key: os.environ/OPENAI_API_KEY
        model_info:
          access_groups: ["restricted-models"]

default-models 접근 권한이 있는 키 생성하기

    curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{
        "models": ["default-models"],
    }'

키 테스트하기

성공 요청 (Successful Request)
거부 요청 (Rejected Request)

와일드카드 접근 - 허용:

    curl -i http://localhost:4000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-<ke...tep>" \
      -d '{
        "model": "openai/gpt-5.6-terra",
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      }'

와일드카드 접근 - 거부:

    curl -i http://localhost:4000/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-<ke...tep>" \
      -d '{
        "model": "openai/o1-mini",
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      }'

API로 접근 그룹 관리하기

데이터베이스 모델 전용.

접근 그룹 관리 API는 데이터베이스에 저장된 모델(/model/new로 추가)에서만 동작해요.

config.yaml에 정의된 모델은 이 API로 관리할 수 없고, config 파일에서 직접 설정해야 해요.

접근 그룹 관리 엔드포인트를 사용하면 프록시를 재시작하지 않고도 접근 그룹을 동적으로 만들고, 업데이트하고, 삭제할 수 있어요.

튜토리얼: 접근 그룹 전체 워크플로

이 튜토리얼은 접근 그룹 만들기, 상세 보기, 키에 연결하기, 그룹의 모델 업데이트하기를 보여줘요.

사전 조건:

모델이 먼저 데이터베이스에 추가돼 있어야 해요 (config.yaml만으로는 안 됨)
인증을 위해 master key가 필요해요

1단계: 데이터베이스에 모델 추가하기

먼저 몇 가지 모델을 데이터베이스에 추가해요:

    # Add gpt-5.6-terra to database
    curl -X POST 'http://localhost:4000/model/new' \
      -H "Authorization: Bearer ***" \
      -H 'Content-Type: application/json' \
      -d '{
        "model_name": "gpt-5.6-terra",
        "litellm_params": {
          "model": "gpt-5.6-terra",
          "api_key": "os.environ/OPENAI_API_KEY"
        }
      }'

    # Add Claude to database
    curl -X POST 'http://localhost:4000/model/new' \
      -H "Authorization: Bearer ***" \
      -H 'Content-Type: application/json' \
      -d '{
        "model_name": "claude-sonnet-5",
        "litellm_params": {
          "model": "claude-sonnet-5",
          "api_key": "os.environ/ANTHROPIC_API_KEY"
        }
      }'

2단계: 접근 그룹 만들기

여러 모델을 포함하는 접근 그룹을 만들어요:

    curl -X POST 'http://localhost:4000/access_group/new' \
      -H "Authorization: Bearer ***" \
      -H 'Content-Type: application/json' \
      -d '{
        "access_group": "production-models",
        "model_names": ["gpt-5.6-terra", "claude-sonnet-5"]
      }'

응답:

    {
      "access_group": "production-models",
      "model_names": ["gpt-5.6-terra", "claude-sonnet-5"],
      "models_updated": 2
    }

3단계: 접근 그룹 정보 보기

접근 그룹 세부 정보를 확인해요:

    curl -X GET 'http://localhost:4000/access_group/production-models/info' \
      -H "Authorization: Bearer ***"

응답:

    {
      "access_group": "production-models",
      "model_names": ["gpt-5.6-terra", "claude-sonnet-5"],
      "deployment_count": 2
    }

4단계: 접근 그룹이 있는 키 만들기

그룹의 모든 모델에 접근할 수 있는 API 키를 만들어요:

    curl -X POST 'http://localhost:4000/key/generate' \
      -H "Authorization: Bearer ***" \
      -H 'Content-Type: application/json' \
      -d '{
        "models": ["production-models"],
        "max_budget": 100
      }'

응답:

    {
      "key": "sk-...",
      "models": ["production-models"]
    }

키 테스트:

    # This succeeds - gpt-5.6-terra is in production-models
    curl -X POST 'http://localhost:4000/v1/chat/completions' \
      -H 'Authorization: Bearer ***' \
      -H 'Content-Type: application/json' \
      -d '{
        "model": "gpt-5.6-terra",
        "messages": [{"role": "user", "content": "Hello"}]
      }'

    # This succeeds - claude-sonnet-5 is in production-models
    curl -X POST 'http://localhost:4000/v1/chat/completions' \
      -H 'Authorization: Bearer ***' \
      -H 'Content-Type: application/json' \
      -d '{
        "model": "claude-sonnet-5",
        "messages": [{"role": "user", "content": "Hello"}]
      }'

5단계: 접근 그룹 업데이트하기

접근 그룹에서 모델을 추가·제거해요:

    curl -X PUT 'http://localhost:4000/access_group/production-models/update' \
      -H "Authorization: Bearer ***" \
      -H 'Content-Type: application/json' \
      -d '{
        "model_names": ["gpt-5.6-terra", "claude-sonnet-5", "gemini-3.8-flash"]
      }'

응답:

    {
      "access_group": "production-models",
      "model_names": ["gpt-5.6-terra", "claude-sonnet-5", "gemini-3.8-flash"],
      "models_updated": 3
    }

4단계의 API 키는 키 자체를 바꾸지 않아도 이제 자동으로 gemini-3.8-flash에 접근할 수 있어요.

예산 (Budgets)

그룹은 그룹이 부여된 모든 키가 함께 쓰는 하나의 공유 예산을 가질 수도 있어요. 모델 접근 그룹 예산을 참고하세요.

API 레퍼런스 - 접근 그룹 관리

모든 엔드포인트, 파라미터, 응답 스키마를 포함한 전체 API 문서는 Access Group Management API Reference에서 확인하세요.

UI로 접근 그룹 관리하기

LiteLLM Admin UI에서도 접근 그룹을 관리할 수 있어요.

1단계: 모델을 접근 그룹에 추가하기

데이터베이스에 모델을 추가할 때 "Model Access Group" 필드로 접근 그룹에 지정해요:

Add Model with Access Group

이 예제에서 gpt-5.6-terra는 production-models 접근 그룹에 추가돼요.

2단계: 접근 그룹이 있는 키 만들기

API 키를 만들 때 "Models" 필드에 접근 그룹을 지정해요:

Create Key with Access Group

키는 production-models 그룹의 모든 모델에 접근할 수 있어요.

3단계: 키 테스트하기

생성된 키로 요청을 보내요:

    # This succeeds - gpt-5.6-terra is in production-models
    curl -X POST 'http://localhost:4000/v1/chat/completions' \
      -H 'Authorization: Bearer ***' \
      -H 'Content-Type: application/json' \
      -d '{
        "model": "gpt-5.6-terra",
        "messages": [{"role": "user", "content": "Hello"}]
      }'

응답:

    {
      "id": "chatcmpl-...",
      "object": "chat.completion",
      "created": 1234567890,
      "model": "gpt-5.6-terra",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! How can I help you today?"
          },
          "finish_reason": "stop"
        }
      ]
    }

접근 그룹에 없는 모델에 접근하려 하면 요청이 거부돼요:

    # This fails - gpt-5.6-luna is not in production-models
    curl -X POST 'http://localhost:4000/v1/chat/completions' \
      -H 'Authorization: Bearer ***' \
      -H 'Content-Type: application/json' \
      -d '{
        "model": "gpt-5.6-luna",
        "messages": [{"role": "user", "content": "Hello"}]
      }'

응답:

    {
      "error": {
        "message": "Invalid model for key",
        "type": "invalid_request_error"
      }
    }

더 알아보기 (Learn more)

모델 접근 그룹 예산: 접근 그룹이 공유 예산을 갖는 방법
Access Group Management API Reference