모델 접근 제한

모델 접근 제한 (Restrict Model Access)

키, 팀, 액세스 그룹 등으로 호출 가능한 모델을 제한하는 방법을 다루는 문서예요.

출처: 문서

본문

가상 키로 모델 제한

models 파라미터로 키에 허용된 모델을 설정해요.

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--data-raw '{"models": ["gpt-5.6-luna", "gpt-5.6-terra"]}'

이 키는 gpt-5.6-luna 또는 gpt-5.6-terra인 모델에만 요청할 수 있어요.

올바르게 설정됐는지 확인해요.

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

이것은 실패할 것으로 예상해요. claude-sonnet-5가 생성된 키의 models에 없기 때문이에요.

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

API 참조 (API Reference)

team_id로 모델 제한

litellm-dev는 azure-gpt-3.5에만 접근할 수 있어요.

/team/new로 팀 생성

curl --location 'http://localhost:4000/team/new' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--data-raw '{
  "team_alias": "litellm-dev",
  "models": ["azure-gpt-3.5"]
}' 

# returns {...,"team_id": "my-unique-id"}

팀용 키 생성

curl --location 'http://localhost:4000/key/generate' \
--header "Authorization: Bearer ***" \
--header 'Content-Type: application/json' \
--data-raw '{"team_id": "my-unique-id"}'

테스트

curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ***' \
    --data '{
        "model": "BEDROCK_GROUP",
        "messages": [
            {
                "role": "user",
                "content": "hi"
            }
        ]
    }'

{"error":{"message":"Invalid model for team litellm-dev: BEDROCK_GROUP.  Valid models for team are: ['azure-gpt-3.5']\n\n\nTraceback (most recent call last):\n  File \"/Users/ishaanjaffer/Github/litellm/litellm/proxy/proxy_server.py\", line 2298, in chat_completion\n    _is_valid_team_configs(\n  File \"/Users/ishaanjaffer/Github/litellm/litellm/proxy/utils.py\", line 1296, in _is_valid_team_configs\n    raise Exception(\nException: Invalid model for team litellm-dev: BEDROCK_GROUP.  Valid models for team are: ['azure-gpt-3.5']\n\n","type":"None","param":"None","code":500}}%

API 참조 (API Reference)

사용 가능한 대체 모델 보기

/v1/models 엔드포인트를 사용해 주어진 모델에 대해 사용 가능한 대체(fallback) 모델을 발견해요. 주 모델을 사용할 수 없거나 제한될 때 사용 가능한 백업 모델을 이해하는 데 도움을 줘요.

include_metadata 파라미터는 앞으로 추가 모델 메타데이터를 노출하기 위한 확장 지점으로 기능해요. 현재는 fallback 모델에 초점을 맞추지만, 이 접근은 가격 정보, 기능, 레이트 리밋 등 다른 모델 메타데이터를 포함하도록 확장될 거예요.

기본 사용법

모든 사용 가능한 모델 가져오기:

curl -X GET 'http://localhost:4000/v1/models' \
  -H 'Authorization: Bearer ***'

메타데이터로 fallback 모델 가져오기

fallback 모델 정보를 보려면 메타데이터를 포함해요.

curl -X GET 'http://localhost:4000/v1/models?include_metadata=true' \
  -H 'Authorization: Bearer ***'

특정 fallback 유형 가져오기

보고 싶은 fallback 유형을 지정할 수 있어요.

curl -X GET 'http://localhost:4000/v1/models?include_metadata=true&fallback_type=general' \
  -H 'Authorization: Bearer ***'

일반(general) fallback은 같은 유형의 요청을 처리할 수 있는 대체 모델이에요.

curl -X GET 'http://localhost:4000/v1/models?include_metadata=true&fallback_type=context_window' \
  -H 'Authorization: Bearer ***'

컨텍스트 창(context_window) fallback은 주 모델의 컨텍스트 제한을 초과할 때 요청을 처리할 수 있는 더 큰 컨텍스트 창을 가진 모델이에요.

curl -X GET 'http://localhost:4000/v1/models?include_metadata=true&fallback_type=content_policy' \
  -H 'Authorization: Bearer ***'

콘텐츠 정책(content_policy) fallback은 주 모델이 안전 정책 때문에 콘텐츠를 거부할 때 요청을 처리할 수 있는 모델이에요.

응답 예시

include_metadata=true를 지정하면 응답에 fallback 정보가 포함돼요.

{
  "data": [
    {
      "id": "gpt-5.6-terra",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai",
      "fallbacks": {
        "general": ["gpt-5.6-luna", "claude-sonnet-5"],
        "context_window": ["gpt-5.6-luna", "claude-sonnet-5"],
        "content_policy": ["claude-sonnet-5"]
      }
    }
  ]
}

사용 사례 (Use Cases)

API 파라미터 (API Parameters)

파라미터	타입	설명
include_metadata	boolean	fallback을 포함한 추가 모델 메타데이터 포함
fallback_type	string	`general`, `context_window`, `content_policy`로 fallback 필터링

시간 창 동안 팀을 위한 배포 예약

배포에 model_info.access_windows를 설정해 매일 로컬 시간 창 동안 특정 팀을 위해 예약해요. 창이 활성인 동안 라우터는 그 배포를 목록에 있는 팀 중 하나에 속한 키의 요청에만 건네요. 다른 팀의 요청과 팀이 없는 키(마스터 키 포함)의 요청은 같은 모델 그룹의 다른 배포로 라우팅되거나, 모든 후보가 예약됐으면 400으로 거부돼요. 창 밖에서는 라우팅이 변하지 않아요. 배포는 항상 /v1/models와 /model/info에 나열돼요.

model_list:
  - model_name: gpt-4o-ptu
    litellm_params:
      model: azure/gpt-4o-ptu
      api_base: os.environ/AZURE_PTU_BASE
      api_key: os.environ/AZURE_PTU_KEY
    model_info:
      access_windows:
        - start: "22:00"
          end: "06:00"
          timezone: "America/New_York"
          team_ids: ["team-nightly-batch"]

start와 end는 주어진 IANA 타임존의 HH:MM 벽시계 시간이며(일광 절약은 자동 적용), start는 포함, end는 제외예요. start가 end보다 늦으면 자정을 넘는 창을 뜻해요. 배포는 여러 창을 나열할 수 있으며 그중 하나가 활성이면 예약됩니다. 프록시는 창의 시간이 유효하지 않거나, 타임존을 알 수 없거나, team_ids가 비었거나, start·end가 같으면 시작을 거부해요.

거부된 요청은 이렇게 보여요.

{"error":{"message":"litellm.BadRequestError: Deployment gpt-4o-ptu is reserved for another team until 06:00 America/New_York","type":"invalid_request_error","param":null,"code":"400"}}

고급: 모델 액세스 그룹 (Model Access Groups)

고급 사용 사례에는 모델 액세스 그룹을 사용해 여러 모델을 동적으로 그룹화하고 프록시 재시작 없이 접근을 관리해요.

모델 접근 제한