# 예시

[`examples/`](https://github.com/huggingface/trl/tree/main/examples) 디렉터리에는 TRL 라이브러리를 다양한 애플리케이션에 활용하는 방법을 보여주는 자체 완결형 예제 모음이 포함되어 있습니다. **각 예제는** 시연하는 메서드와 과제를 나타내는 이름(예: `grpo_wordle`, `sft_gpt_oss_chess`)을 가진 별도의 폴더에 위치하며, 예제에 필요한 스크립트, 노트북, 프롬프트, 채팅 템플릿, 평가 코드가 모두 포함되어 있습니다.

기본적인 단일 트레이너 학습 스크립트는 예제가 아닙니다. [`trl/scripts`](https://github.com/huggingface/trl/tree/main/trl/scripts)에 위치하며 [명령줄 인터페이스](clis)(`trl sft`, `trl dpo`, `trl grpo`, …)를 통해 제공됩니다. 각 트레이너의 문서 페이지에는 완전한 실행 가능한 스니펫도 포함되어 있습니다.

공용 리소스는 `examples/` 루트에 있습니다:

- [`examples/deepspeed_configs`](https://github.com/huggingface/trl/tree/main/examples/deepspeed_configs): `--deepspeed`로 전달되는 DeepSpeed ZeRO 설정 파일로, 많은 예제에서 사용됩니다.
- [`examples/fsdp_configs`](https://github.com/huggingface/trl/tree/main/examples/fsdp_configs): FSDP 설정 파일로, `--fsdp --fsdp_config`와 함께 전달됩니다 (명령줄에서 `--fsdp`만 단독으로 사용하려면 transformers 5.10 이상이 필요합니다. 이전 버전의 경우 학습 설정에서 `fsdp=True`로 설정하세요).
- [`examples/datasets`](https://github.com/huggingface/trl/tree/main/examples/datasets): 예제 전반에서 사용되는 `trl-lib` 데이터셋을 생성하는 데 사용된 스크립트입니다.

**시작하기**

다음과 같이 TRL과 추가 의존성을 설치합니다:

```bash
pip install --upgrade trl[quantization]
```

추가 선택적 의존성은 [여기](https://github.com/huggingface/trl/blob/main/pyproject.toml)에서 확인하세요. Notebook 기반 예제는 자체적으로 완결되어 있어 **무료 Colab**에서 실행할 수 있으며, 스크립트 기반 예제는 단일 GPU, 다중 GPU 또는 DeepSpeed 환경에서 실행됩니다(아래 [분산 학습](#distributed-training) 참고).

## 인덱스

| 예시 | 설명 | Colab에서 열기 |
| --- | --- | --- |
| [`async_distillation_math`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_math) | GSM8K에서 [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.0/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer)를 사용한 비동기 온-폴리시 증류: 교사는 vLLM을 통해 HTTP로 제공됩니다. | |
| [`async_distillation_mopd`](https://github.com/huggingface/trl/tree/main/examples/async_distillation_mopd) | [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.0/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer)를 활용한 다중 교사 온-폴리시 증류(MOPD): Open-MOPD의 수학, 코드, 지시 따르기 전문가를 해당 SFT 체크포인트에 융합합니다. 60단계 만에 AIME24 점수가 17.5에서 24.2로, IFEval 점수가 67.5에서 73.0으로 향상되었습니다(스크립트, Hugging Face Jobs 런처, 결과 README). | |
| [`async_grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_harbor) | [OpenEnv](openenv)를 통해 설치된 코딩 에이전트(`mini-swe-agent`, `opencode`, `claude-code`, ...)로 [Harbor](https://huggingface.co/docs/openenv/environments/harbor) 작업 스위트를 대상으로 AsyncGRPO 학습을 수행합니다. 에이전트는 샌드박스 내에서 자체 루프를 소유하며, TRL은 캡처 프록시가 기록한 토큰 ID와 logprobs를 기반으로 학습합니다. | |
| [`async_grpo_math`](https://github.com/huggingface/trl/tree/main/examples/async_grpo_math) | [AsyncGRPOTrainer](/docs/trl/v1.18.0/ko/async_grpo_trainer#trl.AsyncGRPOTrainer)를 사용한 GSM8K의 비동기 GRPO. 생성(vLLM 서버)과 학습을 분리하며, vLLM 서버에 어댑터만 동기화하는 LoRA 변형도 포함합니다. | |
| [`dpo_reduce_hallucinations`](https://github.com/huggingface/trl/tree/main/examples/dpo_reduce_hallucinations) | [openbmb/RLAIF-V-Dataset](https://huggingface.co/datasets/openbmb/RLAIF-V-Dataset) 데이터셋을 사용하여 환각을 줄이기 위한 Vision Language Model의 DPO fine-tuning. | |
| [`gold_chatbot_arena`](https://github.com/huggingface/trl/tree/main/examples/gold_chatbot_arena) | Qwen2 교사 모델에서 Llama 3.2 학생 모델로의 [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/ko/gold_trainer#trl.experimental.gold.GOLDTrainer)를 사용한 일반 온라인 로짓 증류(GOLD, cross-tokenizer)로, chatbot_arena_completions에서 전체 학습 및 LoRA 변형을 수행합니다. | |
| [`gold_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/gold_qwen3_vl) | [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/ko/gold_trainer#trl.experimental.gold.GOLDTrainer)를 사용하여 Qwen3-VL-8B를 더 작은 VLM 학생 모델로 General Online Logit Distillation(GOLD)하는 과정으로, 동일 계열(JSD loss) 및 이질 계열(ULD loss) 증류를 다룹니다. | |
| [`grpo_2048`](https://github.com/huggingface/trl/tree/main/examples/grpo_2048) | 도구 호출을 활용한 GRPO로 모델이 2048 게임을 플레이하도록 학습합니다. | |
| [`grpo_browsergym`](https://github.com/huggingface/trl/tree/main/examples/grpo_browsergym) | BrowserGym [OpenEnv](openenv) 환경과 LLM 및 VLM 변형을 사용한 GRPO | |
| [`grpo_carla`](https://github.com/huggingface/trl/tree/main/examples/grpo_carla) | CARLA 자율주행 [OpenEnv](openenv) 환경에서 LLM 및 VLM 변형(멀티모달 카메라 이미지 도구 응답)을 사용한 GRPO | |
| [`grpo_catch`](https://github.com/huggingface/trl/tree/main/examples/grpo_catch) | [OpenEnv](openenv) 환경에서 Catch를 활용한 GRPO | |
| [`grpo_continuous_batching`](https://github.com/huggingface/trl/tree/main/examples/grpo_continuous_batching) | 변수 완료 길이를 가진 큰 배치에서 더 빠른 생성을 위해 transformers의 연속 배치 처리 엔진과 함께 사용하는 GRPO | |
| [`grpo_echo`](https://github.com/huggingface/trl/tree/main/examples/grpo_echo) | Echo [OpenEnv](openenv) 환경에서 최소한의 GRPO 학습. | |
| [`grpo_harbor`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor) | 플러그인 기반 에이전트(`bash` / `jupyter` / `terminal_notes` 하네스)를 갖춘 Harbor 태스크 스위트에 대한 GRPO 학습. [Harbor Integration](harbor) 가이드를 참조하세요. | |
| [`grpo_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/grpo_ministral3_vl) | GRPO Ministral 3를 무료 Colab에서 QLoRA로 학습 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_ministral3_vl/grpo_ministral3_vl.ipynb) |
| [`grpo_multi_env`](https://github.com/huggingface/trl/tree/main/examples/grpo_multi_env) | 멀티 환경 GRPO 학습: [OpenEnv](openenv) 환경인 Wordle + Catch를 동일한 학습 실행에서 함께 학습합니다. | |
| [`grpo_qlora`](https://github.com/huggingface/trl/tree/main/examples/grpo_qlora) | 무료 Colab에서 QLoRA를 활용한 GRPO. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_qlora/grpo_qlora.ipynb) |
| [`grpo_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/grpo_qwen3_vl) | GRPO Qwen3-Vl QLoRA 무료 Colab | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_qwen3_vl/grpo_qwen3_vl.ipynb) |
| [`grpo_rnj_1_instruct`](https://github.com/huggingface/trl/tree/main/examples/grpo_rnj_1_instruct) | Colab에서 QLoRA를 사용하여 rnj-1-instruct에 GRPO를 적용하여 추론 기능을 추가합니다. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_rnj_1_instruct/grpo_rnj_1_instruct.ipynb) |
| [`grpo_seta`](https://github.com/huggingface/trl/tree/main/examples/grpo_seta) | openreward.ai 카탈로그의 SETA ORS 환경에 대한 GRPO 학습. [OpenReward Integration](openreward) 가이드를 참조하세요. | |
| [`grpo_sql_agent`](https://github.com/huggingface/trl/tree/main/examples/grpo_sql_agent) | SQL 데이터베이스를 쿼리하여 질문에 답하는 에이전트를 학습하기 위한 GRPO (스크립트 및 노트북; OOM으로 인해 무료 Colab에서 실행 불가). | |
| [`grpo_sudoku`](https://github.com/huggingface/trl/tree/main/examples/grpo_sudoku) | [OpenEnv](openenv) 환경에서 SFT 모델 기반으로 GRPO를 적용하여 Sudoku(TextArena)를 플레이하는 예시입니다. 빈 칸이 26개인 30개의 퍼즐 중 base, SFT, SFT + GRPO 모델이 각각 0, 10, 22개를 해결했습니다(결과가 포함된 스크립트, 노트북, README). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_sudoku/grpo_sudoku.ipynb) |
| [`grpo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/grpo_visual_math) | [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified) 데이터셋을 사용하여 추론을 위한 멀티모달 모델의 GRPO 파인튜닝. | |
| [`grpo_wordle`](https://github.com/huggingface/trl/tree/main/examples/grpo_wordle) | [OpenEnv](openenv) 환경에서 Wordle(TextArena)을 플레이하는 GRPO(스크립트 및 노트북). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/grpo_wordle/grpo_wordle.ipynb) |
| [`gspo_math`](https://github.com/huggingface/trl/tree/main/examples/gspo_math) | [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR) 데이터셋에서 수학 추론을 위한 [GRPOTrainer](/docs/trl/v1.18.0/ko/grpo_trainer#trl.GRPOTrainer)를 통한 GSPO. | |
| [`gspo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/gspo_visual_math) | [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified) 데이터셋을 사용하여 추론을 위한 멀티모달 모델을 파인튜닝하기 위해 [GRPOTrainer](/docs/trl/v1.18.0/ko/grpo_trainer#trl.GRPOTrainer)를 통해 GSPO를 적용합니다. | |
| [`lfm2_5_moe_research_agent`](https://github.com/huggingface/trl/tree/main/examples/lfm2_5_moe_research_agent) | LiquidAI/LFM2.5-8B-A1B를 두 단계로 학습합니다. 먼저 8xH100 노드 하나에서 xLAM function calling 데이터로 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)를 사용해 완전한 SFT를 수행하며, 로드 시 transformers의 `DistributedConfig`로 샤딩을 적용합니다(토큰 디스패치를 사용하는 expert parallelism과 FSDP). 다음으로 [GRPOTrainer](/docs/trl/v1.18.0/ko/grpo_trainer#trl.GRPOTrainer)와 `environment_factory`를 사용해 HotpotQA에서 멀티턴 리서치 에이전트에 대해 GRPO를 수행합니다(`search` / `read` 도구, exact-match 보상). | |
| [`mpo_visual_preferences`](https://github.com/huggingface/trl/tree/main/examples/mpo_visual_preferences) | MPO via the [DPOTrainer](/docs/trl/v1.18.0/ko/dpo_trainer#trl.DPOTrainer) to align a multimodal model based on preferences using the [HuggingFaceH4/rlaif-v_formatted](https://huggingface.co/datasets/HuggingFaceH4/rlaif-v_formatted) dataset and a set of loss weights. | |
| [`online_dpo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/online_dpo_visual_math) | [experimental.online_dpo.OnlineDPOTrainer](/docs/trl/v1.18.0/ko/online_dpo_trainer#trl.experimental.online_dpo.OnlineDPOTrainer)를 사용하여 비전 언어 모델의 온라인 DPO 미세 조정 | |
| [`rloo_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_math) | vLLM을 사용하여 [AI-MO/NuminaMath-TIR](https://huggingface.co/datasets/AI-MO/NuminaMath-TIR) 데이터셋에서 수학 추론을 위한 [RLOOTrainer](/docs/trl/v1.18.0/ko/rloo_trainer#trl.RLOOTrainer) 기반 RLOO. | |
| [`rloo_visual_math`](https://github.com/huggingface/trl/tree/main/examples/rloo_visual_math) | [lmms-lab/multimodal-open-r1-8k-verified](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified) 데이터셋을 사용하여 추론을 위한 멀티모달 모델의 RLOO 파인튜닝. | |
| [`sdft_privileged_context`](https://github.com/huggingface/trl/tree/main/examples/sdft_privileged_context) | [experimental.sdft.SDFTTrainer](/docs/trl/v1.18.0/ko/sdft_trainer#trl.experimental.sdft.SDFTTrainer)를 사용한 자기 증류 미세 조정으로, 특권(교사 전용) 컨텍스트를 모델에 증류합니다. | |
| [`sdpo_math`](https://github.com/huggingface/trl/tree/main/examples/sdpo_math) | 검증 가능한 수학 보상과 [openai/gsm8k](https://huggingface.co/datasets/openai/gsm8k)에 대한 선택적 환경 피드백을 사용하여 [experimental.sdpo.SDPOTrainer](/docs/trl/v1.18.0/ko/sdpo_trainer#trl.experimental.sdpo.SDPOTrainer)로 SDPO를 실행합니다. | |
| [`sft_agent_traces`](https://github.com/huggingface/trl/tree/main/examples/sft_agent_traces) | 에이전트 트레이스에서의 Qwen3.5-2B SFT: Qwen3.5-397B-A17B는 Hugging Face Sandboxes에서 OpenCode 에이전트로 동작하며, 데이터 분석 [Harbor](harbor) 작업을 수행합니다. 이 과정은 [OpenEnv](openenv)에 의해 기록되며, 학생 모델은 어시스턴트 전용 손실로 해결된 대화에 대해 학습합니다. 어떤 트레이스도 해당 데이터를 다루지 않은 작업에서, 약 500개의 트레이스로 성능이 7.6%에서 33.3%로 향상됩니다(롤아웃, 데이터셋 및 학습 스크립트, 그리고 결과를 담은 README 포함). | |
| [`sft_beam`](https://github.com/huggingface/trl/tree/main/examples/sft_beam) | 8xB300 노드 1대에서 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)를 사용하여 reflection/Beam-1.0-501B-A23B의 LoRA SFT를 수행하며, 로드 시점에 transformers의 `DistributedConfig`로 샤딩(전문가 병렬 및 토큰 디스패치)합니다. | |
| [`sft_diffusion_gemma`](https://github.com/huggingface/trl/tree/main/examples/sft_diffusion_gemma) | 블록 확산 목적을 확장하여 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)를 통해 GSM8K에서 DiffusionGemma 블록 확산 언어 모델의 SFT를 수행합니다. | |
| [`sft_gemma3`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3) | Codeforces COTS 데이터셋에서 Gemma 3의 SFT. | |
| [`sft_gemma3_vision`](https://github.com/huggingface/trl/tree/main/examples/sft_gemma3_vision) | 비전-텍스트 작업에서 Gemma 3의 SFT. | |
| [`sft_gpt_oss_chess`](https://github.com/huggingface/trl/tree/main/examples/sft_gpt_oss_chess) | openai/gpt-oss-20b의 체스 퍼즐에 대한 완전한 파인튜닝을 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)로 수행합니다. TRL은 MXFP4 전문가를 역양자화하여 로드하고, 파인튜닝된 전문가를 원래와 동일하게 서빙하기 위해 다시 MXFP4로 양자화합니다. | |
| [`sft_ministral3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_ministral3_vl) | 무료 Colab에서 QLoRA로 SFT Ministral 3 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_ministral3_vl/sft_ministral3_vl.ipynb) |
| [`sft_mistral_large_4`](https://github.com/huggingface/trl/tree/main/examples/sft_mistral_large_4) | 8xB300 노드 1대에서 mistralai/Mistral-Large-4-1T-A52B의 FP8 가중치를 기반으로 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)를 사용하여 LoRA SFT를 수행하며, 로딩 시 transformers의 `DistributedConfig`에 의해 샤딩됩니다(토큰 디스패치를 사용하는 전문가 병렬화). | |
| [`sft_nemotron_3`](https://github.com/huggingface/trl/tree/main/examples/sft_nemotron_3) | NVIDIA Nemotron 3 모델의 SFT(스크립트 및 LoRA 노트북). | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_nemotron_3/sft_nemotron_3.ipynb) |
| [`sft_qlora`](https://github.com/huggingface/trl/tree/main/examples/sft_qlora) | 무료 Colab에서 QLoRA를 사용한 SFT. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_qlora/sft_qlora.ipynb) |
| [`sft_qwen3_8b_1m_context`](https://github.com/huggingface/trl/tree/main/examples/sft_qwen3_8b_1m_context) | 8xH100 노드 1대에서 컨텍스트 병렬성을 사용하여 1,048,576 토큰 길이의 시퀀스로 Qwen3-8B의 SFT를 수행합니다. | |
| [`sft_qwen3_vl`](https://github.com/huggingface/trl/tree/main/examples/sft_qwen3_vl) | 무료 Colab에서 QLoRA를 사용하여 Qwen3-VL을 SFT합니다. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_qwen3_vl/sft_qwen3_vl.ipynb) |
| [`tail_sft_gsm8k`](https://github.com/huggingface/trl/tree/main/examples/tail_sft_gsm8k) | 초기 정책 손실 필터링을 확장하여 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)를 통해 GSM8K에서 TailSFT를 수행합니다. | |
| [`sft_muse_spark_open`](https://github.com/huggingface/trl/tree/main/examples/sft_muse_spark_open) | 8개 노드에서 [SFTTrainer](/docs/trl/v1.18.0/ko/sft_trainer#trl.SFTTrainer)를 사용하여 meta-models/Muse-Spark-Open-816B-A42B의 LoRA SFT를 수행하며, 로딩 시점에 transformers의 `DistributedConfig`로 샤딩됩니다(토큰 디스패치를 사용하는 전문가 병렬화). | |
| [`sft_tool_calling`](https://github.com/huggingface/trl/tree/main/examples/sft_tool_calling) | QLoRA를 활용한 SFT(스크립트, 채팅 템플릿, 노트북)를 사용하여 네이티브 도구 호출을 지원하지 않는 모델에 도구 호출을 학습시키는 방법 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/sft_tool_calling/sft_tool_calling.ipynb) |
| [`sft_visual_chat`](https://github.com/huggingface/trl/tree/main/examples/sft_visual_chat) | 채팅 환경에서 Vision Language Model의 SFT. [LLaVA 1.5](https://huggingface.co/llava-hf/llava-1.5-7b-hf), [LLaVA 1.6](https://huggingface.co/llava-hf/llava-v1.6-mistral-7b-hf), [Llama-3.2-11B-Vision-Instruct](https://huggingface.co/meta-llama/Llama-3.2-11B-Vision-Instruct)로만 테스트했으며, 다른 모델 아키텍처에서는 예상치 못한 동작이 발생할 수 있습니다. | |
| [`xtoken`](https://github.com/huggingface/trl/tree/main/examples/xtoken) | [experimental.gold.GOLDTrainer](/docs/trl/v1.18.0/ko/gold_trainer#trl.experimental.gold.GOLDTrainer)를 사용한 X-Token off-policy cross-tokenizer knowledge distillation 및 projection-matrix 준비 과정 | |

## 분산 학습

torchrun를 사용하여 예제 스크립트를 여러 GPU에서 실행할 수 있습니다:

```shell
torchrun --nproc_per_node {NUM_GPUS} path_to_script.py --all_arguments_of_the_script
```

DeepSpeed ZeRO-{1,2,3}의 경우:

```shell
torchrun --nproc_per_node {NUM_GPUS} path_to_script.py --deepspeed examples/deepspeed_configs/zero{1,2,3}.json --all_arguments_of_the_script
```

필요에 따라 `NUM_GPUS`와 `--all_arguments_of_the_script`를 조정하세요.

