TRL documentation
GRPO Trainer
GRPO Trainer
개요
TRL은 Zhihong Shao, Peiyi Wang, Qihao Zhu, Runxin Xu, Junxiao Song, Mingchuan Zhang, Y. K. Li, Y. Wu, Daya Guo의 논문 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models에 설명된 바와 같이 언어 모델 학습을 위한 GRPO Trainer를 지원합니다.
해당 논문의 초록은 다음과 같습니다:
수학적 추론은 복잡하고 구조화된 특성으로 인해 언어 모델에 상당한 도전 과제를 제시합니다. 본 논문에서는 Common Crawl에서 수집한 120B개의 수학 관련 토큰과 자연어 및 코드 데이터를 함께 사용하여 DeepSeek-Coder-Base-v1.5 7B의 사전 학습을 이어서 진행한 DeepSeekMath 7B를 소개합니다. DeepSeekMath 7B는 외부 툴킷과 투표 기법에 의존하지 않고도 경쟁 수준의 MATH 벤치마크에서 51.7%라는 인상적인 점수를 기록했으며, 이는 Gemini-Ultra와 GPT-4의 성능 수준에 근접한 결과입니다. DeepSeekMath 7B의 64개 샘플에 대한 자기 일관성(self-consistency)은 MATH에서 60.9%를 달성합니다. DeepSeekMath의 수학적 추론 능력은 두 가지 핵심 요인에서 기인합니다. 첫째, 정밀하게 설계된 데이터 선택 파이프라인을 통해 공개된 웹 데이터의 상당한 잠재력을 활용했습니다. 둘째, PPO의 메모리 사용량을 동시에 최적화하면서 수학적 추론 능력을 향상시키는 PPO의 변형인 Group Relative Policy Optimization(GRPO)을 도입했습니다.
이 포스트 트레이닝 방법은 Quentin Gallouédec에 의해 기여되었습니다.
빠른 시작
이 예제는 GRPO 방법을 사용하여 모델을 학습하는 방법을 보여줍니다. DeepMath-103K 데이터셋의 프롬프트를 사용하여 Qwen2.5 0.5B Instruct 모델을 학습합니다. 데이터셋의 데이터는 여기서 확인할 수 있습니다:
아래는 모델을 학습하는 스크립트입니다. accuracy_reward에는 math-verify가 필요하며, pip install trl[math_verify]로 설치할 수 있습니다.
# train_grpo.py
from datasets import load_dataset
from trl import GRPOTrainer
from trl.rewards import accuracy_reward
dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
trainer = GRPOTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
reward_funcs=accuracy_reward,
train_dataset=dataset,
)
trainer.train()다음 명령을 사용하여 스크립트를 실행합니다:
torchrun --nproc_per_node 8 train_grpo.py
8개의 GPU에 분산되어 학습하는 데 약 1일이 소요됩니다.

참고: 위의 보상 곡선은
Qwen/Qwen2-0.5B-Instruct로 생성되었습니다.Qwen/Qwen2.5-0.5B-Instruct를 사용한 결과는 질적으로 유사할 것입니다.
GRPO 방법 자세히 살펴보기
GRPO는 온라인 학습 알고리즘으로, 학습 중에 학습된 모델 자체에서 생성된 데이터를 사용하여 반복적으로 성능을 향상시킵니다. GRPO 목적 함수의 핵심 직관은 모델이 참조 정책(reference policy)에 가깝게 유지되도록 보장하면서 생성된 완성(completions)의 이점을 최대화하는 것입니다. GRPO의 작동 방식을 이해하려면 다음 네 가지 주요 단계로 나눌 수 있습니다: 완성 생성, 이점 계산, KL 발산 추정, 손실 계산.

완성 결과 생성
각 학습 단계에서 프롬프트 배치(batches)를 샘플링하고 각 프롬프트에 대해 개의 completion을 생성합니다(기호는 ).
이점(advantage) 계산
각 시퀀스에 대해 보상 모델 또는 보상 함수를 사용하여 보상을 계산합니다. 보상 모델의 비교적 성격—보통 동일한 질문에 대한 출력 간 비교 데이터셋으로 학습됨—에 맞추기 위해, 이점은 이러한 상대적 비교를 반영하도록 계산됩니다. 다음과 같이 정규화됩니다:
이 접근 방식이 해당 기법에 이름을 부여합니다: Group Relative Policy Optimization (GRPO).
논문 Understanding R1-Zero-Like Training: A Critical Perspective 에서 로 스케일링하면 질문 수준의 난이도 편향이 발생할 수 있습니다. 이 스케일링을 비활성화하려면
scale_rewards=False의 GRPOConfig. 에 std 기반 스케일링을 끄면 분산 정규화도 함께 제거되므로, 업데이트 크기가 원시 보상 스케일과 배치 구성에 직접적으로 의존하게 된다는 점에 유의하세요.
Part I: Tricks or Traps? A Deep Dive into RL for LLM Reasoning (Lite PPO)에서 보여준 바와 같이, 평균을 로컬(그룹) 수준에서, 표준편차를 글로벌(배치) 수준에서 계산하면 더 견고한 보상 성형(reward shaping)이 가능합니다. GRPOConfig에서
scale_rewards="batch"를 설정하여 이 스케일링 전략을 사용할 수 있습니다.
KL 발산 추정
KL 발산은 다음 근사기를 사용하여 추정합니다. Schulman et al. (2020). 해당 근사기는 다음과 같이 정의됩니다:
손실 계산
목표는 모델이 참조 정책과 가깝게 유지되도록 하면서 이점을 최대화하는 것입니다. 따라서 손실은 다음과 같이 정의됩니다:
여기서 첫 번째 항은 스케일된 이점을 나타내며, 두 번째 항은 KL 발산을 통해 참조 정책과의 편차를 패널티로 부과합니다.
원래 논문인 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, 에서는 로 스케일링하지 않습니다. 논문 Understanding R1-Zero-Like Training: A Critical Perspective 에서 이것이 응답 수준(length)의 편향을 유발한다고 밝혀졌기 때문입니다. 자세한 내용은 손실 유형.
원래 논문인 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, 에서 기본값으로 Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model) 등)를 사용하여 KL 발산 항이 GRPO 학습에 필수적이지 않음을 보여준 최근 연구들(e.g., Understanding R1-Zero-Like Training: A Critical Perspective, DAPO: An Open-Source LLM Reinforcement Learning System at Scale). KL 발산 항을 포함하려면
beta의 GRPOConfig 을 0이 아닌 값으로 설정할 수 있습니다.
원래 논문에서는 이 수식화가 각 생성 이후의 여러 업데이트를 고려하도록 일반화됩니다(기호는 , 이며, num_iterations 의 GRPOConfig) 을(를) 활용하여 클립된 서로게이트 목적함수를:
여기서 은 정책 비율을 과 . 사이로 제한하여 업데이트가 참조 정책에서 과도하게 벗어나지 않도록 보장합니다. (기본값인 TRL에서
손실 유형
문헌에서는 목적 함수의 여러 수식 형태가 제안되었습니다. 처음에 GRPO의 목적 함수는 다음과 같이 정의되었습니다:
여기서
DAPO 논문은 DAPO paper GRPO 알고리즘의 샘플 수준 손실이 긴 CoT 시나리오에서 더 긴 응답에 대해 과소 벌점을 부과하여 출력 품질이 저하되는 한계를 강조합니다. 제안된 해결책은 토큰 수준 정규화로, 응답 길이에 관계없이 개별 토큰에 더 균형 잡힌 보상을 부여하여 긴 시퀀스를 더 잘 처리합니다:
이 수식을 사용하려면 GRPOConfig에서 loss_type="dapo"를 설정하세요.
또한, 논문 Understanding R1-Zero-Like Training: A Critical Perspective 에서 초기 GRPO 공식이 응답 길이 편향을 도입한다는 것이 입증되었습니다. DAPO 공식은 이 편향을 줄이지만 완전히 제거하지는 못한다고 보여주었습니다. 이 편향을 완전히 제거하기 위해, 그들은 시퀀스 길이 대신 상수로 나누도록 제안하여 다음 공식을 도출했습니다:
이 상수는 최대 완성 길이로 설정하는 것이 권장됩니다. 이 수식을 사용하려면 GRPOConfig에서 loss_type="dr_grpo"를 설정하세요.
또는, SAPO 논문에서 Qwen 팀은 GRPO의 “hard” 클리핑 메커니즘을 부드러운 온도 제어 소프트 게이팅 메커니즘으로 대체하는 것을 제안합니다. GRPO가 정책이 참조 모델에서 너무 멀리 벗어나면 그라디언트를 0으로 설정하는 반면, SAPO는 부드러운 신뢰 영역을 사용하여 그라디언트 가중치를 부드럽게 감쇠시킵니다. 이를 통해 모델은 “near-on-policy” 토큰에서 유용한 학습 신호를 유지하면서 극단적인 편차에서 발생하는 노이즈를 억제할 수 있습니다.
손실 함수는 다음과 같이 정의됩니다:
소프트 게이팅 함수 는 시그모이드 함수 를 사용하여 다음과 같이 정의됩니다:
온도 는 이점 :
비대칭 온도를 사용하는 것을 권장합니다. (기본값은 ). 이를 통해 불안정성을 방지하기 위해 "나쁜" 동작에는 더 엄격하게 페널티를 부과하고, "좋은" 동작에는 더 관대하게 허용합니다.
이 수식을 사용하려면 GRPOConfig에서 loss_type="sapo"를 설정하세요.
기록된 지표
학습 및 평가 중에 다음 메트릭을 기록합니다:
num_tokens: 프롬프트와 완성 결과를 모두 포함하여 지금까지 처리된 토큰의 총 수입니다. 도구를 사용할 경우 도구 토큰은 제외하고 계산합니다.step_time: 학습 단계당 평균 소요 시간(초 단위, 생성 포함).completions/mean_length: 생성된 completions의 평균 길이입니다. 도구를 사용할 경우, 도구 토큰을 제외한 토큰만 계산됩니다.completions/min_length: 생성된 completions의 최소 길이입니다. 도구를 사용할 경우, 도구 토큰이 아닌 토큰만 계산됩니다.completions/max_length: 생성된 completions의 최대 길이. 도구를 사용할 경우 도구 토큰은 제외하고 카운트합니다.completions/mean_terminated_length: EOS로 종료되는 생성된 completions의 평균 길이입니다. 도구를 사용할 경우, 도구 토큰은 제외하고 계산합니다.completions/min_terminated_length: EOS로 종료되는 생성된 completions의 최소 길이입니다. 도구를 사용할 경우, 도구 토큰이 아닌 토큰만 계산됩니다.completions/max_terminated_length: EOS로 종료되는 생성된 completions의 최대 길이입니다. 도구를 사용할 경우, 도구 토큰이 아닌 토큰만 계산됩니다.completions/clipped_ratio: 잘림(클립)된 completions의 비율.tools/call_frequency: 생성 배치당 완료(completion)별 평균 도구 호출 횟수입니다.tools가 제공된 경우에만 기록됩니다.tools/failure_frequency: 실패한 도구 호출의 비율(도구를 찾을 수 없거나, 예외가 발생하거나, 호출 유형이 지원되지 않는 경우). 도구가 호출되지 않은 경우0.0입니다.tools가 제공된 경우에만 기록됩니다.rewards/{reward_func_name}/mean: 특정 reward function의 평균 reward입니다. 환경이get_reward를 통해 reward를 소유하는 경우,{reward_func_name}은 환경의 클래스 이름입니다.rewards/{reward_func_name}/std: 특정 보상 함수의 보상의 표준편차입니다.reward: 함수 간 보상을 합산한 후(가중치는reward_weights로 적용) 계산된 전체 평균 보상입니다.reward_std: 함수 전체에 걸쳐 합산된 보상(가중치reward_weights적용)의 표준편차로, 전체 배치에 대해 계산됩니다.frac_reward_zero_std: 생성 배치 내에서 보상 표준편차가 0인 샘플의 비율입니다. 이는 해당 프롬프트에 대한 다양성이 적다는 것을 의미하며(모든 답변이 정답이거나 오답임)sampling/sampling_logp_difference/mean: 샘플러(vLLM)가 반환한 로그 확률과 학습 모델이 다시 계산한 로그 확률 간의 완료 토큰에 대한 평균 절대 차이. 값이 증가하면 학습-추론 불일치가 커지고 있음을 나타냅니다.use_vllm=True이고vllm_importance_sampling_correction=True인 경우에만 기록됩니다.sampling/sampling_logp_difference/max: 해당 절대 차이의 최대값.use_vllm=True이고vllm_importance_sampling_correction=True인 경우에만 기록됩니다.sampling/importance_sampling_ratio/min: 학습-추론 불일치를 보정하는 데 사용된 가장 작은 중요도 샘플링 비율입니다.vllm_importance_sampling_mode로 선택된 제약 조건이 적용된 이후의 값으로,*_truncate모드에서는[C_min, C_max]로 클리핑되고,*_mask모드에서는 0으로 설정됩니다. completion 토큰에 대해 계산되며,sequence_*모드의 경우 시퀀스에 대해 계산됩니다.use_vllm=True이고vllm_importance_sampling_correction=True인 경우에만 기록됩니다.sampling/importance_sampling_ratio/mean: 평균 제약 중요도 샘플링 비율.use_vllm=True이고vllm_importance_sampling_correction=True인 경우에만 기록됩니다.sampling/importance_sampling_ratio/max: 가장 큰 제약된 중요도 샘플링 비율.use_vllm=True이고vllm_importance_sampling_correction=True인 경우에만 기록됩니다.policy_loss: 정책 그래디언트 손실 값(엔트로피 보너스 적용 전).entropy_coef이 0이 아니거나use_adaptive_entropy=True인 경우 기록됩니다.entropy: 생성된 완성본 전체에 걸친 토큰 예측의 평균 엔트로피입니다. (mask_truncated_completions=True인 경우, 마스킹된 시퀀스의 토큰은 제외됩니다.)entropy_coef: 현재 엔트로피 정규화 계수입니다.entropy_coef이 0이 아니거나use_adaptive_entropy=True인 경우 기록됩니다.use_adaptive_entropy=True인 경우 옵티마이저 스텝마다 한 번씩 업데이트됩니다.aux_loss: Mixture-of-Experts 모델의 로드 밸런싱 보조 손실입니다.router_aux_loss_coef로 스케일링되어 손실에 추가되기 전의 값입니다. 모델이 MoE 모델이고router_aux_loss_coef가 0이 아닌 경우에만 기록됩니다.kl: 생성된 completions에 대해 모델과 reference model 사이의 평균 KL 발산을 계산한 값입니다.beta가 0이 아닌 경우에만 기록됩니다.clip_ratio/region_mean: GRPO 목적 함수가 신뢰 영역 내에서 유지되도록 클리핑되는 토큰(또는importance_sampling_level="sequence") 확률의 비율입니다: . 값이 높을수록 더 많은 토큰이 클리핑되어 정책 이 변경될 수 있는 범위가 제한됩니다.clip_ratio/low_mean: 토큰(또는importance_sampling_level="sequence") 수준에서)의 확률이 신뢰 영역의 하한에서 클립된 비율의 평균입니다: .clip_ratio/low_min: 완료별 토큰의 최소 비율(또는importance_sampling_level="sequence") trust region의 하한에서 클리핑되는 경우): .clip_ratio/high_mean: 토큰(또는importance_sampling_level="sequence") 수준에서)의 확률 중 trust region의 상한에서 클리핑된 비율의 평균입니다: .clip_ratio/high_max: completion당 토큰의 최대 비율(또는importance_sampling_level="sequence") trust region의 상한에서 클리핑된 경우): .cispo_clip_ratio: 토큰(또는importance_sampling_level="sequence") 의 importance sampling 가중치 중epsilon_high에서 잘리면서 양의 이점을 가진 비율입니다: . 다음인 경우에만 기록됩니다:loss_type="cispo".vespo/phi_seq_mean: VESPO Gamma 가중치의 평균 값 시퀀스 수준 중요도 가중치에 적용됩니다. 값이1.0보다 작으면 시퀀스가 하향 가중됩니다.loss_type="vespo".
커스터마이징
vLLM 기반 생성으로 학습 속도 향상
온라인 방식으로 학습할 때 생성 과정이 주요 병목 현상이 되는 경우가 많습니다. 생성을 가속화하려면 LLM용 고처리량, 저지연 추론 엔진인 vLLM을 사용할 수 있습니다. 이를 활성화하려면 먼저 패키지를 설치해야 합니다.
pip install trl[vllm]
학습 중 vLLM을 사용하는 두 가지 방식을 지원합니다: 서버 모드와 콜로케이트 모드입니다.
기본적으로 vLLM 생성 시 다른 프레임워크를 사용할 때 발생하는 생성-학습 불일치를 해결하기 위해 시퀀스 레벨 Masked Importance Sampling(
vllm_importance_sampling_mode="sequence_mask")이 활성화됩니다.vllm_importance_sampling_correction=False를 설정하여 이를 비활성화할 수 있습니다. 자세한 내용은 Masked Importance Sampling 및 Sequence-level Importance Sampling을 참고하세요.
옵션 1: Colocate 모드
이 모드에서는 vLLM이 트레이너 프로세스 내에서 실행되며 학습 모델과 GPU 메모리를 공유합니다. 이를 통해 별도의 서버를 시작할 필요가 없으며 GPU 활용도를 높일 수 있지만, 학습 GPU에서 메모리 경쟁이 발생할 수 있습니다. 이 모드가 기본 모드입니다.
from trl import GRPOConfig
training_args = GRPOConfig(
...,
use_vllm=True, # vllm_mode="colocate" by default
)옵션 2: 서버 모드
이 모드에서는 vLLM이 별도의 프로세스(그리고 별도의 GPU)에서 실행되며 HTTP를 통해 trainer와 통신합니다. 추론에 전용 GPU가 있는 경우 이상적입니다.
vLLM 서버 시작:
VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \ --weight-transfer-config '{"backend": "nccl"}' \ --logprobs-mode processed_logprobs \ --max-logprobs -1학습 스크립트에서 서버 모드를 활성화합니다:
from trl import GRPOConfig training_args = GRPOConfig( ..., use_vllm=True, vllm_mode="server", )
서버가 trainer와 다른 GPU를 사용하도록 확인하세요. 그렇지 않으면 NCCL 오류가 발생할 수 있습니다. 사용할 GPU는
CUDA_VISIBLE_DEVICES환경 변수로 지정할 수 있습니다.
모델 크기와 학습에 필요한 전체 GPU 메모리 요구 사항에 따라, 리소스 과소 활용 또는 메모리 부족 오류를 방지하기 위해 GRPOConfig의
vllm_gpu_memory_utilization매개변수를 조정해야 할 수 있습니다.모델 구성 및 실험 설정에 기반하여 권장 GPU 메모리 사용률을 추정하는 데 도움이 되는 HF Space를 제공합니다. 아래처럼 사용하면
vllm_gpu_memory_utilization권장 값을 얻을 수 있습니다:권장 값이 사용자의 환경에서 작동하지 않는 경우, 안정성을 보장하기 위해 권장 값에 작은 버퍼(예: +0.05 또는 +0.1)를 추가하는 것을 권장합니다.
여전히 out-of-memory 오류가 발생하면
vllm_enable_sleep_mode을 True로 설정하세요. 그러면 최적화 단계에서 vllm 매개변수와 캐시가 offload됩니다. 자세한 내용은 vLLM Sleep Mode를 사용한 메모리 사용량 감소를 참조하세요.
기본적으로 GRPO는 vLLM에 대해
MASTER_ADDR=localhost와MASTER_PORT=12345를 사용하지만, 환경 변수를 적절히 설정하여 이 값들을 재정의할 수 있습니다.
자세한 내용은 vLLM을 활용한 학습 속도 향상을 참조하세요.
학습-추론 불일치 처리
vLLM은 추론을 크게 가속화하지만, 추론 엔진과 학습 엔진을 분리합니다. 이론적으로 이 두 엔진은 수학적으로 동일하지만, 정밀도 효과와 하드웨어별 최적화로 인해 실제로는 서로 다른 출력을 생성할 수 있습니다. 이러한 차이는 두 시스템의 서로 다른 최적화 목표를 반영합니다. 추론 엔진은 허용 가능한 샘플링 충실도를 유지하면서 샘플링 처리량, 일반적으로 초당 토큰 수로 측정되는 값을 최대화하는 것을 목표로 합니다. 반면 학습 프레임워크는 마스터 가중치와 옵티마이저 상태를 위해 FP32와 같은 더 높은 정밀도 형식을 사용하여 그래디언트 계산의 수치적 안정성과 정밀도에 초점을 맞춥니다. 이러한 상이한 우선순위와 제약 조건은 학습과 추론 사이에 필연적이면서도 미묘한 불일치를 초래합니다.
이러한 불일치는 편향된 기울기 업데이트를 유발하며, 이는 학습 불안정성을 초래하는 것으로 관찰되었습니다([1][2][3][4][5]). 간단함을 위해 REINFORCE 정책 기울기를 고려해 보겠습니다:
여기서 은 어떤 데이터 분포에서 샘플링된 프롬프트를 나타내며, 은 학습 엔진에 의해 구현된 정책입니다. vLLM이 루프에 포함되면 별도의 추론 정책 , 을 얻게 되므로, 유효한 정책 기울기는 다음과 같이 됩니다.
…
이러한 분포 시프트를 보정하는 표준적인 방법은 importance sampling(IS). 두 가지 IS 변형을 제공합니다: Truncated Importance Sampling(TIS) 과 Masked Importance Sampling(MIS). 두 변형 모두 토큰 수준 또는 시퀀스 수준에서 적용할 수 있습니다. 을 importance weight로 표기하면, 예를 들어 은 토큰당이고 시퀀스당입니다. TIS에서는 범위를 벗어난 비율은 [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] 으로 클리핑됩니다.
원본 TIS 논문 은(는) 단일 상한 클리핑 메커니즘, 즉 . TRL의 구현에서는 IcePop 메서드에 영감을 받아 하한도도 도입하여 이를 일반화함으로써, 위에서 보여준 양방향 수식을 도출했습니다.
IcePop에서는 경계값이 와 인 반면, TRL에서는 을(를) 사용합니다. .
MIS에서는 해당 범위를 벗어난 비율이 0으로 설정되므로, 해당 샘플은 그래디언트에 기여하지 않습니다. 즉, TIS에서는 이상치 샘플의 가중치가 낮아지고, MIS에서는 폐기됩니다. 구성 플래그 vllm_importance_sampling_mode는 IS 변형(마스킹 또는 절단)과 그라누라리티(토큰 수준 또는 시퀀스 수준)를 모두 선택합니다.
Importance sampling은 학습–추론 불일치에 대한 원칙적인 알고리즘적 대응입니다. 그러나 두 엔진 자체 간의 불일치를 줄이려는 보다 직접적인 접근법도 있습니다. 이 중 대부분은 엔지니어링 솔루션입니다. 예를 들어, MiniMax M1은 추론 엔진에서 FP32 언어 모델 헤드를 사용합니다. Thinking Machines는 결정론적 추론 커널을 탐구해 왔지만, 이는 상당한 효율성 비용이 수반됩니다. vLLM은 Thinking Machines의 배치 불변 결정론적 커널을 기반으로 구축하여 비트 단위 일관된 정책을 입증했지만, 2025년 11월 기준 표준 vLLM 추론에 비해 여전히 상당한 처리량 페널티가 존재합니다.
transformers 연속 배치로 학습 속도 향상
vLLM의 대안으로, 더 빠른 생성을 위해 transformers의 내장 continuous batching 엔진을 사용할 수 있습니다. Continuous batching은 가장 느린 시퀀스가 완료될 때까지 기다리지 않고, 완료된 시퀀스를 즉시 배치에서 제거합니다. 완료 길이가 가변적인 작업(예: 수학 추론)의 경우, 큰 배치 크기(N≥32)에서 기본 generate()보다 생성 속도가 빠르고 VRAM 사용량이 낮아집니다.
Continuous batching은 서버 설정이나 가중치 동기화 없이 바로 적용할 수 있는 업그레이드입니다. 프로세스 내에서 실행되며, 단일 GPU 학습이나 메모리가 제한된 환경에 적합합니다. 대규모 환경에서 최대 생성 처리량을 원한다면 vLLM을 사용하세요.
from trl import GRPOConfig
training_args = GRPOConfig(
...,
use_transformers_continuous_batching=True,
transformers_continuous_batching_config={
"use_cuda_graph": False,
"max_memory_percent": 0.4, # lower values leave more VRAM for the training backward pass
},
)TRL은 학습 역전파에 충분한 VRAM을 확보하기 위해
max_memory_percent기본값을0.5(transformers의0.9가 아님)로 설정합니다. 대규모 생성 배치(N≥32)를 사용하거나 메모리 부족 오류가 발생하는 경우0.3–0.4로 낮추세요.
전체 학습 예제는 examples/grpo_continuous_batching/grpo_continuous_batching.py를 참고하세요.
대규모 GRPO: 여러 노드에서 70B+ 모델 학습
Qwen2.5-72B와 같은 대규모 모델을 학습할 때는 여러 GPU와 노드에 걸쳐 학습을 효율적이고 확장 가능하게 만들기 위해 몇 가지 핵심 최적화가 필요합니다. 여기에는 다음이 포함됩니다:
- DeepSpeed ZeRO Stage 3: ZeRO는 데이터 병렬성을 활용하여 모델 상태(가중치, 기울기, 옵티마이저 상태)를 여러 GPU와 CPU에 분산 배치하여 각 장치의 메모리 및 계산 요구 사항을 줄입니다. 대규모 모델은 단일 GPU에 적재할 수 없으므로, 이러한 모델을 학습하려면 ZeRO Stage 3 사용이 필수적입니다. 자세한 내용은 DeepSpeed Integration을 참조하세요.
- torchrun: PyTorch의 런처는 모든 노드에서 GPU당 하나의 프로세스를 시작하고 공통 rendezvous를 통해 연결합니다. 자세한 내용은 학습 분산을 참조하세요.
- vLLM: 생성 속도를 높이기 위해 vLLM을 사용하는 방법은 이전 섹션을 참고하세요.
아래는 여러 노드에서 GRPO를 사용하여 70B 모델을 학습하기 위한 SLURM 스크립트 예시입니다. 이 스크립트는 4개의 노드에서 모델을 학습하고, 5번째 노드에서는 vLLM 기반 생성을 수행합니다.
#!/bin/bash
#SBATCH --nodes=5
#SBATCH --gres=gpu:8
# Get the list of allocated nodes
NODELIST=($(scontrol show hostnames $SLURM_JOB_NODELIST))
# Assign the first 4 nodes for training and the 5th node for vLLM
TRAIN_NODES="${NODELIST[@]:0:4}" # Nodes 0, 1, 2, 3 for training
VLLM_NODE="${NODELIST[4]}" # Node 4 for vLLM
# Run training on the first 4 nodes (Group 1)
srun --nodes=4 --ntasks=4 --nodelist="${NODELIST[@]:0:4}" torchrun \
--nnodes 4 \
--nproc_per_node 8 \
--node_rank $SLURM_PROCID \
--rdzv_backend c10d \
--rdzv_endpoint ${NODELIST[0]}:29500 \
train_grpo.py \
--server_ip $VLLM_NODE &
# Run vLLM server on the 5th node (Group 2)
srun --nodes=1 --ntasks=1 --nodelist="${NODELIST[4]}" env VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-72B --tensor-parallel-size 8 \
--weight-transfer-config '{"backend": "nccl"}' \
--logprobs-mode processed_logprobs \
--max-logprobs -1 &
waitimport argparse
from datasets import load_dataset
from trl import GRPOTrainer, GRPOConfig
from trl.rewards import accuracy_reward
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--vllm_server_host", type=str, default="", help="The server IP")
args = parser.parse_args()
dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
training_args = GRPOConfig(
per_device_train_batch_size=4,
deepspeed="examples/deepspeed_configs/zero3.json",
use_vllm=True,
vllm_mode="server",
vllm_server_host=args.vllm_server_host.replace("ip-", "").replace("-", "."), # from ip-X-X-X-X to X.X.X.X
)
trainer = GRPOTrainer(
model="Qwen/Qwen2.5-72B",
args=training_args,
reward_funcs=accuracy_reward,
train_dataset=dataset
)
trainer.train()
if __name__=="__main__":
main()사용자 정의 보상 함수 사용
GRPOTrainer는 밀도형 보상 모델 대신 사용자 정의 보상 함수를 사용할 수 있습니다. 호환성을 보장하기 위해 보상 함수는 다음 요구 사항을 충족해야 합니다:
Reward 함수는 동기 Python callable이거나 비동기 async def 코루틴일 수 있습니다. 여러 비동기 reward 함수를 제공하면 asyncio.gather를 통해 병렬로 실행되어 대기되므로, 지연 시간이 겹치게 됩니다.
입력 인자:
이 함수는 다음을 키워드 인수로 받아야 합니다:
prompts(프롬프트를 포함합니다),completions(생성된 completions을 포함),completion_ids(토큰화된 completions을 포함),trainer_state(TrainerState): 트레이너의 현재 상태입니다. 학습 진행도에 따라 보상이 조정되는 커리큘럼 학습과 같은 동적 보상 함수를 구현하는 데 사용할 수 있습니다.log_extra: completions 테이블에 추가 열을 추가하기 위한 callablelog_extra(column: str, values: list). 예제 6을 참조하세요.log_metric:kl,entropy등과 함께 스칼라 메트릭을 플롯으로 기록하기 위한 콜러블log_metric(name: str, value: float). 예제 6을 참조하세요.environments: 환경 인스턴스의 목록으로, 각 completion마다 하나씩 포함됩니다.environment_factory가 제공된 경우에만 존재합니다. 에피소드 동안 누적된 상태를 읽는 데 사용하세요(예:env.counter). 상태가 있는(stateful) 환경의 경우,get_reward메서드를 통해 환경이 보상을 소유하도록 하는 방식을 권장합니다 — Rewards를 참조하세요.- 데이터셋에 있을 수 있는 모든 열 이름(
prompt제외). 예를 들어, 데이터셋에ground_truth라는 이름의 열이 포함된 경우, 해당 함수는ground_truth를 키워드 인수로 받아 호출됩니다.
이 요구 사항을 충족하는 가장 쉬운 방법은 함수 시그니처에
**kwargs를 사용하는 것입니다.데이터셋 형식에 따라 입력이 달라집니다:
반환 값: 함수는 float의 리스트를 반환해야 합니다. 각 float는 단일 completion에 해당하는 보상을 나타냅니다.
예제 1: 더 긴 완성본을 보상
아래는 더 긴 완성본을 보상하는 표준 형식의 보상 함수 예시입니다:
def reward_func(completion_ids, **kwargs):
"""Reward function that assigns higher scores to longer completions (in terms of token count)."""
return [float(len(ids)) for ids in completion_ids]다음과 같이 테스트할 수 있습니다:
>>> prompts = ["The sky is", "The sun is"] # not used in the reward function, but the trainer will pass it
>>> completions = [" blue.", " in the sky."] # not used in the reward function, but the trainer will pass it
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[2.0, 4.0]예제 1.1: 더 긴 완성본을 보상합니다 (문자 수 기준)
이전 예제와 동일하지만, 이번에는 보상 함수가 토큰이 아닌 문자 수를 기반으로 합니다.
def reward_func(completions, **kwargs):
"""Reward function that assigns higher scores to longer completions (in terms of character count)."""
return [float(len(completion)) for completion in completions]다음과 같이 테스트할 수 있습니다:
>>> prompts = ["The sky is", "The sun is"]
>>> completions = [" blue.", " in the sky."]
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]] # not used in the reward function, but the trainer will pass it
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[6.0, 12.0]예제 2: 특정 형식으로 보상 완료
아래는 완성물이 특정 형식을 갖는지 확인하는 보상 함수의 예시입니다. 이 예시는 DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning 논문에서 사용된 format reward 함수에서 영감을 받았습니다. 프롬프트와 완성물이 구조화된 메시지로 구성된 대화형 형식을 위해 설계되었습니다.
import re
def format_reward_func(completions, **kwargs):
"""Reward function that checks if the completion has a specific format."""
pattern = r"^<think>.*?</think><answer>.*?</answer>$"
completion_contents = [completion[0]["content"] for completion in completions]
matches = [re.match(pattern, content) for content in completion_contents]
return [1.0 if match else 0.0 for match in matches]다음과 같이 이 함수를 테스트할 수 있습니다:
>>> prompts = [
... [{"role": "user", "content": "What is the result of (1 + 2) * 4?"}],
... [{"role": "user", "content": "What is the result of (3 + 1) * 2?"}],
... ]
>>> completions = [
... [{"role": "assistant", "content": "<think>The sum of 1 and 2 is 3, which we multiply by 4 to get 12.</think><answer>(1 + 2) * 4 = 12</answer>"}],
... [{"role": "assistant", "content": "The sum of 3 and 1 is 4, which we multiply by 2 to get 8. So (3 + 1) * 2 = 8."}],
... ]
>>> format_reward_func(prompts=prompts, completions=completions)
[1.0, 0.0]예제 3: 참조를 기반으로 보상 완료
아래는 완성물이 올바른지 확인하는 보상 함수의 예시입니다. 이 예시는 DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning 논문에서 사용된 accuracy reward 함수에서 영감을 받았습니다.
이 예시는 standard format를 위해 설계되었으며, 데이터셋에는 ground_truth라는 이름의 열이 포함되어 있습니다.
import re
def reward_func(completions, ground_truth, **kwargs):
# Regular expression to capture content inside \boxed{}
matches = [re.search(r"\\boxed\{(.*?)\}", completion) for completion in completions]
contents = [match.group(1) if match else "" for match in matches]
# Reward 1 if the content is the same as the ground truth, 0 otherwise
return [1.0 if c == gt else 0.0 for c, gt in zip(contents, ground_truth)]다음과 같이 이 함수를 테스트할 수 있습니다:
>>> prompts = ["Problem: Solve the equation $2x + 3 = 7$. Solution:", "Problem: Solve the equation $3x - 5 = 10$."]
>>> completions = [r" The solution is \boxed{2}.", r" The solution is \boxed{6}."]
>>> ground_truth = ["2", "5"]
>>> reward_func(prompts=prompts, completions=completions, ground_truth=ground_truth)
[1.0, 0.0]예제 4: 다중 작업 보상 함수
아래는 GRPOTrainer에서 여러 보상 함수를 사용하는 예시입니다. 이 예시에서는 두 가지 작업별 보상 함수인 math_reward_func와 coding_reward_func를 정의합니다. math_reward_func는 수학 문제의 정답 여부 기준으로 보상을 부여하고, coding_reward_func는 코딩 문제의 솔루션이 정상적으로 동작하는지 여부 기준으로 보상을 부여합니다.
from datasets import Dataset
from trl import GRPOTrainer
# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
[
{"prompt": "What is 2+2?", "task": "math"},
{"prompt": "Write a function that returns the sum of two numbers.", "task": "code"},
{"prompt": "What is 3*4?", "task": "math"},
{"prompt": "Write a function that returns the product of two numbers.", "task": "code"},
]
)
# Math-specific reward function
def math_reward_func(prompts, completions, task, **kwargs):
rewards = []
for prompt, completion, t in zip(prompts, completions, task):
if t == "math":
# Calculate math-specific reward
correct = check_math_solution(prompt, completion)
reward = 1.0 if correct else -1.0
rewards.append(reward)
else:
# Return None for non-math tasks
rewards.append(None)
return rewards
# Coding-specific reward function
def coding_reward_func(prompts, completions, task, **kwargs):
rewards = []
for prompt, completion, t in zip(prompts, completions, task):
if t == "code":
# Calculate coding-specific reward
works = test_code_solution(prompt, completion)
reward = 1.0 if works else -1.0
rewards.append(reward)
else:
# Return None for non-coding tasks
rewards.append(None)
return rewards
# Use both task-specific reward functions
trainer = GRPOTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
reward_funcs=[math_reward_func, coding_reward_func],
train_dataset=dataset,
)
trainer.train()이 예시에서 math_reward_func와 coding_reward_func는 수학 문제와 코딩 문제를 모두 포함하는 혼합 데이터셋과 함께 작동하도록 설계되었습니다. 데이터셋의 task 컬럼은 각 문제에 어떤 보상 함수를 적용할지 결정하는 데 사용됩니다. 데이터셋의 샘플에 해당하는 보상 함수가 없으면 보상 함수는 None을 반환하고, GRPOTrainer는 유효한 함수와 작업을 계속 처리합니다. 이를 통해 GRPOTrainer는 서로 다른 적용 범위를 가진 여러 보상 함수를 처리할 수 있습니다.
GRPOTrainer는 보상 함수가 반환하는 None 보상을 무시하고, 관련 함수가 반환한 보상만 고려합니다. 이를 통해 모델은 관련 작업으로 학습되고, 관련 보상 함수가 없는 작업은 무시됩니다.
예제 5: 비동상 보상 함수
커스텀 보상 함수는 async def 코루틴으로 정의할 수도 있습니다. 보상이 느린 I/O(예: 원격 서비스 호출)에 의존하는 경우 유용합니다. 여러 개의 async 보상 함수를 전달하면 GRPOTrainer는 이를 병렬로 실행하여 지연 시간이 겹치게 합니다.
다음은 I/O 바운드 작업을 시뮬레이션하는 비동기 보상 함수의 최소 예시입니다:
import asyncio
async def async_reward_func(prompts, completions, **kwargs):
# Simulate an I/O-bound call (e.g., HTTP request, database lookup)
await asyncio.sleep(0.01)
# Simple toy reward: 1.0 if the completion is non-empty, else 0.0
return [1.0 if completion else 0.0 for completion in completions]예제 6: 추가 열 및 지표 로깅
completions 테이블에 추가 열을 기록하고 스칼라 메트릭을 플롯으로 기록하는 보상 함수의 예시는 다음과 같습니다.
import re
def reward_func(completions, ground_truth, log_extra=None, log_metric=None, **kwargs):
extracted = [re.search(r"\\boxed\{(.*?)\}", c) for c in completions]
extracted = [m.group(1) if m else None for m in extracted]
rewards = [1.0 if e == gt else 0.0 for e, gt in zip(extracted, ground_truth)]
if log_extra:
log_extra("golden_answer", list(ground_truth))
log_extra("extracted_answer", [e or "[none]" for e in extracted])
if log_metric:
log_metric("accuracy", sum(rewards) / len(rewards))
return rewards트레이너에 보상 함수 전달
사용자 정의 보상 함수를 사용하려면 다음과 같이 GRPOTrainer에 전달하세요:
from trl import GRPOTrainer
trainer = GRPOTrainer(
reward_funcs=reward_func,
...,
)여러 개의 보상 함수를 리스트로 전달할 수 있으며, 이 리스트에는 동기 함수와 비동기 함수가 모두 포함될 수 있습니다:
from trl import GRPOTrainer
trainer = GRPOTrainer(
reward_funcs=[reward_func, async_reward_func1, async_reward_func2],
...,
)보상은 각 함수의 보상 합으로 계산되며, 설정에 reward_weights가 제공된 경우 가중 합으로 계산됩니다.
GRPOTrainer는 서로 다른 유형의 여러 보상 함수를 지원합니다. 자세한 내용은 매개변수 문서를 참조하세요.
엔트로피 정규화
탐색을 장려하고 정책이 거의 결정론적인 출력으로 수렴하는 것을 방지하기 위해, 학습 목적 함수에 엔트로피 보너스를 추가할 수 있습니다. 엔트로피 정규화는 GRPO 손실을 다음과 같이 확장합니다:
여기서 은 정책의 토큰당 평균 엔트로피이고 은 엔트로피 계수입니다. 보너스는 항상 loss_type; 과 관계없이 토큰당 평균 엔트로피이며, 손실 유형의 정책 정규화에 맞게 재조정되지 않습니다(예: Dr. GRPO의 batch_size * max_completion_length 분모). 따라서 entropy_coef 은 모든 손실 유형에서 동일한 의미를 가집니다.
정적 엔트로피 — 학습 전체에 걸쳐 고정된 계수:
from trl import GRPOConfig, GRPOTrainer
training_args = GRPOConfig(entropy_coef=0.05, ...)적응 엔트로피 — Skywork-OR1에서 소개된 바와 같이, 계수는 목표 엔트로피에 기반하여 각 옵티마이저 단계마다 업데이트됩니다. 현재 엔트로피가 entropy_target 이하인 경우, 계수는 entropy_coef_delta만큼 증가하고, 그렇지 않으면 감소합니다. 계수는 엔트로피가 목표 이하일 때만 적용(즉, 0이 아닐 때)됩니다:
training_args = GRPOConfig(
entropy_coef=0.01, # initial coefficient
use_adaptive_entropy=True,
entropy_target=5.0, # target mean per-token entropy (nats); tune for your model
entropy_coef_delta=0.005, # step size per optimizer step
entropy_coef_min=0.0,
entropy_coef_max=1.0,
...
)일반적인 언어 모델의 토큰별 엔트로피는 2~10 nats 범위이므로, 기본값인
entropy_target=0.2는 거의 정규화를 트리거하지 않습니다. 보너스는 엔트로피가 목표값 이하로 내려갈 때만 적용되므로, 이는 엔트로피가 거의 완전히 붕괴된 상태에 해당합니다. 해당 값을 모델에 의미 있는 값으로 설정하세요. 예를 들어, 학습 초기에 관찰되는 엔트로피(메트릭entropy로 기록됨)에 가까운 값으로 설정할 수 있습니다.top_entropy_quantile < 1.0를 사용하는 경우,entropy_target는 고엔트로피 토큰 하위 집합에 적용됩니다. 이 하위 집합의 엔트로피는 기록된 전체 토큰entropy보다 높으므로, 이에 맞게 보정하세요.
use_adaptive_entropy=True인 경우, 현재 엔트로피 계수 entropy_coef가 각 체크포인트와 함께 저장되고 재개 시 복원되므로 학습을 완전히 재개할 수 있습니다.
GRPO를 위한 빠른 실험
RapidFire AI는 TRL 위에 구축된 오픈소스 실험 엔진으로, 단일 GPU에서도 여러 GRPO 구성을 동시에 실행할 수 있습니다. 구성을 순차적으로 시도하는 대신, RapidFire는 재시작 없이 모든 학습 곡선을 더 일찍 확인하고, 성능이 낮은 실행을 중단하며, 유망한 실행을 새 설정으로 클론하는 것을 지원합니다. 자세한 내용은 RapidFire AI Integration을 참조하세요.
에이전트 학습
GRPO는 에이전트 학습을 지원합니다: 모델은 생성 과정에서 도구를 호출하고 그 결과로부터 학습합니다.
- tool은 모델에 노출되는 일반 Python 함수(동기 또는 비동기)입니다. 상태가 없는 호출(계산기, 웹 검색)에는
tools를 사용하세요. - environment은 보다 일반적인 형태입니다. 각 rollout마다 새로 생성되는 상태가 있는 객체로, 공개된 메서드들이 도구로 노출되며,
reset라이프사이클 훅과 보상을 소유할 수 있도록 하는 선택적get_reward를 포함합니다. rollout별 상태, reset 훅, 또는 환경이 소유하는 보상이 필요할 때는environment_factory를 사용하세요.
구성할 수 있습니다 — environment_factory와 함께 독립적인 tools를 전달할 수 있습니다.
도구
tools 인수는 에이전트가 사용할 수 있는 도구를 정의하는 Python 함수(동기 또는 비동기)의 목록을 기대합니다:
from trl import GRPOTrainer
trainer = GRPOTrainer(
tools=[tool1, tool2],
...,
)각 도구는 타입 힌트가 지정된 인자와 반환 타입을 가진 표준 Python 함수여야 하며, 목적, 인자, 반환 값을 설명하는 Google 스타일 docstring을 포함해야 합니다. 자세한 내용은 Passing tools 가이드를 참조하세요.
GRPO 도구 호출 루프는 채팅 템플릿이 접두어 보존(prefix-preserving) 특성을 가져야 합니다(도구 메시지를 추가해도 이전 메시지의 렌더링 방식이 변경되어서는 안 됩니다). 알려진 모델 계열(예: Qwen3, DeepSeek-V3)의 경우, TRL은 도구가 활성화되면 패치된 학습 템플릿으로 자동으로 교체합니다. 전체 목록은 Chat Templates을 참조하세요.
GRPOConfig의 max_tool_calling_iterations를 사용하여 도구 호출 턴의 수를 제한할 수 있습니다. 기본적으로 제한이 없으며, 모델이 도구 호출이 없는 응답 턴을 생성하거나, 완료(모든 턴 및 도구 결과)가 max_completion_length 토큰에 도달하거나, 전체 시퀀스가 모델의 최대 길이(vllm_mode="colocate"인 경우 vllm_max_model_length, 그 외에는 모델의 max_position_embeddings)에 도달하면 생성이 중단됩니다.
예:
from trl import GRPOTrainer
def multiply(a: int, b: int) -> int:
"""
Multiplies two integers.
Args:
a: The first integer.
b: The second integer.
Returns:
The product of the two integers.
"""
return a * b
async def async_add(a: int, b: int) -> int:
"""
Asynchronously adds two integers.
Args:
a: The first integer.
b: The second integer.
Returns:
The sum of the two integers.
"""
return a + b
trainer = GRPOTrainer(
tools=[multiply, async_add],
...,
)환경
environment_factory를 통해 도구를 제공할 수도 있습니다. 이 모드에서 GRPOTrainer는 각 rollout마다 환경 인스턴스를 하나 생성하고, 환경의 public 메서드를 도구로 노출합니다.
environment_factory에는transformers>=5.2.0이 필요합니다.
environment_factory를 사용하면 환경이 데이터를 소유합니다. 외부의 train_dataset는 없습니다. 각 rollout마다 reset()이 작업을 생성합니다. 환경이 보유하는 코퍼스에서 자체 샘플링을 하거나 상태를 절차적으로 생성하는 방식입니다. 이후 프롬프트를 반환합니다. max_steps는 학습 길이를 설정합니다. 다음은 타겟을 자체 샘플링하고 increment 메서드(도구로 노출됨)를 노출하는 환경의 최소 예시입니다.
import random
from trl import GRPOConfig, GRPOTrainer
class IncrementEnv:
# Reserved methods
def reset(self, **kwargs) -> str | None: # required; called at the start of each rollout
self.counter = 0
self.target = random.randint(1, 6) # self-sample the task
return f"Increment the counter by {self.target}." # returned string becomes the prompt
def get_reward(self) -> float: # optional: the environment scores itself from its own state
return float(self.counter == self.target)
# Public methods (exposed as tools)
def increment(self, step: int) -> int:
"""
Increment the internal counter.
Args:
step: Value to add to the counter.
Returns:
The updated counter value.
"""
self.counter += step
return self.counter
trainer = GRPOTrainer(
model="Qwen/Qwen3-0.6B",
args=GRPOConfig(max_steps=1000, chat_template_kwargs={"enable_thinking": False}),
environment_factory=IncrementEnv,
)
trainer.train()환경 클래스에는 reset와 get_reward라는 두 개의 예약된 메서드가 있습니다. 다른 공개 메서드와 달리, 이 메서드들은 모델에 도구로 노출되지 않습니다.
reset(필수)는 rollout이 시작될 때 호출됩니다.None또는 문자열을 반환할 수 있습니다. GRPO에서 문자열을 반환하는 경우, 해당 문자열이 사용자 프롬프트가 됩니다.get_reward(선택 사항, 동기 또는 비동기)는 인수를 받지 않으며float를 반환합니다. 환경은 자신의 내부 상태(게임이 승리로 끝났는가? 단어가 추측되었는가?)를 기준으로 방금 실행된 에피소드에 점수를 매깁니다. 완료된 롤아웃마다 한 번씩 호출되며 보상 소스로 작용합니다.
환경이 각
reset()호출 시 자체적으로 샘플링하기 때문에, GRPO 그룹의G개 멤버는 동일한 초기 상태를 공유하지 않을 수 있으며, 이로 인해 그룹 베이스라인이 약간 더 노이즈가 생길 수 있습니다. 그룹 내에서 동일한 상태를 유지하려면,reset()이 공유된 키로부터 상태를 결정적으로 유도하도록 하세요.
외부 데이터셋 제공 (선택 사항)
환경이 자체적으로 샘플링하도록 두는 대신, 외부 train_dataset를 제공할 수 있습니다. 예를 들어, 작업이 이미 데이터셋에 포함되어 있거나 여러 환경 사이를 라우팅해야 하는 경우에 사용할 수 있습니다. 롤아웃마다 트레이너는 한 행을 샘플링하고, 그 행의 "prompt" 컬럼을 프롬프트로 사용하며, 행의 나머지 컬럼을 reset()에 키워드 인수로 전달합니다(이렇게 하면 환경이 데이터셋에서 작업을 읽게 됩니다).
from datasets import Dataset
from trl import GRPOTrainer
# Each row carries the prompt and the task data (here, the counter target to reach).
dataset = Dataset.from_dict(
{
"prompt": [[{"role": "user", "content": f"Increment the counter to {i}."}] for i in range(1, 7)],
"target": list(range(1, 7)),
}
)
class IncrementEnv:
def reset(self, target, **kwargs) -> None: # the row's `target` column arrives as a keyword argument
self.counter = 0
self.target = target
def get_reward(self) -> float:
return float(self.counter == self.target)
def increment(self, step: int) -> int: # exposed as a tool (see the full docstring above)
self.counter += step
return self.counter
trainer = GRPOTrainer(
model="Qwen/Qwen3-0.6B",
train_dataset=dataset, # the dataset owns the task; the "target" column reaches reset(target=...)
environment_factory=IncrementEnv,
)
trainer.train()보상
Environment-owned reward와 trainer-owned reward는 상호 배타적이지 않습니다. completion에서 계산하는 것이 자연스러운 reward(예: 텍스트에 대한 형식 검사)의 경우 reward_funcs를 전달하고, 그리고 environment가 상태에 의존하는 reward를 get_reward를 통해 반환하도록 합니다. 모든 소스가 합산되며, reward_weights는 reward_funcs에만 적용됩니다(environment는 자체 스케일을 관리합니다).
def format_reward(completions, **kwargs): # trainer-owned: scores the completion text
...
trainer = GRPOTrainer(
model="Qwen/Qwen3-0.6B",
args=GRPOConfig(max_steps=1000),
reward_funcs=format_reward, # trainer-owned: scores the completion
environment_factory=IncrementEnv, # env-owned: scores its internal state via `get_reward`
)reward_func은 환경 상태를 직접 읽을 수도 있습니다. environment_factory가 설정된 경우, 트레이너는 environments kwarg(완성 결과당 하나의 인스턴스)를 전달합니다. 이는 가끔 유용하지만, 상태에 의존하는 보상에는 get_reward를 사용하는 것이 좋습니다.
이것은 AsyncGRPOTrainer에서도 동일하게 작동합니다.
여러 환경
단일 실행에서 여러 작업의 혼합으로 학습하려면(예: 코딩 작업과 게임), 단일 callable 대신 환경 이름에서 팩토리로 매핑하는 딕셔너리를 전달합니다. 각 롤아웃은 데이터셋의 environment 필드를 통해 환경을 선택하며, 해당 환경의 도구만 노출됩니다. 이를 통해 관련 없는 도구가 누출되는 것을 방지합니다(게임의 move 도구가 코딩 예시에 노출되거나 그 반대의 경우). 각 환경은 여전히 자신의 데이터를 소유하고 reset()에서 프롬프트를 반환하므로, 데이터셋은 환경 간 라우팅을 위해 environment 컬럼만 필요로 합니다.
import random
from datasets import Dataset
from trl import GRPOConfig, GRPOTrainer
class CodingEnv:
def reset(self, **kwargs) -> str:
n = random.randint(1, 20)
return f"Compute the {n}th Fibonacci number."
def run_code(self, code: str) -> str: # exposed as a tool only for "coding" examples
"""Run the given Python code and return its stdout.
Args:
code: The Python source to execute.
Returns:
The captured standard output.
"""
...
class GameEnv:
def reset(self, **kwargs) -> str:
return "Reach the goal tile."
def move(self, action: str) -> str: # exposed as a tool only for "game" examples
"""Apply an action to the game and return the new observation.
Args:
action: One of "up", "down", "left", "right".
Returns:
The observation after the move.
"""
...
# The dataset only routes: each row picks the environment for that rollout
dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})
trainer = GRPOTrainer(
model="Qwen/Qwen3-0.6B",
args=GRPOConfig(chat_template_kwargs={"enable_thinking": False}),
train_dataset=dataset,
reward_funcs=reward_func,
environment_factory={"coding": CodingEnv, "game": GameEnv},
)
trainer.train()보상 함수는 여전히 reward_kwargs["environments"]를 통해 모든 예시의 환경을 받으므로, 환경 유형에 따라 분기 처리(예: isinstance(env, CodingEnv))할 수 있습니다. 환경 인스턴스는 스텝 간에 재사용되며(에피소드 간 리셋)되므로, 비용이 높은 __init__는 매 스텝마다가 아니라 한 번만 수행됩니다. environment 필드는 트레이너에 의해 소비되며 reset로 전달되지 않습니다.
멀티모달 도구 응답
Tools는 텍스트와 함께 이미지를 반환할 수 있으며, 이를 위해 콘텐츠 블록의 리스트를 반환합니다. 이는 도구가 시각적 피드백(예: 스크린샷, 플롯, 카메라 캡처)을 제공하는 VLM 에이전트 학습에 유용합니다.
from PIL import Image
def take_screenshot() -> list:
"""
Takes a screenshot of the current screen.
Returns:
The screenshot image with a description.
"""
img = Image.open("screenshot.png")
return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]반환된 이미지는 자동으로 대화에 삽입되어 VLM에 전달되며, 이후의 생성 턴에 사용됩니다.
지원되는 모델
테스트 환경:
- Beam — 예:
reflection/Beam-1.0-501B-A23B - DeepSeek-R1 — 예:
deepseek-ai/DeepSeek-R1 - Gemma4 — 예:
google/gemma-4-E2B-it - GLM-4-MoE (4.5, 4.6 또는 4.7) — 예:
zai-org/GLM-4.7 - GPT-OSS — 예:
openai/gpt-oss-20b - Llama 3.1 — 예:
meta-llama/Llama-3.1-8B-Instruct - Llama 3.2 — 예:
meta-llama/Llama-3.2-3B-Instruct - Qwen2.5 — 예:
Qwen/Qwen2.5-0.5B-Instruct - Qwen3 — 예:
Qwen/Qwen3-0.6B - Qwen3-VL — 예:
Qwen/Qwen3-VL-2B-Instruct - Qwen3.5 — 예:
Qwen/Qwen3.5-2B - Qwen3.6 — 예:
Qwen/Qwen3.6-35B-A3B
모든 LLM과의 호환성이 보장되지는 않습니다. 특정 모델이 지원되어야 한다고 생각하시면 GitHub에서 이슈를 열어 주세요. 더 좋다면, 필요한 변경 사항이 포함된 pull request를 제출해 주세요.
환경 통합
모든 환경은 동일한 environment_factory 슬롯에 연결되므로 TRL 수준에서 상호 교환 가능합니다. 작업에 적합한 생태계를 가진 환경을 선택하세요:
| 통합 | 개요 | 사용 시점 |
|---|---|---|
| OpenEnv | Hugging Face와 커뮤니티가 지원하는 오픈 환경 표준(Gymnasium 스타일 API, WebSocket 또는 컨테이너화 실행으로 제공). | Hub의 사전 제작된 OpenEnv 환경을 사용하거나, 오픈 표준에 따라 자체 환경을 정의하는 경우(예: Wordle, Sudoku, Catch) |
| OpenReward | ORS 기반 환경(openreward.ai 카탈로그 또는 자체 ORS 서버)과의 통합; 태스크와 보상은 HTTP를 통해 제공됩니다. | ORS 환경에 대해 학습을 수행하려면: 카탈로그(예: Eigent/SETA), 자체 인프라에서 자체 호스팅하는 환경, 또는 개발 중인 로컬 서버를 사용할 수 있습니다. |
| Harbor | Harbor 작업 스위트와의 통합: 각 작업은 지시문, 실제 샌드박스 이미지(docker, e2b, …), 그리고 샌드박스 내 검증기로 구성됩니다. | Harbor 작업 스위트에 대해 학습을 수행하려는 경우: 작업의 트리이며, 각 작업은 자체적으로 완결된 샌드박스 및 검증기(예: 샌드박스 내 파일을 탐색하고 채점자가 확인하는 답을 작성하는 데이터 분석 에이전트)로 구성됩니다. |
비전 언어 모델 학습
GRPO는 텍스트와 이미지를 모두 포함하는 멀티모달 데이터셋에서 Vision-Language Models(VLM)을 학습하는 것을 지원합니다.
지원되는 모델
테스트 환경:
- Gemma3 — 예:
google/gemma-3-4b-it - LLaVA-NeXT — 예:
llava-hf/llava-v1.6-mistral-7b-hf - Qwen2-VL — 예:
Qwen/Qwen2-VL-2B-Instruct - Qwen2.5-VL — 예:
Qwen/Qwen2.5-VL-3B-Instruct - SmolVLM2 — 예:
HuggingFaceTB/SmolVLM2-2.2B-Instruct
모든 VLM과의 호환성이 보장되지는 않습니다. 특정 모델이 지원되어야 한다고 생각하시면 GitHub에서 이슈를 열어 주세요. 더 좋다면, 필요한 변경 사항이 포함된 pull request를 제출해 주세요.
빠른 시작
grpo_vlm.py를 사용하여 VLM을 파인튜닝합니다. lmms-lab/multimodal-open-r1-8k-verified로 학습하는 명령어 예시:
torchrun --nproc_per_node 8 examples/grpo_visual_math/grpo_visual_math.py \
--deepspeed examples/deepspeed_configs/zero3.json \
--model_name_or_path Qwen/Qwen2.5-VL-3B-Instruct \
--output_dir grpo-Qwen2.5-VL-3B-Instruct \
--learning_rate 1e-5 \
--dtype bfloat16 \
--max_completion_length 1024 \
--use_vllm \
--vllm_mode colocate \
--use_peft \
--lora_target_modules "q_proj", "v_proj" \
--log_completions구성 팁
- 시각-언어 투영 레이어에 LoRA 사용
- 메모리 사용량을 줄이기 위해 4-bit 양자화를 활성화
- VLM은 메모리 집약적입니다 — 작은 배치 크기부터 시작하세요
- 대부분의 모델은 vLLM(
server및colocate모드)과 호환됩니다
데이터셋 형식
각 학습 샘플에는 다음을 포함해야 합니다:
prompt: 프로세서의 채팅 템플릿을 통해 포맷된 텍스트image/images: PIL Image 또는 PIL Image 목록
트레이너는 모델의 이미지 프로세서를 통해 이미지에서 텐서로의 변환을 자동으로 처리합니다.
GRPOTrainer
클래스 trl.GRPOTrainer
< source >( model: str | PreTrainedModel | PeftModelreward_funcs: str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]] | list[str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]]] | None = Noneargs: trl.trainer.grpo_config.GRPOConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = Nonereward_processing_classes: transformers.tokenization_utils_base.PreTrainedTokenizerBase | list[transformers.tokenization_utils_base.PreTrainedTokenizerBase] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)quantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = Nonerollout_func: collections.abc.Callable[[list[str], 'GRPOTrainer'], dict[str, typing.Any]] | None = Noneenvironment_factory: collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset]] | None = None )
매개변수
- model (
str또는 PreTrainedModel 또는PeftModel) — 학습할 모델. 다음 중 하나일 수 있습니다:- huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 model id인 문자열, 또는 save_pretrained를 사용하여 모델 가중치를 저장한 디렉터리의 경로, 예:
'./my_model_directory/'입니다. 모델은args.model_init_kwargs의 키워드 인수를 사용하여<ModelArchitecture>.from_pretrained(여기서<ModelArchitecture>는 모델 구성에서 파생됨)로 로드됩니다.args.model_init_kwargs에dtype이 지정되지 않은 경우 기본값은float32입니다. 이는 from_pretrained와 다르며, 후자의 경우(Transfomers v5부터) dtype은 모델 구성에서 추론됩니다. - PreTrainedModel 객체입니다. 인과적 언어 모델만 지원됩니다.
PeftModel객체입니다. 인과 언어 모델만 지원됩니다.
- huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 model id인 문자열, 또는 save_pretrained를 사용하여 모델 가중치를 저장한 디렉터리의 경로, 예:
- reward_funcs (
RewardFunc | list[RewardFunc], 선택 사항) — 보상을 계산하는 데 사용할 보상 함수입니다. 보상을 계산하려면 프롬프트와 완성 결과를 인수로 모든 보상 함수를 호출한 후 보상을 합산합니다. 보상이 환경에 의해 공급되는 경우(아래 참조)에는 생략할 수 있습니다. 다음 중 하나일 수 있습니다:environment_factory(단일 보상 함수, 예: 문자열: huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 모델 ID 또는 save_pretrained를 사용하여 모델 가중치가 저장된 디렉터리의 경로(예: './my_model_directory/'). 모델은 num_labels=1과 args.model_init_kwargs의 키워드 인수를 사용하여 from_pretrained로 로드됩니다. PreTrainedModel 객체: 시퀀스 분류 모델만 지원됩니다. 사용자 정의 보상 함수: 이 함수에는 프롬프트와 생성된 완성 결과, 그리고 데이터셋의 추가 열이 제공됩니다. 보상 목록을 반환해야 합니다. 사용자 정의 보상 함수는 동기식 또는 비동기식일 수 있으며, 보상이 해당 샘플에 적용되지 않는 경우 None을 반환할 수도 있습니다. 이는 서로 다른 유형의 샘플에 서로 다른 보상 함수가 적용되는 멀티태스크 학습에 유용합니다. 보상 함수가 특정 샘플에 대해 None을 반환하면, 해당 샘플의 보상 계산에서 그 보상 함수가 제외됩니다. 자세한 내용은 사용자 정의 보상 함수 사용 문서를 참조하세요. 트레이너의 상태도 보상 함수에 전달됩니다. 트레이너의 상태는 TrainerState의 인스턴스이며, 보상 함수 시그니처의 trainer_state 인수를 통해 접근할 수 있습니다. 보상 함수 목록: 각 항목은 독립적으로 위의 유형 중 하나일 수 있습니다. 목록 내에서 서로 다른 유형을 혼합하는 것(예: 문자열 모델 ID와 사용자 정의 보상 함수)이 허용됩니다.-
다음과 같은 단일 보상 함수:
-
문자열: huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 모델 ID 또는 save_pretrained를 사용하여 모델 가중치를 저장한 디렉터리의 경로, 예:
'./my_model_directory/'. 모델은num_labels=1및args.model_init_kwargs의 키워드 인수를 사용하여 from_pretrained로 로드됩니다. -
PreTrainedModel 객체: 시퀀스 분류 모델만 지원됩니다.
-
사용자 정의 보상 함수: 이 함수에는 프롬프트와 생성된 완성 결과, 그리고 데이터셋의 추가 열이 제공됩니다. 보상 목록을 반환해야 합니다. 사용자 정의 보상 함수는 동기식 또는 비동기식으로 작성할 수 있으며, 해당 샘플에 보상이 적용되지 않는 경우
None을 반환할 수도 있습니다. 이는 서로 다른 유형의 샘플에 서로 다른 보상 함수가 적용되는 멀티태스크 학습에 유용합니다. 보상 함수가 특정 샘플에 대해None을 반환하면, 해당 샘플의 보상 계산에서 그 보상 함수가 제외됩니다. 자세한 내용은 사용자 정의 보상 함수 사용을 참조하세요.Trainer의 상태는 보상 함수에도 전달됩니다. Trainer의 상태는 TrainerState의 인스턴스이며, 보상 함수 시그니처의
trainer_state인수를 통해 접근할 수 있습니다.
-
-
보상 함수의 목록으로, 각 항목은 독립적으로 위의 유형 중 하나일 수 있습니다. 목록 내에서 서로 다른 유형을 혼합하는 것(예: 문자열 모델 ID와 사용자 정의 보상 함수)이 허용됩니다.
-
- args (GRPOConfig, 선택 사항) —
이 trainer의 설정입니다.
None인 경우 기본 설정이 사용됩니다. - train_dataset (Dataset 또는 IterableDataset, 선택 사항) —
학습에 사용할 Dataset입니다. 반드시
"prompt". 컬럼을 포함해야 합니다. Dataset의 추가 컬럼은 무시됩니다. 샘플 형식은 다음과 같습니다:environment_factory가 제공되고 환경이 데이터를 소유하거나 절차적으로 생성하여reset()메서드에서 프롬프트를 반환하는 경우에만 생략할 수 있습니다. 이 경우 학습 길이를 정의하기 위해max_steps를 설정해야 합니다.train_dataset이 IterableDataset(예: 스트리밍 데이터셋)인 경우, 그 길이를 추론할 수 없으므로 학습 루프를 제한하고 학습률 스케줄러를 구성하는 데 필요한 총 학습 단계 수를 지정하기 위해 학습 인자에max_steps를 설정해야 합니다. - eval_dataset (Dataset, IterableDataset, DatasetDict, IterableDatasetDict 또는
dict[str, Dataset | IterableDataset]) — 평가에 사용할 Dataset입니다.train_dataset과 동일한 요구 사항을 충족해야 합니다. - processing_class (PreTrainedTokenizerBase, ProcessorMixin, 선택 사항) —
데이터를 처리하는 데 사용되는 처리 클래스입니다. 패딩 쪽은 “left”로 설정해야 합니다.
None인 경우, from_pretrained를 사용하여 모델 이름에서 처리 클래스를 로드합니다. 패딩 토큰인tokenizer.pad_token이 설정되어 있어야 합니다. 처리 클래스에 패딩 토큰이 설정되지 않은 경우,tokenizer.eos_token이 기본값으로 사용됩니다. - reward_processing_classes (PreTrainedTokenizerBase 또는
list[PreTrainedTokenizerBase], 선택 사항) — 에 지정된 보상 함수에 해당하는 처리 클래스reward_funcs. 다음 중 하나일 수 있습니다:reward_funcs에 보상 함수가 하나만 포함된 경우: 단일 처리 클래스가 사용됩니다.- 처리 클래스 목록:
reward_funcs의 보상 함수 순서와 길이에 일치해야 합니다.None으로 설정하거나, PreTrainedModel에 해당하는 목록 요소가None인 경우, from_pretrained를 사용하여 해당 모델의 토크나이저가 자동으로 로드됩니다.reward_funcs의 요소 중 커스텀 보상 함수(PreTrainedModel이 아닌 경우)에 해당하는reward_processing_classes항목은 무시됩니다.
- callbacks (의 목록 TrainerCallback, 선택 사항) —
학습 루프를 사용자 정의할 콜백 목록입니다. 여기.
기본으로 사용되는 콜백 중 하나를 제거하려면 remove_callback 메서드를 사용하세요.
- optimizers (
tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], 선택 사항, 기본값(None, None)) — 사용할 옵티마이저와 스케줄러를 포함하는 튜플입니다. 기본적으로 모델에AdamW인스턴스와args에 의해 제어되는 get_linear_schedule_with_warmup로 생성된 스케줄러를 사용합니다. - quantization_config (BitsAndBytesConfig, 선택 사항) —
모델 식별자로부터 모델을 로드할 때 사용되는 양자화 구성입니다. QLoRA 학습을 위해
peft_config와 함께 사용하세요. 모델이 이미 인스턴스화되어 있으면 무시됩니다. - peft_config (
PeftConfig, 선택 사항) — 모델을 래핑하는 데 사용되는 PEFT 구성입니다.None인 경우 모델은 래핑되지 않습니다. - tools (
Callable의 목록, 선택 사항) — 모델이 생성 과정에서 호출할 수 있는 콜러블 도구 함수(동기 또는 비동기)의 목록입니다. 각 도구는 적절히 타입 힌트가 지정된 인자와 반환 값을 가진 표준 Python 함수여야 하며, 목적, 인자, 반환 값을 설명하는 Google 스타일 docstring을 포함해야 합니다. 자세한 내용은 https://huggingface.co/docs/transformers/en/chat_extras#passing-tools를 참조하세요. 모델은 함수의 이름, 타입 힌트, docstring을 기반으로 호출 방법을 결정합니다. 모델의 chat template이 도구 사용을 지원하고 도구 호출을 위해 fine-tuning이 되었는지 확인하세요. - rollout_func (
RolloutFunc, 선택 사항) — 완성본을 생성하는 데 사용할 함수입니다. 현재 프로세스에 할당된 프롬프트 목록과 trainer 인스턴스를 인수로 받습니다."prompt_ids","completion_ids","logprobs"필드를 가진 dict를 반환해야 하며, 선택적으로"logprob_token_ids"(형상이"logprobs"와 동일)를 반환할 수 있습니다. 기타 필드는 reward 함수로 전달됩니다. 이 함수는 중복 없이 프로세스별 원시 프롬프트 슬라이스를 수신하며, 프롬프트당 올바른 수의 완성본을 반환하는 것이 책임입니다 (trainer의num_generations/num_generations_eval참조). 이 기능은 실험적이며 사전 통보 없이 언제든 변경되거나 제거될 수 있습니다. - environment_factory (
EnvironmentFactory또는dict[str, EnvironmentFactory], 선택 사항) — 환경 인스턴스를 생성하여 반환하는 호출 가능한 객체, 또는 환경 이름을 이러한 호출 가능한 객체로 매핑하는 사전입니다. 환경 클래스는 생성 중에 도구로 호출될 수 있는 메서드를 정의해야 합니다. 각 메서드는 위에서 설명한tools의 동일한 요구 사항을 충족해야 합니다. 환경은 또한 생성 사이에 상태를 초기화하는 데 사용할 수 있는 호출 가능한reset메서드를 구현해야 합니다.reset메서드는None또는 문자열을 반환해야 합니다. 문자열을 반환하는 경우, 해당 문자열은 생성 전에 마지막 사용자 메시지에 추가됩니다. 환경은 인자를 받지 않고get_reward를 반환하는float: 메서드를 정의할 수도 있습니다. 이 메서드가 존재하면 환경이 보상을 소유하게 되고,get_reward는 완료된 롤아웃마다 한 번씩 호출되어 환경의 내부 상태로부터 점수를 매깁니다. 이는 환경의 클래스 이름으로 기록되는 가중치 1의 추가 보상 소스로 작용하며, 동시에 다음 메서드는 선택 사항이 됩니다. 단일 호출 가능한 객체를 사용하는 경우 모든 예제는 동일한 환경을 사용하며, 롤아웃당 하나의 인스턴스가 생성되어 상호작용이 격리됩니다. 사전을 사용하는 경우 각 예제는 환경 필드를 통해 이름을 지정하여 환경을 선택해야 하며, 해당 환경의 도구만 프롬프트에 노출됩니다. 이를 통해 단일 실행에서 여러 작업을 혼합할 수 있습니다(예: 코딩 환경과 게임). 이 기능은 실험적이며 사전 통보 없이 언제든 변경되거나 제거될 수 있습니다.reward_funcs, 이 선택 사항이 됩니다.단일 callable을 사용하는 경우, 모든 예제는 동일한 환경을 사용하며 rollout당 하나의 인스턴스가 생성되어 상호작용이 격리됩니다. 딕셔너리를 사용하는 경우, 각 예제는
environment필드를 통해 이름을 지정하여 환경을 선택해야 하며, 해당 환경의 도구만 프롬프트에 노출됩니다. 이를 통해 단일 실행에서 여러 작업을 혼합할 수 있습니다(예: 코딩 환경과 게임). 이 기능은 실험적이며 사전 통보 없이 언제든 변경되거나 제거될 수 있습니다.
Group Relative Policy Optimization(GRPO) 방법의 Trainer입니다. 이 알고리즘은 DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models 논문에서 처음 제안되었습니다.
예:
>>> from trl import GRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset
>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
>>> trainer = GRPOTrainer(
... model="Qwen/Qwen2.5-0.5B-Instruct",
... reward_funcs=accuracy_reward,
... train_dataset=dataset,
... )
>>> trainer.train()train
< source >( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput
매개변수
- resume_from_checkpoint (
str또는bool, 선택 사항) —str인 경우, 이전Trainer인스턴스가 저장한 체크포인트의 로컬 경로입니다.bool이고True와 같으면, 이전Trainer인스턴스가 args.output_dir에 저장한 마지막 체크포인트를 로드합니다. 이 값이 지정되어 있으면, 여기서 로드된 모델/옵티마이저/스케줄러 상태로부터 학습이 재개됩니다. - trial (
optuna.Trial또는dict[str, Any], 선택 사항) — 하이퍼파라미터 탐색을 위한 트라이얼 실행 또는 하이퍼파라미터 사전입니다. - ignore_keys_for_eval (
list[str], 선택 사항) — 모델의 출력(사전에 해당하는 경우)에서 학습 중 평가 예측을 수집할 때 무시해야 할 키의 목록입니다.
반환값
~trainer_utils.TrainOutput
전체 스텝 수, 학습 손실, 메트릭을 포함하는 객체.
주요 학습 진입점.
모델을 저장하므로 from_pretrained()를 사용하여 다시 로드할 수 있습니다.
main 프로세스에서만 저장합니다.
push_to_hub
< source >( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )
매개변수
- commit_message (
str, 선택 사항, 기본값"End of training") — 푸시할 때 커밋할 메시지입니다. - blocking (
bool, 선택 사항, 기본값True) —git push가 완료된 후에만 함수가 반환되어야 하는지 여부. - token (
str, 선택 사항, 기본값None) — Trainer의 원래 args를 덮어쓸 수 있는 쓰기 권한이 있는 토큰. - revision (
str, 선택 사항) — 커밋할 git revision입니다. 기본값은 “main” 브랜치의 head입니다. - private (
bool, 선택 사항) — 리포지토리가 생성될 때 비공개로 만들지 여부입니다. 기본값은args.hub_private_repo입니다. 리포지토리가 이미 존재하는 경우 효과가 없습니다. - kwargs (
dict[str, Any], 선택) —~Trainer.create_model_card에 함께 전달되는 추가 키워드 인자입니다.
self.args.hub_model_id 저장소에 self.model과 self.processing_class를 🤗 모델 허브에 업로드합니다.
GRPOConfig
클래스 trl.GRPOConfig
< source >( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool = Truegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 10logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool | None = Falselabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonetrust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonedisable_dropout: bool = Falsecast_lm_head_to_fp32: bool = Falsenum_generations: int | None = 8num_generations_eval: int | None = Nonemax_completion_length: int | None = 512ds3_gather_for_generation: bool = Trueshuffle_dataset: bool | None = Truepad_to_multiple_of: int | str | None = 'auto'generation_batch_size: int | None = Nonesteps_per_generation: int | None = Nonetemperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonegeneration_kwargs: dict | str | None = Nonechat_template_kwargs: dict | str | None = Nonerepetition_penalty: float = 1.0cache_implementation: str | None = Noneuse_vllm: bool = Falsevllm_mode: str = 'colocate'vllm_model_impl: str = 'vllm'vllm_enable_sleep_mode: bool = Falsevllm_structured_outputs_regex: str | None = Nonevllm_server_base_url: str | None = Nonevllm_server_host: str = '0.0.0.0'vllm_server_port: int = 8000vllm_server_timeout: float = 240.0vllm_group_port: int = 51216vllm_gpu_memory_utilization: float = 0.3vllm_max_model_length: int | None = Nonevllm_tensor_parallel_size: int = 1beta: float = 0.0num_iterations: int = 1epsilon: float = 0.2delta: float | None = Noneepsilon_high: float | None = Nonesapo_temperature_neg: float = 1.05sapo_temperature_pos: float = 1.0vespo_k_pos: float = 2.0vespo_lambda_pos: float = 3.0vespo_k_neg: float = 3.0vespo_lambda_neg: float = 2.0importance_sampling_level: str = 'token'reward_weights: list[float] | None = Nonemulti_objective_aggregation: str = 'sum_then_normalize'scale_rewards: str = 'group'loss_type: str = 'dapo'mask_truncated_completions: bool = Falsesync_ref_model: bool = Falseref_model_mixup_alpha: float = 0.6ref_model_sync_steps: int = 512top_entropy_quantile: float = 1.0entropy_coef: float = 0.0use_adaptive_entropy: bool = Falseentropy_coef_min: float = 0.0entropy_coef_max: float = 1.0entropy_coef_delta: float = 0.005entropy_target: float = 0.2max_tool_calling_iterations: int | None = Nonevllm_importance_sampling_correction: bool = Truevllm_importance_sampling_mode: str = 'sequence_mask'vllm_importance_sampling_clip_max: float | None = 3.0vllm_importance_sampling_clip_min: float | None = Noneoff_policy_mask_threshold: float | None = Noneuse_bias_correction_kl: bool = Truelog_completions: bool = Falselog_multimodal: bool = Truenum_completions_to_print: int | None = Nonelog_unique_prompts: bool = Falselog_completions_hub_repo: str | None = Noneuse_transformers_continuous_batching: bool = Falsetransformers_continuous_batching_config: dict | str | None = Noneuse_transformers_paged: bool = Falsevllm_importance_sampling_cap: float | None = None )
모델과 참조 모델을 제어하는 매개변수
- model_init_kwargs (
str또는dict[str, Any], 선택 사항) —model인수가 GRPOTrainer에 문자열로 제공될 때 from_pretrained에 사용되는 키워드 인수입니다.revision값은 처리 클래스를 로드할 때에도 사용됩니다. - trust_remote_code (
bool, optional, defaults toFalse) — Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to from_pretrained and from_pretrained. Also applied to reward-model and reward-tokenizer loads. - router_aux_loss_coef (
float, 선택 사항) — Mixture-of-Experts(MoE) 모델의 로드 밸런싱 보조 손실 계수로, 이 가중치로 학습 손실에 추가됩니다. 설정되지 않으면 모델 구성에서 선언된 값이 사용됩니다. 비활성화하려면0.0으로 설정하세요. MoE가 아닌 모델과 함께 사용하면 실패합니다. - disable_dropout (
bool, 선택 사항, 기본값False) — 모델에서 dropout을 비활성화할지 여부입니다. 이는 참조 모델과 함께 학습할 때 유용하며, 동일한 입력에 대해 모델이 서로 다른 logprobs를 생성하는 것을 방지합니다. - cast_lm_head_to_fp32 (
bool, 선택 사항, 기본값False) — 정책 모델 및 참조 모델의 언어 모델링 헤드를 float32로 캐스팅할지 여부입니다. ScaleRL 레시피에서 권장하는 방식입니다. 이 플래그는 모델의 단어 임베딩과 언어 모델링 헤드 레이어가 연결되지 않은 경우, 즉 모델 구성에서tie_word_embeddings가 False인 경우에만 지원됩니다.
데이터 전처리를 제어하는 매개변수
- remove_unused_columns (
bool, 선택 사항, 기본값False) — 데이터셋에서"prompt"컬럼만 유지할지 여부입니다."prompts"와"completions"이외의 컬럼이 필요한 사용자 정의 보상 함수를 사용하는 경우, 이 값을False로 유지해야 합니다. - num_generations (
int, 선택 사항, 기본값은8) — 프롬프트당 샘플링할 생성 횟수. 유효 배치 크기(num_processes * per_device_batch_size- gradient_accumulation_steps)은 이 값으로 나누어 떨어져야 합니다.
- num_generations_eval (
int, 선택 사항) — 평가 중에 샘플링할 생성 횟수입니다. 이를 통해 평가 시 생성 횟수를 줄여 계산 비용을 절약할 수 있습니다.None인 경우num_generations의 값을 사용합니다. - max_completion_length (
int또는None, 선택 사항, 기본값512) — 생성된 completion의 최대 길이입니다. - ds3_gather_for_generation (
bool, 선택 사항, 기본값True) — 이 설정은 DeepSpeed ZeRO-3에 적용됩니다. 활성화하면 정책 모델 가중치가 생성을 위해 수집되어 생성 속도가 향상됩니다. 그러나 이 옵션을 비활성화하면 단일 GPU의 VRAM 용량을 초과하는 모델을 학습할 수 있지만, 생성 속도가 느려집니다. 이 옵션을 비활성화하면 vLLM 생성과 호환되지 않습니다. - shuffle_dataset (
bool, 선택 사항, 기본값True) — 학습 데이터셋을 섞을지 여부입니다. - pad_to_multiple_of (
int또는str, 선택 사항, 기본값"auto") — 설정된 경우, 프롬프트 ID와 완성문 ID는 이 값의 배수로 패딩됩니다."auto"는 Neuron(AWS Trainium)에서 입력 형식별로 한 번만 컴파일되도록 128의 배수로 패딩하며, 다른 환경에서는 패딩하지 않습니다.
생성을 제어하는 매개변수
- generation_batch_size (
int, 선택 사항) — 생성에 사용할 배치 크기입니다.None인 경우, 실제 학습 배치 크기인per_device_train_batch_size * num_processes * steps_per_generation가 기본값으로 사용됩니다. 즉, 최적화 단계마다 하나의 생성 배치만 처리됩니다.steps_per_generation와 상호 배타적입니다. - steps_per_generation (
int, 선택 사항) — 생성당히 스텝 수입니다.None인 경우 기본값은gradient_accumulation_steps입니다.generation_batch_size와 상호 배타적입니다. - temperature (
float, 선택 사항, 기본값1.0) — 샘플링에 사용할 온도입니다. 온도가 높을수록 완성 결과가 더 무작위적으로 생성됩니다. - top_p (
float, 선택 사항, 기본값1.0) — 고려할 상위 토큰의 누적 확률을 제어하는 값입니다. 값은 (0, 1] 범위에 있어야 합니다. 모든 토큰을 고려하려면1.0으로 설정하세요. - top_k (
int, 선택 사항, 기본값0) — top-k-filtering을 위해 유지할 가장 높은 확률의 어휘 토큰 수입니다.0인 경우 top-k-filtering이 비활성화되고 모든 토큰이 고려됩니다. - min_p (
float, 선택 사항) — 최대 확률을 가진 토큰의 확률로 스케일링되는 최소 토큰 확률입니다.0.0과1.0사이의 값이어야 합니다. 일반적인 값은0.01-0.2범위입니다. - generation_kwargs (
dict[str, Any], 선택 사항) — completions 샘플링 시 GenerationConfig(transformers 사용 시) 또는SamplingParams(vLLM 사용 시)에 전달할 추가 키워드 인자입니다.suppress_tokens,num_beams등을 설정하여 생성 동작을 더 자세히 커스터마이징하는 데 사용할 수 있습니다. 다른 생성 매개변수(예:min_p,top_p등)와 충돌하는 키가 포함된 경우, 해당 키가 우선 적용됩니다. - chat_template_kwargs (
dict[str, Any], 선택) — 완성 결과를 생성할 때apply_chat_template함수에 전달할 추가 키워드 인자입니다. - repetition_penalty (
float, 선택 사항, 기본값1.0) — 프롬프트와 지금까지 생성된 텍스트에 해당 토큰이 등장했는지에 따라 새로운 토큰에 페널티를 부과하는 값입니다.1.0보다 큰 값은 모델이 새로운 토큰을 사용하도록 장려하고,1.0보다 작은 값은 모델이 토큰을 반복하도록 장려합니다. - cache_implementation (
str, 선택 사항) —use_vllm이False로 설정된 경우 더 빠른 생성을 위한 캐시 메서드 구현입니다.
vLLM 기반 생성 가속을 제어하는 매개변수
- use_vllm (
bool, 선택 사항, 기본값False) — 완성 결과를 생성하는 데 vLLM을 사용할지 여부입니다.True로 설정하면 트레이너는 기본인 model.generate() 대신 vLLM을 사용하여 생성을 수행합니다.vllm이 설치되어 있어야 합니다. - vllm_mode (
str, 선택 사항, 기본값은"colocate") — 일 때 vLLM 통합에 사용할 모드use_vllm로 설정되어True. 다음 중 하나여야 합니다"server"또는"colocate"."server": 트레이너가 별도의 vLLM 서버로 생성 요청을 보냅니다. vLLM 서버가 실행 중인지 확인하세요(vllm serve로 시작)."colocate": vLLM이 동일한 프로세스에서 실행되며 학습 GPU를 공유합니다. 별도의 서버가 필요 없지만 학습과 리소스 경쟁이 발생할 수 있습니다.
- vllm_model_impl (
str, 선택 사항, 기본값"vllm") — vLLM에 사용할 모델 구현입니다."transformers"또는"vllm"중 하나여야 합니다."transformers": 모델 구현에transformers백엔드를 사용합니다."vllm": 모델 구현에vllm라이브러리를 사용합니다. - vllm_enable_sleep_mode (
bool, 선택 사항, 기본값False) — 옵티마이저 단계에서 가중치/캐시를 오프로드하기 위해 vLLM sleep mode를 활성화합니다. GPU 메모리 사용량을 낮게 유지하지만, 엔진을 깨울 때 호스트-디바이스 전송 지연이 발생합니다. - vllm_structured_outputs_regex (
str, 선택 사항) — vLLM 구조화 출력을 위한 정규식입니다.None(기본값)인 경우 구조화 출력이 비활성화됩니다.
vLLM 서버를 제어하는 매개변수(`vllm_mode`가 `"server"`인 경우에만 사용)
- vllm_server_base_url (
str, 선택 사항) — vLLM 서버의 기본 URL(예:"http://localhost:8000"). 지정된 경우vllm_server_host및vllm_server_port는 무시됩니다. - vllm_server_host (
str, 선택 사항, 기본값"0.0.0.0") — 연결할 vLLM 서버의 호스트입니다.vllm_server_base_url이 제공된 경우 무시됩니다. - vllm_server_port (
int, 선택 사항, 기본값8000) — 연결할 vLLM 서버의 포트입니다.vllm_server_base_url이 제공된 경우 무시됩니다. - vllm_server_timeout (
float, 선택 사항, 기본값240.0) — vLLM 서버가 실행될 때까지 대기할 총 시간(초). 시간 초과 후에도 서버가 실행되지 않으면ConnectionError가 발생합니다. - vllm_group_port (
int, 선택 사항, 기본값51216) — 가중치 업데이트 그룹에 사용할 포트 번호입니다. vLLM 서버와 통신하는 데 사용됩니다. 포트가 사용 중이 아니라면 변경할 필요가 없습니다.
colocate된 vLLM 실행을 제어하는 매개변수(`vllm_mode`가 `"colocate"`인 경우에만 사용)
- vllm_gpu_memory_utilization (
float, 선택 사항, 기본값0.3) — vLLM의 GPU 메모리 사용률을 제어합니다. 이 설정은vllm_mode가"colocate"로 설정된 경우에만 적용됩니다.vllm_mode="server"를 사용하는 경우, 이 매개변수는--vllm_gpu_memory_utilization플래그를 통해 vLLM 서버를 시작할 때 별도로 전달해야 합니다. - vllm_max_model_length (
int, 선택 사항) — vLLM의 컨텍스트 윈도우입니다. 데이터셋의 최대 프롬프트 길이보다max_completion_length를 더한 값 이상으로 설정해야 하며, 생략하면 모델 구성에서 추론됩니다. - vllm_tensor_parallel_size (
int, 선택 사항, 기본값1) — vLLM의 tensor parallel size를 제어합니다. 이 설정은vllm_mode가"colocate"로 설정된 경우에만 적용됩니다.vllm_mode="server"를 사용하는 경우, 이 매개변수는--vllm_tensor_parallel_size플래그를 통해 vLLM 서버를 시작할 때 별도로 전달해야 합니다.
학습을 제어하는 매개변수
- beta (
float, 선택 사항, 기본값0.0) — KL 계수입니다.0.0(기본값)인 경우 참조 모델이 로드되지 않아 메모리 사용량이 줄고 학습 속도가 향상됩니다. DeepSeek-R1 incentivizes reasoning in LLMs through reinforcement learning에서는0.001값을 사용합니다. - num_iterations (
int, 선택 사항, 기본값1) — 배치당 반복 횟수(알고리즘에서 μ로 표기됨). - epsilon (
float, 선택 사항, 기본값0.2) — 클리핑에 사용되는 Epsilon 값입니다. - delta (
float, 선택 사항) — float로 설정하면 양방향 GRPO 손실의 상단 클리핑 한도를 활성화합니다.None(기본값)인 경우 표준 GRPO 클리핑이 사용됩니다. 활성화할 경우1 + ε보다 큰 값으로 설정하는 것이 권장됩니다. 이 메서드는 INTELLECT-2 기술 보고서에서 소개되었습니다. - epsilon_high (
float, 선택 사항) — 클리핑을 위한 상한 epsilon 값입니다. 지정하지 않으면epsilon인수로 지정된 하한 값과 동일한 값이 기본값으로 사용됩니다. DAPO 논문에서는0.28을 권장합니다.loss_type='cispo'와 함께 사용할 경우, 이는 ScaleRL 논문에서 지정된 ε_max 매개변수에 해당하며, 권장 값인5.0이 기본값으로 사용됩니다. - sapo_temperature_neg (
float, 선택 사항, 기본값1.05) —sapo손실 함수에서 양의 이점이 아닌(비양수) 점수를 가진 토큰에 사용되는 온도입니다. 이 매개변수는 Soft Adaptive Policy Optimization 논문에서 도입되었습니다. - sapo_temperature_pos (
float, 선택 사항, 기본값1.0) —sapo손실 함수에서 양의 이점 점수를 가진 토큰에 사용되는 온도입니다. 이 매개변수는 Soft Adaptive Policy Optimization 논문에서 도입되었습니다. - vespo_k_pos (
float, 선택 사항, 기본값2.0) — 긍정적 이점(advantage)에 대한 k 파라미터로, VESPO 손실 함수의 거듭제곱 지수입니다. 중요도 가중치가 낮은 샘플(중요도 샘플링 비율 < 1)의 가중치를 얼마나 공격적으로 낮출지를 제어합니다. - vespo_lambda_pos (
float, 선택 사항, 기본값3.0) — 긍정적 이점(positive advantages)에 대한 lambda 매개변수이며, VESPO 손실 함수에서 감쇠 계수(decay factor) 역할을 합니다. 중요도(importance) 가중치가 높은 샘플(즉, 중요도 샘플링 비율(importance sampling ratio)이 1보다 큰 경우)의 가중치를 얼마나 공격적으로 낮출지를 제어합니다. - vespo_k_neg (
float, 선택 사항, 기본값3.0) — 부정 이점(negative advantages)에 대한 k 파라미터로, VESPO 손실 함수의 거듭제곱 지수입니다. 중요도 가중치가 낮은 샘플(중요도 샘플링 비율 < 1)의 가중치를 얼마나 공격적으로 낮출지를 제어합니다. - vespo_lambda_neg (
float, 선택 사항, 기본값2.0) — 부정적 이점(advantage)에 대한 lambda 매개변수이며, VESPO 손실 함수에서 지수 감쇠 인자입니다. 중요도 샘플링 비율이 1보다 큰 경우, 높은 중요도 가중치를 가진 샘플의 가중치를 얼마나 공격적으로 낮출지를 제어합니다. - importance_sampling_level (
str, 선택 사항, 기본값"token") — importance sampling 비율이"token"수준인지"sequence"수준인지 계산할지를 제어합니다."token"은 토큰별 원시 log-probability 비율(토큰당 하나의 가중치)을 유지합니다."sequence"는 유효한 토큰에 걸쳐 log-probability 비율을 평균화하여 시퀀스당 하나의 비율을 생성합니다. GSPO 논문에서는 시퀀스 수준 샘플링이 종종 더 안정적인 학습과 시퀀스 수준 보상과의 더 나은 정렬을 제공한다고 보여줍니다. - reward_weights (
list[float], 선택 사항) — 각 보상 함수에 대한 가중치입니다. 보상 함수의 수와 일치해야 합니다.None인 경우, 모든 보상은1.0의 동일한 가중치로 적용됩니다. - multi_objective_aggregation (
str, 선택 사항, 기본값은"sum_then_normalize") — 여러 보상 함수를 집계하는 방법. 지원되는 값은 다음과 같습니다:"sum_then_normalize"(기본값): 각 보상 함수의 가중 보상을 먼저 합산한 다음,scale_rewards에 지정된 대로 보상 스케일링/정규화를 적용합니다(자세한 내용은scale_rewards를 참조)."normalize_then_sum": 먼저 각 세대(그룹) 내에서 각 보상 함수를 정규화/스케일링한 다음, 지정된 가중치를 사용하여 정규화된 보상을 합산합니다. 이후 이산에서 이점을 형성할 때 배치 수준에서 집계된 보상이 정규화됩니다. 이는 논문 GDPO: Group reward-Decoupled Normalization Policy Optimization for Multi-reward RL Optimization에서 제안하는 방법입니다.
- scale_rewards (
str또는bool, 선택 사항, 기본값은"group") — 보상(reward)의 스케일링 전략을 지정합니다. 지원되는 값은 다음과 같습니다:True또는"group"(기본값): 보상은 각 그룹 내의 표준편차로 스케일링되어 그룹 내 단위 분산을 보장합니다."batch": PPO Lite 논문에서 권장하듯, 전체 배치의 표준편차로 보상이 스케일링됩니다.False또는"none": 스케일링이 적용되지 않습니다. Dr. GRPO 논문에서는 표준편차로 스케일링하면 문제 수준의 난이도 편향이 발생하므로, 보상을 스케일링하지 않는 것을 권장합니다.
- loss_type (
str, 선택 사항, 기본값은"dapo") — 사용할 손실 함수를 지정합니다. 지원되는 값은 다음과 같습니다: "grpo": 시퀀스 길이를 기준으로 정규화하여 토큰 수준 손실을 집계합니다. 길이 편향 때문에 권장하지 않습니다. 이 방식은 양의 이점을 가진 짧은 완성 결과와 음의 이점을 가진 긴 완성 결과를 선호하는 경향이 있습니다. "dr_grpo": 전역 상수를 사용하여 정규화하여 토큰 수준 손실을 집계합니다. 이 방법은 Dr. GRPO 논문에서 길이 편향을 제거하기 위해 도입되었습니다. 상수의 값은 max_completion_length에 해당합니다. "dapo" (기본값): 전역 누적 배치의 활성 토큰 수를 기준으로 정규화하여 토큰 수준 손실을 집계합니다. 이 방법은 DAPO 논문에서 길이 편향을 제거하기 위해 도입되었습니다. "bnpo": 로컬 배치의 활성 토큰 수를 기준으로 정규화하여 토큰 수준 손실을 집계합니다. 정규화가 로컬 배치에서만 수행되므로, 유효 배치 크기가 일정하더라도 로컬 배치 크기에 따라 결과가 약간 달라질 수 있습니다. per_device_train_batch_size==1을 사용할 경우, 손실은 GRPO 손실과 동일합니다. "cispo": 이점 스케일링된 중요도 가중치가 아닌 중요도 샘플링 가중치를 클리핑합니다. 클리핑된 가중치는 이점 및 정책 모델의 로그 확률과 곱해집니다. 개별 토큰 손실은 전역 누적 배치의 활성 토큰 수를 기준으로 정규화하여 집계됩니다. 이 방법은 MiniMax-M1 논문에서 도입되었습니다. "sapo": Soft Adaptive Policy Optimization 논문에서 도입된 Soft Adaptive Policy Optimization 손실입니다. 하드 클리핑을 부드러운 온도 제어 게이트로 대체하여 오프-폴리시 업데이트를 적응적으로 감쇠하면서 유용한 학습 신호를 유지합니다. "luspo": Length-Unbiased Sequence Policy Optimization 손실입니다. 각 시퀀스의 손실을 그 길이에 따라 스케일링하는 시퀀스 수준 손실입니다. 이는 GSPO의 변형이며 importance_sampling_level="sequence"가 필요합니다. LUSPO 논문에서 도입되었습니다. "vespo": Variational Sequence-Level Soft Policy Optimization입니다. 하드 클리핑을 시퀀스 수준 중요도 가중치에 직접 적용되는 부드럽고 비대칭적인 Gamma 가중 함수로 대체합니다. VESPO 논문에서 도입되었습니다."grpo": 시퀀스 길이를 기준으로 정규화하여 토큰 수준의 손실을 집계합니다. 길이 편향 때문에 권장하지 않습니다. 이 방식은 양의 이점을 가진 짧은 완성본과 음의 이점을 가진 긴 완성본을 선호하는 경향이 있습니다."dr_grpo": 전역 상수로 정규화하여 토큰 수준의 손실을 집계합니다. 이 방법은 Dr. GRPO 논문에서 길이 편향을 제거하기 위해 도입되었습니다. 상수의 값은max_completion_length에 해당합니다."dapo"(기본값): 전역 누적 배치의 활성 토큰 수로 정규화하여 토큰 수준의 손실을 집계합니다. 이 방법은 DAPO 논문에서 길이 편향을 제거하기 위해 도입되었습니다."bnpo": 로컬 배치의 활성 토큰 수로 정규화하여 토큰 수준의 손실을 집계합니다. 정규화는 로컬 배치에서만 수행되므로, 유효 배치 크기가 일정하더라도 로컬 배치 크기에 따라 결과가 약간 달라질 수 있습니다.per_device_train_batch_size==1을 사용할 경우, 손실은 GRPO 손실과 동일합니다."cispo": 이점 스케일링된 중요도 샘플링 가중치가 아닌 중요도 샘플링 가중치를 클리핑합니다. 클리핑된 가중치는 이점 및 정책 모델의 로그 확률과 곱해집니다. 개별 토큰 손실은 전역 누적 배치의 활성 토큰 수로 정규화하여 집계됩니다. 이 방법은 MiniMax-M1 논문에서 소개되었습니다."sapo": Soft Adaptive Policy Optimization 논문에서 소개된 Soft Adaptive Policy Optimization 손실입니다. 하드 클리핑을 부드러운 온도 제어 게이트로 대체하여 오프폴리시 업데이트를 적응적으로 감쇠시키면서도 유용한 학습 신호를 보존합니다."luspo": Length-Unbiased Sequence Policy Optimization 손실. 각 시퀀스의 길이에 따라 해당 시퀀스의 손실을 스케일링하는 시퀀스 레벨 손실입니다. 이는 GSPO의 변형이며importance_sampling_level="sequence"가 필요합니다. LUSPO 논문에서 소개되었습니다."vespo": Variational Sequence-Level Soft Policy Optimization. 하드 클리핑을 제거하고, 시퀀스 레벨 중요도 가중치에 직접 적용되는 매끄럽고 비대칭적인 Gamma 가중 함수를 사용합니다. VESPO 논문에서 소개되었습니다.
- mask_truncated_completions (
bool, 선택 사항, 기본값False) — 활성화하면 잘린(completed) 응답이 손실 계산에서 제외되어, 학습 과정에서 잘못 페널티를 받거나 노이즈가 도입되는 것을 방지합니다. DAPO 논문에 따르면 이는 학습 안정성을 위한 좋은 관행입니다. - sync_ref_model (
bool, 선택 사항, 기본값False) —ref_model_mixup_alpha매개변수를 사용하여ref_model_sync_steps스텝마다 참조 모델을 활성 모델과 동기화할지 여부입니다. 이 동기화 방식은 TR-DPO 논문에서 유래했습니다. - ref_model_mixup_alpha (
float, 선택 사항, 기본값0.6) — TR-DPO 논문에서 가져온 α 매개변수로, 업데이트 과정에서 현재 정책과 이전 참조 정책 간의 혼합을 제어합니다. 참조 정책은 다음 방정식에 따라 업데이트됩니다:π_ref = α * π_θ + (1 - α) * π_ref_prev. 이 매개변수를 사용하려면sync_ref_model=True를 설정해야 합니다. - ref_model_sync_steps (
int, 선택 사항, 기본값512) — TR-DPO 논문에서 제시한 τ 파라미터로, 현재 정책이 참조 정책과 얼마나 자주 동기화되는지를 결정합니다. 이 파라미터를 사용하려면sync_ref_model=True를 설정해야 합니다. - top_entropy_quantile (
float, 선택 사항, 기본값1.0) — Beyond the 80/20 Rule의 ρ 매개변수입니다. 각 시퀀스 위치에서 확률 분포의 엔트로피 기준으로 상위 ρ 분위에 해당하는 토큰만 정책 손실 항에 유지하여 결과를 개선합니다. 범위:[0.0-1.0].0.0이면 엔트로피가 가장 높은 토큰을 제외한 모든 토큰이 마스킹되고,1.0이면 모든 토큰이 유지됩니다. 해당 논문에서는0.2값을 권장합니다.mask_truncated_completions=True와 함께 사용하는 경우, 잘리지 않은 completion의 토큰만 고려됩니다. - entropy_coef (
float, 선택 사항, 기본값0.0) — 손실 함수에서 엔트로피 정규화 항의 계수입니다. 양의 값은 엔트로피 보너스를 추가하여 정책이 거의 결정론적인 출력으로 수렴하는 것을 방지하고 탐색을 장려합니다. 보너스는loss_type와 관계없이 항상 토큰당 평균 엔트로피이며, 손실 유형의 정책 정규화에 맞게 재조정되지 않으므로entropy_coef는 모든 손실 유형에서 동일한 의미를 가집니다.use_adaptive_entropy=True인 경우, 이 값은 초기 계수로 사용되며 각 옵티마이저 단계마다 업데이트됩니다.0.0(기본값)으로 설정하면 효과가 없습니다. - use_adaptive_entropy (
bool, 선택 사항, 기본값False) — Skywork-OR1에서 도입된 적응형 엔트로피 제어를 사용할지 여부입니다. 활성화되면 엔트로피 계수entropy_coef가 각 옵티마이저 단계마다 업데이트됩니다. 현재 엔트로피가entropy_target보다 낮으면entropy_coef_delta만큼 증가하고, 그렇지 않으면 감소합니다. 이 계수는 엔트로피가entropy_target이하일 때만 적용됩니다. - entropy_coef_min (
float, 선택 사항, 기본값0.0) — 적응형 엔트로피 제어를 사용할 때 엔트로피 계수의 하한입니다. - entropy_coef_max (
float, 선택 사항, 기본값1.0) — 적응형 엔트로피 제어를 사용할 때 엔트로피 계수의 상한값입니다. - entropy_coef_delta (
float, 선택 사항, 기본값0.005) — 적응형 엔트로피 제어 과정에서 각 옵티마이저 스텝마다 엔트로피 계수를 조정할 때 사용하는 스텝 크기입니다. - entropy_target (
float, 선택 사항, 기본값0.2) — 적응형 엔트로피 제어에 사용되는 목표 평균 토큰당 엔트로피(nats 단위)입니다. 현재 엔트로피가 이 값 이하일 때만 계수가 적용됩니다. 정책 손실과 동일한 토큰 집합에서 측정되며, 기본적으로 모든 completion 토큰을 대상으로 하거나top_entropy_quantile < 1.0인 경우 고엔트로피 부분 집합만 대상으로 합니다. 일반적인 언어 모델의 토큰당 엔트로피는 2–10 nats 범위에 있으므로, 기본값0.2는 거의 정규화를 트리거하지 않습니다(엔트로피가 거의 완전히 붕괴된 경우에만). 보너스가 정책 붕괴 전에 발동되도록 학습 초기에 관찰되는 엔트로피(entropy메트릭으로 기록됨)에 가깝게 설정하고,top_entropy_quantile을 사용하는 경우 토큰 부분 집합을 고려하세요. - max_tool_calling_iterations (
int, 선택 사항) — 에이전트를 학습할 때 허용되는 최대 도구 호출 턴 수입니다.None인 경우 제한이 없으며, 모델이 도구 호출이 없는 응답 턴을 생성하거나, 완성물(모든 턴 및 도구 결과)이max_completion_length토큰에 도달하거나, 전체 시퀀스가 모델의 최대 길이(vllm_mode="colocate"인 경우vllm_max_model_length, 그 외에는 모델의max_position_embeddings)에 도달하면 생성이 중단됩니다. - vllm_importance_sampling_correction (
bool, optional, defaults toTrue) — Whether to apply Importance Sampling (IS) to correct for the mismatch between vLLM completion logprobs and recomputed training logprobs. If set toFalse, no IS is applied regardless ofvllm_importance_sampling_mode. WhenTrue, the selected mode determines how the IS ratios are computed and constrained. Withtop_p < 1,top_k > 0ormin_p > 0, the recomputed logprobs are normalized over the candidate set each token was sampled from, which requires vLLM 0.28 or later and, in server mode, a server started with--return-sampling-mask(and--enable-scale-outfrom vLLM 0.30); otherwise, the IS ratios are biased. vLLM bounds that candidate set withtop_k, sotop_p < 1,min_p > 0and structured outputs, which restrict it to the tokens the grammar allows, requiretop_k > 0(e.g.top_k=512). Structured outputs, which would otherwise stall training, also require that candidate set. vLLM also appliesrepetition_penaltyto the logprobs it returns, sorepetition_penalty != 1.0requiresvllm_importance_sampling_correction=False. - vllm_importance_sampling_mode (
str, 선택 사항, 기본값은"sequence_mask") — 가vllm_importance_sampling_correction=True. 인 경우 Importance Sampling이 수행되는 방식을 지정합니다. 가능한 값은 다음과 같습니다:"token_truncate": 토큰 레벨의 잘림 IS. 토큰별 비율이 [C_min, C_max]로 잘립니다."token_mask": 토큰 레벨의 마스킹된 IS. [C_min, C_max] 범위를 벗어난 토큰별 비율은 0으로 설정됩니다."sequence_truncate": 시퀀스 레벨의 잘림된 IS. 단일 시퀀스 비율을 [C_min, C_max]로 클리핑하여 해당 시퀀스의 모든 토큰에 적용합니다."sequence_mask": 시퀀스 레벨의 마스킹된 IS. 비율이 [C_min, C_max] 범위를 벗어나는 시퀀스는 마스킹됩니다.
- vllm_importance_sampling_clip_max (
float, 선택 사항, 기본값3.0) —vllm_importance_sampling_mode에서 사용되는 Importance sampling 상한 C_max입니다.*_truncate모드에서는 importance ratio가 C_max에서 상한으로 클립됩니다.*_mask모드에서는 C_max보다 큰 ratio는 0으로 설정됩니다. - vllm_importance_sampling_clip_min (
float, 선택 사항) —vllm_importance_sampling_mode에서 사용되는 Importance sampling 하한 C_min입니다.*_truncate모드에서는 비율이 C_min에서 아래로 잘립니다.*_mask모드에서는 C_min보다 작은 비율이 0으로 설정됩니다. C_min보다 작은 비율을 상한 없이 엄격하게 마스킹하려면vllm_importance_sampling_clip_max=None으로 설정하세요. - off_policy_mask_threshold (
float, 선택 사항) — 오프 폴리시 시퀀스 마스킹에 사용되는 임계값입니다.None인 경우 오프 폴리시 시퀀스 마스킹이 비활성화됩니다. 값이 설정되면, 부정적인 이점(advantage)과 높은 KL 발산을 가진 시퀀스가 마스킹되어 학습이 안정화됩니다. 이 파라미터는 DeepSeek-V3.2 논문의 식 9에서delta임계값에 해당합니다. 양의 값(예: 0.5)을 기대합니다. - use_bias_correction_kl (
bool, 선택 사항, 기본값True) — KL 항에 중요도 샘플링 비율을 곱하여, DeepSeek-V3.2 논문에 설명된 대로 KL 기울기가 편향 없는 역 KL 기울기가 되도록 하는지 여부입니다.beta != 0인 경우, 온-폴리시(on-policy)를 포함하여 KL 기울기가 변경됩니다. 비율은 미분 가능하므로, 값이 정확히 1인 위치에서도 기울기에 영향을 미칩니다. 편향 없는 역 KL 특성은importance_sampling_level="token"일 때 성립하며,"sequence"인 경우 시퀀스 레벨 가중치가 토큰별 KL에 브로드캐스트됩니다.
로깅을 제어하는 매개변수
- log_completions (
bool, 선택 사항, 기본값False) —logging_steps단계마다 (prompt, completion) 쌍의 샘플을 기록할지 여부입니다.rich가 설치되어 있으면 샘플을 출력합니다.wandb및/또는trackio로깅이 활성화되어 있으면wandb및/또는trackio에 기록합니다. - log_multimodal (
bool, 선택 사항, 기본값True) — 완성 결과와 함께 멀티모달 콘텐츠(이미지, 비디오 등)를 기록할지 여부입니다. 고해상도 멀티모달 데이터를 사용할 때 로그 크기를 줄이려면 이 옵션을 비활성화하세요. - num_completions_to_print (
int, 선택 사항) —rich로 출력할 completions의 수입니다.None인 경우 모든 completions이 기록됩니다. - log_unique_prompts (
bool, 선택 사항, 기본값False) — 고유한 프롬프트만 기록할지 여부입니다.True인 경우 고유한 프롬프트만 기록되고,False인 경우 모든 프롬프트가 기록됩니다. - log_completions_hub_repo (
str, 선택 사항) — completions를 저장할 Hugging Face Hub 저장소입니다.'username/reponame'또는'orgname/reponame'와 같은 완전한 저장소 이름이거나,'reponame'만 지정할 수도 있으며 이 경우 현재 로그인된 Hugging Face 사용자의 네임스페이스에 저장소가 생성됩니다.hub_private_repo=True를 설정하거나 조직의 기본값이 비공개 저장소 생성으로 되어 있지 않는 한, 이 저장소는 공개됩니다.
transformers의 연속 배치 처리로 구동되는 생성 가속을 제어하는 매개변수
- use_transformers_continuous_batching (
bool, 선택 사항, 기본값False) — completions 생성에 transformers의 continuous batching 엔진을 사용할지 여부입니다.transformers>=5.8.0이 필요합니다. - transformers_continuous_batching_config (
dict, 선택 사항) —ContinuousBatchingConfig에 대한 키워드 인자입니다.
비추천되는 매개변수
GRPOTrainer의 설정 클래스입니다.
이 클래스에는 GRPO 학습에 특화된 매개변수만 포함되어 있습니다. 학습 인자의 전체 목록은 TrainingArguments 문서를 참고하세요. 이 클래스의 기본값은 TrainingArguments의 기본값과 다를 수 있습니다.
HfArgumentParser를 사용하면 이 클래스를 커맨드 라인에서 지정할 수 있는 argparse 인수로 변환할 수 있습니다.
이러한 파라미터는 TrainingArguments와 다른 기본값을 가집니다:
logging_steps: 기본값이500대신10입니다.gradient_checkpointing: 기본값이False가 아닌True입니다.bf16:fp16가 설정되지 않은 경우 기본값이False가 아닌True입니다.learning_rate: 기본값이5e-5대신1e-6입니다.