TRL documentation
Ortamlarla LLM'leri Eğitmek İçin Harbor Entegrasyonu
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.harborkonumundadır vetrl[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
vllmiletransformers>=5.2.0gerektirenenvironment_factorykullanı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 daemonHı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:
spec.train_dataset: görev paketini yerel görev dizinlerine çözer (gerekirse HF veri setini indirir) veprompt(boş — env'in talimatıresetsırasında eklenir),task_dir,task_indexile görev başınatask.tomlmeta veri sütunlarını içeren birdatasets.Datasetoluşturur.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.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 rewardnum_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]) # specificAjanlar: 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
execyö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 (
BaseInstalledAgentsı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 directlyYerleş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 daemonKü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
< source >( 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") veyatasks/alt ağacını içeren bir dizine yerel yol. Her görev,instruction.md/task.toml/environment//tests/içeren bir dizindir. - agent (
strveyatype, 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_tasksile birbirini dışlar. - include_metadata (
bool, isteğe bağlı, varsayılanTrue) — Görev başınatask.tomlmeta 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
< source >( environment_type: str = 'docker' )
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).
Tek bash aracı iskeleti; /workdir/answer.txt dosyasına yazarak gönderin.
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.experimentaliçinde — API'ler değişebilir. CI günlüklerindeki uyarıyı susturmak içinTRL_EXPERIMENTAL_SILENCE=1değ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
e2bgibi 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.