OpenAI 호환 프로바이더 추가하기

OpenAI 호환 프로바이더 추가하기 (JSON)

"우리 회사에서 쓰는 모델 API가 OpenAI 호환인데, LiteLLM에 정식 프로바이더로 등록하고 싶어요." Hyperbolic, Nscale처럼 단순한 OpenAI 호환 프로바이더라면, 코드를 한 줄도 안 짜고 JSON 파일 하나만 수정해서 연결할 수 있어요. 이 페이지가 그 방법을 다룹니다.

출처: 공식문서 - Adding OpenAI-Compatible Providers

빠른 시작 — 세 단계

  1. litellm/llms/openai_like/providers.json 파일을 엽니다.
  2. 프로바이더 설정을 추가합니다.
  3. litellm.completion(model="your_provider/model-name", ...)로 테스트합니다.

완전히 OpenAI 호환인 프로바이더라면 설정은 이게 전부예요.

{
  "your_provider": {
    "base_url": "https://api.yourprovider.com/v1",
    "api_key_env": "YOUR_PROVIDER_API_KEY"
  }
}

네, 끝입니다. 이 한 블록만 넣으면 그 프로바이더가 바로 사용 가능해져요.

설정 항목 파헤치기

필수 필드

  • base_url — API 엔드포인트 (예: https://api.provider.com/v1)
  • api_key_env — API 키를 담은 환경변수 이름 (예: PROVIDER_API_KEY)

선택 필드

  • api_base_env — base_url을 덮어쓰는 환경변수
  • base_class — "openai_gpt"(기본값) 또는 "openai_like"
  • param_mappings — OpenAI 파라미터 이름을 프로바이더 고유 이름으로 매핑
  • constraints — 파라미터 값의 제약 (최솟값/최댓값)
  • special_handling — 콘텐츠 형식 변환 같은 특수 동작

실제 예시로 익히기

완전 호환 프로바이더 — 가장 단순한 형태입니다.

{
  "hyperbolic": {
    "base_url": "https://api.hyperbolic.xyz/v1",
    "api_key_env": "HYPERBOLIC_API_KEY"
  }
}

파라미터 매핑이 필요한 프로바이더 — OpenAI가 max_completion_tokens라고 부르는 것을 프로바이더는 max_tokens로 받는다면, 매핑을 지정할 수 있어요.

{
  "publicai": {
    "base_url": "https://api.publicai.co/v1",
    "api_key_env": "PUBLICAI_API_KEY",
    "param_mappings": {
      "max_completion_tokens": "max_tokens"
    }
  }
}

제약 조건이 있는 프로바이더 — 예를 들어 temperature 범위를 강제하고 싶다면 constraints를 씁니다.

{
  "custom_provider": {
    "base_url": "https://api.custom.com/v1",
    "api_key_env": "CUSTOM_API_KEY",
    "constraints": {
      "temperature_max": 1.0,
      "temperature_min": 0.0
    }
  }
}

Responses API 지원

프로바이더가 OpenAI의 Responses API(/v1/responses)도 지원한다면 supported_endpoints를 추가하세요.

{
  "your_provider": {
    "base_url": "https://api.yourprovider.com/v1",
    "api_key_env": "YOUR_PROVIDER_API_KEY",
    "supported_endpoints": ["/v1/chat/completions", "/v1/responses"]
  }
}

이렇게 하면 litellm.responses()를 추가 코드 없이 바로 쓸 수 있어요.

import litellm

response = litellm.responses(
    model="your_provider/model-name",
    input="Hello, what can you do?",
)
print(response.output)

supported_endpoints를 생략하면 기본값 []가 적용돼요. 단, chat completions는 이 필드와 무관하게 JSON 프로바이더에서 항상 활성화됩니다. 프로바이더는 OpenAI Responses API의 요청·응답 처리를 그대로 물려받기 때문에 스트리밍, 도구, 표준 파라미터가 전부 추가 코드 없이 동작해요.

일상적인 사용

import litellm
import os

# API 키 설정
os.environ["YOUR_PROVIDER_API_KEY"] = "your-key-here"

# Chat completions
response = litellm.completion(
    model="your_provider/model-name",
    messages=[{"role": "user", "content": "Hello"}],
)

# Responses API (supported_endpoints에 "/v1/responses"가 있을 때)
response = litellm.responses(
    model="your_provider/model-name",
    input="Hello",
)

언제 Python 설정 클래스를 써야 하나요

JSON 방식이 항상 정답은 아니에요. 다음이 필요하면 Python 설정 클래스를 써야 합니다.

  • 커스텀 인증 흐름 (OAuth, JWT 등)
  • 복잡한 요청/응답 변환
  • 프로바이더 고유의 스트리밍 로직
  • 고급 도구 호출 변형

채팅 완성의 경우 litellm/llms/your_provider/chat/transformation.py에 OpenAIGPTConfig 또는 OpenAILikeChatConfig를 상속한 설정 클래스를 만들면 됩니다. Responses API에 약간의 오버라이드만 필요하다면 OpenAIResponsesAPIConfig를 상속해 필요한 부분만 덮어써요. litellm/llms/perplexity/responses/transformation.py가 약 40줄짜리 최소 예시로 훌륭한 참고가 됩니다(보통 400줄+ 대비).

테스트하기

등록한 프로바이더를 간단히 테스트해 보세요.

python -c "
import litellm
import os
os.environ['PROVIDER_API_KEY'] = 'your-key'
response = litellm.completion(
    model='provider/model-name',
    messages=[{'role': 'user', 'content': 'test'}]
)
print(response.choices[0].message.content)
"

이미 등록된 프로바이더 예시는 litellm/llms/openai_like/providers.json에서 확인할 수 있어요. 하나씩 열어보면 어떤 패턴이 JSON으로 충분한지 감이 잡힐 거예요.

더 알아보기