OpenAI 호환 엔드포인트 연결하기

여러분이 직접 띄운 vLLM 서버나, 새로 나온 OpenAI 호환 추론 API를 LiteLLM에서 불러야 한다면 어떻게 해야 할까요? 답은 의외로 간단해요. LiteLLM은 OpenAI 공식 Python 라이브러리를 그대로 사용해서 OpenAI 호환 엔드포인트를 openai/ 프리픽스로 호출합니다. 이 페이지가 그 연결 방법의 전부예요.

출처: 공식문서 - OpenAI-Compatible Endpoints

기본 원리 — `openai/` 프리픽스

프로바이더를 openai로 잡으면 LiteLLM은 요청을 OpenAI 호환 엔드포인트로 라우팅하고, OpenAI 공식 Python 라이브러리로 그 호출을 처리해요. 이 라이브러리는 모든 요청에 API 키를 요구합니다. api_key 파라미터나 OPENAI_API_KEY 환경변수로 주면 돼요.

주의할 점이 하나 있어요. 요청마다 가짜 API 키를 넘기는 게 싫다면, openai/ 대신 그 엔드포인트에 정확히 맞는 프로바이더(hosted_vllm, llamafile 등)를 쓰는 편이 낫습니다. 그런 프로바이더는 키 없이 인증을 처리하거든요.

OpenAI 프록시 뒤에 있는 모델을 호출하려면 두 가지만 고치면 돼요.

/chat/completions를 부를 때는 모델 이름 앞에 openai/를 붙여요. 그렇게 해야 LiteLLM이 "OpenAI 채팅 엔드포인트를 부르는 구나" 하고 알아챕니다.
/completions(완성)을 부를 때는 앞에 text-completion-openai/를 붙여요. 단, /v1/completions 경로로 부르는 openai/ 엔드포인트에는 필요 없습니다.
base url에 /v1/embedding 같은 걸 추가로 붙이지 마세요. LiteLLM이 openai-client로 호출하면서 관련 엔드포인트를 자동으로 붙여 넣습니다.

SDK에서 호출하기

완성(completion) 호출 예시입니다.

import litellm
import os

response = litellm.completion(
    model="openai/mistral",               # model에 `openai/` 프리픽스를 붙여 OpenAI로 라우팅
    api_key="sk-1234",                    # OpenAI 호환 엔드포인트의 API 키
    api_base="http://0.0.0.0:4000",       # 커스텀 OpenAI 엔드포인트의 API Base
    messages=[
                {
                    "role": "user",
                    "content": "Hey, how's it going?",
                }
    ],
)
print(response)

임베딩도 같은 패턴이에요. input에 텍스트 목록을 넘기면 됩니다.

import litellm
import os

response = litellm.embedding(
    model="openai/GPT-J",                 # model에 `openai/` 프리픽스
    api_key="sk-1234",                    # OpenAI 호환 엔드포인트의 API 키
    api_base="http://0.0.0.0:4000",       # 커스텀 OpenAI 엔드포인트의 API Base
    input=["good morning from litellm"]
)
print(response)

Proxy 서버에서 쓰기

LiteLLM Proxy로 OpenAI 호환 엔드포인트를 노출하는 흐름도 크게 다르지 않아요. config.yaml을 고치고, 프록시를 띄우고, 요청을 보내면 됩니다.

1. config.yaml 수정

model_list:
  - model_name: my-model
    litellm_params:
      model: openai/<your-model-name>  # OpenAI 프로바이더로 라우팅하려면 openai/ 프리픽스
      api_base: <model-api-base>       # OpenAI 호환 프로바이더의 api base
      api_key: api-key                 # 모델에 보낼 api key

테스트할 때 Not Found Error가 나면 api_base에 /v1 접미사가 있는지 확인하세요. 예를 들면 http://vllm-endpoint.xyz/v1처럼요.

2. 프록시 시작

$ litellm --config /path/to/config.yaml

3. 요청 보내기 — 프록시 주소를 base_url로 한 OpenAI 클라이언트를 쓰면 됩니다(가상 키를 쓰는 경우 api_key에 프록시 키를 넣어요).

import openai
client = openai.OpenAI(
    api_key="sk-1234",             # litellm proxy key (가상 키를 쓸 때)
    base_url="http://0.0.0.0:4000" # litellm proxy base url
)

response = client.chat.completions.create(
    model="my-model",
    messages = [
        {
            "role": "user",
            "content": "what llm are you"
        }
    ],
)

print(response)

curl로도 같은 요청을 보낼 수 있어요.

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

고급 — 시스템 메시지 비활성화

일부 vLLM 모델(gemma 등)은 시스템 메시지를 지원하지 않아요. 그런 모델의 요청을 user 메시지로 매핑하고 싶다면 supports_system_message 플래그를 씁니다.

model_list:
- model_name: my-custom-model
  litellm_params:
      model: openai/google/gemma
      api_base: http://my-custom-base
      api_key: "" 
      supports_system_message: False # 핵심 변경

어떤 때 이 방법을 쓰나요

우리가 운영 중인 OpenAI 호환 서버(vLLM, 내부 게이트웨이 등)가 있을 때.
아직 LiteLLM에 정식 프로바이더로 등록되지 않은 OpenAI 호환 서비스를 빠르게 연결할 때.

반대로 OpenAI 호환 프로바이더를 "정식"으로 등록하고 싶다면, 다음 페이지인 OpenAI 호환 프로바이더 추가(JSON)를 보세요. JSON 한 줄로 끝나는 간단한 방법이 기다리고 있어요.

더 알아보기

OpenAI 호환 프로바이더 추가(JSON) — 등록을 영구적으로 만들기
지원 프로바이더 개요 — 어떤 프로바이더가 정식 지원되는지
커스텀 API 서버 (Custom Format) — OpenAI 호환도 아닌 독자 형식을 연결

OpenAI 호환 엔드포인트 연결하기