Integrasi Harbor untuk Pelatihan LLM dengan Lingkungan

Harbor adalah kerangka kerja untuk menjalankan tugas agentic di dalam sandbox. Kerangka ini memisahkan tugas (instruksi + image sandbox + verifier), harness/agent (permukaan alat + loop), dan sandbox (docker, e2b, daytona, gke, …) sehingga ketiganya dapat dicampur secara bebas. Hal ini menjadikannya pilihan yang alami untuk RL: suite tugas yang sama dapat dilatih dengan permukaan alat yang berbeda, di backend sandbox mana pun yang Anda pilih.

Panduan ini membahas bagaimana mengintegrasikan Harbor dengan TRL. Untuk Harbor itu sendiri, lihat dokumentasi Harbor.

Integrasi ini berada di trl.experimental.harbor dan diaktifkan melalui ekstra trl[harbor] (diimpor secara lazy — pengguna yang tidak memakainya tidak menanggung biaya apa pun).

Kapan menggunakan lingkungan Harbor

GRPOTrainer mendukung pelatihan berbasis lingkungan melalui slot environment_factory — lihat OpenEnv untuk kontrak umum. Gunakan Harbor ketika Anda ingin melatih terhadap Harbor task suite: sebuah struktur direktori tugas, di mana masing-masing tugas merupakan sandbox + verifier yang mandiri (misalnya, suite agen analisis data di mana model menjelajahi file dalam sandbox dan menulis jawaban yang diperiksa oleh grader).

Instalasi

pip install trl[harbor]

Harbor menggerakkan generasi melalui vLLM dan menggunakan environment_factory, yang membutuhkan vllm dan transformers>=5.2.0.

Disalin

pip install vllm

Ini menginstal kerangka kerja harbor (Python >= 3.12). Integrasi ini mengimpor harbor secara lambat dan menjalankannya dalam proses, sehingga pengguna yang tidak menyentuh trl.experimental.harbor tidak terpengaruh.

Backend sandbox juga harus diinstal dan dapat diakses saat pelatihan. Harbor menyimpan backend cloud di balik extras-nya sendiri, jadi instal yang ingin Anda gunakan dan sediakan kredensialnya:

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

Mulai cepat

HarborSpec menghubungkan satu suite tugas Harbor ke tiga slot trainer TRL — train_dataset, environment_factory, reward_funcs — dengan mengekspos properti yang memetakan 1:1 ke nama kwarg tersebut:

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

Di balik layar, HarborSpec melakukan tiga hal, secara malas (lazy) pada akses pertama:

1. spec.train_dataset: menyelesaikan task suite menjadi direktori task lokal (mengunduh dataset HF jika diperlukan) dan membangun datasets.Dataset dengan prompt (kosong — instruksi env ditambahkan saat reset), task_dir, task_index, serta kolom metadata task.toml per-task.
2. spec.environment_factory: mengembalikan callable tanpa argumen yang menghasilkan HarborEnv baru untuk setiap rollout. Pada reset(task_dir), metode ini memulai sandbox Harbor untuk tugas tersebut dan mengembalikan instruksinya; metode tool mengeksekusi perintah ke dalam sandbox; env.reward menjalankan verifier sekali setelah rollout selesai.
3. spec.reward_funcs: reward hasil yang membaca skalar per rollout dari verifier Harbor.

Dataset

dataset adalah id repo dataset Hugging Face yang berisi pohon tugas Harbor, atau path lokal yang berisi subpohon tasks/. Setiap tugas adalah sebuah direktori:

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

Pilih subset dengan num_tasks atau indices (saling eksklusif):

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

Agen: eksternal vs terinstal

Harbor mendukung dua cara agen menjalankan tugas, dan pembeda ini menentukan apa yang dapat dilatih dengan RL:

• Agen eksternal berjalan di luar sandbox dan menggerakkan loop secara mandiri, menerbitkan perintah ke dalam container melalui antarmuka lingkungan Harbor (“biasanya dengan mengeksekusi perintah bash melalui metode exec”). Agen menentukan setiap tindakan dan menafsirkan setiap hasil; sandbox hanya mengeksekusi.
• Agent yang terpasang dipasang ke dalam image container dan dijalankan di sana sebagai subprocess headless (memperluas BaseInstalledAgent). Harbor meluncurkan agent di dalam sandbox dan kemudian mem-parsing file trajectory-nya (populate_context_post_run); agent berjalan secara otonom dengan inferensinya sendiri.

Integrasi TRL adalah pola agen eksternal, dan hanya pola tersebut yang didukung untuk saat ini. Pelatihan RL membutuhkan trainer untuk menggerakkan rollout per giliran: model kebijakan yang sedang dilatih menghasilkan setiap giliran, dan TRL menangkap token serta log-prob-nya lalu menerapkan mask lingkungan — persis apa yang disediakan oleh environment_factory di atas rollout_func yang bersifat black-box. Agen yang terpasang bersifat tidak transparan terhadap hal ini: ia berjalan di dalam container dengan model nya sendiri dan hanya mengeluarkan trajektori setelahnya, sehingga tidak ada token kebijakan atau log-prob untuk dioptimalkan oleh trainer, dan model yang sedang dilatih tidak pernah dipanggil. Oleh karena itu, HarborEnv adalah agen eksternal — metode tool-nya exec ke dalam sandbox, tetapi loop, dan model yang sedang dilatih, tetap berada di TRL.

Memilih agen dasar (harness)

agen dasar adalah kerangka kerja — metode alat apa yang diungkap oleh env dan bagaimana ia mengirimkannya. Pilihnya dengan agent=:

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

Harness "bash" bawaan (HarborBashEnv) mengekspos satu tool bash dan mengirim jawaban dengan menulis ke /workdir/answer.txt. Dua harness yang lebih kaya disertakan sebagai contoh — masing-masing dalam folder tersendiri dengan README yang mencantumkan tool-nya — di bawah examples/grpo_harbor/harnesses/:

• jupyter/ (JupyterEnv) — kernel Python berstatus (variabel tetap tersimpan antar sel) + alat shell.
• terminal_notes/ (TerminalNotesEnv) — 6 alat shell (termasuk proses latar belakang) + toolkit catatan persisten 4-alat.

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

Untuk menulis harness Anda sendiri, subclass HarborEnv dan tambahkan metode tool — setiap metode publik menjadi sebuah tool (TRL menemukannya dengan inspect.getmembers), jadi berikan setiap metode signature bertipe dan docstring (digunakan untuk membangun skema tool). Pertahankan helper dengan awalan underscore. Gunakan self._exec(cmd) untuk menjalankan perintah shell di dalam sandbox, dan atur PROMPT_SUFFIX untuk menambahkan panduan harness ke instruksi tugas:

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}")

Backend sandbox

environment_type diteruskan langsung ke Harbor (tidak divalidasi oleh TRL):

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

e2b direkomendasikan untuk pelatihan klaster: hanya environment.exec yang menyeberang ke sandbox cloud, sehingga GPU tetap didedikasikan untuk kebijakan dan Anda dapat menjalankan banyak rollout secara bersamaan.

Fungsi reward

spec.reward_funcs secara default menggunakan reward hasil akhir — untuk setiap rollout, ia membaca skalar dari verifier Harbor (env.reward), yang dihitung sekali setelah rollout dengan menjalankan verifier tests/ dari tugas tersebut di dalam sandbox. Untuk reward kustom, tulis fungsi reward TRL biasa:

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

API

Keterbatasan

• Integrasi ini ada di trl.experimental — API dapat berubah. Atur TRL_EXPERIMENTAL_SILENCE=1 untuk membisukan peringatan di log CI.
• Klien sandbox asinkron Harbor terikat pada satu event loop, sehingga setiap env menjalankan start/exec/verify secara sinkron pada loop-nya sendiri; provisioning sandbox karenanya bersifat berurutan di seluruh batch generasi (backend cloud seperti e2b memitigasi biaya per-sandbox).
• Satu HarborSpec mencakup satu suite tugas + satu harness; pelatihan multi-suite belum didukung.

Referensi

• Framework Harbor
• Dokumen pelatihan RL Harbor