VESSL에서 OpenAI GPT‑OSS를 LoRA로 파인튜닝하는 가장 쉬운 방법

이 가이드는 VESSL 플랫폼에서 OpenAI GPT‑OSS 모델(20B, 120B)을 LoRA로 파인튜닝하고, 결과물을 모델 레지스트리 업로드 → 서빙까지 연결하는 과정을 단계별로 설명합니다.

What is GPT‑OSS?

GPT‑OSS는 OpenAI가 2025년 8월 5일 공개한 오픈‑웨이트 모델 패밀리로, Harmony 응답 포맷과 MXFP4(4‑bit) 양자화를 채택해 대형 모델을 단일 H100 80 GB(120B) / 16 GB급(20B) 환경에서도 구동할 수 있도록 설계되었습니다. 상용 모델과는 달리 누구나 무료로 다운로드, 사용할 수 있으며 사용자의 목적에 맞게 수정할 수 있습니다. GPT-OSS의 라이선스는 Apache‑2.0입니다.(OpenAI)

1) MoE(Mixture‑of‑Experts) 아키텍처

120B: 128 전문가 중 토큰당 4개 활성, 20B: 32 전문가 중 4개 활성(shared expert 없음).
MoE 가중치가 전체 모델 파라미터의 90%를 차지하지만, 희소(sparse) 구조로, 추론 효율을 확보합니다.
모델 크기 대비 매우 빠른 추론이 가능한 핵심 요소

2) Native MXFP4(마이크로스케일링 FP4)

OCP(Open Compute Project) Microscaling Formats v1.0의 FP4 사양 기반으로, 32개 단위의 블록 스케일링을 적용합니다.
FP4는 확률적 반올림(Stochastic Rounding)과 RHT(Random Hadamard Transform)과 결합해, 대형 MoE 가중치에 4‑bit 정밀도(precision)를 적용하면서도 정확도를 유지하도록 설계되었으며 추론뿐만 아니라 학습에서도 직접 사용 가능합니다.

3) Harmony 포맷(대화/추론/툴 호출)

GPT‑OSS는 Harmony 포맷으로 사후학습(post‑training) 되어 있으며, o200k_harmony 토크나이저와 함께 사용하는 것이 권장됩니다.
다중 채널 출력: CoT(Chain‑of‑Thought), 도구 호출(tool call), 일반 응답을 지원하며, 명확한 지시 계층 구조와 도구 네임스페이스를 제공합니다.
- 역할/채널 체계: system / developer / user / assistant / tool + analysis / final
추론(reasoning) 아웃풋 또는 structured function call(= tool call)을 효율적으로 생성할 수 있도록 설계되어 있습니다.

왜 VESSL로 GPT‑OSS 파인튜닝을 해야 할까요?

바로 사용 가능한 학습 환경: VESSL에서는 GPT‑OSS 학습에 맞춘 Torch/CUDA Triton 커널이 포함된 컨테이너 이미지를 제공하여 바로 실행할 수 있습니다.
최적화된 하드웨어 제공: 즉시 사용 가능한 H100 80GB GPU로 GPT-OSS-20B/120B 모델을 지원합니다. 120B는 단일 GPU 적재도 가능하지만 처리량을 위해 TP(Tensor Parallel) 구성을 권장합니다. (vLLM Blog)
통합 ML/LLMOps 환경: 실시간 학습 지표 모니터링, 자동 체크포인트·모델 저장, 레지스트리·원클릭 배포까지 엔드‑투‑엔드 워크플로를 제공합니다.

단계별 가이드

1. VESSL 계정 및 프로젝트 생성

먼저 vessl.ai에서 VESSL 계정을 생성하고, 대시보드에서 새 프로젝트를 원하는 이름으로 만듭니다. 예제에서는 gpt-oss-finetuning 이름을 사용합니다.

2. VESSL CLI 설정

VESSL CLI를 설치하고 CLI 환경을 설정합니다.

# Install VESSL CLI (skip if already installed)
pip install vessl

# Configure VESSL
vessl configure --organization YOUR_ORG_NAME --project gpt-oss-finetuning

3. 예제 레포지토리 클론

VESSL 예제 레포지토리에 이미 GPT‑OSS를 파인튜닝하기 위한 코드와 레시피가 포함되어 있습니다. 레포지토리를 클론하고 파인튜닝 디렉토리로 이동합니다.

git clone https://github.com/vessl-ai/examples.git
cd examples/runs/finetune-llms

4. 파인튜닝 실행

finetune-llms 폴더에는 파인튜닝에 필요한 아래와 같은 스크립트들이 준비되어 있습니다.

파인튜닝 스크립트: main.py, model.py, dataset.py 등 모델을 효율적으로 파인튜닝하기 위한 최적화된 코드
VESSL Run 템플릿: run_yamls/run_lora_gpt_oss.yaml — VESSL에서 바로 실행 가능한 파인튜닝 설정 파일

run_lora_gpt_oss.yaml 파일을 열어 설정을 확인해봅니다. 주요 설정은 다음과 같습니다.

모델 및 데이터셋:

env:
  MODEL_NAME: openai/gpt-oss-20b  # or openai/gpt-oss-120b
  DATASET_NAME: HuggingFaceH4/Multilingual-Thinking
  REPOSITORY_NAME: gpt-oss-20b-multilingual-reasoner

HuggingFace에 업로드된 HuggingFaceH4/Multilingual-Thinking 데이터셋을 사용하여 학습 진행 - Huggingface에 올라온 다른 데이터셋 혹은 별도의 데이터셋 사용도 가능합니다.
gpt-oss-20b-multilingual-reasoner라는 이름의 VESSL Model에 모델이 저장됩니다.

리소스 설정:

resources:
  cluster: vessl-eu-h100-80g-sxm
  preset: gpu-h100-80g-small
image: quay.io/vessl-ai/torch:2.8.0-cuda12.8

gpu-h100-80g-small: H100 80 GB 1장 사용. gpt-oss-120b과 같은 큰 사이즈 모델 학습 긴 시퀀스·고처리량이 필요하면 멀티 GPU/TP 구성을 권장합니다.
GPT‑OSS를 지원하는 Torch 2.8.0 + CUDA 12.8 컨테이너 환경 사용.

학습 하이퍼파라미터
- lora_r: 32 - 파라미터 효율성을 위한 LoRA 랭크
- lora_alpha: 64 - LoRA 스케일링 팩터
- lora_target_modules: all-linear - MoE 전문가 레이어를 포함한 모든 선형 레이어 대상
최적화 설정:
- lr_scheduler_type: cosine_with_min_lr - 최소 학습률(learning rate)이 있는 코사인 스케줄
- warmup_ratio: 0.03 - 3% 워밍업 스텝
메모리 최적화:
- load_in_4bit: True - 메모리 효율을 위한 4비트 양자화
- gradient_checkpointing: True - 메모리를 위해 연산 트레이드오프
- per_device_train_batch_size: 4 - GPU당 배치 크기
- gradient_accumulation_steps: 4 - 실질적 배치 크기 16
bf16: True - GPT-OSS에 필요한 BFloat16 정밀도

설정 파일을 활용해 아래 커맨드로 모델 학습을 위한 VESSL Run을 생성합니다:

vessl run create -f run_yamls/run_lora_gpt_oss.yaml

5. 학습 진행상황 모니터링

Run이 생성되면 콘솔 로그에 대시보드 링크가 나타납니다. 대시보드에서 작업의 상세 정보, 로그, 실험 메트릭을 확인할 수 있습니다.

Docker 이미지 풀링·모델 다운로드 속도에 따라 시작이 지연될 수 있습니다. 로그에 Pulling image "..."가 보이면 정상입니다.

The plots (epoch, grad_norm, learning_rate, loss, mean_token_accuracy, num_tokens) in run.

메모리 부족(OOM, Out Of Memory) 트러블슈팅 가이드

아래의 사항을 하나씩 수정하면서 문제를 해결해보세요.

1. per_device_train_batch_size를 2 또는 1로 감소
2. gradient_accumulation_steps를 그에 맞게 증가
3. lora_r을 32에서 16으로 감소
4. max_length를 2048에서 1024로 감소

6. 모델 업로드 확인

학습이 완료되면 LoRA 어댑터가 자동으로 VESSL Model에 업로드됩니다.

The LoRA adapter is uploaded VESSL Model

모델 각 버전의 상세 내용에서 실제 업로드된 LoRA 어댑터들의 파일도 확인할 수 있습니다.

모델에는 다음과 같은 내용이 포함되어 있습니다:

LoRA 어댑터 가중치 (adapter_model.safetensors)
설정 파일 (adapter_config.json)
모델의 README.md

7. 파인튜닝된 어댑터 서빙: 직서빙 vs 병합(merge)

대부분의 모델 인퍼런스 프레임워크(예: vLLM)가 2025년 8월 현재는 GPT-OSS의 LoRA 어댑터 서빙을 아직 지원하지 않습니다. 따라서, 추론 작업 실행을 위해서는 모델 어댑터를 병합(merge) 후 실행해야 합니다.

어댑터를 머지한 후 머지된 모델로 추론을 진행하는 추론 서버(Inference Server)를 실행합니다.

# Modify {YOUR_ORGANIZATION} in the YAML to your actual organization name
vessl run create -f run_yamls/run_lora_gpt_oss_merge.yaml

아래와 같이 서버가 실행되면 Connect Dropdown에서 Api 버튼을 눌러 endpoint에 접근해볼 수 있습니다.

아래의 파이썬 스크립트를 활용해 파인튜닝된 API를 테스트해보세요!

#!/usr/bin/env python3
"""
Simple streaming test script for GPT-OSS API
"""
import openai
from datetime import datetime

# Configure client for your GPT-OSS server
client = openai.OpenAI(
    base_url="https://{YOUR_API_ENDPOINT}/v1",
    api_key="dummy"  # Not needed for our server
)

# OpenAI Harmony format system prompt
current_date = datetime.now().strftime("%Y-%m-%d")
system_prompt = f"""
<|start|>system<|message|>You are VESSL-GPT, a large language model fine-tuned on VESSL.
Knowledge cutoff: 2024-06
Current date: {current_date}
Reasoning: low
# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>
"""

def test_streaming():
    print("🚀 Testing GPT-OSS Streaming...")
    print("=" * 50)

    try:
        stream = client.chat.completions.create(
            model="gpt-oss-20b",
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": "Write a haiku about artificial intelligence"}
            ],
            max_tokens=1024,
            temperature=0.7,
            stream=True
        )

        print("🤖 GPT-OSS: ", end="", flush=True)

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

        print("\n" + "=" * 50)
        print("✅ Streaming test completed!")

    except Exception as e:
        print(f"❌ Error: {e}")

if __name__ == "__main__":
    test_streaming()