키 기반 인증 동작 방식
키 기반 인증 동작 방식 (How Key-Based Auth Works)
가상 키가 무엇을 호출할 수 있는지 프록시가 어떻게 결정하는지 설명해요. 초점은 키에 team_id가 있을 때와 없을 때 models 필드를 어떻게 평가하는지, 그리고 SpecialModelNames의 센티널 값이 일반 해석을 어떻게 재정의하는지예요. 설정은 가상 키와 모델 액세스 그룹 문서를 참고하세요.
출처: 문서
본문
models 필드 (The models field)
모든 가상 키 행은 models 목록을 담아요. 항목은 네 가지 범주로 나뉩니다.
| 항목 | 의미 |
|---|---|
| 구체적 모델 그룹 | config.yaml model_name의 이름 (gpt-4, azure-gpt-3.5) |
| 와일드카드 | model_name에 대해 매칭되는 프로바이더 접두사 패턴 (openai/*, openai/o1-*) |
| 액세스 그룹 | model_info.access_groups 또는 /access_group/new 아래에 선언된 라벨. 요청 시점에 그 라벨이 붙은 모델 집합으로 확장 |
| 센티널 | SpecialModelNames의 예약 문자열 중 하나(아래) |
빈 목록과 리터럴 *는 키나 팀에서 평가될 때 둘 다 "프록시의 모든 모델"을 의미해요.
센티널 (Sentinels)
이 문자열들은 litellm.proxy._types.SpecialModelNames의 enum 값으로 예약돼 있어요. 일반 매칭을 단락(short-circuit)시켜요.
| 센티널 | 위치 | 효과 |
|---|---|---|
| all-proxy-models | 키·팀·사용자 models 목록 |
프록시의 모든 모델 부여. 팀에서는 빈 models 목록과 동일하게 취급. 사용자에서는 모든 비팀 배포에 대한 직접 접근 부여 |
| all-team-models | 키 models 목록만 |
요청 시점에 상위 팀의 models를 상속. 키에 team_id가 없으면 검사가 빈 제한 목록으로 해석되어 키가 무제한(모든 프록시 모델)이 됨. 키를 제한해야 하면 team_id를 붙이거나 명시적 모델 목록을 사용 |
| no-default-models | 사용자 models 목록만 |
사용자 경로에서 하드 거부. 사용자가 팀을 통해 요청을 라우팅하도록 강제. default_internal_user_params.models로 설정해 SSO 가입자가 프록시 전체 접근의 독립 키를 만들지 못하게 함 |
all-team-models는 빈 목록과 가장 자주 혼동되는 센티널이에요. 빈 목록은 "모든 모델"을 의미하고, all-team-models는 "팀이 말하는 대로"를 의미하며, 팀이 없으면 거부가 아니라 모든 모델로도 해석돼요.
해석: team_id 유무 (Resolution: with team_id vs without)
두 가지 규칙이 모든 경우를 다룹니다. 독립 키(team_id 없음)는 자체 models 목록에 대해서만 인증돼요.
팀 연결 키는 자체 목록과 team.models에 대한 두 번째 검사를 모두 통과해야 해요. 교집합이 호출자가 실제로 도달할 수 있는 것이므로, ["azure-gpt-3.5"]를 가진 팀 아래의 ["gpt-5.6-terra"]를 가진 키는 아무것도 호출할 수 없어요.
두 단계 모두 같은 메시지 형태로 거부해요. {object_type} not allowed to access model. This {object_type} can only access models=[...]. Tried to access <model>여기서 object_type은 key, team, user, org 중 하나이며, 접두사로 어느 단계가 거부했는지 알 수 있어요. 별도의 팀 구성 검증 경로는 Invalid model for team <team_id>: <model>. Valid models for team are: [...]를 발생시켜요(팀 id로 모델 제한 참조).
센티널은 이 두 검사의 형태를 바꿔요. 팀의 all-proxy-models는 팀 단계를 사소하게 통과시키지만 키는 여전히 일치해야 해요. 키의 all-team-models는 키 단계를 건너뛰고 팀 단계로 위임해요(팀이 없으면 전체 프록시 목록으로 해석).
액세스 그룹과 와일드카드 (Access groups and wildcards)
액세스 그룹은 어떤 키 행도 변경하지 않고 모델을 그룹에 추가하면 연결된 모든 키에 접근을 부여하기 위해 존재해요. 라벨은 키나 팀에 저장되고, 확장은 인증 검사 시점에 그 라벨을 model_info.access_groups에 가진 배포를 조회해 일어나요.
와일드카드는 같은 방식으로 해석되지만 태그가 아니라 model_name에 매칭하며, 자체가 액세스 그룹에 속해 하위 패밀리를 분리할 수 있어요(default-models의 openai/*, restricted-models의 openai/o1-*; default-models만 가진 키는 o1 패밀리를 호출할 수 없음). 모델 액세스 그룹 문서를 참고하세요.
마스터 키가 건너뛰는 것 (What the master key skips)
마스터 키는 메모리에서 평문으로 비교되며 LiteLLM_VerificationToken에 저장되지 않고 models 목록이 없으며 위의 모든 검사를 우회해요. 운영자 자격증명으로 취급하세요. 유출 시 팀, 액세스 그룹, 센티널 구성에 관계없이 프록시의 모든 모델을 부여해요. 마스터 키 로테이션 참조.
관련 문서 (Related)
모델 액세스 · 모델 액세스 그룹 · 가상 키 · 멀티 테넌트 아키텍처