동적 콜백 관리

동적 콜백 관리 (Dynamic Callback Management)

Enterprise 기능

이 기능은 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험판을 시작하거나 데모를 예약하세요. Enterprise에 포함된 것 보기.

LiteLLM의 동적 콜백 관리는 팀이 중앙 인프라 변경 없이 요청별로 로깅 동작을 제어할 수 있게 해줘요. 대규모 서비스 생태계를 관리하는 조직에 필수적이에요:

  • 팀이 자체 컴플라이언스 관리 - 중앙 감독 없이 서비스가 민감한 데이터를 적절히 처리
  • 분산 책임 (Decentralized responsibility) - 공유 인프라를 사용하면서 각 팀이 데이터 처리를 제어

요청에 x-litellm-disable-callbacks 헤더를 전달해 콜백을 비활성화할 수 있어, 팀이 데이터가 로깅되는 위치를 세밀하게 제어해요.

출처: 문서

본문

시작하기: 콜백 목록 보기 및 비활성화 (Getting Started: List and Disable Callbacks)

콜백 관리는 두 단계 프로세스예요:

  1. 먼저 활성 콜백을 나열해 현재 활성화된 것을 확인
  2. 그런 다음 요청에 필요한 특정 콜백을 비활성화

1. 활성 콜백 나열 (List Active Callbacks)

프록시에서 현재 활성화된 모든 콜백을 확인해 무엇을 비활성화할 수 있는지 보세요.

요청

curl -X 'GET' \
  'http://localhost:4000/callbacks/list' \
  -H 'accept: application/json' \
  -H 'x-litellm-api-key: sk-<yo...ey>'

응답

{
  "success": [
    "deployment_callback_on_success",
    "sync_deployment_callback_on_success"
  ],
  "failure": [
    "async_deployment_callback_on_failure",
    "deployment_callback_on_failure"
  ],
  "success_and_failure": [
    "langfuse",
    "datadog"
  ]
}

응답 필드 (Response Fields)

응답은 활성 콜백을 분류하는 세 개의 배열을 포함해요:

  • success - 요청이 성공적으로 완료될 때만 실행되는 콜백. 성공적인 LLM 응답에서 데이터를 받음.
  • failure - 요청이 실패하거나 오류를 만날 때만 실행되는 콜백. 오류 정보와 실패한 요청 데이터를 받음.
  • success_and_failure - 성공과 실패 요청 모두에서 실행되는 콜백. 보통 결과와 무관하게 모든 요청 데이터를 잡아야 하는 로깅/관측성 도구.

2. 콜백 비활성화 (Disable Callbacks)

이제 어떤 콜백이 활성인지 알았으니, x-litellm-disable-callbacks 헤더를 사용해 선택적으로 비활성화할 수 있어요. 위 목록 응답의 어떤 콜백 이름이든 참조할 수 있어요.

단일 콜백 비활성화

x-litellm-disable-callbacks 헤더를 사용해 개별 요청에 대한 특정 콜백을 비활성화해요.

curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer ***" \
    --header 'x-litellm-disable-callbacks: langfuse' \
    --data '{
    "model": "claude-sonnet-5",
    "messages": [
        {
        "role": "user",
        "content": "what llm are you"
        }
    ]
}'

import openai
client = openai.OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://0.0.0.0:4000")
response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {
            "role": "user",
            "content": "what llm are you"
        }
    ],
    extra_headers={
        "x-litellm-disable-callbacks": "langfuse"
    })
print(response)

여러 콜백 비활성화

헤더에 쉼표로 구분된 목록을 제공해 여러 콜백을 비활성화할 수 있어요. /callbacks/list 응답의 콜백 이름 조합을 사용하세요.

curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer ***" \
    --header 'x-litellm-disable-callbacks: langfuse,datadog,prometheus' \
    --data '{
    "model": "claude-sonnet-5",
    "messages": [
        {
        "role": "user",
        "content": "what llm are you"
        }
    ]
}'

import openai
client = openai.OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://0.0.0.0:4000")
response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {
            "role": "user",
            "content": "what llm are you"
        }
    ],
    extra_headers={
        "x-litellm-disable-callbacks": "langfuse,datadog,prometheus"
    })
print(response)

헤더 형식과 대소문자 (Header Format and Case Sensitivity)

예상 헤더 형식 (Expected Header Format)

x-litellm-disable-callbacks 헤더는 다음 형식의 콜백 이름을 받아요 (/callbacks/list가 반환하는 정확한 이름 사용):

  • 단일 콜백: x-litellm-disable-callbacks: langfuse
  • 여러 콜백: x-litellm-disable-callbacks: langfuse,datadog,prometheus

여러 콜백을 지정할 때는 쉼표 주위에 공백 없이 쉼표로 구분된 값을 사용하세요.

대소문자 구분 (Case Sensitivity)

콜백 이름 확인은 대소문자를 구분하지 않아요. 즉 다음은 모두 동등해요:

# These are all equivalent
x-litellm-disable-callbacks: langfuse
x-litellm-disable-callbacks: LANGFUSE
x-litellm-disable-callbacks: LangFuse
x-litellm-disable-callbacks: langFUSE

이것은 단일과 여러 콜백 지정 모두에 적용돼요:

# Case insensitive for multiple callbacks
x-litellm-disable-callbacks: LANGFUSE,datadog,PROMETHEUS
x-litellm-disable-callbacks: langfuse,DATADOG,prometheus

동적 콜백 관리 비활성화 (Disabling Dynamic Callback Management, Enterprise)

일부 조직은 모든 상황에서 모든 요청이 로깅되어야 하는 컴플라이언스 요구사항이 있어요. 이런 경우 동적 콜백 관리를 완전히 비활성화해 사용자가 로깅 콜백을 비활성화하지 못하게 할 수 있어요.

사용 사례 (Use Case)

이는 다음을 요구하는 엔터프라이즈 시나리오를 위해 설계됐어요:

  • 컴플라이언스 요구사항이 모든 API 요청이 로깅되어야 함을 명시
  • 감사 추적이 공백 없이 완전해야 함
  • 보안 정책이 모든 트래픽이 모니터링되어야 함을 요구
  • 콜백 비활성화에 대한 예외가 허용되지 않음

비활성화 방법 (How to Disable)

config.yaml에서 allow_dynamic_callback_disabling을 false로 설정하세요:

litellm_settings:
  allow_dynamic_callback_disabling: false

효과 (Effect)

비활성화되면:

  • x-litellm-disable-callbacks 헤더가 무시됨
  • 모든 구성된 콜백이 매 요청에서 항상 실행
  • 사용자가 헤더나 요청 메타데이터로 로깅을 우회할 수 없음
  • 모든 요청이 프록시 구성대로 로깅이 보장됨

예시: 컴플라이언스 로깅 설정 (Example: Compliance Logging Setup)

보장 로깅이 필요한 조직의 완전한 예시:

# config.yaml
model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
litellm_settings:
  callbacks: ["langfuse", "datadog", "s3"]
  # Disable dynamic callback disabling for compliance
  allow_dynamic_callback_disabling: false

이 구성으로:

  • 모든 요청이 Langfuse, Datadog, S3에 로깅됨
  • 사용자가 헤더로 이 콜백 중 어느 것도 비활성화할 수 없음
  • 컴플라이언스 요구사항에 대해 완전한 감사 추적이 보장됨

info

기본 동작: 동적 콜백 비활성화는 기본적으로 활성화돼 있어요 (allow_dynamic_callback_disabling: true). 보장 로깅을 강제하려면 명시적으로 false로 설정해야 해요.