Generic API

Generic API

LiteLLM 로그를 임의의 HTTP 엔드포인트로 보내는 방법을 알려드릴게요. generic_api 콜백을 쓰면 어떤 HTTP 엔드포인트든 로그 수신 대상으로 삼을 수 있어요.

출처: 문서

본문

빠른 시작 (Quick Start)

model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  callbacks: ["custom_api_name"]

callback_settings:
  custom_api_name:
    callback_type: generic_api
    endpoint: https://your-endpoint.com/logs
    headers:
      Authorization: Bearer ***

구성 (Configuration)

기본 설정 (Basic Setup)

callback_settings:
  <callback_name>:
    callback_type: generic_api
    endpoint: https://your-endpoint.com  # required
    headers:                              # optional
      Authorization: Bearer ***
      Custom-Header: value
    event_types:                          # optional, defaults to all events
      - llm_api_success
      - llm_api_failure

파라미터 (Parameters)

파라미터 타입 필수 설명
callback_type string 예 generic_api여야 함
endpoint string 예 로그를 보낼 HTTP 엔드포인트
headers dict 아니오 요청용 사용자 지정 헤더
event_types list 아니오 이벤트 필터: llm_api_success, llm_api_failure. 기본값은 모든 이벤트.
log_format string 아니오 출력 형식: json_array(기본값), ndjson, 또는 single. 로그를 배치로 묶고 보내는 방식을 제어해요.

사전 구성된 콜백 (Pre-configured Callbacks)

generic_api_compatible_callbacks.json의 내장 구성을 사용할 수 있어요:

litellm_settings:
  callbacks: ["rubrik"]  # loads pre-configured settings

callback_settings:
  rubrik:
    callback_type: generic_api
    endpoint: https://your-endpoint.com  # override defaults
    headers:
      Authorization: Bearer ***

페이로드 형식 (Payload Format)

로그는 JSON 형식의 StandardLoggingPayload 객체로 보내져요:

[
  {
    "id": "chatcmpl-123",
    "call_type": "litellm.completion",
    "model": "gpt-5.6-luna",
    "messages": [...],
    "response": {...},
    "usage": {...},
    "cost": 0.0001,
    "startTime": "2024-01-01T00:00:00",
    "endTime": "2024-01-01T00:00:01",
    "metadata": {...}
  }
]

환경 변수 (Environment Variables)

config 대신 환경 변수로 설정할 수 있어요:

export GENERIC_LOGGER_ENDPOINT=https://your-endpoint.com
export GENERIC_LOGGER_HEADERS="Authorization=Bearer token,Custom-Header=value"

배치 설정 (Batch Settings)

배칭 동작을 제어해요(CustomBatchLogger에서 상속):

callback_settings:
  my_api:
    callback_type: generic_api
    endpoint: https://your-endpoint.com
    batch_size: 100        # default: 100
    flush_interval: 60     # seconds, default: 60

로그 형식 옵션 (Log Format Options)

로그가 엔드포인트로 어떻게 포맷되고 전송되는지 제어해요.

JSON 배열 (JSON Array, 기본값)

callback_settings:
  my_api:
    callback_type: generic_api
    endpoint: https://your-endpoint.com
    log_format: json_array  # default if not specified

배치의 모든 로그를 단일 JSON 배열 [{log1}, {log2}, ...]로 보내요. 기본 동작이며 하위 호환성을 유지해요.

사용 시점: 배치 JSON 데이터를 기대하는 대부분의 HTTP 엔드포인트.

NDJSON (Newline-Delimited JSON)

callback_settings:
  my_api:
    callback_type: generic_api
    endpoint: https://your-endpoint.com
    log_format: ndjson

로그를 줄바꿈으로 구분된 JSON(행당 한 레코드)으로 보내요:

{log1}
{log2}
{log3}

사용 시점: Sumo Logic, Splunk, Datadog처럼 개별 레코드에서 필드 추출을 지원하는 로그 집계 서비스.

장점:

  • 각 로그가 별도 메시지로 수집돼요
  • 필드 추출 규칙이 수집 시점에 작동해요
  • 파싱과 쿼리 성능이 더 좋아요

Single

callback_settings:
  my_api:
    callback_type: generic_api
    endpoint: https://your-endpoint.com
    log_format: single

배치가 플러시될 때 각 로그를 개별 HTTP 요청으로 병렬 전송해요.

사용 시점: 개별 레코드를 기대하는 엔드포인트, 또는 최대 호환성이 필요할 때.

참고: 이 모드는 배치당 N개의 HTTP 요청을 보내서(오버헤드 증가) 엔드포인트가 지원한다면 ndjson 사용을 고려해 보세요.

더 알아보기 (Learn more)