# Async Distillation

> [!IMPORTANT]
> 이 trainer는 `vllm`, `transformers>=5.2.0` 및 `kernels`가 필요합니다(학습 시 이를 통해 Hub에서 FlashAttention을 로드합니다). 분산 학습의 경우 FSDP2만 지원되며(DeepSpeed ZeRO는 지원되지 않습니다).
>
> 현재 `vllm`과 `transformers`의 종속성 제약 조건이 충돌합니다. 이를 우회하려면 먼저 vLLM을 설치한 후, transformers를 강제 설치하고, `kernels`를 TRL의 extra를 통해 추가하여 transformers가 허용하는 버전을 고정하세요:
>
> ```bash
> pip install vllm
> pip install 'transformers>=5.2.0' --no-deps
> pip install 'trl[kernels]'
> ```

## 개요

[experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.2/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer)는 [DistillationTrainer](/docs/trl/v1.18.2/ko/distillation_trainer#trl.DistillationTrainer)의 비동기 버전으로, [AsyncGRPOTrainer](/docs/trl/v1.18.2/ko/async_grpo_trainer#trl.AsyncGRPOTrainer)와 유사한 구조를 가집니다. 백그라운드 롤아웃 워커가 학생 모델의 자체 온-폴리시 완성을 생성하고 이를 교사와 비교하여 점수를 매기며, 학습은 생성과 그라디언트 업데이트를 번갈아 수행하는 대신 병렬로 진행됩니다. 동기 트레이너와 달리 교사는 로컬에 로드되지 않으며 vLLM 서버 URL만 필요합니다. 따라서 교사는 학생과 트레이너와 완전히 다른 하드웨어에서 실행되거나, 학생과 함께 실행하기에는 너무 큰 모델일 수 있습니다.

`compute_loss`는 학생 모델과 교사 모델의 위치별 토큰 분포 사이의 일반화된 Jensen-Shannon Divergence를 최소화합니다(`beta=0.0`는 forward KL, `beta=1.0`는 reverse KL이며, 그 사이의 값은 보간을 수행합니다). 이는 [DistillationTrainer](/docs/trl/v1.18.2/ko/distillation_trainer#trl.DistillationTrainer)와 `ServerDistillationTrainer`가 사용하는 것과 동일한 목적 함수입니다. 학습은 항상 on-policy로 수행되며, 학생 모델은 학습에 사용하는 모든 completion을 직접 생성합니다.

### 멀티-티처 온-폴리시 디스틸레이션(MOPD)

MOPD는 이 트레이너의 핵심 목표가 기반을 둔 [2306.13649](https://huggingface.co/papers/2306.13649) 논문(동기식, 단일 교사 설정을 설명)의 일부가 아닙니다. 이는 [MOPD: Multi-Teacher On-Policy Distillation for Capability Integration in LLM Post-Training]( https://huggingface.co/papers/2606.30406)에 설명된 별개의 방법론입니다. 해당 논문에서 MOPD는 세 단계 중 세 번째 단계입니다. 즉, 일반적인 SFT, 도메인별 독립적인 RL 훈련을 통해 도메인당 하나의 전문가를 훈련하는 단계, 그리고 MOPD가 해당 동결된 전문가들을 단일 학생 모델로 융합하는 단계입니다. `AsyncDistillationTrainer`는 이 세 번째, 즉 융합 단계만 구현합니다. 도메인별 전문가 교사는 이미 존재해야 하며(예: [GRPOTrainer](/docs/trl/v1.18.2/ko/grpo_trainer#trl.GRPOTrainer)/[RLOOTrainer](/docs/trl/v1.18.2/ko/rloo_trainer#trl.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](https://huggingface.co/papers/2608.19098)와 함께 공개된 수학, 코드, 지시 따르기 전문가를 공유된 SFT 체크포인트로 융합하는 실행 가능한 예제는 `examples/async_distillation_mopd/async_distillation_mopd.py`를 참고하고, 이를 4개 GPU에서 단일 [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs) 명령어로 실행하는 방법은 `examples/async_distillation_mopd/launcher.py`를 참고하세요.

> [!WARNING]
> 모든 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](/docs/trl/v1.18.2/ko/distillation_trainer#trl.DistillationTrainer)와의 차이점

[DistillationTrainer](/docs/trl/v1.18.2/ko/distillation_trainer#trl.DistillationTrainer)에서는 teacher가 로컬에 로드된 모델입니다. 생성, teacher forward pass, gradient update가 모두 동일한 프로세스에서 순차적으로 수행됩니다. [experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.2/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer)는 [AsyncGRPOTrainer](/docs/trl/v1.18.2/ko/async_grpo_trainer#trl.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](/docs/trl/v1.18.2/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationConfig)의 `beta` 및 `teacher_top_k` 문서를 참조하세요.

모든 `weight_sync_steps` 학습 단계마다 업데이트된 student 가중치가 NCCL을 통해 해당 vLLM 서버로 전송됩니다. [AsyncGRPOTrainer](/docs/trl/v1.18.2/ko/async_grpo_trainer#trl.AsyncGRPOTrainer)와 마찬가지로 생성이 학습보다 앞서 진행되므로, 샘플은 약간 오래된 정책을 반영할 수 있습니다. `max_staleness`는 샘플이 폐기되기 전에 가중치 업데이트를 얼마나 뒤처질 수 있는지를 제어합니다.

## 빠른 시작

```python
# 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`(또는 기본값)은 학생의 값보다 커야 합니다:

```bash
# 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
```

```bash
# 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"}'
```

```bash
# Terminal 3: training on GPU 2
CUDA_VISIBLE_DEVICES=2 python train_async_distillation.py
```

## LoRA

`peft_config`를 전달하여 전체 모델 대신 학생 모델에 LoRA 어댑터를 학습합니다:

```python
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입니다:

```bash
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 6
```

`VLLM_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/` 아래에 작성하고 서버에 해당 경로를 전달합니다. 서버가 다른 머신에서 실행되는 경우, 해당 디렉토리는 두 머신 모두에서 접근할 수 있는 파일시스템에 위치해야 합니다.

> [!WARNING]
> `<output_dir>/.vllm_lora/`는 서빙 캐시이며, 학습된 어댑터가 저장되는 위치가 아닙니다. 이 디렉터리에는 최신 버전만 보관되며, 각 버전은 스탈니스 윈도우(staleness window)에서 벗어난 직후에 삭제됩니다. 체크포인트가 학습한 어댑터를 보존하므로, 체크포인트 저장을 비활성화하지 마세요. `save_strategy="no"`를 사용하면 수 시간 동안 실행된 작업이 종료된 후에도 아무것도 남지 않습니다. 또한 `output_dir`은 서버가 읽을 수 있어야 하고, 작업 종료 후에도 유지되어야 하므로, 느린 공유 파일시스템과의 동기화를 피할 수 있다는 장점에도 불구하고 노드 로컬 스크래치 공간은 사용할 수 없습니다.

> [!TIP]
> 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/`     | generate-and-score 왕복 1회: 소요 시간, 진행 정도         |
| `completions/` | student(vLLM)이 하나의 프롬프트에 대해 생성한 결과                            |
| `sample/`      | 큐에 도착하는 _하나_의 학습 샘플을 나타냅니다                |
| `batch/`       | 하나의 마이크로 배치 또는 하나의 옵티마이저 스텝(하나 이상의 샘플로 구성됨)  |
| `perf/`        | 측정된 초와 FLOPs                                                  |

손실 함수가 측정하는 모든 값은 접두사 없이 기록됩니다(`jsd`, `entropy`, `teacher_entropy`). MOPD에서는 `teacher/<teacher_id>/*` 하위 항목으로 세부 내역이 제공되며, 자세한 내용은 아래 [분산](#the-divergence) 섹션을 참조하세요.

토큰 메트릭의 모호함을 없애기 위해 몇 가지 용어를 정의해 보겠습니다:

- **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](/docs/trl/v1.18.2/ko/grpo_trainer#trl.GRPOTrainer)가 추가로 기록하는 메트릭은 GRPO 이름(`completions/mean_length`, `completions/clipped_ratio`)을 그대로 유지합니다.

### 배치 번호의 구성 방식

**row**는 **하나의** DP rank가 하나의 micro-batch에서 forward하는 단위로, 여러 샘플을 하나의 시퀀스로 연결한 것이며 `position_ids`는 각 샘플 경계에서 다시 시작됩니다. 플래너는 어떤 샘플이 어떤 row에 배치될지 결정하며(Σ Lᵢ²를 균형 있게 하여 어떤 rank도 straggler가 되지 않도록 합니다), 데이터 콜레이터가 연결을 수행합니다.

모든 지표에서 **"step"은 항상 하나의 전체(FULL) 옵티마이저 스텝을 의미하며**, 마이크로 배치(micro-batch)를 의미하지 않습니다. `gradient_accumulation_steps`개의 마이크로 배치가 하나의 스텝을 구성하며, `_per_step`로 이름이 붙은 모든 지표는 옵티마이저 스텝당 값으로, `global_step`, `logging_steps` 및 `Trainer` 어휘의 나머지 부분과 일치합니다. 지표가 마이크로 배치당 값인 경우 명시적으로 그렇게 표기(`batch/microbatches_per_step`)하거나, 행(row)당 양(`batch/row_*`, `batch/samples_per_row`)입니다.

따라서 한 단계에는 고정된 수의 **row-slots**가 포함됩니다:

```
row-slots per step = gradient_accumulation_steps x world_size
```

batch 메트릭이 서로 비교할 수 있는 계단 형태로 구성되도록 합니다:

```
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` 스텝만큼 앞서 있었기 때문에 생성이 얼마나 대기했는지입니다. [롤아웃 큐](#the-rollout-queue)를 참조하세요.                                                                                                                           |
| `rollout/queue_size`       | rollout 큐에 대기 중인 점수화된 샘플, trainer가 이를 가져오는 지점에서 측정됩니다. [rollout 큐](#the-rollout-queue)를 참조하세요.                                                                                                              |

### 큐에서 도착하는 샘플

각 샘플은 `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 큐](#the-rollout-queue)를 참조하세요. |
| `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 및 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`                                             | 큐가 비어 있어 트레이너가 얼마나 오래 차단되어 있었는지 확인합니다. [롤아웃 큐](#the-rollout-queue)를 참조하세요.                                             |
| `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[[trl.experimental.async_distillation.AsyncDistillationConfig]]

#### trl.experimental.async_distillation.AsyncDistillationConfig[[trl.experimental.async_distillation.AsyncDistillationConfig]]

```python
trl.experimental.async_distillation.AsyncDistillationConfig(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 1e-06, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool | None = None, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 1, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = True, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = True, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, dtype: str = 'float32', trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, max_completion_length: int = 2048, temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, repetition_penalty: float = 1.0, chat_template_kwargs: dict | str | None = None, vllm_server_base_url: str = 'http://localhost:8000', vllm_server_timeout: float = 1800.0, teacher_server_urls: dict[str, str] | str | None = None, beta: float = 0.0, teacher_temperature: float = 1.0, teacher_top_k: int = 8, add_tail_bucket: bool = True, token_budget: int | None = None, max_concurrent_rollouts: int = 512, max_staleness: int = 4, weight_sync_steps: int = 1, rollout_worker_timeout: float = 300.0, log_completions: bool = False, log_completions_steps: int = 100, num_completions_to_print: int | None = None)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.2/trl/experimental/async_distillation/async_distillation_config.py#L22)

**모델을 제어하는 매개변수:**

model_init_kwargs (`dict[str, Any]` 또는 `str`, *선택 사항*) : 경로에서 student 모델을 인스턴스화할 때 [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained)에 사용되는 키워드 인수입니다. `revision` 값은 처리 클래스를 로드할 때에도 사용됩니다.

dtype (`str`, *선택 사항*, 기본값 `"float32"`) : student 모델을 로드할 데이터 타입으로, `"auto"`, `"bfloat16"`, `"float16"` 또는 `"float32"` 중 하나입니다. 기본값이 `"float32"`인 이유는, async trainer들이 측정 기준으로 삼는 training-inference mismatch([Defeating the Training-Inference Mismatch via FP16](https://huggingface.co/papers/2510.26788))가 trainer 자체의 정밀도에 민감하기 때문입니다. 이러한 격차를 끝에서 끝까지 해소하려면 student의 vLLM 서버도 동일한 dtype(`vllm serve --dtype`)으로 서빙해야 합니다. `model_init_kwargs`의 `dtype`가 우선합니다. Teacher 서버에는 영향을 주지 않습니다. Teacher는 업데이트되지 않으므로입니다. 이 설정은 가중치가 로드되는 dtype만 지정합니다. FSDP와 혼합 정밀도(`bf16=True`가 기본값)를 사용하는 경우, accelerate는 샤딩 전에 모든 학습 가능한 파라미터를 fp32로 업캐스트하므로, `dtype` 값과 관계없이 마스터 가중치와 옵티마이저 상태는 fp32가 되며, forward와 backward는 bf16 또는 fp16으로 실행됩니다. 이후 체크포인트는 fp32가 아닌 해당 혼합 정밀도 dtype로 저장됩니다. FSDP를 사용하지 않으면 업캐스트가 일어나지 않습니다. `dtype="bfloat16"`와 `bf16=True`를 함께 사용하면 bf16 가중치와 옵티마이저 상태를 유지하므로, 순수한 bf16 학습이 됩니다.

trust_remote_code (`bool`, *optional*, defaults to `False`) : Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) and [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.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]`, *선택 사항*) : completions 생성 시 `apply_chat_template` 함수에 전달할 추가 키워드 인수입니다.

**vLLM 서버를 제어하는 매개변수:**

vllm_server_base_url (`str`, *선택 사항*, 기본값 `"http --//localhost:8000"`): 학생의 vLLM 서버 기본 URL입니다. 생성과 스트리밍 방식의 가중치 업데이트 모두에 사용됩니다.

vllm_server_timeout (`float`, *선택 사항*, 기본값 `1800.0`) : vLLM 서버 호출에 대한 초 단위 타임아웃입니다. 시작 시 학생 서버가 준비될 때까지 대기하는 시간, 각 생성 또는 스코어링 요청, 각 가중치 동기화 호출에 적용됩니다. 서버 대기 및 가중치 동기화 호출은 타임아웃이 발생하면 예외를 발생시키고, 타임아웃이 발생한 생성 또는 스코어링 요청은 재시도됩니다.

teacher_server_urls (`dict[str, str]`, *선택 사항*, 기본값 `{"default" : "http://localhost:8001"}`): Teacher vLLM 서버입니다. 각 서버는 `vllm serve <teacher-model> --logprobs-mode processed_logprobs --max-logprobs -1` 명령으로 시작합니다. 모든 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](https://huggingface.co/papers/2606.30406) 참조)가 활성화됩니다. 각 학습 행의 `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](/docs/trl/v1.18.2/ko/distillation_trainer#trl.DistillationTrainer)가 내부적으로 계산하는 것과 동일한 일반화된 JSD 공식에 따라 보간됩니다. 발산(divergence)을 계산하는 지원 범위(support)는 `ServerDistillationTrainer`와 마찬가지로 레짐에 따라 다릅니다. `beta=0.0`인 경우, forward KL의 가중치가 정확히 해당 지원 범위가 제공하는 것이므로, `teacher_top_k` 폭의 전체 teacher-reported support(및 tail bucket)가 사용됩니다. `beta != 0.0`인 경우, 지원 범위는 teacher의 top-1 토큰과 completion의 실제/실현된 토큰이라는 두 후보로 축소됩니다. 이는 와이어 프로토콜이 더 넓은(또는 전체) 어휘를 전송하지 않고도 teacher logprob를 보장하는 두 가지 토큰 정체성뿐이기 때문입니다. 그보다 넓은 범위는 학생의 자체적으로 가능성이 높은 토큰을 커버하는 확률적 근사에 불과할 뿐, 보장이 되지 않습니다.

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`가 작을 때 자명한 수준의 작은 발산을 피하기 위해, `teacher_top_k` 외부의 나머지 확률 질량을 나타내는 tail bucket을 추가할지 여부.

token_budget (`int`, *선택 사항*) : 단일 행(하나의 DP rank의 forward)에 패킹되는 실제 토큰의 최대 수입니다. `TokenBudgetBatcher`는 각 행이 이 예산 내에서 유지되도록 Σ Lᵢ² 균형이 잡힌 마이크로 배치들을 형성하여, 샘플 수와 독립적으로 피크 메모리를 제한합니다(행당 샘플 수는 동적으로 결정됩니다). `None`(기본값)인 경우, 학습 시작 시 조회되는 학생 vLLM 서버의 `max_model_len`(프롬프트 + 완성 길이 상한)로 설정되어, 어떤 롤아웃 샘플도 예산을 초과할 수 없습니다. `token_budget`보다 긴 샘플은 어떤 행에도 맞지 않아 경고와 함께 폐기되며, `batch/dropped_oversize_count`로 집계됩니다.

**비동기 롤아웃 파이프라인을 제어하는 매개변수:**

max_concurrent_rollouts (`int`, *선택 사항*, 기본값 `512`) : student와 teacher의 vLLM 서버에 동시에 진행 중인 최대 rollout 수입니다. 생성 중이거나 점수를 받는 rollout을 포함합니다.

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`) : 완료 결과를 로깅하는 사이마다 점수를 매긴 샘플 수. `log_completions`가 `True`인 경우에만 사용됩니다. 옵티마이저 스텝이 아닌, 롤아웃 워커가 점수를 매긴 샘플 수로 계산됩니다. 워커는 트레이너와 별도의 프로세스에서 실행되며 `self.state.global_step`에 대한 가시성이 없습니다.

num_completions_to_print (`int`, *선택 사항*) : `rich`로 출력할 completions의 수입니다. `None`인 경우 모든 completions이 기록됩니다.

[experimental.async_distillation.AsyncDistillationTrainer](/docs/trl/v1.18.2/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationTrainer)의 구성 클래스입니다.

이 클래스는 비동기 온-폴리시 디스틸레이션에 특화된 매개변수만 포함합니다. 전체 학습 인자 목록은 [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) 문서를 참조하세요. 이 클래스의 기본값은 [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments)의 기본값과 다를 수 있습니다. 구조는 [AsyncGRPOConfig](/docs/trl/v1.18.2/ko/async_grpo_trainer#trl.AsyncGRPOConfig)(비동기 파이프라인, vLLM 서버, 로깅 필드가 동일)를 따르며, GRPO의 클리핑/그룹 필드는 아래 교사 디스틸레이션 손실 필드로 대체됩니다.

> [!NOTE]
> 이러한 파라미터는 [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.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 루프는 비동기 롤아웃 큐에 적용되지 않습니다.

## AsyncDistillationTrainer[[trl.experimental.async_distillation.AsyncDistillationTrainer]]

#### trl.experimental.async_distillation.AsyncDistillationTrainer[[trl.experimental.async_distillation.AsyncDistillationTrainer]]

```python
trl.experimental.async_distillation.AsyncDistillationTrainer(model: str | PreTrainedModel, args: trl.experimental.async_distillation.async_distillation_config.AsyncDistillationConfig | None = None, train_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None), peft_config: PeftConfig | None = None)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.2/trl/experimental/async_distillation/async_distillation_trainer.py#L1059)

**매개변수:**

model (`str` 또는 [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) : 학습할 Student 모델입니다. 다음 중 하나여야 합니다:  - huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 *model id*인 문자열, 또는 [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained)를 사용하여 모델 가중치를 저장한 *directory*의 경로입니다. [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained)로 로드됩니다. - [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) 객체입니다. 패딩이 없는 학습을 위해 그 attention 구현이 trainer의 FlashAttention 백엔드로 전환됩니다.  config의 모델 이름은 vLLM 서버에서 student 모델을 식별하는 데 사용됩니다.

args ([experimental.async_distillation.AsyncDistillationConfig](/docs/trl/v1.18.2/ko/async_distillation_trainer#trl.experimental.async_distillation.AsyncDistillationConfig), *선택 사항*) : 이 trainer의 설정입니다. `None`인 경우 기본 설정이 사용됩니다.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) 또는 [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset)) : 학습에 사용할 Dataset입니다. `"prompt"` 컬럼([conversational](dataset_formats#conversational) 형식)을 포함해야 합니다. 추가 컬럼은 무시됩니다.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase), *선택*) : 데이터를 처리하는 데 사용되는 처리 클래스입니다. `None`인 경우 [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained)를 사용하여 모델 이름에서 로드됩니다. 패딩 토큰이 없는 경우 `tokenizer.eos_token`이 사용됩니다.

callbacks ([TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback) 목록, *선택 사항*) : 학습 루프를 커스터마이징하기 위한 콜백 목록입니다. 기본 콜백에 추가됩니다([여기](https://huggingface.co/docs/transformers/main_classes/callback) 참조).

optimizers (`tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None]`, *선택 사항*, 기본값 `(None, None)`) : 사용할 옵티마이저와 스케줄러를 포함하는 튜플입니다. 기본값은 `args`에 의해 제어되는 선형 스케줄과 함께 `AdamW`입니다.

peft_config ([PeftConfig](https://huggingface.co/docs/peft/v0.22.0/en/package_reference/config#peft.PeftConfig), *선택 사항*) : 모델을 래핑하는 데 사용되는 PEFT 구성입니다. `None`인 경우 모델은 래핑되지 않습니다. 학생 모델의 vLLM 서버가 `--enable-lora`로 시작되었을 때, LoRA 어댑터는 병합된 가중치가 아닌 어댑터로 동기화됩니다. AsyncDistillation 문서의 LoRA 섹션을 참조하세요.

[DistillationTrainer](/docs/trl/v1.18.2/ko/distillation_trainer#trl.DistillationTrainer)의 비동기 대응체로, [AsyncGRPOTrainer](/docs/trl/v1.18.2/ko/async_grpo_trainer#trl.AsyncGRPOTrainer)와 동일한 아키텍처를 갖추고 있습니다. 백그라운드 롤아웃 워커가 학생 모델의 온-폴리시 완성을 생성하고 교사 서버와 점수를 매기는 동안 학습이 병렬로 진행되어, 롤아웃을 그라디언트 업데이트 루프와 분리합니다. GRPO의 클립된 정책 그라디언트 손실이 그룹 상대 이점을 읽는 것과 달리, 이 트레이너의 `compute_loss`는 위치별 희소 교사 분포를 읽고 이에 대한 일반화 JSD를 최소화합니다(자세한 내용은 `AsyncDistillationConfig.beta` 참조). 항상 온-폴리시로 동작하며, 학생 모델이 학습에 사용하는 모든 완성을 직접 생성합니다.

동기식 `DistillationTrainer`와 달리, 이 트레이너는 HTTP로 제공되는 teacher(외부 vLLM 서버)에 대한 점수 계산만 지원합니다. GRPO의 보상 함수처럼 로컬(프로세스 내, GPU) teacher forward pass를 rollout worker의 CUDA가 비활성화된 spawn된 자식 프로세스 내에서 실행할 수 없으며, 대신 메인 학습 프로세스에서 실행되어야 합니다. 해당 경로는 아직 구현되지 않았습니다.

예:

```python
>>> 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()
```

