TRL documentation

예시

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

예시

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

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

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

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

시작하기

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

pip install --upgrade trl[quantization]

추가 선택적 의존성은 여기에서 확인하세요. Notebook 기반 예제는 자체적으로 완결되어 있어 무료 Colab에서 실행할 수 있으며, 스크립트 기반 예제는 단일 GPU, 다중 GPU 또는 DeepSpeed 환경에서 실행됩니다(아래 분산 학습 참고).

인덱스

예시설명Colab에서 열기
async_distillation_mathGSM8K에서 experimental.async_distillation.AsyncDistillationTrainer를 사용한 비동기 온-폴리시 증류: 교사는 vLLM을 통해 HTTP로 제공됩니다.
async_distillation_mopdexperimental.async_distillation.AsyncDistillationTrainer를 활용한 다중 교사 온-폴리시 증류(MOPD): Open-MOPD의 수학, 코드, 지시 따르기 전문가를 해당 SFT 체크포인트에 융합합니다. 60단계 만에 AIME24 점수가 17.5에서 24.2로, IFEval 점수가 67.5에서 73.0으로 향상되었습니다(스크립트, Hugging Face Jobs 런처, 결과 README).
async_grpo_harborOpenEnv를 통해 설치된 코딩 에이전트(mini-swe-agent, opencode, claude-code, …)로 Harbor 작업 스위트를 대상으로 AsyncGRPO 학습을 수행합니다. 에이전트는 샌드박스 내에서 자체 루프를 소유하며, TRL은 캡처 프록시가 기록한 토큰 ID와 logprobs를 기반으로 학습합니다.
async_grpo_mathAsyncGRPOTrainer를 사용한 GSM8K의 비동기 GRPO. 생성(vLLM 서버)과 학습을 분리하며, vLLM 서버에 어댑터만 동기화하는 LoRA 변형도 포함합니다.
dpo_reduce_hallucinationsopenbmb/RLAIF-V-Dataset 데이터셋을 사용하여 환각을 줄이기 위한 Vision Language Model의 DPO fine-tuning.
gold_chatbot_arenaQwen2 교사 모델에서 Llama 3.2 학생 모델로의 experimental.gold.GOLDTrainer를 사용한 일반 온라인 로짓 증류(GOLD, cross-tokenizer)로, chatbot_arena_completions에서 전체 학습 및 LoRA 변형을 수행합니다.
gold_qwen3_vlexperimental.gold.GOLDTrainer를 사용하여 Qwen3-VL-8B를 더 작은 VLM 학생 모델로 General Online Logit Distillation(GOLD)하는 과정으로, 동일 계열(JSD loss) 및 이질 계열(ULD loss) 증류를 다룹니다.
grpo_2048도구 호출을 활용한 GRPO로 모델이 2048 게임을 플레이하도록 학습합니다.
grpo_browsergymBrowserGym OpenEnv 환경과 LLM 및 VLM 변형을 사용한 GRPO
grpo_carlaCARLA 자율주행 OpenEnv 환경에서 LLM 및 VLM 변형(멀티모달 카메라 이미지 도구 응답)을 사용한 GRPO
grpo_catchOpenEnv 환경에서 Catch를 활용한 GRPO
grpo_continuous_batching변수 완료 길이를 가진 큰 배치에서 더 빠른 생성을 위해 transformers의 연속 배치 처리 엔진과 함께 사용하는 GRPO
grpo_echoEcho OpenEnv 환경에서 최소한의 GRPO 학습.
grpo_harbor플러그인 기반 에이전트(bash / jupyter / terminal_notes 하네스)를 갖춘 Harbor 태스크 스위트에 대한 GRPO 학습. Harbor Integration 가이드를 참조하세요.
grpo_ministral3_vlGRPO Ministral 3를 무료 Colab에서 QLoRA로 학습Open In Colab
grpo_multi_env멀티 환경 GRPO 학습: OpenEnv 환경인 Wordle + Catch를 동일한 학습 실행에서 함께 학습합니다.
grpo_qlora무료 Colab에서 QLoRA를 활용한 GRPO.Open In Colab
grpo_qwen3_vlGRPO Qwen3-Vl QLoRA 무료 ColabOpen In Colab
grpo_rnj_1_instructColab에서 QLoRA를 사용하여 rnj-1-instruct에 GRPO를 적용하여 추론 기능을 추가합니다.Open In Colab
grpo_setaopenreward.ai 카탈로그의 SETA ORS 환경에 대한 GRPO 학습. OpenReward Integration 가이드를 참조하세요.
grpo_sql_agentSQL 데이터베이스를 쿼리하여 질문에 답하는 에이전트를 학습하기 위한 GRPO (스크립트 및 노트북; OOM으로 인해 무료 Colab에서 실행 불가).
grpo_sudokuOpenEnv 환경에서 SFT 모델 기반으로 GRPO를 적용하여 Sudoku(TextArena)를 플레이하는 예시입니다. 빈 칸이 26개인 30개의 퍼즐 중 base, SFT, SFT + GRPO 모델이 각각 0, 10, 22개를 해결했습니다(결과가 포함된 스크립트, 노트북, README).Open In Colab
grpo_visual_mathlmms-lab/multimodal-open-r1-8k-verified 데이터셋을 사용하여 추론을 위한 멀티모달 모델의 GRPO 파인튜닝.
grpo_wordleOpenEnv 환경에서 Wordle(TextArena)을 플레이하는 GRPO(스크립트 및 노트북).Open In Colab
gspo_mathAI-MO/NuminaMath-TIR 데이터셋에서 수학 추론을 위한 GRPOTrainer를 통한 GSPO.
gspo_visual_mathlmms-lab/multimodal-open-r1-8k-verified 데이터셋을 사용하여 추론을 위한 멀티모달 모델을 파인튜닝하기 위해 GRPOTrainer를 통해 GSPO를 적용합니다.
lfm2_5_moe_research_agentLiquidAI/LFM2.5-8B-A1B를 두 단계로 학습합니다. 먼저 8xH100 노드 하나에서 xLAM function calling 데이터로 SFTTrainer를 사용해 완전한 SFT를 수행하며, 로드 시 transformers의 DistributedConfig로 샤딩을 적용합니다(토큰 디스패치를 사용하는 expert parallelism과 FSDP). 다음으로 GRPOTrainer와 environment_factory를 사용해 HotpotQA에서 멀티턴 리서치 에이전트에 대해 GRPO를 수행합니다(search / read 도구, exact-match 보상).
mpo_visual_preferencesMPO via the DPOTrainer to align a multimodal model based on preferences using the HuggingFaceH4/rlaif-v_formatted dataset and a set of loss weights.
online_dpo_visual_mathexperimental.online_dpo.OnlineDPOTrainer를 사용하여 비전 언어 모델의 온라인 DPO 미세 조정
rloo_mathvLLM을 사용하여 AI-MO/NuminaMath-TIR 데이터셋에서 수학 추론을 위한 RLOOTrainer 기반 RLOO.
rloo_visual_mathlmms-lab/multimodal-open-r1-8k-verified 데이터셋을 사용하여 추론을 위한 멀티모달 모델의 RLOO 파인튜닝.
sdft_privileged_contextexperimental.sdft.SDFTTrainer를 사용한 자기 증류 미세 조정으로, 특권(교사 전용) 컨텍스트를 모델에 증류합니다.
sdpo_math검증 가능한 수학 보상과 openai/gsm8k에 대한 선택적 환경 피드백을 사용하여 experimental.sdpo.SDPOTrainer로 SDPO를 실행합니다.
sft_agent_traces에이전트 트레이스에서의 Qwen3.5-2B SFT: Qwen3.5-397B-A17B는 Hugging Face Sandboxes에서 OpenCode 에이전트로 동작하며, 데이터 분석 Harbor 작업을 수행합니다. 이 과정은 OpenEnv에 의해 기록되며, 학생 모델은 어시스턴트 전용 손실로 해결된 대화에 대해 학습합니다. 어떤 트레이스도 해당 데이터를 다루지 않은 작업에서, 약 500개의 트레이스로 성능이 7.6%에서 33.3%로 향상됩니다(롤아웃, 데이터셋 및 학습 스크립트, 그리고 결과를 담은 README 포함).
sft_beam8xB300 노드 1대에서 SFTTrainer를 사용하여 reflection/Beam-1.0-501B-A23B의 LoRA SFT를 수행하며, 로드 시점에 transformers의 DistributedConfig로 샤딩(토큰 디스패치를 사용하는 전문가 병렬)합니다.
sft_diffusion_gemma블록 확산 목적을 확장하여 SFTTrainer를 통해 GSM8K에서 DiffusionGemma 블록 확산 언어 모델의 SFT를 수행합니다.
sft_gemma3Codeforces COTS 데이터셋에서 Gemma 3의 SFT.
sft_gemma3_vision비전-텍스트 작업에서 Gemma 3의 SFT.
sft_gpt_oss_chessopenai/gpt-oss-20b의 체스 퍼즐에 대한 완전한 파인튜닝을 SFTTrainer로 수행합니다. TRL은 MXFP4 전문가를 역양자화하여 로드하고, 파인튜닝된 전문가를 원래와 동일하게 서빙하기 위해 다시 MXFP4로 양자화합니다.
sft_ministral3_vl무료 Colab에서 QLoRA로 SFT Ministral 3Open In Colab
sft_mistral_large_48xB300 노드 1대에서 mistralai/Mistral-Large-4-1T-A52B의 FP8 가중치를 기반으로 SFTTrainer를 사용하여 LoRA SFT를 수행하며, 로드 시 transformers의 DistributedConfig에 의해 샤딩됩니다(토큰 디스패치를 사용하는 전문가 병렬화).
sft_nemotron_3NVIDIA Nemotron 3 모델의 SFT(스크립트 및 LoRA 노트북).Open In Colab
sft_qlora무료 Colab에서 QLoRA를 사용한 SFT.Open In Colab
sft_qwen3_8b_1m_context8xH100 노드 1대에서 컨텍스트 병렬성을 사용하여 1,048,576 토큰 길이의 시퀀스로 Qwen3-8B의 SFT를 수행합니다.
sft_qwen3_vl무료 Colab에서 QLoRA를 사용하여 Qwen3-VL을 SFT합니다.Open In Colab
tail_sft_gsm8k초기 정책 손실 필터링을 확장하여 SFTTrainer를 통해 GSM8K에서 TailSFT를 수행합니다.
sft_muse_spark_open8개 노드에서 SFTTrainer를 사용하여 meta-models/Muse-Spark-Open-816B-A42B의 LoRA SFT를 수행하며, 로딩 시점에 transformers의 DistributedConfig로 샤딩됩니다(토큰 디스패치를 사용하는 전문가 병렬화).
sft_tool_callingQLoRA를 활용한 SFT(스크립트, 채팅 템플릿, 노트북)를 사용하여 네이티브 도구 호출을 지원하지 않는 모델에 도구 호출을 학습시키는 방법Open In Colab
sft_visual_chat채팅 환경에서 Vision Language Model의 SFT. LLaVA 1.5, LLaVA 1.6, Llama-3.2-11B-Vision-Instruct로만 테스트했으며, 다른 모델 아키텍처에서는 예상치 못한 동작이 발생할 수 있습니다.
xtokenexperimental.gold.GOLDTrainer를 사용한 X-Token off-policy cross-tokenizer knowledge distillation 및 projection-matrix 준비 과정

분산 학습

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

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

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

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를 조정하세요.

Update on GitHub