# vLLM Entegrasyonu

Bu belge, GRPO ve Online DPO gibi çevrimiçi yöntemlerde daha hızlı üretim için vLLM'i TRL ile nasıl kullanacağınız konusunda sizi adım adım yönlendirecektir. Önce vLLM'in TRL ile nasıl kullanılacağına dair kısa bir özet (tl;dr) sunacağız, ardından bunun arka planda nasıl çalıştığına dair detaylara gireceğiz.

> [!WARNING]
> TRL şu anda yalnızca `0.23.0` ile `0.33.x` arasındaki vLLM sürümlerini desteklemektedir. Uyumluluk sorunlarını önlemek için bu aralıkta bir sürümün yüklü olduğundan emin olun.

> [!TIP]
> Aşağıdaki eğitimciler şu anda vLLM ile üretimi desteklemektedir:
>
> - [GRPOTrainer](/docs/trl/v1.18.2/tr/grpo_trainer#trl.GRPOTrainer) - [RLOOTrainer](/docs/trl/v1.18.2/tr/rloo_trainer#trl.RLOOTrainer) - [experimental.online_dpo.OnlineDPOTrainer](/docs/trl/v1.18.2/tr/online_dpo_trainer#trl.experimental.online_dpo.OnlineDPOTrainer)

## 🚀 TRL ile vLLM'yi kullanarak eğitimi nasıl hızlandırabilirim?

💡 **Not**: Bu özel örnek için gereken kaynaklar: 8 GPU'lu tek bir düğüm.

> [!WARNING]
> TRL ile vLLM kullanırken, **vLLM sunucusu** ve **eğiticinin** çakışmaları önlemek için **ayrı CUDA cihazlarında** çalışması gerekir. Bunu doğru yapılandırmak için [eğitim sırasında vLLM kullanım modları](#modes-of-using-vllm-during-training) bölümüne bakın.

Öncelikle aşağıdaki komutu kullanarak vLLM'i yükleyin:

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

Ardından sunucuyu belirli GPU'larda (ör. GPU 0-3) çalıştırın:

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

Sunucu çalışmaya başladığında, eğitim için tamamlama üretmek üzere kullanabilirsiniz. Aşağıdaki örnekte, üretim için vLLM sunucusunu kullanarak desteklenen farklı eğitimciler kullanılmaktadır. `--tensor-parallel-size` ve `--data-parallel-size` argümanları, modelin ve verinin GPU'lar arasında nasıl paylaştırılacağını kontrol eder.

Bu örnekte, bir model tensor paralelliği ile 4 GPU arasında bölünür. Ardından, eğitim argümanlarına aşağıdaki gibi `use_vllm=True` geçirerek eğitim betiğini farklı GPU'larda (ör. GPU 4-7) çalıştırın:

Basit bir `train.py` betiğinin örneği:

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

Ve sunucudan ayrı GPU'larda train komutu:

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

## vLLM kullanmanın nedeni

Online yöntemler eğitim sırasında tamamlamalar üretir ve bunları modelin kendi `generate` fonksiyonuyla üretmesi darboğazdır. vLLM, [PagedAttention](https://blog.vllm.ai/2023/06/20/vllm.html) gibi teknikler sayesinde bu tamamlamaları çok daha hızlı sunar.

## TRL sunucuyu nasıl kullanır 🔍

Trainer, OpenAI ile uyumlu `/v1/completions` uç noktasından tamamlamalar ister ve istem (prompt) jeton kimliklerini gönderir. Çok modlu istemler farklı bir yol izler: sunucu, görüntüleri kendi işler ve OpenAI ile uyumlu bir uç nokta hem jeton kimliklerini hem de görüntüleri aynı anda kabul etmediği için, elde edilen özellikler aynı jeton kimlikleriyle `/inference/v1/generate` üzerinde eşleştirilir.

Sunucu yalnızca üretim yapar. Her optimizasyon adımı sonrasında eğitimci, güncellenmiş ağırlıkları NCCL üzerinden sunucuya akıtır; bunları `/start_weight_update` ve `/update_weights` ile duyurur ve `/finish_weight_update` ile onaylar.

## Gelişmiş kullanım

### 🍷 vLLM ile daha fazla özelleştirme seçeneği?

Sunucu yapılandırmasını, `vllm serve` komutuna herhangi bir argüman geçirerek özelleştirebilirsiniz; örneğin `--tensor-parallel-size`, `--data-parallel-size`, `--max-model-len`, `--enable-prefix-caching`, `--enforce-eager`, `--kv-cache-dtype` veya `--trust-remote-code`. Tam liste için `vllm serve --help` komutunu çalıştırın.

TRL tarafından yalnızca aşağıdakiler gereklidir:

| Ayar | Neden |
| --- | --- |
| `VLLM_SERVER_DEV_MODE=1` | Sunucu içine eğitim ağırlıklarını göndermek için kullanılan ağırlık aktarımı ve önek önbelleği uç noktalarını açar. Ayrıca vLLM'in diğer geliştirme uç noktalarını da açtığından, sunucuyu güvendiğiniz bir ağda tutun. |
| `--weight-transfer-config '{"backend": "nccl"}'` | NCCL ağırlık aktarım motorunu etkinleştirir. Eğitmen ve sunucu bir GPU paylaşıyorsa bunun yerine `"ipc"` kullanın. |
| `--logprobs-mode processed_logprobs` | Sıcaklık ölçeklendirmesi ve logit işleme sonrasında logprobs döner; bu, önem örneklemesi düzeltmesinin beklediği değerdir. |
| `--max-logprobs -1` | Token başına 20 logprob ile sınırlı olan OpenAI uyumlu sınırı kaldırır; bu, damıtma için top-k öğretmen dağılımının istenmesi için gereklidir. |
| `--enable-scale-out` | vLLM 0.30.0 ve sonraki sürümler, çok modlu istemler ve yalnızca `--return-sampling-mask` için: eğitimcinin görüntüleri işlemek ve örneklenen her token'ın aday kümesini almak için kullandığı `/v1/chat/completions/render` ve `/inference/v1/generate` uç noktalarını kaydeder. Önceki sürümler bu bayrağı reddeder. |

> [!WARNING]
> `trl vllm-serve` kullanımdan kaldırıldı: artık yalnızca bu komutu oluşturur ve vLLM sunucusunu çalıştırır. Çalıştırdığı tam `vllm serve` komutunu yazdırır, böylece onu kopyalayıp sarmalayıcıyı kaldırabilirsiniz.

### 💆🏻‍♀️ En iyi dağıtık kurulumu hangisidir?

`--tensor-parallel-size` ile üretimi ölçekleyin. Yoğun modeller için veri paralelliği artık işe yaramıyor: [vLLM PR #30739](https://github.com/vllm-project/vllm/pull/30739) (`0.14.0` sürümünde yayımlandı) ile MoE olmayan modeller için çevrimdışı veri paralel ölçekleme desteklenmiyor.

### Transformers Arka Ucu ile vLLM

vLLM, model uygulamaları için **Transformers backend** kullanabilir; bu hem LLM'ler hem de VLM'ler için çalışır. Bunu etkinleştirmek için yapılandırmanızda `vllm_model_impl="transformers"` değerini ayarlayın veya bunu komut satırı argümanı olarak iletin.

Daha fazla ayrıntı için [vLLM Transformers Backend](https://blog.vllm.ai/2025/04/11/transformers-backend.html) sayfasına göz atın.

Örnek:

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

### Eğitim Sırasında vLLM Kullanım Modları

TRL, eğitim sırasında vLLM entegrasyonu için **iki modu** destekler: **colocate modu** (varsayılan) ve **server modu**.

#### Colocate Modu

**colocate modu**nda vLLM, eğitimci sürecinin içinde çalışır ve eğitim modeliyle GPU belleğini paylaşır. Bu, ayrı bir sunucu başlatmayı önler ve GPU kullanımını artırabilir, ancak eğitim GPU'larında bellek çakışmasına yol açabilir. Bu, varsayılan moddur.

Örnek yapılandırma:

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

#### Sunucu Modu

**sunucu modunda**, vLLM ayrı bir süreç olarak özel GPU'larda çalışır ve eğitimciyle HTTP üzerinden iletişim kurar. Bu yapı, çıkarım için ayrılmış GPU'larınız varsa idealdir.

Örnek yapılandırma:

```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 kullanımı ve parametrelerine ilişkin ayrıntılar için kullandığınız trainer'ın dokümantasyonunu kontrol edin.

> [!WARNING]
> vLLM çalıştırırken GPU bellek kullanımını azaltmak için [vLLM uyku modunu etkinleştirmeyi](reducing_memory_usage#vllm-sleep-mode) düşünün.

