TRL documentation

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

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

Harbor, 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'ne bakın.

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, environment_factory yuvası üzerinden ortam tabanlı eğitimi destekler — genel sözleşme için 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

pip install trl[harbor]

Harbor, üretimi vLLM üzerinden gerçekleştirir ve vllm ile transformers>=5.2.0 gerektiren environment_factory kullanır.

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:

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:

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 ü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: Harbor doğrulayıcısının rollout başına 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ı):

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

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) 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/ altında yer alır:

  • jupyter/ (JupyterEnv) — durumlu bir Python çekirdeği (değişkenler hücreler arasında kalıcıdır) + bir kabuk aracı.
  • terminal_notes/ (TerminalNotesEnv) — 6 kabuk aracı (arka plan süreçleri dahil) + 4 araçlı kalıcı not seti.
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 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:

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:

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 içinde çalıştırılmasıyla bir kez hesaplanır. Özel bir ödül için standart bir TRL ödül fonksiyonu yazın:

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

API

sınıf trl.experimental.harbor.HarborSpec

< >

( dataset: stragent: str | type[HarborEnv] = 'bash'environment_type: str = 'docker'num_tasks: int | None = Noneindices: list[int] | None = Noneinclude_metadata: bool = True )

Parametreler

  • dataset (str) — 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ını içeren bir dizine yerel 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 agent / harness — yani env'in açığa çıkardığı araç yüzeyi. Şunlardan biri: yerleşik bir ad ("bash"), bir import yolu "package.module:ClassName", bir dosya yolu "path/to/file.py:ClassName" veya doğrudan bir 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şlemlerini 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ı) — Sıralı görev listesine giren belirli görev indeksleri. num_tasks ile birbirini dışlar.
  • 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 ekler.

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

sınıf trl.experimental.harbor.HarborEnv

< >

( environment_type: str = 'docker' )

Parametreler

  • environment_type (str, isteğe bağlı, varsayılan "docker") — Harbor sandbox arka ucu, Harbor'a iletilir ("docker", "e2b", "daytona", …).

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 başına sürdüğü 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 (doğrulayıcıyı, rollout sonrasında, tembelce bir kez çalıştır).

sınıf trl.experimental.harbor.HarborBashEnv

< >

( environment_type: str = 'docker' )

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

bash

< >

( command: str )

Parametreler

  • command — Çalıştırılacak kabuk komutu.

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 "<value>" > /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 ve sandbox sağlama, üretim partisi genelinde sıralı 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

Update on GitHub