TRL documentation
Async Distillation
Async Distillation
이 trainer는
vllm,transformers>=5.2.0및kernels가 필요합니다(학습 시 이를 통해 Hub에서 FlashAttention을 로드합니다). 분산 학습의 경우 FSDP2만 지원되며(DeepSpeed ZeRO는 지원되지 않습니다).현재
vllm과transformers의 종속성 제약 조건이 충돌합니다. 이를 우회하려면 먼저 vLLM을 설치한 후, transformers를 강제 설치하고,kernels를 TRL의 extra를 통해 추가하세요. 이 extra는 transformers가 허용하는 버전을 고정합니다.pip install vllm pip install 'transformers>=5.2.0' --no-deps pip install 'trl[kernels]'
개요
experimental.async_distillation.AsyncDistillationTrainer는 DistillationTrainer의 비동기 버전으로, AsyncGRPOTrainer와 유사한 구조를 가집니다. 백그라운드 롤아웃 워커가 학생 모델의 자체 온-폴리시 완성을 생성하고 이를 교사와 비교하여 점수를 매기며, 학습은 생성과 그라디언트 업데이트를 번갈아 수행하는 대신 병렬로 진행됩니다. 동기 트레이너와 달리 교사는 로컬에 로드되지 않으며 vLLM 서버 URL만 필요합니다. 따라서 교사는 학생과 트레이너와 완전히 다른 하드웨어에서 실행되거나, 학생과 함께 실행하기에는 너무 큰 모델일 수 있습니다.
compute_loss는 학생 모델과 교사 모델의 위치별 토큰 분포 사이의 일반화된 Jensen-Shannon Divergence를 최소화합니다(beta=0.0는 forward KL, beta=1.0는 reverse KL이며, 그 사이의 값은 보간을 수행합니다). 이는 DistillationTrainer와 ServerDistillationTrainer가 사용하는 것과 동일한 목적 함수입니다. 학습은 항상 on-policy로 수행되며, 학생 모델은 학습에 사용하는 모든 completion을 직접 생성합니다.
멀티-티처 온-폴리시 디스틸레이션(MOPD)
MOPD는 이 트레이너의 핵심 목표가 기반을 둔 2306.13649 논문(동기식, 단일 교사 설정을 설명)의 일부가 아닙니다. 이는 MOPD: Multi-Teacher On-Policy Distillation for Capability Integration in LLM Post-Training에 설명된 별개의 방법론입니다. 해당 논문에서 MOPD는 세 단계 중 세 번째 단계입니다. 즉, 일반 SFT, 도메인별 독립적인 RL 훈련을 통해 도메인당 하나의 전문가를 훈련하는 단계, 그리고 MOPD가 해당 동결된 전문가들을 단일 학생 모델로 융합하는 단계입니다. AsyncDistillationTrainer는 이 세 번째, 즉 융합 단계만 구현합니다. 도메인별 전문가 교사는 이미 존재해야 하며(예: GRPOTrainer/RLOOTrainer로 별도로 훈련), teacher_server_urls를 해당 서버로 지정하기 전에 HTTP를 통해 서빙되어야 합니다. 논문 자체의 Stage 3은 이 트레이너의 기본값인 beta=0.0(forward KL)이 아닌 역 KL(beta=1.0)을 사용합니다.
teacher_server_urls에는 여러 항목을 지정할 수 있습니다. 항목이 하나인 경우, 모든 샘플은 해당 단일 teacher에 의해 점수를 받습니다(일반적인 on-policy distillation). 항목이 여러 개인 경우, 각 학습 샘플의 teacher_id 컬럼이 해당 샘플을 점수화할 teacher를 선택합니다. 예를 들어, 수학 프롬프트는 수학 전문 teacher로, 코드 프롬프트는 코드 전문 teacher로 라우팅되며, 각 teacher는 독립적으로 서빙됩니다. 각 샘플은 일치하는 하나의 teacher로만 분배되며, teacher 간에 평균화되거나 앙상블되지 않습니다. teacher_id가 누락되었거나 매핑되지 않은 샘플은 잘못된 teacher로 조용히 폴백되는 대신 예외를 발생시킵니다. Open-MOPD와 함께 공개된 수학, 코드, 지시 따르기 전문가를 공유된 SFT 체크포인트로 융합하는 실행 가능한 예제는 examples/async_distillation_mopd/async_distillation_mopd.py를 참고하고, 이를 4개 GPU에서 단일 Hugging Face Jobs 명령어로 실행하는 방법은 examples/async_distillation_mopd/launcher.py를 참고하세요.
모든 teacher는 student의 tokenizer를 공유해야 합니다. Completions는 raw token id 형태로 teacher로 전송되며, teacher가 보고하는 candidate id는
compute_loss에서 student의 자체 어휘를 직접 인덱싱합니다. student와 동일한 모델 계열의 teacher(MOPD 예시처럼, 동일한 checkpoint에서 학습된 SmolLM3 전문가로부터 융합된 SmolLM3 student의 경우)는 이 조건을 충족합니다. 반면, 다른 어휘를 가진 teacher는 student를 잘못된 토큰에 대해 학습시키며, teacher의 어휘가 student의 어휘보다 크지 않는 한 이 문제는 조용히 발생합니다.
체크포인트 및 재개: ignore_data_skip의 기본값은 True입니다. 기본 Trainer의 skip-and-replay 루프는 라이브 롤아웃 큐에는 적용되지 않습니다. 대신, 아직 학습되지 않은 첫 번째 프롬프트의 인덱스가 각 체크포인트와 함께 rollout_state.json에 저장되고 재개 시 복원되므로, 워커는 샘플을 재생하지 않고 해당 프롬프트까지 빠르게 이동합니다. 이는 생성기의 위치가 아니라 학습된 위치입니다. 워커는 롤아웃 큐 깊이만큼 학습보다 앞서 실행되며, 이러한 버퍼링된 샘플은 실행이 종료되면 손실되므로, 생성기의 위치에서 재개하면 생성되었지만 학습되지 않은 프롬프트가 건너뛰어집니다. 스트리밍 데이터셋(IterableDataset)은 위치를 재설정할 수 없으며, 재개 시 워커는 프롬프트 0부터 다시 시작합니다. bf16=True(기본값) 또는 fp16=True인 FSDP 환경에서는 마스터 가중치가 fp32임에도 불구하고 model.safetensors가 해당 dtype으로 기록되므로, 푸시된 체크포인트의 크기는 서빙되는 모델의 크기와 같고 두 배가 아닙니다. fp32 마스터 가중치와 옵티마이저 상태는 여전히 재개 파일(pytorch_model_fsdp.bin, optimizer.bin)에 저장되며, 재개 시 읽히는 것이 바로 이 파일들이므로 재개에는 영향이 없습니다. FSDP를 사용하지 않으면 체크포인트가 재개 파일이기도 하므로 마스터 dtype을 유지합니다.
DistillationTrainer와의 차이점
DistillationTrainer에서는 teacher가 로컬에 로드된 모델입니다. 생성, teacher forward pass, gradient update가 모두 동일한 프로세스에서 순차적으로 수행됩니다. experimental.async_distillation.AsyncDistillationTrainer는 AsyncGRPOTrainer가 GRPO의 rollout과 update를 분리하는 것과 동일한 방식으로 이러한 역할을 분리합니다:
- Rollout worker(백그라운드 프로세스) — 학생의 vLLM 서버에서 completions을 생성하고, teacher-forced scoring을 위해
prompt_logprobs와 함께 전체 시퀀스를 resolved teacher의/v1/completions으로 전송하며(teacher는 새로운 토큰을 생성하지 않음), 학습 준비가 된 샘플을 큐에 넣습니다. - 학습 루프 (메인 프로세스) — 큐에서 샘플을 가져와 일반화된 JSD 손실을 계산하고 학생 모델의 가중치를 업데이트합니다.
교사가 로컬 forward pass가 아닌 HTTP를 통해 점수를 매기기 때문에, 전체 어휘가 아니라 분포의 희소 top-k 슬라이스(teacher_top_k)만 전송됩니다. 각 beta regime에서 wire protocol이 교사의 logprob를 보장하는 정확한 후보에 대해서는 experimental.async_distillation.AsyncDistillationConfig의 beta 및 teacher_top_k 문서를 참조하세요.
모든 weight_sync_steps 학습 단계마다 업데이트된 student 가중치가 NCCL을 통해 해당 vLLM 서버로 전송됩니다. AsyncGRPOTrainer와 마찬가지로 생성이 학습보다 앞서 진행되므로, 샘플은 약간 오래된 정책을 반영할 수 있습니다. max_staleness는 샘플이 폐기되기 전에 가중치 업데이트를 얼마나 뒤처질 수 있는지를 제어합니다.
빠른 시작
# train_async_distillation.py
from datasets import load_dataset
from trl.experimental.async_distillation import AsyncDistillationTrainer
if __name__ == "__main__": # the rollout worker is a spawned process that re-imports this script
dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
trainer = AsyncDistillationTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
train_dataset=dataset,
)
trainer.train()Teacher 서버, 학생의 vLLM 서버, trainer는 별도의 GPU에서 실행되어야 합니다. 둘 다 단순한 vllm serve 인스턴스이지만, 서로 다른 플래그가 필요합니다. Teacher는 점수 계산만 수행하므로 --logprobs-mode processed_logprobs를 설정하여 teacher_temperature가 반환되는 logprobs에 반영되도록 하고, --max-logprobs -1를 설정하여 teacher_top_k가 vLLM의 기본 상한인 20을 초과할 수 있도록 합니다. 반면 학생은 생성만 수행하며, trainer가 업데이트된 가중치를 학생에 전달할 수 있도록 NCCL 가중치 전송이 활성화되어 있어야 합니다. 점수 계산 시 학생의 전체 시퀀스를 전송하고 teacher에게 토큰 하나를 더 요청하므로, teacher의 --max-model-len(또는 기본값)은 학생의 값보다 커야 합니다:
# Terminal 1: teacher server on GPU 0 (static, never updated)
CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen2.5-1.5B-Instruct \
--port 8001 \
--logprobs-mode processed_logprobs \
--max-logprobs -1# Terminal 2: student's vLLM server on GPU 1 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct \
--port 8000 \
--weight-transfer-config '{"backend":"nccl"}'# Terminal 3: training on GPU 2
CUDA_VISIBLE_DEVICES=2 python train_async_distillation.pyLoRA
peft_config를 전달하여 전체 모델 대신 학생 모델에 LoRA 어댑터를 학습합니다:
from peft import LoraConfig
trainer = AsyncDistillationTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
train_dataset=dataset,
peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)모든 가중치 동기화 시 업데이트된 student를 해당 서버로 전송해야 합니다. 기본적으로 trainer는 어댑터를 베이스 모델에 병합하여 병합된 전체 가중치를 전송하며, 7B 모델의 경우 동기화마다 약 15 GB가 됩니다. student의 vLLM 서버를 --enable-lora 옵션으로 시작하면 어댑터만 전송하며, r=32일 경우 약 160 MB입니다:
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct \
--port 8000 \
--weight-transfer-config '{"backend":"nccl"}' \
--enable-lora \
--max-lora-rank 32 \
--max-loras 6VLLM_ALLOW_RUNTIME_LORA_UPDATING=1은 트레이너가 각 새 어댑터를 게시하는 엔드포인트를 노출합니다. 텐서 병렬로 서빙하는 경우 VLLM_WORKER_MULTIPROC_METHOD=spawn을 추가하고, 어떤 경우에도 --weight-transfer-config를 유지하세요. 트레이너는 시작 시에만 동기화 모드를 선택하며, 그 시점에는 서버가 이미 실행 중이므로 병합 동기화가 폴백으로 사용됩니다. 티처 서버에는 영향이 없습니다. 업데이트되지 않기 때문입니다.
--max-lora-rank은 1, 8, 16, 32, 64, 128, 256, 320, 512 중 하나여야 합니다. 서버가 제공할 수 있는 최대 랭크를 설정하는 것이므로, 8 환경에서도 r=4 어댑터가 정상적으로 작동합니다. --max-loras는 최소 max_staleness + 2 이상이어야 합니다. 트레이너는 max_staleness + 1개의 어댑터 버전을 등록해 두어, 이전 정책 하에서 시작된 롤아웃이 생성 중간에 정책을 전환하지 않고 해당 정책 하에서 완료될 수 있도록 하며, 각 동기화 시 가장 오래된 버전을 해제하기 전에 다음 버전을 로드합니다. 트레이너는 시작 시 두 값을 확인하고, 서버를 재시작할 때 사용할 값을 알려줍니다.
vLLM은 네트워크가 아닌 디스크에서 어댑터를 로드하므로, 트레이너는 각 버전을 <output_dir>/.vllm_lora/ 아래에 작성하고 서버에 해당 경로를 전달합니다. 서버가 다른 머신에서 실행되는 경우, 해당 디렉토리는 두 머신 모두에서 접근할 수 있는 파일시스템에 위치해야 합니다.
<output_dir>/.vllm_lora/는 서빙 캐시이며, 학습된 어댑터가 저장되는 위치가 아닙니다. 이 디렉터리에는 최신 버전만 보관되며, 각 버전은 스탈니스 윈도우(staleness window)에서 벗어난 직후에 삭제됩니다. 체크포인트가 학습한 어댑터를 보존하므로, 체크포인트 저장을 비활성화하지 마세요.save_strategy="no"를 사용하면 수 시간 동안 실행된 작업이 종료된 후에도 아무것도 남지 않습니다. 또한output_dir은 서버가 읽을 수 있어야 하고, 작업 종료 후에도 유지되어야 하므로, 느린 공유 파일시스템과의 동기화를 피할 수 있다는 장점에도 불구하고 노드 로컬 스크래치 공간은 사용할 수 없습니다.
Adapter sync가 항상 더 빠르지는 않습니다. vLLM은 LoRA adapter를 서빙할 때 병합된 가중치를 서빙하는 경우보다 토큰당 약 1.33~1.39배 느린 속도로 생성하며, 생성 과정이 일반적으로 전체 실행 시간을 지배합니다. 대신 얻는 이점은 각 sync 시마다 훨씬 짧은 대기 시간과 약 1% 수준의 sync 대역폭입니다. 생성 처리량이 병목이라면 병합 sync가 여전히 더 나은 선택일 수 있습니다.
기록된 지표
롤아웃는 그라디언트가 되기까지 여러 단계를 거칩니다. 프롬프트에서 최종 배치 구성에 이르기까지의 각 단계를 먼저 살펴보겠습니다:
Dataset row = PROMPT (message list + optional `teacher_id`)
└─ ROLLOUT (1 prompt -> 1 student completion -> 1 teacher scoring call)
├─ generate (student's vLLM /v1/completions, sampled)
└─ score (the routed teacher's /v1/completions with `prompt_logprobs`, teacher-forced)
└─ SAMPLE (prompt + completion + the teacher's sparse per-position distribution)
════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════
└─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
└─ ROW (Planner assigns it to one of `dp` rows, Σ Lᵢ²-balanced)
└─ MICRO-BATCH (`dp` rows, one per rank)
└─ PACKED ROW (1 concat sequence, `position_ids` reset per sample)
└─ FORWARD (`compute_loss`, bs=1, inter-rank padding stripped)
└─ OPTIMIZER STEP (from `grad_accum` micro-batches)위에서 아래로 읽으면:
- rollout는 한 번 생성되고 한 번 점수화되는 프롬프트 하나를 의미합니다. 그룹이 없습니다. 증류에는 세대 간에 계산할 이점 베이스라인이 없으므로 프롬프트가 반복되지 않으며, 하나의 rollout은 정확히 하나의 학습 샘플을 생성합니다.
- 샘플은 해당 completion과 각 completion 위치별 교사의 상위
teacher_top_k후보입니다. 이것이 프로세스 경계를 넘어 전달됩니다. - 경계를 넘어 trainer는 샘플을 rows(DP rank당 하나)로 계획하고, 각 row를 하나의 연결된 시퀀스로 패킹하며,
grad_accum개의 마이크로 배치로 단일 옵티마이저 스텝을 누적합니다.
따라서 메트릭은 어떤 단계(또는 entity)에 관한지에 따라 다음과 같이 구분됩니다:
| 네임스페이스 | 가 카운트하는 |
|---|---|
rollout/ | one generate-and-score round trip: how long it took, how far it got |
completions/ | student(vLLM)이 하나의 프롬프트에 대해 생성한 결과 |
sample/ | 큐에 도착하는 하나의 학습 샘플을 나타냅니다 |
batch/ | 하나의 마이크로 배치 또는 하나의 옵티마이저 스텝(하나 이상의 샘플로 구성됨) |
perf/ | 측정된 초와 FLOPs |
손실 함수가 측정하는 모든 값은 접두사 없이 기록됩니다(jsd, entropy, teacher_entropy). MOPD에서는 teacher/<teacher_id>/* 하위 항목으로 세부 내역이 제공되며, 자세한 내용은 아래 분산 섹션을 참조하세요.
토큰 메트릭의 모호함을 없애기 위해 몇 가지 용어를 정의해 보겠습니다:
- generated 토큰은 학생 모델이 생성한 결과(
completions/*)입니다. - forwarded 토큰은 forward 패스가 처리하는 모든 토큰을 의미하며, 프롬프트와 생성된 토큰을 포함합니다.
- trained 토큰은
completion_mask == 1인 부분집합으로, 손실이 계산되는 대상입니다. Trained ≠ generated: teacher가 어떤 후보도 점수 매기지 않은 completion 위치는 발산(divergence) 계산에서 마스킹되지만, 여전히 포워딩됩니다.
Metrics는 logging window마다 한 번씩 기록됩니다. 이는 이전 로그 이후에 기록된 모든 내용으로, 마지막 logging_steps개의 optimizer steps를 포함합니다. 해당 window 동안:
rollout/duration_s및rollout/score_s와 같이 롤아웃, 샘플 또는 호출별로 측정된 평균은 해당 윈도우 내의 모든 롤아웃, 샘플 또는 호출에 대해 평균화됩니다.rollout/generated_tokens_per_s와 같은 레이트는 총 토큰 수를 총 초로 나눈 값입니다.- 그렇지 않은 경우, 마지막 부분에
count라는 단어가 포함된 이름은 합산됩니다:sample/dropped_stale_count는 학습 시작 시점이 아니라 마지막 로그 이후에 드롭된 샘플의 수입니다. - 마지막 부분에
max또는min이라는 단어가 포함된 이름, 예를 들어sample/staleness_max또는completions/max_length와 같은 이름은 가장 큰 값 또는 가장 작은 값을 유지합니다. - 다른 모든 지표는 윈도우에 기록된 값들의 평균입니다.
단위:
_s: 초.tokens_per_s: 초당 토큰 수._frac: 0과 1 사이의 비율._per_step: 하나의 optimizer step당 양으로, 윈도우 내의 step들에 대해 평균화된 값입니다.
GRPOTrainer가 추가로 기록하는 메트릭은 GRPO 이름(completions/mean_length, completions/clipped_ratio)을 그대로 유지합니다.
배치 번호의 구성 방식
row는 하나의 DP rank가 하나의 micro-batch에서 forward하는 단위로, 여러 샘플을 하나의 시퀀스로 연결한 것이며 position_ids는 각 샘플 경계에서 다시 시작됩니다. 플래너는 어떤 샘플이 어떤 row에 배치될지 결정하며(Σ Lᵢ²를 균형 있게 하여 어떤 rank도 straggler가 되지 않도록 합니다), 데이터 콜레이터가 연결을 수행합니다.
모든 지표에서 “step”은 항상 하나의 FULL optimizer step을 의미하며, micro-batch를 의미하지 않습니다. gradient_accumulation_steps개의 micro-batch가 하나의 step을 구성하며, _per_step로 이름이 붙은 모든 지표는 optimizer step당 값을 나타내며, 이는 global_step, logging_steps 및 Trainer 어휘의 나머지 부분과 일치합니다. 지표가 micro-batch당 값을 나타내는 경우 명시되어 있으며(batch/microbatches_per_step), 그렇지 않으면 행(row)당 양(batch/row_*, batch/samples_per_row)입니다.
따라서 한 단계에는 고정된 수의 row-slots가 포함됩니다:
row-slots per step = gradient_accumulation_steps x world_sizebatch 메트릭이 서로 비교할 수 있는 계단 형태로 구성되도록 합니다:
sample sample/forwarded_tokens_mean
└─ packed into a ROW batch/samples_per_row, batch/row_tokens_mean
└─ one row per DP rank = one micro-batch
└─ gradient_accumulation_steps micro-batches = one STEP
batch/samples_per_step, batch/forwarded_tokens_per_step즉, batch/samples_per_step ≈ row-slots x batch/samples_per_row이며, 토큰도 마찬가지입니다. 두 값은 스텝 안의 마이크로 배치 간 변동성까지만 일치합니다. 스텝별 지표는 합계이고, 행별 지표는 평균이기 때문에 정확한 일치보다는 몇 퍼센트 이내의 오차를 예상해야 합니다.
샘플이 긴 경우 batch/row_fill_frac을 주목해야 합니다. 10k 토큰 샘플은 32k 예산을 효율적으로 채우지 못합니다(3개는 들어가고 4개는 절대 들어가지 않으므로, 패커는 보통 2개만 채우고 행이 약 77%만 차 있는 상태가 됩니다). 반면 1k 토큰 샘플은 예산을 거의 완벽하게 채웁니다. 이는 버그가 아니라 양자화(quantization)의 특성이며, token_budget이 이를 조절하는 레버입니다. 다만 각 시퀀스당 어텐션이 O(L²)이므로, 긴 시퀀스로 구성된 행이 더 차 있다고 해서 메모리 비용이 선형으로 증가하지는 않습니다.
롤아웃 큐
워커는 점수가 매겨진 샘플을 큐에 넣고, 트레이너는 해당 큐에서 데이터를 가져옵니다. 이 하나의 큐를 설명하는 네 가지 지표는 각각 다른 질문에 답합니다:
| 메트릭 | 질문 |
|---|---|
rollout/queue_size | 현재 대기 중인 샘플은 몇 개인가요 |
sample/time_in_queue_s | 단일 샘플이 학습되기 전에 얼마나 오래 대기했는지를 나타내며, 이는 오프폴리니스(off-policyness)의 절반을 차지하는 시간입니다 |
perf/rollout_wait_s | 큐가 비어 있어 훈련이 얼마나 오래 막혀 있었는지 |
rollout/backpressure_s | 생성(워커)이 학습보다 max_staleness 스텝 앞서 있었기 때문에 대기한 시간 |
마지막 두 지표(perf/rollout_wait_s와 rollout/backpressure_s)는 서로 대칭 관계입니다. 큐 크기와 함께 읽으면 어느 쪽이 병목인지 알 수 있습니다:
- 큐가 거의 비어 있고
perf/rollout_wait_s가 높으면 생성 병목 상태입니다. 트레이너가 대기 중이므로rollout/generated_tokens_per_s,rollout/concurrency,rollout/score_s를 확인하세요. - 약
max_staleness스텝 분량의 토큰을 담는 큐,rollout/backpressure_s높음 → trainer-bound. 생성이 지연되고sample/staleness_mean이 상한선에 근접합니다. - 둘 다 높음 →
max_staleness한계 자체를 너무 엄격하게 설정한 것입니다. 진행 중인 롤아웃가 샘플이 큐에 도달하기 전에 한계를 채우므로, 생성이 지연되는 동안 트레이너가 대기합니다.max_staleness값을 높여야 합니다. - 둘 다 0에 가까움 → 균형 잡힘!
Completions
completion은 학생의 vLLM 서버가 하나의 프롬프트에 대해 생성한 결과입니다.
| 메트릭 | 의미 |
|---|---|
completions/mean_length | 롤아웃당 생성된 토큰 |
completions/min_length, completions/max_length | 윈도우 내 가장 짧고 가장 긴 완성 |
completions/clipped_ratio | EOS로 끝나지 않고 max_completion_length에 의해 잘린 완료의 비율 |
completions/mean_terminated_length, completions/min_terminated_length, completions/max_terminated_length | EOS로 끝난 completions에 대해 동일한 길이를 |
롤아웃
rollout는 하나의 프롬프트를 끝까지 처리하는 것을 의미합니다. 학생 모델이 생성한 후, 해당 학생의 티처 모델에 대해 teacher-forcing을 수행하는 과정입니다. 티처 호출은 모든 rollout의 critical path에 위치하므로(완료된 그룹에 대한 점수 계산이 별도의 루프인 GRPO와 다름), 느린 티처는 rollout/duration_s에 직접적으로 반영됩니다.
| 메트릭 | 의미 |
|---|---|
rollout/duration_s | 디스패치부터 점수가 매겨진 샘플까지, 한 번의 롤아웃에 걸리는 wall time: 생성 및 teacher 호출 |
rollout/score_s | 그 중, 교사의 /v1/completions 호출에 걸린 시간 |
teacher/<id>/score_s | MOPD 전용: 동일하게, 교사별로. 느린 전문가 한 명이 자신에게 라우팅된 롤아웃만 스로틀링하며, 이는 블렌디드 평균에 의해 가려집니다 |
rollout/generated_tokens_per_s | 최근 구간(윈도우)의 생성 처리량, 따라서 스톨이 나타납니다 |
rollout/concurrency | 진행 중인 롤아웃, 즉 생성 중이거나 점수 평가 중인 |
rollout/vllm_retry_count | 재시도된 vLLM 요청을 학생 서버 또는 교사 서버로 라우팅합니다. 성능이 저하된 서버는 그렇지 않으면 원인을 알 수 없는 느린 응답으로 나타납니다. 이 항목은 생성된 텍스트가 아니라 서버에 대한 요청을 집계하기 때문에 completions/가 아닌 여기에 위치합니다. |
rollout/backpressure_s | max_staleness 스텝만큼 앞서 있었기 때문에 생성이 얼마나 대기했는지입니다. 롤아웃 큐를 참조하세요. |
rollout/queue_size | rollout 큐에 대기 중인 점수화된 샘플, trainer가 이를 가져오는 지점에서 측정됩니다. rollout 큐를 참조하세요. |
큐에서 도착하는 샘플
각 샘플은 RolloutSample 하나입니다: 프롬프트, 학생의 완성 결과, 그리고 이에 대한 교사의 희소 점수입니다. 워커는 이들을 rollout_buffer에 넣습니다. 아래에 설명하는 모든 내용은 트레이너 측에서 학습을 위해 이들을 가져오는 시점에 측정됩니다.
| 메트릭 | 의미 |
|---|---|
sample/forwarded_tokens_mean, sample/forwarded_tokens_max | sample 하나당 토큰 수: 프롬프트 + 생성된 토큰. Packing은 행(row) 수준의 문제이며, batch/row_*을 참조하세요. |
sample/trained_tokens_mean | 그 중 손실이 계산되는 샘플의 수 |
sample/time_in_queue_s | 이 샘플이 학습되기 전에 해당 큐에 얼마나 오래 머물렀는지를 나타냅니다. perf/rollout_wait_s와 동일하지 않으며, rollout 큐를 참조하세요. |
sample/staleness_mean, sample/staleness_max | 데이터가 정책 버전보다 얼마나 뒤처져 있는지 나타냅니다. jsd는 오프폴리니스가 손실에 미치는 영향을 보여주며, 이는 원인을 나타냅니다 |
sample/dropped_stale_count | max_staleness 초과로 인해 제거된 샘플 |
배치
마이크로 배치 1개는 world_size개의 행으로 구성됩니다(패킹이 1개의 시퀀스로 평탄화한다는 점을 기억하세요). 따라서 DP 랭크당 1개씩 할당되어, 랭크 i는 행 i를 포워드로 전달합니다. 이러한 마이크로 배치 gradient_accumulation_steps개가 하나의 옵티마이저 스텝을 구성합니다. 따라서 스텝 1개는 총 gradient_accumulation_steps × world_size개의 행을 처리합니다. 아래에 나열된 모든 _per_step 메트릭은 전체 스텝과 모든 랭크에 대한 합계이며, batch/row_* 메트릭은 행에 대한 평균입니다.
| 메트릭 | 의미 |
|---|---|
batch/forwarded_tokens_per_step, batch/trained_tokens_per_step | tokens in one optimizer step, forwarded and trained respectively |
batch/samples_per_step | training samples per optimizer step |
batch/microbatches_per_step | 설정에서 읽는 것이 아니라 계산됩니다 |
batch/masked_token_frac | completion_mask == 0인 전달된 토큰 — 그래디언트를 얻지 못하는 포워드 비율 |
batch/samples_per_row, batch/row_tokens_mean, batch/row_tokens_max | planner가 각 rank의 행을 얼마나 밀도 있게 채웠는지 |
batch/row_fill_frac | token_budget에 대한 row tokens. 값이 낮으면 예산이 충분히 사용되지 않고 있음을 의미합니다 |
batch/row_imbalance | max Σ Lᵢ² / mean Σ Lᵢ² 행별 값. Attention은 O(L²)이므로, 이는 어떤 rank가 gradient all-reduce를 지연시키는지 예측합니다. 1.0이 완벽합니다 |
batch/pad_frac | 랭크 간 패딩. 브로드캐스트 바이트 비용만 발생하며, 포워드 전에 제거됩니다 |
batch/dropped_oversize_count | token_budget 초과로 인해 제거된 샘플 |
발산
학습된 윈도우의 토큰에 대해 평균화된 목표 함수 자체의 측정값입니다. 처리량(throughput)이 아닌 학습을 모니터링할 때 주목해야 할 수치입니다.
| 메트릭 | 의미 |
|---|---|
jsd | 설정된 beta 값에서 손실이 최소화하는 일반화된 JSD입니다. 값이 감소한다는 것은 학생 모델의 분포가 교사 모델의 분포로 수렴하고 있음을 의미합니다. |
entropy | 학생의 자체 예측 엔트로피입니다. 여기서 jsd가 감소하면서 붕괴가 발생하면, 학생 모델이 학습하는 것이 아니라 예측 범위를 좁히는 것입니다. |
teacher_entropy | 교사가 보고한 후보들에 대한 엔트로피입니다. teacher_top_k개의 후보만 전송되므로 실제 값보다 아래로 제한됩니다. |
teacher/<id>/jsd | MOPD 전용: jsd는 교사가 점수를 매긴 토큰으로 제한됩니다. 서로 다른 도메인의 교사들은 매우 다른 속도로 발산할 수 있으며, 혼합된 jsd는 이를 혼동시킵니다 |
teacher/<id>/entropy | MOPD 전용: teacher_entropy의 동일한 분해 |
teacher/<id>/token_frac | MOPD 전용: 스코어링된 토큰 중 teacher가 가져간 비율. 라우팅 스커우는 그 외에는 보이지 않습니다. 행을 충분히 받지 못하는 teacher도 여전히 건강한 teacher/<id>/jsd를 보고합니다. |
aux_loss | router_aux_loss_coef가 0이 아니고 모델이 router logits를 반환할 때 기록되는, rank에 걸쳐 평균화된 MoE 라우터의 마이크로 배치별 로드 밸런싱 손실입니다. 위의 행들과 달리 토큰별 평균이 아닙니다. |
교사별 entropy는 없습니다. 학생의 엔트로피는 해당 샘플을 점수화한 교사가 누구인지에 따라 달라지는 것이 아니라, 학생 자체의 정책(policy)에 고유한 속성이므로, 블렌딩된 지표가 이를 이미 포괄합니다.
성능
Throughput은 트레이너가 초당 처리하는 토큰 수를 측정합니다. Model FLOPs Utilization (MFU)는 모델의 forward pass와 backward pass에 사용된 학습 장치의 이론적 연산 용량의 백분율을 추정합니다. 이 추정에서 사용되는 용량은 하드웨어와 학습 정밀도에 따라 달라집니다.
Throughput과 MFU는 두 가지 시간 기준에 따라 보고됩니다:
fwd_bwd_은 순전파와 역전파 과정에서의 성능을 측정합니다.wall_clock_는 옵티마이저 업데이트, 가중치 동기화, 롤아웃 대기 시간을 포함한 전체 옵티마이저 스텝에 걸친 성능을 측정합니다.
이 차이는 계산 성능과 대기 및 조정 비용을 구별하는 데 도움이 됩니다. 두 MFU 지표 모두 학습 장치만 설명합니다. 외부 롤아웃 또는 티처 서버의 계산 또는 하드웨어 용량은 포함되지 않습니다. Wall-clock MFU는 해당 서비스를 위한 트레이너의 대기 시간을 반영하며, 서비스 자체의 사용률을 반영하지 않습니다.
MFU는 선택된 정밀도에서 로컬 학습 장치의 피크 컴퓨트 용량이 알려진 경우, 그리고 FLOPs 추정치가 모델의 아키텍처(예: Llama, Qwen2, Qwen3, Qwen3-MoE 또는 Qwen3-VL)를 지원하는 경우에만 보고됩니다. 그렇지 않으면 MFU는 생략되며, 학습은 계속되고 처리량 및 타이밍 지표는 계속 사용할 수 있습니다.
| 메트릭 | 의미 |
|---|---|
perf/step_s | optimizer 단계 사이의 wall time: compute, optimizer, weight sync 및 queue 대기 시간 포함 |
perf/fwd_bwd_s | forward + backward, 해당 스텝의 마이크로 배치에 대해 합산된 값입니다. 이는 아래 모든 fwd_bwd_ 메트릭의 분모입니다 |
perf/fwd_s | 그의 forward 부분입니다. fwd_s / fwd_bwd_s가 1/3 근처인 것이 일반적인 분할이며, 이 값이 더 높다는 것은 backward가 저렴하거나 forward에서 recompute 비용이 발생하고 있음을 의미합니다. |
perf/optimizer_s | optimizer.step() |
perf/rollout_wait_s | 큐가 비어 있어 트레이너가 얼마나 오래 차단되어 있었는지 확인합니다. 롤아웃 큐를 참조하세요. |
perf/weight_sync_s | 전체 동기화, _pause_s (vLLM 대기), _barrier_s (rank skew), _transfer_s (바이트 수) |
perf/fwd_bwd_forwarded_tokens_per_s, perf/wall_clock_forwarded_tokens_per_s | 각 기준에 따른 초당 전달된 토큰 |
perf/wall_clock_trained_tokens_per_s | loss가 확인한 토큰만 계산하여 동일하게 |
perf/fwd_bwd_mfu, perf/wall_clock_mfu | 각 기준에 따른 모델 FLOPs 활용도 |
디자인 철학
이 trainer은 의도적으로 최소한으로 유지되며 범용 솔루션으로 확장될 목적으로 설계되지 않았습니다. 지원하지 않는 기능이 필요하시다면, 저장소를 클론한 후 trainer을 직접 필요에 맞게 수정하는 것을 권장합니다. 커뮤니티의 수요가 상당할 경우에만 새로운 기능이 검토됩니다.
AsyncDistillationConfig
class trl.experimental.async_distillation.AsyncDistillationConfig
< 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 = 1logging_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 = Truerestore_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 = Truelabel_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 = Nonedtype: str = 'float32'trust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonemax_completion_length: int = 2048temperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonerepetition_penalty: float = 1.0chat_template_kwargs: dict | str | None = Nonevllm_server_base_url: str = 'http://localhost:8000'vllm_server_timeout: float = 1800.0teacher_server_urls: dict[str, str] | str | None = Nonebeta: float = 0.0teacher_temperature: float = 1.0teacher_top_k: int = 8add_tail_bucket: bool = Truetoken_budget: int | None = Nonemax_concurrent_rollouts: int = 512max_staleness: int = 4weight_sync_steps: int = 1rollout_worker_timeout: float = 300.0log_completions: bool = Falselog_completions_steps: int = 100num_completions_to_print: int | None = None )
모델을 제어하는 매개변수
- model_init_kwargs (
dict[str, Any]또는str, 선택 사항) — 경로에서 student 모델을 인스턴스화할 때 from_pretrained에 사용되는 키워드 인수입니다.revision값은 처리 클래스를 로드할 때에도 사용됩니다. - dtype (
str, 선택 사항, 기본값은"float32") — 학생 모델을 로드할 데이터 타입으로, 다음 중 하나입니다."auto","bfloat16","float16"또는"float32". 기본값은"float32"입니다. 비동기 트레이너가 측정되는 학습-추론 불일치FP16을 통한 학습-추론 불일치 극복) 은 트레이너 자체의 정밀도에 민감합니다. 이러한 격차를 끝에서 끝까지 해소하려면 학생의 vLLM 서버도 동일한 dtype으로 서빙해야 합니다(vllm serve --dtype). Adtype의model_init_kwargsdtype이 우선합니다. 교사 서버에는 영향을 미치지 않습니다. 교사 서버는 업데이트되지 않으므로.이 설정은 가중치가 로드될 때 사용할 dtype만 지정합니다. FSDP의 혼합 정밀도 환경(
bf16=True가 기본값)에서 accelerate는 샤딩 전에 모든 학습 가능한 파라미터를 fp32로 업캐스트합니다. 따라서dtype값과 관계없이 마스터 가중치와 옵티마이저 상태는 fp32로 유지되며, 포워드와 백워드는 bf16 또는 fp16으로 실행됩니다. 이후 체크포인트는 fp32가 아닌 해당 혼합 정밀도 dtype로 저장됩니다. FSDP를 사용하지 않으면 업캐스트가 발생하지 않습니다.dtype="bfloat16"와bf16=True를 함께 사용하면 가중치와 옵티마이저 상태가 모두 bf16으로 유지되며, 이는 순수한 bf16 학습을 의미합니다. - 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. - router_aux_loss_coef (
float, 선택 사항) — Mixture-of-Experts(MoE) 모델의 로드 밸런싱 보조 손실 계수로, 이 가중치로 학습 손실에 추가됩니다. 설정되지 않으면 모델 구성에서 선언된 값이 사용됩니다. 비활성화하려면0.0으로 설정하세요. MoE가 아닌 모델과 함께 사용하면 실패합니다.
생성을 제어하는 매개변수
- max_completion_length (
int, 선택 사항, 기본값2048) — 각 completion당 생성할 최대 토큰 수. - temperature (
float, 선택 사항, 기본값1.0) — 학생 모델의 온-폴리시(on-policy) 완성 결과를 샘플링할 때 사용할 온도입니다. - top_p (
float, 선택 사항, 기본값1.0) — 온-폴리시(on-policy) 생성을 위한 Top-p (nucleus) 샘플링 파라미터. - top_k (
int, 선택 사항, 기본값0) — 온-폴리시(on-policy) 생성을 위한 Top-k 샘플링 매개변수입니다.0은 top-k 필터링을 비활성화합니다. - min_p (
float, 선택 사항) — 최대 확률을 가진 토큰의 확률로 스케일링되는 최소 토큰 확률입니다.0.0과1.0사이의 값이어야 합니다. 일반적인 값은0.01-0.2범위입니다. - repetition_penalty (
float, 선택 사항, 기본값1.0) — 프롬프트와 지금까지 생성된 텍스트에 해당 토큰이 등장했는지에 따라 새로운 토큰에 페널티를 부과하는 값입니다.1.0보다 큰 값은 모델이 새로운 토큰을 사용하도록 장려하고,1.0보다 작은 값은 모델이 토큰을 반복하도록 장려합니다. - chat_template_kwargs (
dict[str, Any], 선택) — 완성 결과를 생성할 때apply_chat_template함수에 전달할 추가 키워드 인자입니다.
vLLM 서버를 제어하는 매개변수
- vllm_server_base_url (
str, 선택 사항, 기본값"http --//localhost:8000"): 학생의 vLLM 서버 기본 URL입니다. 생성 및 스트리밍 가중치 업데이트 모두에 사용됩니다. - vllm_server_timeout (
float, 선택 사항, 기본값1800.0) — vLLM 서버 호출에 대한 초 단위 타임아웃입니다. 시작 시 student 서버가 준비될 때까지 대기하는 시간, 각 generation 또는 scoring 요청, 각 weight-sync 호출에 적용됩니다. 서버 대기 및 weight-sync 호출은 타임아웃이 발생하면 예외를 발생시키고, generation 또는 scoring 요청은 타임아웃 시 재시도됩니다. - teacher_server_urls (
dict[str, str], 선택 사항, 기본값{"default" -- "http://localhost:8001"}): 각각vllm serve <teacher-model> --logprobs-mode processed_logprobs --max-logprobs -1로 시작하는 Teacher vLLM 서버입니다. 모든 teacher는 정적(static)입니다. 이 trainer는 어떤 teacher에도 가중치 업데이트를 스트리밍하지 않으므로, teacher는VLLM_SERVER_DEV_MODE나 가중치 전송 백엔드가 필요하지 않으며, 점수를 정확히 계산하게 해주는 두 개의 플래그만 필요합니다(teacher_temperature및teacher_top_k참조). 모든 teacher는 student의 tokenizer를 공유해야 합니다. 완성본은 원시 토큰 ID로 전송되며, teacher가 보고하는 ID는compute_loss에서 student의 어휘를 직접 인덱싱하는 데 사용됩니다. 어휘가 다른 teacher는 잘못된 토큰을 기준으로 학습하게 되며, 어휘 크기가 student보다 크지 않은 경우 이를 감지하지 못한 채 진행됩니다. 점수 계산은 student 자신의 완성 토큰에 대한 teacher-forced 요청(max_tokens=1,prompt_logprobs=teacher_top_k,temperature=teacher_temperature)이며, 동기식 서버-teacher trainer에서get_sequence_logprobs()가 발행하는 요청과 동일합니다. 이 일회용 토큰 때문에 teacher는 student보다 큰--max-model-len이 필요하며, 그렇지 않으면 가장 긴 완성본에 점수를 매길 수 없습니다. 단일 항목은 모든 샘플에 점수를 매깁니다(기본값인 일반 단일-teacher on-policy distillation). 여러 항목은 MOPD(multi-teacher on-policy distillation, MOPD 참조)를 활성화합니다. 각 학습 행의teacher_id컬럼이 해당 행에 점수를 매길 항목을 선택하며, 예를 들어{"math": "http://localhost:8002", "code": "http://localhost:8003"}에서 행별로teacher_id가"math"또는"code"인 경우입니다.
디스틸레이션 손실을 제어하는 매개변수
- beta (
float, 선택 사항, 기본값0.0) — 일반화 Jensen-Shannon Divergence의 보간 계수입니다.0.0은 forward KL (mean-seeking)을,1.0은 reverse KL (mode-seeking)을 나타내며, 그 사이의 값은 DistillationTrainer가 내부적으로 계산하는 것과 동일한 일반화 JSD 공식에 따라 보간됩니다. 발산(divergence)을 계산하는 support는ServerDistillationTrainer와 일치하도록 regime에 따라 달라집니다.beta=0.0인 경우, forward KL의 가중치가 정확히 해당 support에서 제공되므로,teacher_top_k폭의 teacher-reported support 전체(plus tail bucket)가 사용됩니다.beta != 0.0인 경우, wire protocol이 더 넓은(또는 전체) 어휘를 전송하지 않고도 teacher logprob를 보장하는 두 개의 토큰 정체성, 즉 teacher의 top-1 토큰과 completion의 실제/실현된 토큰으로 support가 좁혀집니다. 더 넓은 범위는 student의 유력한 토큰을 커버하는 확률적 근사에 불과할 뿐, 보장은 아닙니다. - teacher_temperature (
float, 선택 사항, 기본값1.0) — 발산(divergence)에 적용되는 Softmax 온도입니다. 양쪽에 모두 적용되며, teacher로 전송되어 vLLM이 서버 측에서 이 온도로 logprobs를 계산하도록 합니다(클라이언트 측 재스케일링이 아닌 정확한 계산). 또한compute_loss에서 student의 자체 logits에도 적용되어,ServerDistillationTrainer의 단일temperature를 반영합니다. student가 completions을 샘플링하는 방식을 제어하는temperature와는 무관합니다. 이 설정이 반환되는 logprobs에 실제로 반영되려면 teacher 서버가--logprobs-mode processed_logprobs옵션으로 실행되어야 합니다. 그렇지 않으면 teacher는 raw logprobs를 조용히 보고하며, 이 설정은 student 측에만 영향을 미칩니다. - teacher_top_k (
int, 선택 사항, 기본값8) —prompt_logprobs를 통해 teacher로부터 요청하는 위치별 후보 토큰의 수입니다. teacher의 분포를 근사하는 데에는 이 후보들(실제 생성된 토큰은 vLLM이 top-k 범위를 벗어나더라도 항상 보고하므로 포함되며, 나머지 확률 질량을 포착하는 tail 버킷도 포함됩니다.add_tail_bucket참조)만 사용되며, 전체 어휘는 HTTP를 통해 전송되지 않습니다. 발산(divergence)의 student 측 값은 정확합니다. student는 학습 대상 모델이므로 전체 logits가 이미compute_loss에서 사용 가능하기 때문에 근사하지 않고 로컬에서 계산됩니다.8은 스모크 테스트를 위한 가벼운 기본값입니다. 인접한 RL 프레임워크의 프로덕션 on-policy-distillation 설정에서는 대략 동일한 범위의 희소 teacher support를 사용하므로(miles의 기본값은16, EasyOPD는64), 실제 학습을 시작할 때 이 값을16~64로 높이는 것이 적절합니다.20을 초과하는 값은 teacher 서버를--max-logprobs -1옵션으로 시작해야 하며, 이는 vLLM의 토큰별 logprob 상한을 해제합니다. - add_tail_bucket (
bool, 선택 사항, 기본값True) —teacher_top_k외부의 나머지 확률 질량을 나타내는 tail bucket을 추가할지 여부입니다.teacher_top_k가 작을 때 자명한 수준의 작은 발산을 방지하기 위해 사용합니다. - token_budget (
int, 선택) — 단일 행(하나의 DP rank의 forward)에 패킹되는 실제 토큰의 최대 수입니다.TokenBudgetBatcher는 각 행이 이 예산 내에서 유지되도록 Σ Lᵢ² 균형이 잡힌 마이크로 배치들을 형성하여, 샘플 수와 독립적으로 피크 메모리를 제한합니다(행당 샘플 수는 동적으로 결정됩니다).None(기본값)인 경우, 학습 시작 시 조회되는 학생 vLLM 서버의max_model_len(프롬프트 + 완성 길이 상한)로 설정되어, 어떤 롤아웃 샘플도 예산을 초과할 수 없습니다.token_budget보다 긴 샘플은 어떤 행에도 적합하지 않아 경고와 함께 폐기되며,batch/dropped_oversize_count로 집계됩니다.
비동기 롤아웃 파이프라인을 제어하는 매개변수
- max_concurrent_rollouts (
int, 선택 사항, 기본값512) — 학생과 교사의 vLLM 서버에 동시에 진행 중인 롤아웃의 최대 수입니다. 생성 중이거나 점수를 받는 롤아웃을 포함합니다. - max_staleness (
int, 선택 사항, 기본값4) — 롤아웃 샘플이 현재 모델 버전보다 최대 몇 단계의 가중치 업데이트를 뒤처질 수 있는지, 그 한계치입니다. 이 한계를 초과하면 샘플은 폐기됩니다. 생성 과정은 이 규칙에 따라 제어됩니다. 큐에 대기 중이거나 전송 중인 토큰이 트레이너가max(max_staleness, 1)단계 동안 소비하는 양에 맞을 때만 롤아웃가 시작됩니다. - weight_sync_steps (
int, 선택 사항, 기본값1) — 학생의 vLLM 서버로 가중치를 동기화하는 훈련 스텝 간격. - rollout_worker_timeout (
float, 선택 사항, 기본값300.0) — rollout worker의 마지막 heartbeat 이후 trainer가 해당 worker를 hung 상태로 간주하고 작업을 중단하기까지의 초 단위 시간입니다.
로깅을 제어하는 매개변수
- log_completions (
bool, 선택 사항, 기본값False) — 점수화된 샘플마다log_completions_steps간격으로 (prompt, completion) 쌍의 샘플을 기록할지 여부. - log_completions_steps (
int, 선택 사항, 기본값100) — completions 로깅 사이에 점수를 매긴 샘플 수입니다.log_completions가True인 경우에만 사용됩니다. optimizer steps가 아니라 rollout worker가 점수를 매긴 샘플 수로 계산됩니다. worker는 trainer와 별도의 프로세스에서 실행되며self.state.global_step에 대한 가시성이 없습니다. - num_completions_to_print (
int, 선택 사항) —rich로 출력할 completions의 수입니다.None인 경우 모든 completions이 기록됩니다.
experimental.async_distillation.AsyncDistillationTrainer의 구성 클래스입니다.
이 클래스에는 비동기 온-폴리시 디스틸레이션에 특화된 매개변수만 포함되어 있습니다. 전체 학습 인자 목록은 TrainingArguments 문서를 참고하세요. 이 클래스의 기본값은 TrainingArguments의 기본값과 다를 수 있습니다. 구조는 AsyncGRPOConfig(비동기 파이프라인, vLLM 서버, 로깅 필드가 동일)를 따르며, GRPO의 클리핑/그룹 필드는 아래 교사 디스틸레이션 손실 필드로 대체됩니다.
이러한 파라미터는 TrainingArguments와 다른 기본값을 가집니다:
logging_steps: 기본값이500대신1입니다.gradient_checkpointing: 기본값이False가 아닌True입니다.bf16:fp16가 설정되지 않은 경우 기본값이False가 아닌True입니다.learning_rate: 기본값이5e-5대신1e-6입니다.ignore_data_skip: 기본값이False가 아닌True입니다. 기본 Trainer의 skip-and-replay 루프는 비동기 rollout 큐에 적용되지 않습니다.
AsyncDistillationTrainer
class trl.experimental.async_distillation.AsyncDistillationTrainer
< source >( model: str | PreTrainedModelargs: trl.experimental.async_distillation.async_distillation_config.AsyncDistillationConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneprocessing_class: 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)peft_config: PeftConfig | None = None )
매개변수
- model (
str또는 PreTrainedModel) — 학습할 Student model입니다. 다음 중 하나일 수 있습니다:- huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 model id인 문자열, 또는 save_pretrained를 사용하여 저장된 모델 가중치가 포함된 directory의 경로입니다. from_pretrained로 로드됩니다.
- PreTrainedModel 객체입니다. 패딩이 없는 학습을 위해 어텐션 구현이 트레이너의 FlashAttention 백엔드로 전환됩니다.
config의 모델 이름은 vLLM 서버에서 student 모델을 식별하는 데 사용됩니다.
- args (experimental.async_distillation.AsyncDistillationConfig, 선택 사항) —
이 trainer에 대한 설정입니다.
None인 경우 기본 설정이 사용됩니다. - train_dataset (Dataset 또는 IterableDataset) —
학습에 사용할 Dataset입니다.
"prompt"컬럼(conversational 형식)을 포함해야 합니다. 추가 컬럼은 무시됩니다. - processing_class (PreTrainedTokenizerBase, 선택 사항) —
데이터를 처리하는 데 사용되는 처리 클래스입니다.
None인 경우, from_pretrained를 사용하여 모델 이름에서 로드됩니다. 패딩 토큰이 없는 경우tokenizer.eos_token이 사용됩니다. - callbacks (TrainerCallback의 목록, 선택 사항) — 학습 루프를 커스터마이징하기 위한 콜백 목록입니다. 기본 콜백에 추가됩니다( 여기를 참조).
- optimizers (
tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], 선택 사항, 기본값(None, None)) — 사용할 옵티마이저와 스케줄러를 포함하는 튜플입니다. 기본값은args에 의해 제어되는 선형 스케줄과 함께AdamW입니다. - peft_config (
PeftConfig, 선택 사항) — 모델을 래핑하는 데 사용되는 PEFT 구성입니다.None인 경우 모델은 래핑되지 않습니다. 학생 모델의 vLLM 서버가--enable-lora옵션으로 시작되었을 경우, LoRA 어댑터는 병합된 가중치가 아닌 어댑터로 동기화됩니다. AsyncDistillation 문서의 LoRA 섹션을 참조하세요.
DistillationTrainer의 비동기 대응체로, AsyncGRPOTrainer와 동일한 아키텍처를 갖추고 있습니다. 백그라운드 롤아웃 워커가 학생 모델의 온-폴리시 완성을 생성하고, 학습이 병렬로 진행되는 동안 교사 서버에 대해 점수를 매김으로써 롤아웃을 그라디언트 업데이트 루프와 분리합니다. GRPO의 클립된 정책 그라디언트 손실이 그룹 상대 이점을 읽는 반면, 이 트레이너의 compute_loss는 위치별 희소 교사 분포를 읽고 이에 대해 일반화된 JSD를 최소화합니다(AsyncDistillationConfig.beta 참조). 항상 온-폴리시로 동작하며, 학생 모델은 학습에 사용하는 모든 완성을 스스로 생성합니다.
동기식 DistillationTrainer와 달리, 이 트레이너는 HTTP로 제공되는 teacher(외부 vLLM 서버)에 대한 점수 계산만 지원합니다. 로컬(인-프로세스, GPU) teacher의 forward pass는 GRPO의 보상 함수처럼 rollout worker의 CUDA 비활성화 spawn 자식 프로세스 내에서 실행할 수 없으며, 대신 메인 학습 프로세스에서 실행되어야 합니다. 해당 경로는 아직 구현되지 않았습니다.
예:
>>> from trl.experimental.async_distillation import AsyncDistillationTrainer
>>> from datasets import load_dataset
>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
>>> trainer = AsyncDistillationTrainer(
... model="Qwen/Qwen2.5-0.5B-Instruct",
... train_dataset=dataset,
... )
>>> trainer.train()