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 "..."가 보이면 정상입니다.

메모리 부족(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에 업로드됩니다.

모델 각 버전의 상세 내용에서 실제 업로드된 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()

참고자료

• OpenAI
  • https://openai.com/index/introducing-gpt-oss
  • https://cdn.openai.com/pdf/419b6906-9da6-406c-a19d-1bb078ac7637/oai_gpt-oss_model_card.pdf
  • https://cookbook.openai.com/articles/openai-harmony
• OCP MX v1.0
  • https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf
• Hugging Face
  • https://huggingface.co/datasets/HuggingFaceH4/Multilingual-Thinking
• vLLM
  • https://docs.vllm.ai/en/v0.9.1/features/lora
  • https://blog.vllm.ai/2025/08/05/gpt-oss
• Miscellaneous references
  • https://www.codecademy.com/article/gpt-oss-run-locally
  • https://huggingface.co/blog/RakshitAralimatti/learn-ai-with-me
  • https://arxiv.org/abs/2106.09685

VESSL은 엔터프라이즈 환경에서 GPT‑OSS 워크로드를 운영하기 위한 통합 ML/LLMOps입니다. 모델 저장소를 통해 파인튜닝 산출물을 체계적으로 관리하고 신속하게 서비스를 배포할 수 있습니다.