클라이언트 측 메타데이터 태그 거부

클라이언트 측 메타데이터 태그 거부 (Reject Client-Side Metadata Tags)

출처: 문서

본문

개요 (Overview)

reject_clientside_metadata_tags 설정을 사용하면 사용자가 API 요청에서 클라이언트 측 metadata.tags를 넘기는 것을 막을 수 있어요. 이를 통해 태그가 API 키 메타데이터에서만 상속되고, 사용자가 예산 추적이나 라우팅 결정에 영향을 주려고 태그를 재정의할 수 없게 보장해요.

사용 사례 (Use Case)

이 기능은 다음과 같은 멀티 테넌트 시나리오에서 특히 유용해요:

  • API 키 태그를 기반으로 엄격한 예산 추적을 적용하고 싶을 때
  • 사용자가 커스텀 클라이언트 측 태그를 보내 라우팅 결정을 조작하는 것을 막고 싶을 때
  • 일관된 태그 기반 필터링과 보고를 보장해야 할 때

설정 (Configuration)

config.yaml에 다음을 추가해요:

general_settings:
  reject_clientside_metadata_tags: true
  # Default is false/null

동작 (Behavior)

reject_clientside_metadata_tags: true 일 때

거부되는 요청 예시:

curl -X POST http://localhost:4000/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [{"role": "user", "content": "Hello"}],
    "metadata": {
      "tags": ["custom-tag"]  # This will be rejected
    }
  }'

오류 응답:

{
  "error": {
    "message": "Client-side 'metadata.tags' not allowed in request. 'reject_clientside_metadata_tags'=True. Tags can only be set via API key metadata.",
    "type": "bad_request_error",
    "param": "metadata.tags",
    "code": 400
  }
}

허용되는 요청 예시:

curl -X POST http://localhost:4000/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [{"role": "user", "content": "Hello"}],
    "metadata": {
      "custom_field": "value"  # Other metadata fields are allowed
    }
  }'

reject_clientside_metadata_tags: false이거나 설정되지 않았을 때

클라이언트 측 metadata.tags가 포함된 요청을 포함해 모든 요청이 허용돼요.

API 키로 태그 설정하기

reject_clientside_metadata_tags가 활성화되면 태그는 API 키 메타데이터에 설정해야 해요:

curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "tags": ["team-a", "production"]
    }
  }'

이 태그들은 해당 API 키로 만든 모든 요청에 자동으로 상속돼요.

완전한 예시 설정 (Complete Example Configuration)

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

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: "postgresql://user:***@localhost:5432/litellm"
    # Reject client-side tags
  reject_clientside_metadata_tags: true

    # Optional: Also enforce user parameter
  enforce_user_param: true

유사한 기능들 (Similar Features)

  • enforce_user_param — 모든 요청에 'user' 파라미터를 포함하도록 요구해요.
  • 태그 기반 라우팅 (Tag-based routing) — 지능적인 요청 라우팅에 태그를 사용해요.
  • 예산 추적 (Budget tracking) — 태그별 지출을 추적해요.

참고 사항 (Notes)

  • 이 검사는 LLM API 라우트(예: /chat/completions, /embeddings)에만 적용돼요.
  • 관리 엔드포인트(예: /key/generate)는 영향을 받지 않아요.
  • 검사는 요청 본문에 클라이언트 측 metadata.tags가 없는지 검증해요.
  • 다른 메타데이터 필드는 요청에서 계속 전달할 수 있어요.
  • API 키에 설정된 태그는 모든 요청에 계속 적용돼요.

더 알아보기 (Learn more)