헬스 체크

헬스 체크 (Health Checks)

프록시의 헬스 상태를 소비하는 것은 두 가지예요. 오케스트레이터(Kubernetes, 로드 밸런서, uptime 모니터)는 가벼운 프로브 엔드포인트를 폴링해 프로세스가 올라와 있고 트래픽을 받을 준비가 됐는지 판단해요. 운영자는 각 구성된 LLM이 실제로 요청을 서빙할 수 있는지 확인해요. 이 페이지는 둘 다 다룹니다.

출처: 문서

본문

프로브 엔드포인트 (Probe endpoints)

이 엔드포인트들은 LLM 호출 없이 "게이트웨이 프로세스가 올라와 있고 트래픽을 서빙할 수 있는가?"에 답해요. 프록시의 표준적인 liveness·readiness 계약이에요.

db 값은 오케스트레이터가 정상 워커와 부팅됐지만 데이터베이스에 도달하지 못하는 워커를 구분하게 해줘요. 데이터베이스가 구성되어 있는데 접근할 수 없으면 readiness가 503을 반환해 파드가 로테이션에서 제외돼요.

기본 readiness 페이로드는 의도적으로 상세 정보가 적어서 인증되지 않은 프로브에 안전하게 노출할 수 있어요. 전체 진단(callbacks, cache, version)을 보려면 general_settings.allow_public_health_readiness_details: true로 /health/readiness 자체를 확장하거나, 인증된 GET /health/readiness/details 엔드포인트를 호출하세요.

프록시 포트 4000에서의 최소 Kubernetes 프로브 쌍:

livenessProbe:
  httpGet:
    path: /health/liveliness
    port: 4000
readinessProbe:
  httpGet:
    path: /health/readiness
    port: 4000

전체 배포 매니페스트는 Production Deployment 가이드와 production 체크리스트를 참고하세요.

Admin UI의 모델 헬스

모델이 서빙되고 있는지 확인하는 주요 방법은 Admin UI예요. Models + Endpoints로 이동해 Health Status 탭을 열고 Run All Checks를 클릭하면 돼요. 각 모델에 상태, 실패 시 오류 상세, 마지막 체크·마지막 성공 시간이 표시돼요.

API 대응은 GET /health이며 유효한 키라면 아무 키나 받아요. 구성된 모든 모델에 실제 테스트 요청을 실행하므로 모델당 몇 개의 토큰이 소요돼요.

curl --location 'http://0.0.0.0:4000/health' -H "Authorization: Bearer ***"

{
    "healthy_endpoints": [
        {"model": "azure/gpt-5.6-luna", "api_base": "https://my-endpoint-canada-berri992.openai.azure.com/"}
    ],
    "unhealthy_endpoints": [
        {"model": "azure/gpt-5.6-luna", "api_base": "https://openai-france-1234.openai.azure.com/"}
    ]
}

단일 모델을 확인하려면 ?model=<model_name> 또는 ?model_id=<id>를 전달해요. 모델의 id는 GET /v1/model/info에서 찾을 수 있어요.

백그라운드 헬스 체크 (Background health checks)

기본적으로 /health는 호출마다 모든 모델을 프로브해요. 모델을 너무 자주 조회하지 않으려면 체크를 백그라운드에서 실행하고 /health가 마지막 캐시 결과를 서빙하게 해요. general_settings에서 구성해요.

general_settings:
  background_health_checks: true      # run checks in the background
  health_check_interval: 300          # seconds between runs (default 300)
  health_check_details: true          # include endpoint URLs and errors in the response (default true)

프록시가 넓은 대상에 노출될 때 health_check_details: false로 설정해 응답에서 엔드포인트 URL, 오류 메시지, 기타 파라미터를 제거할 수 있어요.

백그라운드 루프에서 모델을 제외하려면 그 model_info에 disable_background_health_check: true를 설정해요. 이 설정은 백그라운드 루프만 건너뜁니다. 온디맨드 GET /health는 여전히 프로브를 수행하며, general_settings.health_check_skip_disabled_background_models: true로 설정하면 온디맨드 및 공유 헬스 체크에서도 해당 배포를 제외해요.

model_list:
  - model_name: openai/gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      disable_background_health_check: true

모델을 하나씩 제외하는 대신 백그라운드 루프를 특정 모델 그룹으로 제한하려면 general_settings.background_health_check_model_groups에 프로브할 모델 그룹 이름 목록을 설정해요. 목록에 있는 그룹의 배포만 검사되므로 /health는 그 그룹만 보고하고, 헬스 체크 기반 라우팅도 그 그룹에만 적용돼요. 목록에 없는 그룹은 구성된 라우팅 동작을 유지해요. 나중에 추가된 모델 그룹은 목록에 추가하기 전까지 프로브되지 않으며, 문자열 목록이 아닌 값은 시작 시 실패해요.

general_settings:
  background_health_checks: true
  background_health_check_model_groups: ["prod-openai"]

여러 파드에 걸쳐 검사를 조정해서 비싼 모델을 파드당 한 번씩 프로브하지 않게 하려면 공유 헬스 체크 상태를 참고하세요.

모델 모드 (Model modes)

헬스 체크는 모델의 model_info.mode에서 테스트할 작업을 선택해요. 프로브가 올바른 API 표면을 사용하도록 설정하세요. 설정하지 않으면 LiteLLM이 모델의 기능에서 자동 감지하고 채팅 완성으로 대체해요.

와일드카드 라우트(litellm_params.model의 *)에서는 프로브가 호출할 구체적 모델을 health_check_model로 설정해요. 와일드카드 라우트에서 mode를 설정하지 않으면 프로브 요청의 max_tokens가 설정되지 않은 채로 남아요.

model_list:
  - model_name: azure-embedding-model
    litellm_params:
      model: azure/azure-embedding-model
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: "2023-07-01-preview"
    model_info:
      mode: embedding

헬스 체크 튜닝 참조 (Health check tuning reference)

별도로 명시하지 않는 한 모델의 model_info 아래에 설정해요. 프로브 요청의 형태를 제어해요.

Reasoning 모델은 프로바이더가 reasoning 토큰을 완성 예산에 포함시키므로 더 높은 프로브 max_tokens가 필요한 경우가 많아요. reasoning·비-reasoning용 별도 키로 모든 모델을 나열하지 않고도 값을 올릴 수 있어요. 세 개의 환경 변수가 전역 기본값을 설정해요. DEFAULT_HEALTH_CHECK_PROMPT는 기본 프로브 프롬프트("test from litellm")를 재정의하고, BACKGROUND_HEALTH_CHECK_MAX_TOKENS는 전역 max_tokens 대체값이며, BACKGROUND_HEALTH_CHECK_MAX_TOKENS_REASONING은 비와일드카드 reasoning 모델에서 우선합니다.

헬스 체크에 실패한 배포에서 트래픽을 라우팅하지 않으려면 Health Check Driven Routing 문서를 참고하세요.

기타 헬스 엔드포인트 (Other health endpoints)

별도로 명시하지 않는 한 모두 유효한 키가 필요해요.

더 알아보기 (Learn more)

• 헬스 체크 기반 라우팅
• 공유 헬스 체크 상태