Admin UI 빠른 시작

Admin UI 빠른 시작 (Quick Start)

LiteLLM 프록시의 Admin UI를 통해 별도의 config나 CRUD 엔드포인트를 신경 쓰지 않고 키를 만들고, 지출을 추적하고, 모델을 추가할 수 있어요. 어드민 대시보드를 처음 시작하고 로그인 보안을 설정하는 전체 과정을 안내할게요.

출처: 문서

본문

키를 만들고, 지출을 추적하고, config나 CRUD 엔드포인트를 걱정하지 않고 모델을 추가할 수 있어요.

Quick Start

프록시 마스터 키가 설정되어 있어야 해요.
DB가 연결되어 있어야 해요.

셋업을 따라가 볼게요.

1. 프록시 시작하기

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

#INFO: Proxy running on http://0.0.0.0:4000

2. UI 접속하기

http://0.0.0.0:4000/ui # <proxy_base_url>/ui

3. Swagger에서 Admin UI 링크 확인하기

프록시 Swagger는 프록시의 루트에서 확인할 수 있어요. 예: http://localhost:4000/

4. 처음으로 로그인하기

기본적으로 UI는 환경 변수로 만든 로그인을 받아요. 사용자 이름은 UI_USERNAME(기본값 admin), 비밀번호는 UI_PASSWORD예요. UI_PASSWORD가 설정되지 않으면 마스터 키 자체를 비밀번호로 받아들여요. 이 방식으로 로그인하는 모든 사람은 프록시 어드민이 돼요.

LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)" # master key for the proxy; must start with sk-
UI_USERNAME=ishaan-litellm   # username to sign in on UI
UI_PASSWORD=langchain        # password to sign in on UI

LiteLLM UI에 접속하면 사용자 이름과 비밀번호를 입력하라는 안내가 나와요. 환경 변수 자격 증명은 부트스트래핑 전용이에요.

이 로그인 방식은 영구적이고 공유되는 평문 어드민 자격 증명을 환경에 저장하며, 사람별로 교체할 수 없고 어떤 어드민이 무엇을 했는지도 알 수 없어요. 로그인한 뒤 아래 단계를 따라 사용자별 계정으로 전환하고 이 방식을 비활성화하세요. 그렇게 하기 전까지 대시보드는 모든 어드민에게 경고 배너를 보여줘요.

5. 자신의 어드민 계정을 만들고 환경 자격 증명 로그인 비활성화하기

먼저 환경 자격 증명으로 로그인한 상태에서 자신을 위한 proxy_admin 사용자를 만들어요. Internal Users -> + Invite User로 이동해 역할을 proxy_admin으로 설정하고, 생성된 초대 링크를 열어 비밀번호를 설정하면 돼요. POST /user/new에 user_role을 proxy_admin으로 지정해 API로도 사용자를 만들 수 있어요 (invite users 참고). 계속하기 전에 로그아웃하고 이메일과 새 비밀번호로 로그인되는지 확인하세요.

그런 다음 config.yaml에서 환경 자격 증명 로그인 방식을 끄고 프록시를 재시작해요:

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  disable_env_credential_login: true

재시작 후에는 로그인 페이지에서 UI_USERNAME/UI_PASSWORD와 마스터 키가 401 Invalid credentials used to access UI로 거부되고, 경고 배너는 사라지며, DB 사용자(그리고 설정했다면 SSO)만 로그인할 수 있어요. 이제 환경에서 UI_USERNAME과 UI_PASSWORD를 제거해도 돼요.

note

비밀번호가 있는 proxy_admin 사용자를 만들기 전에 disable_env_credential_login을 켜면 로그인할 수 없게 돼요. 이런 상황이 되면 마스터 키로 disable_env_credential_login을 끄고 프록시를 재시작해 접근을 복구하세요.

SSO를 쓴다면 disable_password_login_when_sso_enabled도 이 로그인 방식을 막아요. SSO 제공자가 완전히 구성되면 모든 사용자 이름/비밀번호 로그인을 거부하거든요. Admin UI용 SSO를 참고하세요.

6. 루트 리다이렉트 URL 구성하기

DOCS_URL이 "/"가 아닌 다른 값으로 설정된 경우, ROOT_REDIRECT_URL로 루트 경로(/)가 리다이렉트될 위치를 구성할 수 있어요:

DOCS_URL="/docs"              # Set docs to a different path
ROOT_REDIRECT_URL="/ui"       # Redirect root path (/) to /ui

기본적으로 DOCS_URL은 "/"라서, DOCS_URL을 다른 경로로 바꿨을 때만 이 설정이 필요해요.

실패한 로그인 시도 제한하기

Admin UI에 실패한 사용자 이름/비밀번호 로그인은 출처 주소별로 집계돼요. 한 주소에서 60초 안에 모든 사용자 이름을 통틀어 10번 이상 틀린 비밀번호를 입력하면 그 주소는 5분간 차단돼요. 계정이 잠기는 일은 없어요. 같은 사용자 이름이 다른 주소에서는 여전히 로그인할 수 있어요. 주소 한도의 절반(기본 5)이 그 주소의 단일 사용자 이름 허용치예요. 이걸 넘기면 그 주소와 사용자 이름 쌍만 차단되고, 이후 실패는 주소 집계에 더 이상 포함되지 않아요. 그래서 한 계정에 붙어 있는 스크립트 하나가 공유 사무실 주소 뒤의 다른 사람들을 모두 잠그지 않아요.

차단이 활성화된 동안 그 주소 또는 쌍의 모든 로그인 시도는 비밀번호를 확인하기 전에 429 Too many failed sign-in attempts와 Retry-After 헤더로 거부돼요. 올바른 비밀번호, UI_USERNAME/UI_PASSWORD, 그리고 마스터 키를 폼에 입력한 경우도 포함돼요. 거부된 시도는 차단을 연장하지 않아요. 차단되어 기다릴 수 없다면, 마스터 키가 여전히 API의 bearer 토큰으로 동작하니 그것(로그인 제한 대상이 아닌)을 쓰면 돼요.

카운터는 프록시에 Redis가 있으면 Redis에 저장돼요. 그래서 차단이 모든 워커와 파드에 적용돼요. Redis가 없으면 각 워커가 자체적으로 집계해서 실질 한도는 설정값 × 워커 수가 돼요. 프록시는 시작 시 이에 대해 경고해요. Redis에 연결할 수 없게 되면 프록시는 워커별 카운터로 폴백하고 로그인을 계속 받아들여요.

주소별로 집계하려면 프록시가 어떤 주소가 클라이언트인지 알아야 해요. general_settings.trusted_proxy_ranges에 LiteLLM 앞에 있는 로드 밸런서나 인그레스의 CIDR 범위를 설정하세요. 그러면 클라이언트는 그 범위 밖의 첫 번째 X-Forwarded-For 홉이 돼요. 클라이언트가 LiteLLM에 직접 연결하면 []로 설정해서 피어 주소를 쓰고 X-Forwarded-For는 무시하게 하세요. 설정하지 않으면 프록시가 클라이언트와 공유 인그레스를 구분할 수 없어서 시작 시 경고하고 사용자 이름별 한도만 적용해요. IPv6 주소는 /64 단위로 묶여요.

general_settings:
  trusted_proxy_ranges: ["10.0.0.0/8"]        # or [] when clients connect directly
  max_failed_login_attempts_per_source: 10    # default; the per-username allowance is half of this
  failed_login_window_seconds: 60             # default
  failed_login_block_seconds: 300             # default
  max_failed_login_attempts_per_source_overrides:
    "203.0.113.7": 50                         # a NAT gateway many admins share; 25 per username there
    "192.0.2.0/24": 100                       # the most specific match wins
    "198.51.100.4": 0                         # 0 exempts this address from both limits

오버라이드는 그 주소의 두 한도를 모두 올려요. 사용자 이름별 허용치가 주소 한도를 따르기 때문이에요. 0은 그 주소를 완전히 면제해요. LITELLM_DISABLE_LOGIN_RATE_LIMIT=true는 제한을 모든 곳에서 꺼요. 시작 시 한 번만 읽혀요. 기본값의 근거는 Security best practices를 참고하세요.

다른 사용자 초대하기

다른 사람들이 자신의 키를 만들고/삭제할 수 있게 해줘요.

Go Here

모델 관리 (Model Management)

Admin UI는 다음과 같은 모델 관리 기능을 제공해요:

모델 추가 (Add Models): 프록시를 재시작하지 않고 UI에서 새 모델을 추가해요.
AI Hub: 모델과 에이전트를 공개해 개발자들이 무엇이 가능한지 발견하게 해요.
가격 데이터 동기화 (Price Data Sync): GitHub에서 동기화해 모델 가격 데이터를 최신으로 유지해요.

모델 관리에 대한 자세한 내용은 Model Management를 참고하세요. 모델과 에이전트 공유에 대한 내용은 AI Hub를 참고하세요. 모델 가격 데이터 동기화하기 GitHub에서 모델 가격 데이터를 동기화해 비용 정보를 최신으로 유지해요.

Admin UI 비활성화하기

환경에서 DISABLE_ADMIN_UI="True"를 설정하면 Admin UI를 비활성화할 수 있어요. 보안 팀이 UI 사용에 추가 제한을 두는 경우 유용해요.

Admin UI 빠른 시작