LiteLLM config.yaml 구조: 프록시 설정 파일 뜯어보기

LiteLLM 프록시는 서버 하나에 수십 개의 LLM을 통합하는 게이트웨이예요. 그런데 '어떤 모델을, 어떤 방식으로 노출할지'를 어디에 적어 두느냐가 중요하죠. 바로 그 중심이 config.yaml입니다. 이 한 파일이 모델 목록, 라우팅 방식, 서버 인증, 환경 변수까지 프록시의 거의 모든 설정을 담아요.

config.yaml은 크게 다섯 개의 섹션으로 나뉩니다. 각각이 맡는 역할부터 짚고 가면 나중에 어디에 무엇을 적어야 할지 헷갈리지 않아요.

model_list — 이 서버가 지원하는 모델 목록. 모델별 설정(모델명, api_base, api_key, 온도, 최대 토큰 등)을 함께 담아요.
router_settings — LiteLLM 라우터 설정. 예를 들어 routing_strategy="least-busy"처럼 요청을 어떤 배포로 보낼지 정해요.
litellm_settings — litellm 모듈 전역 설정. litellm.drop_params=True, litellm.set_verbose=True, litellm.cache 같은 것들이 여기 들어가요.
general_settings — 프록시 서버 자체 설정. 예를 들어 master_key: sk-my_special_key로 모든 호출에 인증 키를 요구하게 할 수 있어요.
environment_variables — 환경 변수 목록. REDIS_HOST, REDIS_PORT 같은 값들을 여기 정의할 수 있어요.

이 파일에 담을 수 있는 모든 조합을 확인하려면 프록시가 뜬 URL의 Swagger UI(<your-proxy-url>/#/config.yaml, 예: http://0.0.0.0:4000/#/config.yaml)를 보면 됩니다.

출처: 공식문서 — config.yaml Overview

서버를 config.yaml로 띄우기

config.yaml 파일을 만들고, 프록시를 그 설정으로 시작하는 명령은 아주 단순해요.

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

디버깅이 필요하면 --detailed_debug 옵션을 붙여 자세한 로그를 볼 수 있어요.

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

프록시가 설정을 제대로 읽었는지는 실행 로그에서 이 한 줄을 찾으면 됩니다. LiteLLM: Proxy initialized with Config, Set models: — 이 메시지가 보이면 config.yaml 로딩이 성공한 거예요.

model_list: 모델은 여기서 정의해요

model_list는 이 게이트웨이가 노출할 모델들을 정의하는 핵심 섹션입니다. 여기서 이름이 두 개 나오는데, 헷갈리기 쉬우니 확실히 구분할게요.

model_name — 외부 클라이언트가 LiteLLM에 요청할 때 쓰는, 사용자에게 보이는 이름(앨리어스)이에요.
litellm_params.model — 실제로 litellm.completion() 함수에 넘겨지는 모델 문자열이에요.

예를 들어 아래 설정에서 model=gpt-4o 로 요청이 오면, LiteLLM이 eur쪽 Azure와 canada쪽 Azure 두 배포에 부하를 나눠 보냅니다. model=vllm-models 요청은 openai/facebook/opt-125m으로 라우팅되고요.

model_list:
  - model_name: gpt-4o                                    ### 클라이언트가 보는 이름 ###
    litellm_params:                                       # litellm.completion()이 받는 모든 파라미터
      model: azure/gpt-4o-eu                              ### litellm.completion()에 보내는 실제 모델 ###
      api_base: https://my-endpoint-europe-berri-992.openai.azure.com/
      api_key: "os.environ/AZURE_API_KEY_EU"              # os.getenv("AZURE_API_KEY_EU") 실행
      rpm: 6                                              # [선택] 이 배포의 분당 요청 수 제한
  - model_name: gpt-4o
    litellm_params:
      model: azure/gpt-4o-ca
      api_base: https://my-endpoint-canada-berri992.openai.azure.com/
      api_key: "os.environ/AZURE_API_KEY_CA"
      rpm: 6
  - model_name: vllm-models
    litellm_params:
      model: openai/facebook/opt-125m                     # `openai/` 접두사 = OpenAI 호환 제공자
      api_base: http://0.0.0.0:4000/v1
      api_key: none
      rpm: 1440

여기서 api_key: "os.environ/AZURE_API_KEY_EU"처럼 쓰는 걸 눈여겨보세요. 이 문법은 os.getenv("AZURE_API_KEY_EU")를 실행해서 비밀값을 환경에서 읽어와요. out.env나 api_key처럼 "값이 노출되기 싫은 곳" 어디든 이 방식으로 환경에서 로드할 수 있어요. config.yaml의 어떤 값이든 os.environ/<환경변수명> 형태로 바꿀 수 있다고 보면 됩니다.

같은 이름의 모델 여러 개 = 로드밸런싱

model_name이 같은 배포를 여러 개 정의하면, LiteLLM이 그 이름으로 들어온 요청을 여러 배포에 분산합니다. 이를 라우팅 전략이라고 해요. 최적 성능을 위해선 두 가지를 권장합니다.

배포마다 tpm/rpm을 설정하세요. 그러면 가중치 기반 선택이 그 값들을 기준으로 동작해요.
router_settings의 routing_strategy를 목적에 맞게 고르세요. 지원하는 전략은 ["simple-shuffle", "least-busy", "usage-based-routing", "latency-based-routing"]이고, 기본값은 simple-shuffle이에요.

실제 부하 테스트에서 tpm/rpm을 모든 배포에 설정하고 routing_strategy==simple-shuffle을 쓰는 게 처리량을 최대화했다고 합니다.

litellm_settings와 general_settings

litellm_settings는 litellm 모듈 레벨의 옵션을, general_settings는 프록시 서버 자체의 옵션을 담아요. 전형적인 예시를 함께 보여드릴게요.

litellm_settings:
  drop_params: True
  success_callback: ["langfuse"]   # [선택] Langfuse로 LLM 로그 전송
                                   # LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY 환경변수 필요

general_settings:
  master_key: sk-1234              # [선택] 모든 호출에 이 키를 요구 (Authorization: Bearer sk-1234)
  alerting: ["slack"]              # [선택] 행/hanging 요청, 느린 응답, 예산 초과 알림
                                   # SLACK_WEBHOOK_URL 환경변수 필요

환경에 따라 노출할 모델만 바꾸기

특정 모델을 특정 환경(production/staging/development)에서만 노출하고 싶다면, 환경 변수 LITELLM_ENVIRONMENT를 설정하고 각 모델의 model_info.supported_environments에 허용 환경 목록을 적으면 됩니다.

model_list:
  - model_name: gpt-4
    litellm_params:
      model: openai/gpt-4
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      supported_environments: ["production", "staging"]   # production, staging에서만 노출
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      supported_environments: ["production"]              # production에서만 노출

데이터베이스가 설정의 진실 원천이 되는 경우

store_model_in_db를 켜면(general_settings.store_model_in_db: true 또는 env STORE_MODEL_IN_DB="True"), Admin UI와 /config/update API가 설정을 LiteLLM_Config 테이블에 기록하고, 데이터베이스가 그들이 쓴 값의 진실 원천(source of truth)이 됩니다.

동작 방식을 정확히 알아둘 필요가 있어요. 프록시는 시작할 때마다, 그리고 config refresh 때마다 먼저 config.yaml을 로드한 다음, DB의 general_settings, router_settings, litellm_settings, environment_variables 행을 그 위에 덮어씁니다. 덮어쓰기는 깊은 병합(deep merge)이라, 두 곳에 모두 존재하는 키는 DB 값이 이깁니다. 즉 그 키를 YAML에서 고치고 파드를 재시작해도 운영값은 바뀌지 않아요.

그래서 이 네 개 섹션은 YAML을 '부트스트랩'으로만 생각하고, UI가 쓴 키는 UI에서 바꾸거나 LiteLLM_Config 행을 지우는 방식으로 관리하는 게 맞아요. 다음 세부사항도 기억해 두면 좋습니다.

DB 값이 null이거나 빈 리스트면 '값 없음'으로 취급해서 YAML이 제공한 값을 덮지 않아요.
이 오버레이가 적용되는 건 네 설정 섹션뿐이에요. model_list는 이렇게 병합되지 않습니다. UI/API로 추가된 모델은 LiteLLM_ProxyModelTable에 저장되어 YAML 모델과 나란히 제공되는데, DB 모델이 같은 이름의 YAML 항목을 대체하는 게 아니라 추가 배포가 되어 함께 로드밸런싱돼요.
store_model_in_db를 끄면 DB는 설정을 위해 아예 읽히지 않아서 config.yaml이 완전히 권위(authoritative)를 가져요.

환경 변수로 config 경로·원격 버킷 지정하기

배포 환경에서 config 파일을 마운트하지 못하는 경우(AWS Fargate, Railway 등)가 있어요. 그럴 땐 파일 경로를 환경 변수로 넘길 수 있습니다.

export CONFIG_FILE_PATH="/path/to/config.yaml"
litellm   # http://0.0.0.0:4000 에서 구동

S3나 GCS 버킷에서 직접 config를 읽을 수도 있어요.

export LITELLM_CONFIG_BUCKET_TYPE="gcs"            # "gcs"로 지정
export LITELLM_CONFIG_BUCKET_NAME="litellm-proxy"  # GCS의 버킷 이름
export LITELLM_CONFIG_BUCKET_OBJECT_KEY="proxy_config.yaml"  # 버킷 내 객체 키

Swagger 문서나 Redoc 문서를 끄고 싶으면 각각 NO_DOCS="True", NO_REDOC="True"를 환경에 설정하고 프록시를 재시작하면 됩니다.

LiteLLM config.yaml 구조: 프록시 설정 파일 뜯어보기