본문 바로가기
삵
AI

gpt-oss를 vLLM 한 장으로 서빙하기

sstdio.h·2026년 11월 20일·조회 0

OpenAI가 가중치를 공개한 gpt-oss가 나온 뒤로, 사내 GPU 한 장에 이걸 올려 달라는 요청을 자주 받는다. 외부 API로 코드나 로그를 보내기 꺼려지는 팀일수록 그렇다. 막상 올려 보면 모델이 뜨는 것까지는 쉬운데, 생각 과정을 어느 필드에서 받아야 하는지, 함수 호출을 어떻게 켜는지에서 한 번씩 막힌다. 그 두 지점을 중심으로 정리한다.

결론부터 말하자면, gpt-oss-20b는 MXFP4 양자화 상태로 약 16GB VRAM 한 장, gpt-oss-120b는 80GB 한 장(A100 또는 H100)에 올라간다. vllm serve로 그대로 띄우고, 함수 호출은 --tool-call-parser openai --enable-auto-tool-choice로 켠다. 모델이 생각한 내용은 응답의 message.reasoning 필드로 들어온다. 예전 이름인 reasoning_content를 읽으면 최신 vLLM에서는 빈 값이 나온다.

한 장에 올라가는 이유와 harmony 포맷

gpt-oss는 전문가 혼합(MoE) 구조의 모델이고, OpenAI가 가중치를 MXFP4로 미리 양자화해 배포한다. MXFP4는 4비트 부동소수 형식으로, MoE 가중치 대부분이 여기에 담긴다. 덕분에 120b가 80GB 한 장에, 20b가 16GB급 한 장에 들어간다. 별도로 양자화 단계를 거칠 필요 없이 받은 그대로 올리면 된다.

harmony는 gpt-oss가 학습된 전용 대화 포맷이다. 일반 모델처럼 단일 텍스트로 답하지 않고, 생각을 적는 analysis 채널과 사용자에게 보여줄 final 채널을 나눠서 출력한다. vLLM은 이 harmony 출력을 해석해서 analysis 쪽은 reasoning, final 쪽은 content로 갈라 OpenAI 호환 응답에 담아 준다. 그래서 클라이언트 코드에서 harmony 토큰을 직접 파싱할 일은 없다.

vLLM 올리고 모델 띄우기

출시 당시에는 uv pip install --pre vllm==0.10.1+gptoss처럼 전용 휠을 받아야 했지만, 지금은 메인라인 vLLM에 gpt-oss 지원이 들어가 있다. 최신 릴리스를 그냥 설치한다. Python 3.12 기준 가상환경을 권한다.

python3.12 -m venv .venv
source .venv/bin/activate
pip install -U vllm

$ vllm --version
0.34.0

버전 번호는 설치 시점에 따라 다를 수 있다. 중요한 건 뒤에서 다룰 reasoning 필드가 적용된 0.16.0 이상인지다.

20b를 한 장에 띄운다. HuggingFace에서 가중치를 당겨오므로 첫 실행은 다운로드 시간이 걸린다.

vllm serve openai/gpt-oss-20b

120b는 80GB 한 장이면 모델 이름만 바꿔 같은 방식으로 올라간다.

vllm serve openai/gpt-oss-120b

로그 끝에 아래 줄이 보이면 8000번 포트에서 OpenAI 호환 API가 열린 것이다.

INFO:     Started server process
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

KV 캐시가 VRAM에 안 들어가 No available memory for the cache blocks로 죽는 경우가 있다. 이땐 --max-model-len을 낮추거나 --gpu-memory-utilization 0.95로 여유분을 조금 더 내준다. 긴 컨텍스트가 필요 없으면 --max-model-len 8192 정도로 시작해도 충분하다.

생각은 reasoning 필드로 받는다

gpt-oss는 추론량을 요청 단위로 조절한다. 채팅 요청에 reasoning_effort를 low, medium, high 중 하나로 넣는다. 지정하지 않으면 medium으로 동작한다. 낮을수록 생각을 짧게 하고 빨리 답하며, 높을수록 analysis 채널을 길게 쓴다.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

r = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[{"role": "user", "content": "12와 18의 최대공약수는?"}],
    reasoning_effort="high",
)

msg = r.choices[0].message
print("reasoning:", msg.reasoning)
print("answer:", msg.content)

여기서 한 번 걸린다. 예전 안내를 따라 msg.reasoning_content를 찍으면 None이나 빈 문자열이 나온다. vLLM이 추론 필드 이름을 reasoning_content에서 reasoning으로 바꿨기 때문이다(PR #27752, 2025-11-08 병합). 0.16.0부터는 응답에서 옛 이름을 아예 뺐다. 그래서 최신 vLLM을 설치한 상태에서 reasoning_content를 읽으면 조용히 빈 값을 받는다. 에러도 안 난다.

이 증상을 만나면 vLLM을 더 올리지 말고 클라이언트 코드에서 reasoning_content를 reasoning으로 바꾼다. 방향이 반대다. 버전을 올릴수록 옛 필드는 더 확실히 사라지므로, 최신으로 올리라는 조언은 문제를 고착시킨다. 요청 본문에서 입력으로 넣는 reasoning_effort는 그대로 두면 된다.

함수 호출은 --tool-call-parser openai로

함수 호출을 쓰려면 서버를 띄울 때 파서를 지정한다. --tool-call-parser openai가 harmony의 도구 호출 채널을 OpenAI 호환 tool_calls로 바꿔 준다. 이 파서는 --enable-auto-tool-choice가 같이 켜져 있을 때만 로드된다. 둘을 함께 준다.

vllm serve openai/gpt-oss-20b \
    --tool-call-parser openai \
    --enable-auto-tool-choice

이렇게 띄우면 평소 OpenAI SDK 쓰던 대로 tools를 넘기고 tool_calls를 받는다.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "도시의 현재 날씨를 조회한다",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

r = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[{"role": "user", "content": "서울 날씨 알려줘"}],
    tools=tools,
)

print(r.choices[0].message.tool_calls)
[ChatCompletionMessageToolCall(id='call_...', function=Function(arguments='{"city": "서울"}', name='get_weather'), type='function')]

--enable-auto-tool-choice 없이 --tool-call-parser만 주면 파서가 로드되지 않아 모델이 도구 호출 대신 그냥 텍스트로 답한다. 로그에 파서 로드 줄이 안 보이면 이 조합을 먼저 의심한다.

여기까지 올렸으면 reasoning effort를 low와 high로 번갈아 던져 응답 지연과 답의 품질이 어떻게 달라지는지 직접 재 본다. 측정은 요청에 걸리는 시간을 재면 된다.

time curl -s http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"하노이탑 4개 원반 해법"}],"reasoning_effort":"low"}' > /dev/null

effort를 올리면 생성 토큰이 늘어 지연도 함께 늘어난다. 폭은 질문과 하드웨어에 따라 다르므로, 서비스에 쓰기 전에 실제 트래픽에 가까운 프롬프트로 두 설정을 비교해 기본값을 정하는 편이 낫다.

자주 묻는 질문

gpt-oss-20b와 120b는 GPU 한 장에 올라가나?

올라간다. OpenAI가 MXFP4로 미리 양자화해 배포하므로 20b는 약 16GB VRAM 한 장, 120b는 80GB 한 장(A100 또는 H100)에 들어간다. 별도 양자화 없이 vllm serve로 그대로 띄우면 된다.

reasoning_content를 읽었는데 값이 비어 있다.

vLLM이 추론 필드 이름을 reasoning_content에서 reasoning으로 바꿨고, 0.16.0부터 응답에서 옛 이름을 제거했다. 최신 vLLM에서는 message.reasoning을 읽어야 한다. 버전을 더 올리는 게 아니라 클라이언트 코드에서 필드 이름을 바꾸는 게 올바른 조치다.

reasoning effort는 어떻게 설정하나?

채팅 요청 본문에 reasoning_effort를 low, medium, high 중 하나로 넣는다. 지정하지 않으면 medium으로 동작한다. 서버 재시작 없이 요청마다 바꿀 수 있다.

함수 호출이 동작하지 않고 텍스트로만 답한다.

서버를 띄울 때 --tool-call-parser openai와 --enable-auto-tool-choice를 함께 줘야 한다. 파서는 enable-auto-tool-choice가 켜져 있을 때만 로드되므로, 하나만 주면 도구 호출이 파싱되지 않는다.

harmony 포맷을 직접 파싱해야 하나?

OpenAI 호환 API(/v1/chat/completions)를 쓰면 직접 파싱할 필요가 없다. vLLM이 harmony의 analysis 채널을 reasoning으로, final 채널을 content로 갈라 담아 준다. 오프라인 LLM 클래스로 직접 샘플링할 때만 openai-harmony로 인코딩이 필요하다.

관련 글

댓글 0

로그인 후 댓글을 남길 수 있습니다.

아직 댓글이 없습니다.