openai/gpt-oss

gpt‑oss – OpenAI에서 출시한 오픈웨이트 LLM

무엇인가요 – OpenAI가 새로 출시한 오픈웨이트 언어 모델인 gpt‑oss‑120b (약 117B 파라미터, 5.1B 활성) 및 gpt‑oss‑20b (약 21B 파라미터, 3.6B 활성)을 실행하기 위한 레퍼런스 코드를 제공하는 리포지토리입니다. 이 모델들은 고수준 추론, 도구 사용(브라우저, Python), 에이전트 작업에 최적화되어 있습니다. 리포지토리 자체에는 모델 가중치가 포함되어 있지 않습니다. 가중치는 Hugging Face에 호스팅되어 있으며, HF CLI로 다운로드할 수 있습니다.

핵심 아이디어

Harmony 응답 형식 – 모델이 훈련된 구조화된 채팅 스키마입니다. 모든 추론 코드는 이 형식에 따라 프롬프트와 출력을 기대합니다. 그렇지 않으면 모델이 올바르게 동작하지 않습니다.
MXFP4 양자화 – 훈련 후 양자화로 MoE 가중치를 압축하여 120B 모델을 단일 80GB GPU(예: H100, MI300X)에 맞추고, 20B 모델을 약 16GB에 맞춥니다.
Apache‑2.0 라이선스 – 허용적인 라이선스로, 상용 사용 및 수정이 가능하며, 코피레프트 제한이 없습니다.

주요 기능 (README에서)

기능	의미
가변 추론 노력	추론 시 저/중/고 수준의 노력 선택 가능. 지연과 추론 깊이 사이의 트레이드오프 가능.
완전한 사고 체인	모델이 내부 추론 단계를 반환합니다(엔드유저용이 아님). 디버깅 및 신뢰성 향상에 도움.
파인튜닝 가능	표준 PyTorch 파이프라인을 통해 사용자 데이터로 추가 파인튜닝 가능.
에이전트 기능	함수 호출, 웹 브라우징, Python 실행, 구조화된 출력의 네이티브 지원. 모두 Harmony 형식으로 표현.
양자화 (MXFP4)	120B 모델을 단일 80GB GPU, 20B 모델을 16GB에서 실행 가능. 전체 정밀도 체크포인트와 동일한 평가 품질 유지.
다중 백엔드	PyTorch(교육용), Triton(단일 GPU 최적화), Metal(Apple Silicon), vLLM, Transformers, Ollama, LM Studio용 즉시 사용 가능한 래퍼 포함.

모델 다운로드 방법

# 120B
hf download openai/gpt-oss-120b --include "original/*" --local-dir gpt-oss-120b/
# 20B
hf download openai/gpt-oss-20b --include "original/*" --local-dir gpt-oss-20b/

가중치는 Hugging Face Hub에서 SafeTensors 형식으로 저장됩니다. Apple Silicon 사용자는 사전 변환된 Metal 바이너리도 다운로드할 수 있습니다.

🤗 Transformers를 통한 빠른 추론

from transformers import pipeline
model_id = "openai/gpt-oss-120b"
pipe = pipeline(
    "text-generation",
    model=model_id,
    torch_dtype="auto",
    device_map="auto",
)
messages = [{"role": "user", "content": "양자역학을 명확하고 간결하게 설명해 주세요."}]
out = pipe(messages, max_new_tokens=256)
print(out[0]["generated_text"][-1])

파이프라인은 자동으로 Harmony 채팅 템플릿을 적용합니다. model.generate를 직접 호출할 경우, 프롬프트를 수동으로 포맷하거나 openai‑harmony 패키지를 사용해야 합니다.

레퍼런스 백엔드 실행

백엔드	설치 방법	일반적인 하드웨어
PyTorch (레퍼런스)	`pip install -e "[torch]"`	4× H100 (비효율적, 교육용)
Triton (단일 GPU)	Triton을 소스에서 빌드한 후 `pip install -e "[triton]"`	1× 80GB GPU (H100/MI300X)
Metal (Apple Silicon)	`GPTOSS_BUILD_METAL=1 pip install -e "[metal]"`	Apple M-시리즈 칩
vLLM	`uv pip install --pre vllm==0.10.1+gptoss …`	vLLM가 지원하는 모든 GPU
Ollama	`ollama pull gpt-oss:20b` (또는 `:120b`)	Ollama 런타임을 통한 소비자급 CPU/GPU
LM Studio	`lms get openai/gpt-oss-20b`	Ollama와 동일

각 구현은 작은 CLI(python -m gpt_oss.generate …)와 터미널 채팅 예제를 제공하며, 도구 사용(브라우저, Python)과 Harmony 형식을 시연합니다.

리포지토리에 포함된 도구

브라우저 도구 – 모델 훈련 시 사용된 최소한의 웹 검색/페이지 가져오기 인터페이스. 두 가지 백엔드(YouComBackend, ExaBackend) 제공. 코드는 의도적으로 단순하며 교육용만으로 표시됨. 프로덕션 시스템은 보안되고 사전 격리된 브라우저 서비스로 교체해야 함.
Python 도구 – 임의의 Python 스크립트를 실행하는 상태 없는 실행기. 연구용 데모용. 사전 격리(샌드박싱)는 사용자 책임.

두 도구 모두 모델이 Harmony 메시지를 통해 호출할 수 있는 작은 JSON 기반 프로토콜을 노출합니다.

클라이언트 예제

터미널 채팅 (gpt_oss.chat) – 추론 노력 수준 전환, 브라우저 또는 Python 도구 활성화, 추론 백엔드 선택이 가능한 인터랙티브 REPL.
응답 API 서버 (gpt_oss.responses_api.serve) – OpenAI의 Responses API를 모방하는 경량 서버. 기존 채팅 완성 프론트엔드와의 통합에 유용.
Codex 통합 – 작은 설정 스니펫으로 오픈소스 Codex 클라이언트를 로컬에서 제공된 gpt‑oss 엔드포인트(예: Ollama 경유)에 연결하는 방법을 보여줌.

라이선스 및 기여

라이선스: Apache 2.0 – 상용 및 연구용으로 자유롭게 사용 가능. 바이럴 코피레프트 없음.
기여: 일반적인 OpenAI 오픈소스 기여 모델(풀 리퀘스트, 코드 스타일 체크)을 따릅니다. 레퍼런스 구현은 의도적으로 최적화되지 않았습니다. 성능 향상이나 프로덕션 수준 도구 추가 기여는 특히 환영합니다.

이 리포지토리를 사용할 때

연구 및 프로토타이핑 – 검사, 파인튜닝, 사용자 정의 에이전트에 통합 가능한 최신 오픈웨이트 LLM이 필요할 때.
도구 확장 에이전트 – 내장된 브라우저 및 Python 도구를 통해 검색 기반 생성 또는 코드 실행 루프 실험 가능.
성능 탐색 – Triton 및 Metal 백엔드는 MXFP4 양자화가 120B MoE 모델을 단일 GPU에 맞추는 방법을 보여줍니다.
학습 – PyTorch 레퍼런스 코드는 의도적으로 단순하여 MoE 아키텍처와 토큰 수준 추론 파이프라인 교육 자료로 적합합니다.

결론: openai/gpt-oss는 진정한 프로덕션 중심의 오픈웨이트 LLM 프로젝트입니다. 모델, 구조화된 채팅 형식(Harmony), 여러 하드웨어 스택용 레퍼런스 추론 코드, 예제 클라이언트를 제공하여, 어떠한 프로퍼라이어터리 OpenAI API 없이도 120B 및 20B 모델에서 추론, 파인튜닝, 에이전트 애플리케이션 구축이 가능하게 합니다.