CLI 인자

CLI 인자 (CLI Arguments)

이 페이지는 LiteLLM 프록시 서버에서 사용할 수 있는 모든 커맨드라인 인터페이스(CLI) 인자를 문서화해요.

출처: 문서

본문

서버 구성 (Server Configuration)

--host

  • 기본값: '0.0.0.0'
  • 서버가 수신할 호스트.
litellm --host 127.0.0.1

환경 변수로 설정하기: HOST

export HOST=127.0.0.1
litellm

--port

  • 기본값: 4000
  • 서버를 바인딩할 포트.
litellm --port 8080

환경 변수로 설정하기: PORT

export PORT=8080
litellm

--num_workers

  • 기본값: 시스템의 논리 CPU 수, 또는 판별 불가 시 4
  • 실행할 워커 프로세스 수 (uvicorn, gunicorn, 또는 Granian --workers).
litellm --num_workers 4

환경 변수로 설정하기: NUM_WORKERS

export NUM_WORKERS=4
litellm

--config

  • 짧은 형식: -c
  • 기본값: None
  • 프록시 콘피그 파일 경로 (예: config.yaml).
litellm --config path/to/config.yaml

--log_config

  • 기본값: None
  • 타입: str
  • uvicorn용 로깅 콘피그 파일 경로.
litellm --log_config path/to/log_config.conf

--keepalive_timeout

  • 기본값: None
  • 타입: int
  • uvicorn keepalive 타임아웃 설정 (초, uvicorn timeout_keep_alive 파라미터).
litellm --keepalive_timeout 30

환경 변수로 설정하기: KEEPALIVE_TIMEOUT

export KEEPALIVE_TIMEOUT=30
litellm

--timeout_worker_healthcheck

  • 기본값: None (uvicorn의 자체 기본값 5초 적용)
  • 타입: int
  • uvicorn 워커 헬스체크 타임아웃 설정 (초, uvicorn timeout_worker_healthcheck 파라미터). --num_workers > 1로 uvicorn을 실행하면 슈퍼바이저 프로세스가 각 워커를 ping 해요. 이 창 안에 응답하지 않는 워커(예: 이벤트 루프가 동기 작업에 막힌 경우)는 SIGKILL로 종료되고 교체돼요. 종료는 로그에 Waiting for child process [<pid>] 다음에 Child process [<pid>] died로 나타나요. 긴 동기 작업 중에 정상 워커가 재활용된다면 이 값을 올리세요.
  • uvicorn>=0.37.0 필요. 오래된 uvicorn 버전에서는 플래그가 효과가 없어요: LiteLLM이 시작 시 Ignoring the flag 경고를 출력하고 uvicorn의 내장 5초 타임아웃이 적용돼요. 이 플래그를 설정했다면 시작 로그에서 그 경고를 확인해 효과가 있었는지 확인하세요.
  • --num_workers > 1로 uvicorn을 직접 실행할 때만 적용돼요. --run_gunicorn / --run_hypercorn에서는 무시돼요.
litellm --num_workers 4 --timeout_worker_healthcheck 30

환경 변수로 설정하기: TIMEOUT_WORKER_HEALTHCHECK

export TIMEOUT_WORKER_HEALTHCHECK=30
litellm

--max_requests_before_restart

  • 기본값: None
  • 타입: int
  • 이 요청 수만큼 처리한 후 워커를 재시작해요. 시간이 지남에 따른 메모리 증가를 완화하는 데 유용해요.
  • uvicorn: limit_max_requests로 매핑
  • gunicorn: max_requests로 매핑
litellm --max_requests_before_restart 10000

환경 변수로 설정하기: MAX_REQUESTS_BEFORE_RESTART

export MAX_REQUESTS_BEFORE_RESTART=10000
litellm

--max_requests_before_restart_jitter

  • 기본값: None
  • 타입: int
  • 각 워커에 --max_requests_before_restart에 대해 [0, jitter] 범위의 무작위 값을 더해, 워커가 한꺼번에가 아니라 분산된 요청 수로 재활용되게 해요. --max_requests_before_restart 없이는 효과가 없어요.
  • uvicorn: limit_max_requests_jitter로 매핑 (uvicorn>=0.41.0 필요. 오래된 버전에서는 경고와 함께 무시됨)
  • gunicorn: max_requests_jitter로 매핑
litellm --max_requests_before_restart 10000 --max_requests_before_restart_jitter 1000

환경 변수로 설정하기: MAX_REQUESTS_BEFORE_RESTART_JITTER

export MAX_REQUESTS_BEFORE_RESTART=10000
export MAX_REQUESTS_BEFORE_RESTART_JITTER=1000
litellm

서버 백엔드 옵션 (Server Backend Options)

--run_gunicorn

  • 기본값: False
  • 타입: bool (Flag)
  • uvicorn 대신 gunicorn으로 프록시를 시작해요. 프로덕션에서 여러 워커를 관리하는 데 더 좋아요.
litellm --run_gunicorn

--run_hypercorn

  • 기본값: False
  • 타입: bool (Flag)
  • uvicorn 대신 hypercorn으로 프록시를 시작해요. HTTP/2를 지원해요.
litellm --run_hypercorn

--run_granian

  • 기본값: False
  • 타입: bool (Flag)
  • 상태: Beta. 더 높은 게이트웨이 처리량을 원할 때 옵트인하세요. uvicorn이 기본값으로 유지돼요.
  • uvicorn 대신 Granian(Rust 기반 ASGI 서버)으로 프록시를 시작해요. HTTP/1과 HTTP/2를 지원해요.
  • 왜 사용하나요: Granian은 HTTP 계층을 Python에서 Rust 런타임으로 옮겨서, uvicorn 단독보다 동시 프록시 트래픽을 더 예측 가능하게 처리하는 경향이 있어요. LiteLLM 부하 테스트에서 Granian은 동등한 uvicorn 멀티 워커 설정보다 10–20 RPS 향상을 보였고, 지속 부하에서 더 나은 안정성과 더 적은 요청 실패를 보였어요.
  • 요구사항: Python 3.10+와 granian 패키지 (litellm[proxy]에 포함).
  • Granian 사용 시 제한사항:
    • --max_requests_before_restart는 지원되지 않아요 (Granian은 요청당 한도가 아닌 초 단위 workers_lifetime을 사용).
    • --ciphers는 적용되지 않아요.
    • --keepalive_timeout와 --log_config는 uvicorn에만 적용돼요.
litellm --config config.yaml --run_granian --num_workers 4

--skip_server_startup

  • 기본값: False
  • 타입: bool (Flag)
  • 설정 후 서버 시작을 건너뛰어요 (데이터베이스 마이그레이션에만 유용).
litellm --skip_server_startup

SSL/TLS 구성 (SSL/TLS Configuration)

--ssl_keyfile_path

  • 기본값: None
  • 타입: str
  • SSL 키파일 경로. 프록시 시작 시 SSL 인증서를 제공하고 싶을 때 사용해요.
litellm --ssl_keyfile_path /path/to/key.pem --ssl_certfile_path /path/to/cert.pem

환경 변수로 설정하기: SSL_KEYFILE_PATH

export SSL_KEYFILE_PATH=/path/to/key.pem
litellm

--ssl_certfile_path

  • 기본값: None
  • 타입: str
  • SSL 인증서 파일 경로. 프록시 시작 시 SSL 인증서를 제공하고 싶을 때 사용해요.
litellm --ssl_certfile_path /path/to/cert.pem --ssl_keyfile_path /path/to/key.pem

환경 변수로 설정하기: SSL_CERTFILE_PATH

export SSL_CERTFILE_PATH=/path/to/cert.pem
litellm

--ciphers

  • 기본값: None
  • 타입: str
  • SSL 설정에 사용할 Ciphers. --run_hypercorn에서만 사용돼요.
litellm --run_hypercorn --ssl_keyfile_path /path/to/key.pem --ssl_certfile_path /path/to/cert.pem --ciphers "ECDHE+AESGCM"

모델 구성 (Model Configuration)

--model 또는 -m

  • 기본값: None
  • LiteLLM에 전달할 모델 이름.
litellm --model gpt-5.6-luna

--alias

  • 기본값: None
  • 모델의 별칭. 사용자 친화적 참조용. litellm 모델 이름(예: "huggingface/codellama/CodeLlama-7b-Instruct-hf")에 더 사용자 친화적인 이름(예: "codellama")을 주는 데 사용해요.
litellm --alias my-gpt-model

--api_base

  • 기본값: None
  • LiteLLM이 호출해야 하는 모델의 API base.
litellm --model huggingface/tinyllama --api_base https://k58ory32yinf1ly0.us-east-1.aws.endpoints.huggingface.cloud

--api_version

  • 기본값: 2024-07-01-preview
  • Azure 서비스의 경우 API 버전을 지정해요.
litellm --model azure/gpt-deployment --api_version 2023-08-01 --api_base https://<your api base>"

--headers

  • 기본값: None
  • API 호출용 헤더 (JSON 문자열).
litellm --model my-model --headers '{"Authorization": "Bearer token"}'

--add_key

  • 기본값: None
  • 모델 콘피그에 키를 추가해요.
litellm --add_key my-api-key

--save

  • 타입: bool (Flag)
  • 모델별 콘피그 저장.
litellm --model gpt-5.6-luna --save

모델 파라미터 (Model Parameters)

--temperature

  • 기본값: None
  • 타입: float
  • 모델의 temperature 설정.
litellm --temperature 0.7

--max_tokens

  • 기본값: None
  • 타입: int
  • 모델 출력의 최대 토큰 수 설정.
litellm --max_tokens 50

--request_timeout

  • 기본값: None
  • 타입: int
  • completion 호출의 타임아웃(초) 설정.
litellm --request_timeout 300

--max_budget

  • 기본값: None
  • 타입: float
  • API 호출의 최대 예산 설정. OpenAI, TogetherAI, Anthropic 같은 호스팅 모델에서 동작해요.
litellm --max_budget 100.0

--drop_params

  • 타입: bool (Flag)
  • 매핑되지 않은 파라미터를 버려요.
litellm --drop_params

--add_function_to_prompt

  • 타입: bool (Flag)
  • 함수가 전달됐지만 지원되지 않으면, 프롬프트의 일부로 전달해요.
litellm --add_function_to_prompt

데이터베이스 구성 (Database Configuration)

--iam_token_db_auth

  • 기본값: False
  • 타입: bool (Flag)
  • Amazon RDS 또는 Amazon Aurora의 PostgreSQL에 저장된 비밀번호 대신 수명이 짧은 IAM 토큰으로 인증해요.
  • LiteLLM은 boto3로 토큰을 생성하고 만료 전에 갱신해요.
  • 이 옵션은 AWS만 지원해요. Azure Database for PostgreSQL은 --azure_postgresql_auth를 사용하세요. Google Cloud SQL은 --auto-iam-authn으로 Cloud SQL Auth Proxy를 실행한 후 DATABASE_URL을 로컬 프록시 연결로 구성하세요. Cloud SQL에서는 이 플래그를 활성화하지 마세요.
  • 필수 환경 변수:
    • DATABASE_HOST - RDS 데이터베이스 호스트
    • DATABASE_PORT - 데이터베이스 포트
    • DATABASE_USER - 데이터베이스 사용자
    • DATABASE_NAME - 데이터베이스 이름
    • DATABASE_SCHEMA (선택) - 데이터베이스 스키마
litellm --iam_token_db_auth

환경 변수로 설정하기: IAM_TOKEN_DB_AUTH

export IAM_TOKEN_DB_AUTH=True
export DATABASE_HOST=mydb.us-east-1.rds.amazonaws.com
export DATABASE_PORT=5432
export DATABASE_USER=mydbuser
export DATABASE_NAME=mydb
litellm

Amazon ECS 설정

Amazon ECS에서 LiteLLM을 실행하는 경우:

  • Amazon RDS 또는 Aurora PostgreSQL 인스턴스에서 IAM 데이터베이스 인증을 활성화하세요.
  • IAM 인증용 PostgreSQL 사용자를 구성하세요.
  • ECS 태스크 역할에 그 사용자로 데이터베이스에 연결할 권한을 부여하세요.
  • ECS 태스크 정의에 IAM_TOKEN_DB_AUTH=True와 필수 DATABASE_* 변수를 설정하세요.
  • LiteLLM은 태스크 역할의 AWS 자격 증명을 사용해 데이터베이스 토큰을 생성·갱신해요. 정적 데이터베이스 비밀번호는 필요 없어요.
  • 이 설정들은 LiteLLM이 시작할 때 태스크 환경에서 읽혀요. 플래그나 연결 파라미터를 바꾸려면 새 태스크 정의를 배포하거나 프록시 태스크를 재시작하세요. 토큰 갱신은 재시작이 필요 없어요.

--azure_postgresql_auth

  • 기본값: False
  • 타입: bool (Flag)
  • Azure Database for PostgreSQL Flexible Server에 저장된 비밀번호 대신 수명이 짧은 Microsoft Entra ID 액세스 토큰으로 인증해요.
  • LiteLLM은 Azure Identity 라이브러리를 통해 https://ossrdbms-aad.database.windows.net/.default 스코프의 토큰을 요청하고 만료 전에 갱신해요.
  • 이 옵션은 Azure만 지원하며 --iam_token_db_auth와 결합할 수 없어요. 둘 다 활성화되면 시작 시 프록시가 종료돼요.
  • 필수 환경 변수:
    • DATABASE_HOST - 서버 호스트 (예: myserver.postgres.database.azure.com)
    • DATABASE_USER - PostgreSQL 역할로 존재하는 Microsoft Entra 주체 (예: 관리 ID 이름이나 사용자 주체 이름)
    • DATABASE_NAME - 데이터베이스 이름
    • DATABASE_PORT (선택) - 데이터베이스 포트, 기본 5432
    • DATABASE_SCHEMA (선택) - 데이터베이스 스키마
litellm --azure_postgresql_auth

환경 변수로 설정하기: AZURE_POSTGRESQL_AUTH

export AZURE_POSTGRESQL_AUTH=True
export DATABASE_HOST=myserver.postgres.database.azure.com
export DATABASE_USER=litellm-proxy
export DATABASE_NAME=litellm
litellm

Azure ID 선택 (Choosing the Azure identity)

LiteLLM은 자격 증명을 환경에서 읽으므로, 하나의 플래그가 모든 호스팅 모델을 다뤄요.

ID 선택 방법
사용자 할당 관리 ID (User-assigned managed identity) ID의 client ID로 AZURE_CLIENT_ID 설정
시스템 할당 관리 ID (System-assigned managed identity) 호스트에 연결된 경우 추가 설정 없음
AKS의 워크로드 ID (Workload identity on AKS) 워크로드 ID 웹훅이 pod에 AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_AUTHORITY_HOST, AZURE_FEDERATED_TOKEN_FILE 주입
서비스 주체 (Service principal) AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET 설정
로컬 개발 (Local development) az login 실행, LiteLLM이 그 세션 사용

DATABASE_USER 설정

주체를 PostgreSQL이 아는 그대로 DATABASE_USER에 넣으세요. @ 포함. [email protected] 같은 사용자 주체 이름은 그대로 들어가고, LiteLLM은 연결 URL을 조립하며 이를 퍼센트 인코딩해요. litellm%40contoso.onmicrosoft.com처럼 이미 퍼센트 인코딩된 값은 그대로 통과되므로, RDS IAM 인증에서 이어받은 배포도 계속 동작해요.

Azure Kubernetes Service 설정

AKS에서 워크로드 ID로 LiteLLM을 실행하는 경우:

  • Azure Database for PostgreSQL Flexible Server에서 Microsoft Entra 인증을 활성화하세요.
  • 워크로드 ID용 PostgreSQL 역할을 생성하세요. Microsoft Entra 관리자로 추가하거나, 기존 관리자가 pgaadauth_create_principal을 실행해 만들 수 있어요.
  • 그 역할에 LiteLLM이 데이터베이스에서 필요로 하는 권한을 부여하세요.
  • LiteLLM 서비스 계정에 ID의 client ID를 어노테이션하고 pod를 워크로드 ID용으로 라벨링하세요.
  • 배포에 AZURE_POSTGRESQL_AUTH=True와 필수 DATABASE_* 변수를 설정하세요.
  • LiteLLM은 pod의 페더레이션 토큰을 사용해 데이터베이스 토큰을 요청·갱신해요. 정적 데이터베이스 비밀번호가 필요 없으므로 서버는 비밀번호 인증을 비활성화한 채 유지할 수 있어요.
  • 이 설정들은 LiteLLM이 시작할 때 환경에서 읽혀요. 플래그나 연결 파라미터를 바꾸려면 프록시를 재시작하세요. 토큰 갱신은 재시작이 필요 없어요.

Helm 차트로 배포하기 (Deploying with the Helm chart)

차트는 데이터베이스 엔드포인트별로 플래그를 켜요. database.writer.useAzureEntraAuth를 설정하면 AZURE_POSTGRESQL_AUTH=true를 내보내고 DATABASE_PASSWORD를 생략하므로, writer는 Secret에 비밀번호가 필요 없어요. 사용자 이름은 여전히 passwordSecret.usernameKey에서 와요.

database:
  writer:
    host: myserver.postgres.database.azure.com
    dbname: litellm
    useAzureEntraAuth: true
    passwordSecret:
      name: litellm-writer-secret
      usernameKey: username

읽기 복제본은 database.reader 아래 같은 키를 받으며, 프록시가 하나의 전역 토글을 읽으므로 writer가 Entra 인증을 사용해야 해요. 같은 엔드포인트에 useIAMAuth와 useAzureEntraAuth를 설정하면 둘을 명명하는 메시지와 함께 렌더가 실패해요.

--use_prisma_db_push

  • 기본값: False
  • 타입: bool (Flag)
  • 데이터베이스 스키마 업데이트에 prisma migrate 대신 prisma db push를 사용해요. 마이그레이션 파일을 만들지 않고 스키마를 빠르게 동기화하고 싶을 때 유용해요.
litellm --use_prisma_db_push

디버깅 (Debugging)

--debug

  • 기본값: False
  • 타입: bool (Flag)
  • 입력에 대한 디버깅 모드 활성화.
litellm --debug

환경 변수로 설정하기: DEBUG

export DEBUG=True
litellm

--detailed_debug

  • 기본값: False
  • 타입: bool (Flag)
  • 상세 디버그 로그를 보기 위한 상세 디버깅 모드 활성화.
litellm --detailed_debug

환경 변수로 설정하기: DETAILED_DEBUG

export DETAILED_DEBUG=True
litellm

--local

  • 기본값: False
  • 타입: bool (Flag)
  • 로컬 디버깅용.
litellm --local

테스트 및 헬스 체크 (Testing & Health Checks)

--test

  • 타입: bool (Flag)
  • 프록시 chat completions URL에 테스트 요청을 보내요.
litellm --test

--test_async

  • 기본값: False
  • 타입: bool (Flag)
  • /queue/requests와 /queue/response 비동기 엔드포인트 호출.
litellm --test_async

--num_requests

  • 기본값: 10
  • 타입: int
  • 비동기 엔드포인트에 보낼 요청 수 (--test_async와 함께 사용).
litellm --test_async --num_requests 100

--health

  • 타입: bool (Flag)
  • config.yaml의 모든 모델에 대해 헬스 체크를 실행해요.
litellm --health

기타 옵션 (Other Options)

--version

  • 짧은 형식: -v
  • 타입: bool (Flag)
  • LiteLLM 버전을 출력하고 종료.
litellm --version

--use_queue

  • 기본값: False
  • 타입: bool (Flag)
  • 비동기 엔드포인트용 celery 워커를 사용하려면.
litellm --use_queue