OpenAI

LiteLLM에서 OpenAI 채팅 + 임베딩 호출을 사용하는 방법을 알아봐요. 응답 API, 비전, PDF 파싱, 함수 호출 등도 지원해요.

출처: 문서

본문

LiteLLM은 OpenAI Chat + Embedding 호출을 지원해요.

팁: 최신 OpenAI 모델(GPT-5, gpt-5-codex, o3-mini 등)에는 litellm.responses() / Responses API 사용을 권장해요.

필수 API 키

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

사용법

import os
from litellm import completion

os.environ["OPENAI_API_KEY"] = "your-api-key"

# openai call
response = completion(
    model = "gpt-5.6-terra",
    messages=[{ "content": "Hello, how are you?","role": "user"}]
)

Metadata passthrough (preview): litellm.enable_preview_features = True일 때 LiteLLM은 metadata 안의 값만 OpenAI로 전달해요.

LiteLLM Proxy 서버 사용법

여기서 OpenAI 모델을 LiteLLM Proxy Server로 호출하는 방법이에요.

1. 환경에 키 저장

export OPENAI_API_KEY=""

2. Proxy 시작

config.yaml:

model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna                          # The `openai/` prefix will call openai.chat.completions.create
      api_key: os.environ/OPENAI_API_KEY
  - model_name: gpt-3.5-turbo-instruct
    litellm_params:
      model: text-completion-openai/gpt-3.5-turbo-instruct # The `text-completion-openai/` prefix will call openai.completions.create
      api_key: os.environ/OPENAI_API_KEY

하나의 API 키로 모든 openai 모델을 추가하려면:

model_list:
  - model_name: "*"             # all requests where model not in your config go to this deployment
    litellm_params:
      model: openai/*           # set `openai/` to use the openai route
      api_key: os.environ/OPENAI_API_KEY

경고: 이렇게 하면 로드 밸런싱을 하지 않아요. gpt-5.6-terra, gpt-5.6-luna 요청이 모두 이 라우트를 거쳐요.

CLI:

$ litellm --model gpt-5.6-luna

# Server running on http://0.0.0.0:4000

3. 테스트

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

OpenAI SDK:

import openai
client = openai.OpenAI(
    api_key="anything",
    base_url="http://0.0.0.0:4000"
)

# request sent to model set on litellm proxy, `litellm --model`
response = client.chat.completions.create(model="gpt-5.6-luna", messages = [
    {
        "role": "user",
        "content": "this is a test request, write a short poem"
    }
])

print(response)

선택 키 - OpenAI Organization, OpenAI API Base

import os
os.environ["OPENAI_ORGANIZATION"] = "your-org-id"       # OPTIONAL
os.environ["OPENAI_BASE_URL"] = "https://your_host/v1"     # OPTIONAL

Workload Identity Federation (API 키 없음)

정적 OPENAI_API_KEY 대신 proxy는 workload identity federation으로 OpenAI에 인증할 수 있어요. OIDC 토큰을 파일(예: Kubernetes projected service account token)에서 읽고, 단기 OpenAI bearer 토큰으로 교환하며, 만료 전에 갱신해요. openai>=2.32.0 필요.

(환경 변수로 proxy 전역 기본값 설정):

export OPENAI_IDENTITY_PROVIDER_ID="idp_..."
export OPENAI_SERVICE_ACCOUNT_ID="user-..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/tokens/openai"

(config.yaml로 배포별 설정, Admin UI의 Credentials로 자격 증명으로도 가능) 배포에 설정된 값이 환경 변수보다 우선하므로 다른 배포가 다른 서비스 계정으로 연합할 수 있어요.

정적 키가 항상 우선해요. 배포·자격 증명·OPENAI_API_KEY가 API 키를 담고 있으면 연합을 사용하지 않아요. 연합은 API base가 https://api.openai.com이거나 https://eu.api.openai.com 같은 지역 호스트일 때만 적용되며, 다른 OpenAI 호환 서버를 가리키는 사용자 정의 api_base는 계속 키를 사용해요.

proxy 관리자만 배포·자격 증명에 이 필드를 설정할 수 있어요(토큰 파일 경로가 어떤 워크로드 아이덴티티를 교환할지 결정하므로). 채팅 완성, Responses API, 임베딩은 연합을 사용하고, 이미지·오디오·전사·조정·파일·배치·파인튜닝·어시스턴트 호출은 계속 OPENAI_API_KEY를 읽어요.

OpenAI 채팅 완성 모델

모델 목록은 LiteLLM이 유지 관리하며 다음을 포함해요: gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-chat, gpt-5-pro, gpt-5.2, gpt-5.4, gpt-5.5, gpt-6-astra, gpt-5.2-pro, gpt-5.4-pro, gpt-5.5-pro, gpt-5.1 등. 각각 completion(model="<모델명>", messages=messages)으로 호출해요. 이 모델들은 OPENAI_BASE_URL 환경 변수도 지원해요.

OpenAI 웹 검색 모델

OpenAI는 엔드포인트에 따라 두 가지 방식으로 웹 검색을 사용해요:

접근	엔드포인트	모델	활성화 방법
Search Models	`/chat/completions`	`gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview`	`web_search_options` 파라미터 전달
Web Search Tool	`/responses`	`gpt-5`, `gpt-4.1`, `gpt-4o`, 기타 일반 모델	`web_search_preview` 도구 전달

from litellm import completion

response = completion(
    model="openai/gpt-5-search-api",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    web_search_options={
        "search_context_size": "medium"  # Options: "low", "medium", "high"
    }
)

from litellm import responses

response = responses(
    model="openai/gpt-5.6-terra",
    input="What is the capital of France?",
    tools=[{
        "type": "web_search_preview",
        "search_context_size": "low"
    }]
)

자세한 내용은 웹 검색 가이드를 참고해요.

OpenAI 비전 모델

gpt-4o, gpt-4-turbo, gpt-4-vision-preview 등의 모델을 지원해요.

import os
from litellm import completion

os.environ["OPENAI_API_KEY"] = "your-api-key"

# openai call
response = completion(
    model = "gpt-5.6-terra",
    messages=[
        {
            "role": "user",
            "content": [
                            {
                                "type": "text",
                                "text": "What’s in this image?"
                            },
                            {
                                "type": "image_url",
                                "image_url": {
                                "url": "https://awsmp-logos.s3.amazonaws.com/seller-xw5kijmvmzasy/c233c9ade2ccb5491072ae232c814942.png"
                                }
                            }
                        ]
        }
    ],
)

PDF 파일 파싱

OpenAI의 새 file 메시지 타입으로 PDF 파일을 전달해 구조화 출력으로 파싱할 수 있어요.

import base64
from litellm import completion

with open("draconomicon.pdf", "rb") as f:
    data = f.read()

base64_string = base64.b64encode(data).decode("utf-8")

completion = completion(
    model="gpt-5.6-terra",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "file",
                    "file": {
                        "filename": "draconomicon.pdf",
                        "file_data": f"data:application/pdf;base64,{base64_string}",
                    }
                },
                {
                    "type": "text",
                    "text": "What is the first dragon in the book?",
                }
            ],
        },
    ],
)

print(completion.choices[0].message.content)

Proxy에서도 동작해요(config.yaml에 모델 등록 후 /chat/completions 호출).

OpenAI 파인튜닝 모델

ft:gpt-4-0613, ft:gpt-4o-2024-05-13, ft:gpt-3.5-turbo-0125 등 파인튜닝된 모델을 completion(model="ft:...", messages=messages)으로 호출할 수 있어요.

[BETA] 모든 .completions 요청을 Responses API로 라우팅

활성화하면 LiteLLM이 litellm.completion()과 proxy /chat/completions의 OpenAI 트래픽을 Chat Completions 대신 Responses API로 보내요. 이 경로는 일반적으로 OpenAI의 최신 모델 동작·품질과 일치해요(GPT-5급 모델의 추론 출력 등).

옵션 A, 요청별 접두사: openai/responses/ 모델 접두사 사용.

옵션 B, 전역 플래그 (권장): route_all_chat_openai_to_responses = True 설정. 모델 접두사 없이 모든 OpenAI /chat/completions 요청을 자동으로 Responses API로 라우팅해요.

import litellm

litellm.route_all_chat_openai_to_responses = True

response = litellm.completion(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    reasoning_effort="low",
)

proxy config:

litellm_settings:
  route_all_chat_openai_to_responses: true

note: route_all_chat_openai_to_responses는 openai 제공사에만 적용돼요. Azure OpenAI는 영향받지 않아요. LITELLM_ROUTE_ALL_CHAT_OPENAI_TO_RESPONSES=true env var로도 설정할 수 있어요.

고급: `summary` 필드와 함께 `reasoning_effort` 사용

기본적으로 reasoning_effort는 문자열 값("none", "minimal", "low", "medium", "high", "xhigh" — "xhigh"는 gpt-5.1-codex-max와 gpt-5.2 모델만 지원)을 받고 추론 요약 없이 노력 수준만 설정해요.

summary 기능을 선택하려면 reasoning_effort를 딕셔너리로 전달할 수 있어요. 참고: summary 필드는 OpenAI 조직에 검증 상태가 있어야 해요. 검증 없이 summary를 쓰면 OpenAI가 400 오류를 반환해요.

# Option 1: String format (default - no summary)
response = litellm.completion(
    model="openai/responses/gpt-5.6-luna",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    reasoning_effort="high"  # Only sets effort level
)

# Option 2: Dict format (with optional summary - requires org verification)
response = litellm.completion(
    model="openai/responses/gpt-5.6-luna",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    reasoning_effort={"effort": "high", "summary": "auto"}  # "auto", "detailed", or "concise"
)

Summary 필드 옵션: "auto"(모델 기반 자동), "concise"(GPT-5 시리즈 미지원), "detailed"(더 완전한 요약). GPT-5 시리즈는 "auto"·"detailed" 지원, "concise" 미지원. O-시리즈(o3-pro, o4-mini, o3)는 세 가지 모두 지원. o3-mini, o1 같은 일부 모델은 추론 요약을 전혀 지원하지 않아요.

모델별 지원 reasoning_effort 값 (일부):

gpt-5: 기본 medium, 지원 minimal, low, medium, high
gpt-5-nano: 기본 none, 지원 none, low, medium, high
gpt-5.1-codex-max, gpt-5.2, gpt-5.2-pro, gpt-5.5, gpt-5.5-pro: reasoning_effort="xhigh" 지원
gpt-5-pro: reasoning_effort="high"만 허용

참고: GPT-5.1은 더 빠른 저지연 응답을 위해 새 reasoning_effort="none" 설정을 도입했어요. 이는 GPT-5의 "minimal" 설정을 대체해요. reasoning_effort가 설정되지 않으면 OpenAI가 기본값을 사용해요.

`reasoning_items`가 있는 다중 턴 대화

다중 턴 대화에는 OpenAI가 다음 요청에서 추론 상태를 복원하는 데 쓰는 encrypted_content 토큰을 포함한 구조화 블록 reasoning_items가 필요해요. 그 토큰이 반환되길 원하는 모든 호출에 include=["reasoning.encrypted_content"]를 전달해요.

import litellm

messages = [{"role": "user", "content": "Solve this step by step: 2 + 2"}]

# Turn 1 — get reasoning_items (encrypted_content);
response = litellm.completion(
    model="openai/responses/gpt-5.6-luna",
    messages=messages,
    reasoning_effort="low",
    include=["reasoning.encrypted_content"],
)

assistant_msg = response.choices[0].message

# Turn 2 — pass reasoning_items back; LiteLLM converts to the correct Responses API format
messages.append({
    "role": "assistant",
    "content": assistant_msg.content,
    "reasoning_items": assistant_msg.reasoning_items,
})
messages.append({"role": "user", "content": "Now summarize your reasoning."})

response2 = litellm.completion(
    model="openai/responses/gpt-5.6-luna",
    messages=messages,
    reasoning_effort="low",
    include=["reasoning.encrypted_content"],
)

스트리밍에서 reasoning_items(encrypted_content 포함)는 전체 응답이 완료될 때 최종 청크에 도착해요. 스트리밍 중 delta.reasoning_items를 수집해 다음 턴에 다시 전달할 수 있어요.

GPT-5 모델의 Verbosity 제어

verbosity 파라미터는 GPT-5 패밀리 모델의 응답 길이·세부 수준을 제어해요. "low", "medium", "high" 세 값을 받아요. 지원 모델: gpt-5, gpt-5.1, gpt-5-mini, gpt-5-nano, gpt-5-pro. GPT-5-Codex 모델은 verbosity를 지원하지 않아요.

import litellm

# Low verbosity - concise responses
response = litellm.completion(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Write a function to reverse a string"}],
    verbosity="low"
)

OpenAI 채팅 완성 → Responses API 브리지

LiteLLM은 채팅 완성에서 Responses API로의 브리지를 제공해요. completion 인터페이스를 쓰면서 내부적으로 Responses API를 호출하게 해줘요. Responses API 전용 기능(내장 도구, 웹 검색 프리뷰, 코드 인터프리터)을 쓰려 할 때 유용해요.

`openai/responses/` 접두사를 언제 쓸까

각 모델은 model_prices_and_context_window.json에 정의된 mode 속성이 있어서 기본으로 어떤 API 엔드포인트를 쓸지 결정해요:

mode: responses - 모델이 자동으로 Responses API 사용 (예: o1-pro, o3-pro, gpt-5.1-codex, codex-mini-latest)
mode: chat - 모델이 Chat Completions API 기본 사용 (예: gpt-4o, gpt-5, gpt-5-mini, o3, o4-mini)

mode: chat 모델에 web_search_preview 같은 내장 도구를 쓰려면 openai/responses/ 접두사를 추가해요. mode: responses 모델은 접두사 없이 자동으로 내장 도구를 지원해요.

# This will FAIL - gpt-5.6-terra has mode: chat, uses Chat Completions API
response = litellm.completion(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "What is the weather in Paris today?"}],
    tools=[{"type": "web_search_preview"}],  # Not supported in Chat Completions
)

# This will WORK - prefix forces Responses API
response = litellm.completion(
    model="openai/responses/gpt-5.6-terra",
    messages=[{"role": "user", "content": "What is the weather in Paris today?"}],
    tools=[{"type": "web_search_preview"}],  # Supported in Responses API
)

OpenAI 오디오 전사

LiteLLM은 OpenAI 오디오 전사 엔드포인트를 지원해요. 지원 모델: whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe.

from litellm import transcription
import os

# set api keys
os.environ["OPENAI_API_KEY"] = ""
audio_file = open("/path/to/audio.mp3", "rb")

response = transcription(model="gpt-4o-transcribe", file=audio_file)

print(f"response: {response}")

고급

OpenAI API 응답 헤더 가져오기

litellm.return_response_headers = True로 설정하면 OpenAI의 원시 응답 헤더를 얻을 수 있어요. litellm.completion(), litellm.embedding() 함수에서 항상 _response_headers 필드를 얻을 수 있어요.

litellm.return_response_headers = True

# /chat/completion
response = completion(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "hi"}],
)
print("_response_headers=", response._response_headers)

헤더에는 openai-model, openai-organization, openai-processing-ms, x-ratelimit-* 등이 포함돼요.

병렬 함수 호출

import litellm
import json
import os
os.environ['OPENAI_API_KEY'] = "" # litellm reads OPENAI_API_KEY from .env and sends the request

# Example dummy function hard coded to return the same weather
def get_current_weather(location, unit="fahrenheit"):
    """Get the current weather in a given location"""
    if "tokyo" in location.lower():
        return json.dumps({"location": "Tokyo", "temperature": "10", "unit": "celsius"})
    elif "san francisco" in location.lower():
        return json.dumps({"location": "San Francisco", "temperature": "72", "unit": "fahrenheit"})
    elif "paris" in location.lower():
        return json.dumps({"location": "Paris", "temperature": "22", "unit": "celsius"})
    else:
        return json.dumps({"location": location, "temperature": "unknown"})

messages = [{"role": "user", "content": "What's the weather like in San Francisco, Tokyo, and Paris?"}]
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        },
    }
]

response = litellm.completion(
    model="gpt-5.6-luna",
    messages=messages,
    tools=tools,
    tool_choice="auto",  # auto is default, but we'll be explicit
)
print("\nLLM Response1:\n", response)
response_message = response.choices[0].message
tool_calls = response.choices[0].message.tool_calls

completion 호출에 `extra_headers` 설정

import os
from litellm import completion

os.environ["OPENAI_API_KEY"] = "your-api-key"

response = completion(
    model = "gpt-5.6-luna",
    messages=[{ "content": "Hello, how are you?","role": "user"}],
    extra_headers={"AI-Resource Group": "ishaan-resource"}
)

completion 호출에 Organization-ID 설정

이것은 다음 중 한 방식으로 설정할 수 있어요:

환경 변수 OPENAI_ORGANIZATION
litellm.completion(model=model, organization="your-organization-id") 파라미터
litellm.organization="your-organization-id"로 설정

`ssl_verify=False` 설정

자체 httpx.Client를 설정해 고정해요: litellm.completion은 litellm.client_session=httpx.Client(verify=False), litellm.acompletion은 litellm.aclient_session=httpx.AsyncClient(verify=False).

LiteLLM과 함께 OpenAI Proxy 사용

import os
import litellm
from litellm import completion

os.environ["OPENAI_API_KEY"] = ""

# set custom api base to your proxy
litellm.api_base = "https://your_host/v1"

messages = [{ "content": "Hello, how are you?","role": "user"}]

# openai call
response = completion("openai/your-model-name", messages)

api_base를 동적으로 설정해야 한다면 completions에 전달하면 돼요 — completions(...,api_base="your-proxy-api-base").

Proxy 요청에 Org ID 전달

forward_openai_org_id 파라미터로 클라이언트에서 OpenAI로 org ID를 전달해요.

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

general_settings:
    forward_openai_org_id: true # 👈 KEY CHANGE

GPT-5 Pro 특별 참고

GPT-5 Pro는 OpenAI의 가장 고급 추론 모델로 고유한 특성이 있어요:

Responses API Only: /v1/responses 엔드포인트에서만 사용 가능
No Streaming: 스트리밍 응답 미지원
High Reasoning: 최고 노력 추론으로 복잡한 추론 작업용
Context Window: 입력 400,000 토큰 / 출력 272,000 토큰
Pricing: 표준 입력 $15.00 / 출력 $120.00 (1M), 배치 입력 $7.50 / 출력 $60.00
Tools: Web Search, File Search, Image Generation, MCP 지원 (Code Interpreter, Computer Use는 미지원)
Modalities: 텍스트·이미지 입력, 텍스트 출력만

# GPT-5 Pro usage example
response = completion(
    model="gpt-5-pro",
    messages=[{"role": "user", "content": "Solve this complex reasoning problem..."}]
)

비디오 생성

LiteLLM은 Sora를 포함한 OpenAI의 비디오 생성 모델을 지원해요. 자세한 문서는 OpenAI 비디오 생성 문서를 참고해요.

더 알아보기 (Learn more)

OpenAI 응답 API 문서
OpenAI 웹 검색 가이드
OpenAI 비디오 생성 문서

OpenAI

OpenAI

본문

필수 API 키

사용법

LiteLLM Proxy 서버 사용법

1. 환경에 키 저장

2. Proxy 시작

3. 테스트

선택 키 - OpenAI Organization, OpenAI API Base

Workload Identity Federation (API 키 없음)

OpenAI 채팅 완성 모델

OpenAI 웹 검색 모델

OpenAI 비전 모델

PDF 파일 파싱

OpenAI 파인튜닝 모델

[BETA] 모든 .completions 요청을 Responses API로 라우팅

고급: summary 필드와 함께 reasoning_effort 사용

reasoning_items가 있는 다중 턴 대화

GPT-5 모델의 Verbosity 제어

OpenAI 채팅 완성 → Responses API 브리지

openai/responses/ 접두사를 언제 쓸까

OpenAI 오디오 전사

고급

OpenAI API 응답 헤더 가져오기

병렬 함수 호출

completion 호출에 extra_headers 설정

completion 호출에 Organization-ID 설정

ssl_verify=False 설정

LiteLLM과 함께 OpenAI Proxy 사용

Proxy 요청에 Org ID 전달

GPT-5 Pro 특별 참고

비디오 생성

더 알아보기 (Learn more)

고급: `summary` 필드와 함께 `reasoning_effort` 사용

`reasoning_items`가 있는 다중 턴 대화

`openai/responses/` 접두사를 언제 쓸까

completion 호출에 `extra_headers` 설정

`ssl_verify=False` 설정