# vLLM 통합

이 문서는 GRPO와 Online DPO와 같은 온라인 방법에서 더 빠른 생성을 위해 vLLM을 TRL과 함께 사용하는 과정을 안내합니다. 먼저 vLLM을 TRL과 함께 사용하는 방법에 대한 요약을 제시하고, 이후 내부 작동 원리에 대해 자세히 설명합니다.

> [!WARNING]
> TRL은 현재 `0.23.0`부터 `0.33.x`까지의 vLLM 버전만 지원합니다. 호환성 문제를 피하려면 이 범위의 버전이 설치되어 있는지 확인하십시오.

> [!TIP]
> 다음 트레이너들은 현재 vLLM을 통한 생성을 지원합니다:
>
> - [GRPOTrainer](/docs/trl/v1.18.1/ko/grpo_trainer#trl.GRPOTrainer) - [RLOOTrainer](/docs/trl/v1.18.1/ko/rloo_trainer#trl.RLOOTrainer) - [experimental.online_dpo.OnlineDPOTrainer](/docs/trl/v1.18.1/ko/online_dpo_trainer#trl.experimental.online_dpo.OnlineDPOTrainer)

## 🚀 vLLM을 TRL과 함께 사용하여 학습 속도를 높이는 방법은 무엇인가요?

💡 **참고**: 이 특정 예제에 필요한 리소스: 8개의 GPU를 갖춘 단일 노드.

> [!WARNING]
> TRL과 vLLM을 함께 사용할 때, **vLLM 서버**와 **trainer**는 충돌을 방지하기 위해 **별도의 CUDA 장치**에서 실행되어야 합니다. 이를 올바르게 구성하는 방법에 대한 안내는 [학습 중 vLLM 사용 모드](#modes-of-using-vllm-during-training)를 참고하세요.

먼저 다음 명령을 사용하여 vLLM을 설치합니다:

```bash
pip install "trl[vllm]"
```

그런 다음 특정 GPU(예: GPU 0-3)에서 서버를 실행합니다:

```sh
CUDA_VISIBLE_DEVICES=0,1,2,3 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-7B --tensor-parallel-size 4 \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1
```

서버가 실행되면 학습을 위한 completions 생성에 사용할 수 있습니다. 아래 예시에서는 vLLM 서버를 생성에 활용하여 다양한 지원되는 trainers를 사용합니다. `--tensor-parallel-size` 및 `--data-parallel-size` 인수는 모델과 데이터가 GPU에 걸쳐 어떻게 분할(sharding)되는지를 제어합니다.

이 예제에서는 텐서 병렬성을 사용하여 하나의 모델을 4개의 GPU에 샤딩합니다. 그런 다음, 학습 인자에 `use_vllm=True`를 전달하여 다른 GPU(예: GPU 4-7)에서 학습 스크립트를 실행합니다.

간단한 `train.py` 스크립트 예시:

```python
from datasets import load_dataset
from trl import GRPOTrainer, GRPOConfig
from trl.rewards import accuracy_reward

dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-7B",
    args=GRPOConfig(use_vllm=True, vllm_mode="server"),
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)

trainer.train()
```

```python
from datasets import load_dataset
from trl.experimental.online_dpo import OnlineDPOConfig, OnlineDPOTrainer
from trl.rewards import accuracy_reward

dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

trainer = OnlineDPOTrainer(
    model="Qwen/Qwen2.5-7B",
    args=OnlineDPOConfig(use_vllm=True, vllm_mode="server"),
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)

trainer.train()
```

```python
from datasets import load_dataset
from trl import RLOOTrainer, RLOOConfig
from trl.rewards import accuracy_reward

dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

trainer = RLOOTrainer(
    model="Qwen/Qwen2.5-7B",
    args=RLOOConfig(use_vllm=True, vllm_mode="server"),
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)

trainer.train()
```

서버와 다른 GPU에서 train 명령을 실행합니다:

```sh
CUDA_VISIBLE_DEVICES=4,5,6,7 torchrun --nproc_per_node 4 train.py
```

## vLLM을 사용하는 이유는 무엇인가요?

Online 방법은 학습 중에 completions을 생성하며, 모델 자체의 `generate`를 사용하여 이를 생성하는 것이 병목입니다. [PagedAttention](https://blog.vllm.ai/2023/06/20/vllm.html)와 같은 기술 덕분에 vLLM은 이러한 completions을 훨씬 빠르게 제공합니다.

## TRL이 서버를 사용하는 방식 🔍

Trainer는 OpenAI 호환 `/v1/completions` 엔드포인트에 completion을 요청하며, 프롬프트 토큰 ID를 전송합니다. 멀티모달 프롬프트는 다른 경로를 따릅니다. 서버가 이미지를 자체적으로 처리하고, OpenAI 호환 엔드포인트가 토큰 ID와 이미지를 동시에 받지 않으므로, 생성된 특징은 `/inference/v1/generate`에서 동일한 토큰 ID와 짝을 이룹니다.

서버는 생성만 수행합니다. 각 옵티마이저 단계 이후 트레이너는 NCCL을 통해 업데이트된 가중치를 서버로 스트리밍하며, `/start_weight_update`와 `/update_weights`로 이를 알리고 `/finish_weight_update`로 커밋합니다.

## 고급 사용

### 🍷 vLLM으로 더 많은 커스터마이징 옵션?

`vllm serve` 인수를 전달하여 서버 구성을 사용자 지정할 수 있습니다. 예를 들어 `--tensor-parallel-size`, `--data-parallel-size`, `--max-model-len`, `--enable-prefix-caching`, `--enforce-eager`, `--kv-cache-dtype` 또는 `--trust-remote-code`를 사용할 수 있습니다. 전체 목록을 보려면 `vllm serve --help`를 실행하세요.

TRL에서 요구하는 것은 다음 항목뿐입니다:

| 설정 | 왜 |
| --- | --- |
| `VLLM_SERVER_DEV_MODE=1` | 서버로 학습 가중치를 푸시하는 데 사용되는 weight-transfer 및 prefix-cache 엔드포인트를 노출합니다. 또한 vLLM의 기타 개발용 엔드포인트도 노출하므로, 서버를 신뢰할 수 있는 네트워크에 유지하세요. |
| `--weight-transfer-config '{"backend": "nccl"}'` | NCCL 가중치 전송 엔진을 활성화합니다. 트레이너와 서버가 GPU를 공유하는 경우 대신 `"ipc"`를 사용하세요. |
| `--logprobs-mode processed_logprobs` | logprobs는 temperature scaling과 logit 처리 이후의 값으로, importance sampling 보정이 기대하는 형태입니다. |
| `--max-logprobs -1` | 토큰당 20개인 OpenAI 호환 logprobs 상한을 해제하여, 증류에 필요한 top-k teacher 분포를 요청할 수 있습니다. |
| `--enable-scale-out` | 멀티모달 프롬프트와 `--return-sampling-mask`의 경우 vLLM 0.30.0 이상에서만 지원됩니다. 해당 버전에서는 `/v1/chat/completions/render`와 `/inference/v1/generate`가 등록되며, 트레이너가 이미지를 처리하고 각 샘플링된 토큰의 후보 집합을 가져오도록 합니다. 이전 버전에서는 이 플래그를 거부합니다. |

> [!WARNING]
> `trl vllm-serve`는 더 이상 사용되지 않습니다: 이제 이 명령만 빌드하고 vLLM 서버를 실행합니다. 실행하는 `vllm serve` 명령을 정확히 출력하므로, 이를 복사하여 래퍼를 제거할 수 있습니다.

### 💆🏻‍♀️ 최적의 분산 설정은 무엇인가요?

`--tensor-parallel-size`를 사용하여 생성을 확장하세요. 데이터 병렬성은 더 이상 dense 모델에 도움이 되지 않습니다. [vLLM PR #30739](https://github.com/vllm-project/vllm/pull/30739)(`0.14.0`에서 릴리스됨) 이후, non-MoE 모델에 대한 오프라인 데이터 병렬 확장은 지원되지 않습니다.

### Transformers 백엔드를 사용한 vLLM

vLLM은 LLM과 VLM 모두에 적용되는 모델 구현을 위해 **Transformers 백엔드**를 사용할 수 있습니다. 이를 활성화하려면 구성에서 `vllm_model_impl="transformers"`를 설정하거나 커맨드라인 인자로 전달하세요.

자세한 내용은 [vLLM Transformers Backend](https://blog.vllm.ai/2025/04/11/transformers-backend.html)를 확인하세요.

예:

```sh
CUDA_DEVICE_ORDER=PCI_BUS_ID CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-VL-3B-Instruct \
    --tensor-parallel-size 1 --port 8000 --enforce-eager --model-impl transformers \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1 \
    --enable-scale-out  # vLLM 0.30.0 and later, drop on earlier versions
```

### 학습 중 vLLM 사용 모드

TRL은 학습 중 vLLM을 통합하기 위한 **두 가지 모드**를 지원합니다: **colocate 모드**(기본값)와 **server 모드**입니다.

#### Colocate 모드

**colocate mode**에서는 vLLM이 trainer 프로세스 내에서 실행되며 학습 모델과 GPU 메모리를 공유합니다. 이를 통해 별도의 서버를 시작할 필요가 없으며 GPU 활용도를 높일 수 있지만, 학습 GPU에서 메모리 경쟁이 발생할 수 있습니다. 이 모드가 기본 모드입니다.

예시 구성:

```python
from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)
```

```python
from trl.experimental.online_dpo import OnlineDPOConfig

training_args = OnlineDPOConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)
```

```python
from trl import RLOOConfig

training_args = RLOOConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)
```

#### 서버 모드

**서버 모드**에서는 vLLM이 전용 GPU에서 별도의 프로세스로 실행되며 HTTP를 통해 트레이너와 통신합니다. 추론에 전용으로 할당된 GPU가 있는 경우 이 구성이 이상적입니다.

예시 구성:

```python
from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_vllm=True,
    vllm_mode="server",
)
```

```python
from trl.experimental.online_dpo import OnlineDPOConfig

training_args = OnlineDPOConfig(
    ...,
    use_vllm=True,
    vllm_mode="server",
)
```

```python
from trl import RLOOConfig

training_args = RLOOConfig(
    ...,
    use_vllm=True,
    vllm_mode="server",
)
```

> [!WARNING]
> vLLM 사용 및 매개변수에 대한 구체적인 세부 사항은 사용 중인 trainer의 문서를 확인하세요.

> [!WARNING]
> vLLM 실행 시 GPU 메모리 사용량을 줄이려면 [vLLM sleep mode 활성화](reducing_memory_usage#vllm-sleep-mode)를 고려해 보세요.

