# Ortamlarla LLM'leri Eğitmek İçin Harbor Entegrasyonu

[Harbor](https://www.harborframework.com), ajanik görevlerin kum havuzlarında (sandbox) çalıştırılması için bir çerçevedir. Bir **görevi** (talimat + kum havuzu görüntüsü + doğrulayıcı), bir **iskelet/ajanı** (araç yüzeyi + döngü) ve bir **kum havuzunu** (`docker`, `e2b`, `daytona`, `gke`, …) birbirinden ayırarak bunların serbestçe karıştırılmasına olanak tanır. Bu durum, onu pekiştirmeli öğrenme (RL) için doğal bir uyum haline getirir: aynı görev seti, farklı araç yüzeyleriyle ve tercih ettiğiniz herhangi bir kum havuzu altyapısında eğitilebilir.

Bu kılavuz, **Harbor'ın TRL ile nasıl entegre edileceğini** kapsar. Harbor'ın kendisi için [Harbor belgeleri](https://www.harborframework.com/docs)'ne bakın.

> [!NOTE]
> Entegrasyon `trl.experimental.harbor` konumundadır ve `trl[harbor]` ek özelliğiyle (lazy-import — kullanıcı olmayanlar hiçbir şey ödemez) sınırlıdır.

## Harbor ortamlarının ne zaman kullanılacağı

[GRPOTrainer](/docs/trl/v1.18.2/tr/grpo_trainer#trl.GRPOTrainer), `environment_factory` yuvası üzerinden ortam tabanlı eğitimi destekler — genel sözleşme için [OpenEnv](openenv)'e bakın. Bir **Harbor görev seti** üzerinde eğitim almak istediğinizde Harbor'u kullanın: görevlerin oluşturduğu bir dizin ağacı, her biri kendi içinde bağımsız bir kum havuzu + doğrulayıcı (örneğin, modelin kum havuzundaki dosyaları keşfedip bir değerlendiricinin kontrol ettiği bir yanıt yazdığı veri analizi ajanı seti).

## Kurulum

```bash
pip install trl[harbor]
```

> [!IMPORTANT]
> Harbor, üretimi vLLM üzerinden gerçekleştirir ve `vllm` ile `transformers>=5.2.0` gerektiren `environment_factory` kullanır.
>
> ```bash
> pip install vllm
> ```

Bu, `harbor` çerçevesini (Python >= 3.12) yükler. Entegrasyon, `harbor` kütüphanesini tembelce (lazy) içe aktarır ve onu **süreç içinde** çalıştırır; bu nedenle `trl.experimental.harbor` bileşenine dokunmayan kullanıcılar etkilenmez.

Bir sandbox backend'inin de eğitim sırasında yüklü ve erişilebilir olması gerekir. Harbor, bulut backend'lerini kendi extras'larının arkasında tutar, bu nedenle kullanmayı planladığınızı yükleyin ve kimlik bilgilerini sağlayın:

```bash
pip install "harbor[e2b]"      # E2B cloud sandbox  -> environment_type="e2b",  needs E2B_API_KEY
# docker backend (environment_type="docker", Harbor's default) just needs a reachable Docker daemon
```

## Hızlı başlangıç

`HarborSpec`, Harbor görev setini TRL eğitimcisinin üç yuvasına — `train_dataset`, `environment_factory`, `reward_funcs` — bağlar; bu yuva adlarıyla birebir eşleşen özellikler sunar:

```python
from trl import GRPOConfig, GRPOTrainer
from trl.experimental.harbor import HarborSpec

spec = HarborSpec("AdithyaSK/data_agent_rl_environment_train", agent="bash", num_tasks=64)

trainer = GRPOTrainer(
    model="Qwen/Qwen3-4B",
    args=GRPOConfig(
        num_generations=8,
        max_steps=50,
        max_tool_calling_iterations=25,
        log_completions=True,
    ),
    train_dataset=spec.train_dataset,
    environment_factory=spec.environment_factory,
    reward_funcs=spec.reward_funcs,
)
trainer.train()
```

Arka planda `HarborSpec`, ilk erişimde tembel olarak üç şey yapar:

1. **`spec.train_dataset`**: görev paketini yerel görev dizinlerine çözer (gerekirse HF veri setini indirir) ve `prompt` (boş — env'in talimatı `reset` sırasında eklenir), `task_dir`, `task_index` ile görev başına `task.toml` meta veri sütunlarını içeren bir `datasets.Dataset` oluşturur.
2. **`spec.environment_factory`**: her rollout için taze bir [HarborEnv](/docs/trl/v1.18.2/tr/harbor#trl.experimental.harbor.HarborEnv) üreten, argüman almayan çağrılabilir bir nesne döndürür. `reset(task_dir)` çağrısında görevin Harbor kum havuzunu başlatır ve talimatını döndürür; araç yöntemleri kum havuzuna komut çalıştırır; `env.reward`, rollout tamamlandıktan sonra doğrulayıcıyı bir kez çalıştırır.
3. **`spec.reward_funcs`**: her rollout için Harbor doğrulayıcısının skaler değerini okuyan bir sonuç ödülü.

## Veri seti

`dataset`, bir Harbor görev ağacı içeren bir Hugging Face veri seti deposu kimliği veya `tasks/` alt ağacı içeren yerel bir yoldur. Her görev bir dizindir:

```
tasks/<task_id>/
├── instruction.md          # the task prompt (returned by reset)
├── task.toml               # config + metadata (gold answer, difficulty, ...)
├── environment/            # Dockerfile (+ any pre-agent data hooks)
└── tests/                  # test.sh / grader → writes the reward
```

`num_tasks` veya `indices` ile bir alt küme seçin (karşılıklı dışlayıcı):

```python
spec = HarborSpec("AdithyaSK/data_agent_rl_environment_train", num_tasks=10)        # first 10
spec = HarborSpec("AdithyaSK/data_agent_rl_environment_train", indices=[0, 5, 13])  # specific
```

## Ajanlar: harici ve kurulu

Harbor, bir ajanın bir görevi yürütmesinin iki yolunu destekler ve bu ayrım, RL ile neyin eğitilebileceğini belirler:

- [**Dış ajanlar**](https://www.harborframework.com/docs/agents#external-agents) *sandbox dışında* çalışır ve döngüyü kendileri yönetir, Harbor'un ortam arayüzü üzerinden konteynere komutlar gönderirler ("genellikle `exec` yöntemiyle bash komutları çalıştırarak"). Ajan her eylemi kendisi belirler ve her sonucu yorumlar; sandbox yalnızca çalıştırır.
- [**Yüklü ajanlar**](https://www.harborframework.com/docs/agents#installed-agents) *konteyner görüntüsüne* yüklenir ve orada başsız bir alt süreç olarak çalışır (`BaseInstalledAgent` sınıfını genişletir). Harbor, ajanı kum havuzunun içinde başlatır ve ardından yörünge dosyasını ayrıştırır (`populate_context_post_run`); ajan kendi çıkarımını kullanarak otonom olarak çalışır.

**TRL entegrasyonu, dış ajan desenidir ve şu an için yalnızca bu desen desteklenmektedir.** RL eğitimi, eğitimcinin rollout'u tur tur yönlendirmesini gerektirir: *eğitilen politika modeli* her turu üretir ve TRL, token'larını ve log-olasılıklarını yakalayıp ortam maskesini uygular — bu, `environment_factory`'nin siyah kutu bir `rollout_func` üzerinde sağladığı şeydir. Kurulu bir ajan buna karşı saydam değildir: *kendi* modeliyle konteynerin içinde çalışır ve yalnızca olaydan sonra bir yörünge yayar; bu nedenle eğitimcinin optimize edebileceği politika token'ları veya log-olasılıkları yoktur ve eğitimdeki model asla çağrılmaz. Dolayısıyla bir [HarborEnv](/docs/trl/v1.18.2/tr/harbor#trl.experimental.harbor.HarborEnv) bir dış ajandır — araç yöntemleri `exec` ile sandbox'a çalışır, ancak döngü ve eğitimdeki model TRL'de kalır.

## Temel ajanın (iskeletin) seçimi

**Temel ajan** iskelettir — env hangi araç yöntemlerini açığa vurur ve nasıl gönderir. `agent=` ile seçin:

```python
HarborSpec(dataset, agent="bash")                          # built-in single-bash-tool harness
HarborSpec(dataset, agent="my_pkg.harnesses:JupyterEnv")   # import path to your HarborEnv subclass
HarborSpec(dataset, agent="path/to/harness.py:JupyterEnv") # file path to your HarborEnv subclass
HarborSpec(dataset, agent=MyHarborEnv)                     # a HarborEnv subclass directly
```

Yerleşik `"bash"` iskeleti ([HarborBashEnv](/docs/trl/v1.18.2/tr/harbor#trl.experimental.harbor.HarborBashEnv)) tek bir `bash` aracı sunar ve `/workdir/answer.txt` dosyasına yazarak gönderim yapar. Daha zengin iki iskelet örnek olarak, her biri kendi klasöründe ve araçlarını listeleyen bir README ile birlikte, [`examples/grpo_harbor/harnesses/`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor/harnesses) altında yer alır:

- [`jupyter/`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor/harnesses/jupyter) (`JupyterEnv`) — durumlu bir Python çekirdeği (değişkenler hücreler arasında kalıcıdır) + bir kabuk aracı.
- [`terminal_notes/`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor/harnesses/terminal_notes) (`TerminalNotesEnv`) — 6 kabuk aracı (arka plan süreçleri dahil) + 4 araçlı kalıcı not seti.

```python
HarborSpec(dataset, agent="examples/grpo_harbor/harnesses/jupyter/env.py:JupyterEnv")
HarborSpec(dataset, agent="examples/grpo_harbor/harnesses/terminal_notes/env.py:TerminalNotesEnv")
```

Kendi harness'inizi yazmak için [HarborEnv](/docs/trl/v1.18.2/tr/harbor#trl.experimental.harbor.HarborEnv) sınıfından türetin ve tool metodları ekleyin — her public metod bir tool olur (TRL bunları `inspect.getmembers` ile keşfeder), bu yüzden her birine tip işaretli bir imza ve docstring verin (tool şemasını oluşturmak için kullanılır). Yardımcı metodları alt çizgiyle başlatın. Sandbox içinde shell komutları çalıştırmak için `self._exec(cmd)` kullanın ve görev talimatına harness yönergelerini eklemek için `PROMPT_SUFFIX` değerini ayarlayın:

```python
from trl.experimental.harbor import HarborEnv

class GrepEnv(HarborEnv):
    PROMPT_SUFFIX = "\n\nUse `grep` and `read_file`. Submit by writing /workdir/answer.txt."

    def grep(self, pattern: str, path: str) -> str:
        """Search for `pattern` under `path`.

        Args:
            pattern: The regex to search for.
            path: The file or directory to search.
        """
        return self._exec(f"grep -rn {pattern!r} {path!r}")
```

## Sandbox arka ucu

`environment_type`, TRL tarafından doğrulanmadan doğrudan Harbor'a iletilir:

```python
HarborSpec(dataset, environment_type="e2b")   # cloud sandbox (offloads provisioning), needs E2B_API_KEY
HarborSpec(dataset, environment_type="docker")  # default; needs a local Docker daemon
```

Küme eğitimi için `e2b` önerilir: yalnızca `environment.exec` bulut kum havuzuna geçer, bu sayede GPU'lar politika için ayrılmış kalır ve birçok rollout eşzamanlı olarak çalıştırılabilir.

## Ödül işlevleri

`spec.reward_funcs` varsayılan olarak bir sonuç ödülüdür — her rollout için Harbor doğrulayıcısının skalerini (`env.reward`) okur; bu değer, rollout tamamlandıktan sonra görevin `tests/` doğrulayıcısının sandbox'ta çalıştırılmasıyla bir kez hesaplanır. Özel bir ödül için standart bir TRL ödül fonksiyonu yazın:

```python
def my_reward(environments, **kwargs) -> list[float]:
    return [env.reward for env in environments]
```

## API[[trl.experimental.harbor.HarborSpec]]

#### trl.experimental.harbor.HarborSpec[[trl.experimental.harbor.HarborSpec]]

```python
trl.experimental.harbor.HarborSpec(dataset: str, agent: str | type[HarborEnv] = 'bash', environment_type: str = 'docker', num_tasks: int | None = None, indices: list[int] | None = None, include_metadata: bool = True)
```

[Kaynak](https://github.com/huggingface/trl/blob/v1.18.2/trl/experimental/harbor/_spec.py#L113)

**Parametreler:**

dataset (`str`) : Bir Harbor görev ağacı içeren bir Hugging Face veri seti deposu kimliği (ör. `"AdithyaSK/data_agent_rl_environment_train"`) veya `tasks/` alt ağacı içeren bir dizine yerel bir yol. Her görev, `instruction.md` / `task.toml` / `environment/` / `tests/` içeren bir dizindir.

agent (`str` veya `type`, *isteğe bağlı*, varsayılan `"bash"`) : Temel ajan / iskelet — yani env'in açığa çıkardığı araç yüzeyi. Şunlardan biri: yerleşik bir ad (`"bash"`), bir içe aktarma yolu `"package.module:ClassName"`, bir dosya yolu `"path/to/file.py:ClassName"` veya doğrudan bir [HarborEnv](/docs/trl/v1.18.2/tr/harbor#trl.experimental.harbor.HarborEnv) alt sınıfı.

environment_type (`str`, *isteğe bağlı*, varsayılan `"docker"`) : Harbor sandbox arka ucu, Harbor'a iletilir (desteklediği her şey — `"docker"`, `"e2b"`, `"daytona"`, `"gke"`, `"modal"`, `"runloop"`, ...). Burada doğrulanmaz; Harbor doğrular. `"docker"`, Harbor'ın kendi varsayılanıdır; sandbox işini buluta devretmek için `"e2b"` seçin.

num_tasks (`int`, *isteğe bağlı*) : Veri setine çekilen görev sayısının üst sınırı. `None`, ağaçtaki tüm görevleri kullanır.

indices (`list[int]`, *isteğe bağlı*) : Belirli görev dizinleri (sıralı görev listesine göre). `num_tasks` ile karşılıklı olarak dışlayıcıdır.

include_metadata (`bool`, *isteğe bağlı*, varsayılan `True`) : Görev başına `task.toml` meta verilerini (gold_answer, difficulty, ...) veri seti satırlarına katlar.

Bir Harbor görev süitini bir TRL eğitimcisine bağlayan tek bir spec nesnesi.

#### trl.experimental.harbor.HarborEnv[[trl.experimental.harbor.HarborEnv]]

```python
trl.experimental.harbor.HarborEnv(environment_type: str = 'docker')
```

[Kaynak](https://github.com/huggingface/trl/blob/v1.18.2/trl/experimental/harbor/_env.py#L37)

**Parametreler:**

environment_type (`str`, *isteğe bağlı*, varsayılan `"docker"`) : Harbor kum havuzu arka ucu, Harbor'a (`"docker"`, `"e2b"`, `"daytona"`, ...) iletilir.

Harbor kum havuzu + doğrulayıcı tarafından desteklenen temel TRL ortamı.

Alt sınıflar, araç yöntemlerini (iskeleti) tanımlar. TRL'nin her rollout için yönettiği yaşam döngüsü: `reset(task_dir)` (görevin kum havuzunu başlat, talimatını döndür) -> araç yöntemleri (kum havuzuna komut çalıştır) -> `reward` (rollout sonrasında doğrulayıcıyı bir kez, tembelce çalıştır).

#### trl.experimental.harbor.HarborBashEnv[[trl.experimental.harbor.HarborBashEnv]]

```python
trl.experimental.harbor.HarborBashEnv(environment_type: str = 'docker')
```

[Kaynak](https://github.com/huggingface/trl/blob/v1.18.2/trl/experimental/harbor/_env.py#L210)

Tek `bash` aracı iskeleti; `/workdir/answer.txt` dosyasına yazarak gönderin.

#### bash[[trl.experimental.harbor.HarborBashEnv.bash]]

```python
bash(command: str)
```

[Kaynak](https://github.com/huggingface/trl/blob/v1.18.2/trl/experimental/harbor/_env.py#L215)

**Parametreler:**

command : Çalıştırılacak kabuk komutu.

**Dönüş:**

Komutun birleştirilmiş stdout ve stderr çıktısı.

Sandbox içinde bir shell komutu çalıştırın ve birleşik stdout+stderr çıktısını döndürün. Shell, çağrılar arasında durum tutmaz. Dosyaları keşfetmek (ls, head, cat), Python çalıştırmak (`python3 -c "..."`) ve cevabı göndermek (`echo -n "" > /workdir/answer.txt`) için kullanın.

## Kısıtlamalar

- Entegrasyon `trl.experimental` içinde — API'ler değişebilir. CI günlüklerindeki uyarıyı susturmak için `TRL_EXPERIMENTAL_SILENCE=1` değerini ayarlayın.
- Harbor'ın asenkron sandbox istemcisi tek bir olay döngüsüne bağlıdır, bu nedenle her env kendi döngüsünde start/exec/verify işlemlerini senkron olarak yürütür; dolayısıyla sandbox sağlama, üretim partisi boyunca ardışık olarak gerçekleşir (bulut altyapıları gibi `e2b` gibi altyapılar, sandbox başına maliyeti azaltır).
- Tek bir `HarborSpec`, bir görev seti + bir test çerçevesi (harness) kapsamındadır; çoklu set eğitimi henüz desteklenmemektedir.

## Referans

- [Harbor çerçevesi](https://www.harborframework.com)
- [Harbor RL eğitim belgeleri](https://www.harborframework.com/docs/training-workflows/rl)

