vLLM 워커의 OpenAI API 호환성

vLLM 워커는 OpenAI API 호환성을 구현해서, 배포한 모델을 기존 OpenAI 클라이언트 라이브러리로 그대로 쓸 수 있어요. base URL과 API 키만 RunPod 값으로 바꾸면 되죠. API 키는 RunPod API 키, 엔드포인트 ID는 Serverless 엔드포인트 ID를 쓰면 돼요.

출처: vLLM 워커의 OpenAI API 호환성

설정(Setup)

Python

from openai import OpenAI

client = OpenAI(
    api_key="RUNPOD_API_KEY",
    base_url="https://api.runpod.ai/v2/ENDPOINT_ID/openai/v1"
)

JavaScript

import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: ***
  baseURL: "https://api.runpod.ai/v2/ENDPOINT_ID/openai/v1"
});

ENDPOINT_ID와 RUNPOD_API_KEY는 실제 값으로 바꿔 주세요.

지원되는 엔드포인트

Endpoint	Description
`/chat/completions`	채팅 모델 완성(instruction-tuned 모델)
`/completions`	텍스트 완성(베이스 모델)
`/models`	사용 가능한 모델 목록

채팅 완성(Chat completions)

채팅 형식을 따르는 instruction-tuned 모델용이에요.

일반(Standard)

response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, who are you?"}
    ],
    temperature=0.7,
    max_tokens=500
)

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

스트리밍(Streaming)

stream = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Write a short poem about stars."}
    ],
    temperature=0.7,
    max_tokens=200,
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

텍스트 완성(Text completions)

베이스 모델과 원문 텍스트 완성용이에요.

일반(Standard)

response = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    prompt="Write a poem about artificial intelligence:",
    temperature=0.7,
    max_tokens=150
)

print(response.choices[0].text)

스트리밍(Streaming)

stream = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    prompt="The future of AI is",
    temperature=0.7,
    max_tokens=100,
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].text or "", end="", flush=True)

모델 이름

model 파라미터는 아래 둘 중 하나와 일치해야 해요.

배포한 Hugging Face 모델 (예: mistralai/Mistral-7B-Instruct-v0.2)
OPENAI_SERVED_MODEL_NAME_OVERRIDE 환경 변수로 설정한 커스텀 이름

모델 목록을 확인하려면:

models = client.models.list()
print([model.id for model in models])

파라미터

표준 OpenAI 파라미터가 지원돼요. 요청에 그대로 넣으면 됩니다.

공통 파라미터

Parameter	Type	Default	Description
`model`	`string`	Required	배포한 모델 이름
`messages`	`list`	Required	`role`과 `content`를 가진 채팅 메시지
`prompt`	`string`	Required	텍스트 완성 프롬프트
`temperature`	`float`	`0.7`	샘플링 무작위성. 낮을수록 결정적
`max_tokens`	`int`	`16`	생성할 최대 토큰 수
`top_p`	`float`	`1.0`	Nucleus sampling 임계값
`n`	`int`	`1`	생성할 완성 개수
`stop`	`string` or `list`	None	중단 문자열
`stream`	`bool`	`false`	스트리밍 활성화
`presence_penalty`	`float`	`0.0`	이미 나온 토큰에 페널티
`frequency_penalty`	`float`	`0.0`	빈번한 토큰에 페널티

추가 vLLM 파라미터

Parameter	Type	Default	Description
`best_of`	`int`	None	이만큼 생성 후 상위 `n` 반환
`top_k`	`int`	`-1`	Top-k 샘플링. -1 = 모든 토큰
`repetition_penalty`	`float`	`1.0`	반복 토큰 페널티
`min_p`	`float`	`0.0`	최소 확률 임계값
`use_beam_search`	`bool`	`false`	샘플링 대신 beam search 사용
`length_penalty`	`float`	`1.0`	beam search 길이 페널티
`ignore_eos`	`bool`	`false`	EOS 토큰 뒤에도 계속 생성
`skip_special_tokens`	`bool`	`true`	출력에서 특수 토큰 생략
`echo`	`bool`	`false`	출력에 프롬프트 포함

환경 변수

OpenAI 호환성을 커스터마이즈하는 데 쓰는 환경 변수예요.

Variable	Default	Description
`RAW_OPENAI_OUTPUT`	`1`	스트리밍에 원시 OpenAI SSE 형식 활성화
`OPENAI_SERVED_MODEL_NAME_OVERRIDE`	None	응답의 모델 이름 덮어쓰기
`OPENAI_RESPONSE_ROLE`	`assistant`	채팅 완성 응답의 역할

모든 옵션은 환경 변수 레퍼런스에서 확인해요.

OpenAI와의 차이점

토큰 계산: 토크나이저가 달라 수치가 다를 수 있어요.
요금 제한(Rate limits): OpenAI가 아니라 RunPod 정책을 따르고요.
함수/도구 호출: 모델과 vLLM 지원 여부에 달려 있어요.
비전/멀티모달: 기반 모델 지원 여부에 달려 있어요.

문제 해결(Troubleshooting)

Issue	Solution
"Invalid model" 오류	모델 이름이 배포와 일치하는지 확인
인증 오류	OpenAI 키가 아니라 RunPod API 키 사용
타임아웃 오류	큰 모델은 클라이언트 타임아웃 늘리기
예상치 못한 응답 형식	`RAW_OPENAI_OUTPUT=1` 설정

워크플로 도구와 연동

OpenAI 호환 RunPod 엔드포인트를 자동화 워크플로에 붙이려면 n8n 통합 가이드를 따라가 보세요.

vLLM 워커의 OpenAI API 호환성