TRL documentation

환경을 활용한 LLM 학습을 위한 Harbor 통합

You are viewing v1.18.0 version. A newer version v1.18.1 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

환경을 활용한 LLM 학습을 위한 Harbor 통합

Harbor는 샌드박스에서 에이전틱 작업을 실행하기 위한 프레임워크입니다. task(지시사항 + 샌드박스 이미지 + 검증기), harness/agent(도구 표면 + 루프), sandbox(docker, e2b, daytona, gke, …)를 분리하여 자유롭게 조합할 수 있습니다. 이를 통해 RL에 자연스럽게 적용할 수 있으며, 동일한 작업 스위트에 대해 서로 다른 도구 표면과 선호하는 샌드박스 백엔드를 사용하여 학습할 수 있습니다.

이 가이드는 Harbor를 TRL에 통합하는 방법을 다룹니다. Harbor 자체에 대해서는 Harbor 문서를 참고하세요.

통합 코드는 trl.experimental.harbor에 위치하며, trl[harbor] 추가 항목으로 게이트 처리되어 있습니다(레이지 임포트 — 비사용자는 아무 비용도 부담하지 않음).

Harbor 환경을 사용할 때

GRPOTrainer는 environment_factory 슬롯을 통해 환경 기반 학습을 지원합니다. 일반적인 계약은 OpenEnv를 참고하세요. Harbor task suite에 대해 학습하려면 Harbor를 사용하세요. Harbor task suite는 태스크의 디렉터리 트리로, 각 태스크는 자체적인 샌드박스 + 검증기(예: 모델이 샌드박스에서 파일을 탐색하고 채점자가 답을 확인하는 데이터 분석 에이전트 스위트)로 구성됩니다.

설치

pip install trl[harbor]

Harbor는 vLLM을 통해 생성을 구동하며, vllm과 transformers>=5.2.0이 필요한 environment_factory를 사용합니다.

pip install vllm

이 명령은 harbor 프레임워크(Python >= 3.12)를 설치합니다. 이 통합은 harbor를 지연 로드하고 프로세스 내에서 실행하므로, trl.experimental.harbor를 사용하지 않는 사용자에게는 영향을 주지 않습니다.

샌드박스 백엔드도 학습 시점에 설치되어 있어야 하며, 접근이 가능해야 합니다. Harbor는 클라우드 백엔드를 자체 extras 뒤에 유지하므로, 사용할 백엔드를 설치하고 해당 자격 증명을 제공하세요:

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

빠른 시작

HarborSpec는 단일 Harbor 작업 스위트를 TRL 트레이너의 세 슬롯인 train_dataset, environment_factory, reward_funcs에 연결하며, 해당 kwarg 이름과 1:1로 매핑되는 속성을 노출합니다:

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

HarborSpec는 내부적으로 첫 접근 시 지연 실행으로 세 가지 작업을 수행합니다:

  1. spec.train_dataset: 태스크 스위트를 로컬 태스크 디렉터리로 해석합니다(필요한 경우 HF 데이터셋을 다운로드) 그리고 prompt(비어 있음 — env의 지시문은 reset 시점에 추가됨), task_dir, task_index, 그리고 태스크별 task.toml 메타데이터 컬럼을 포함하는 datasets.Dataset를 생성합니다.
  2. spec.environment_factory: 롤아웃마다 새로운 HarborEnv를 생성하는 인자 없는 콜러블을 반환합니다. reset(task_dir) 호출 시 해당 태스크의 Harbor 샌드박스를 시작하고 그 지시문을 반환하며, 도구 메서드는 샌드박스에서 실행됩니다. env.reward는 롤아웃 완료 후 검증기를 한 번 실행합니다.
  3. spec.reward_funcs: Harbor 검증기의 롤아웃별 스칼라 값을 읽는 결과 보상입니다.

데이터셋

dataset은 Harbor 태스크 트리를 포함하는 Hugging Face 데이터셋 저장소 ID이거나, tasks/ 하위 트리를 포함하는 로컬 경로입니다. 각 태스크는 디렉터리입니다:

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 또는 indices(서로 배타적)를 사용하여 부분 집합을 선택합니다:

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

에이전트: 외부 vs 설치

Harbor는 에이전트가 작업을 수행하는 두 가지 방식을 지원하며, 이 구분이 RL로 학습할 수 있는 범위를 결정합니다:

  • 외부 에이전트는 샌드박스 외부에서 실행되며 루프를 직접 제어합니다. Harbor의 환경 인터페이스를 통해 컨테이너에 명령을 발행하며, “일반적으로 exec 메서드를 통해 bash 명령을 실행하는 방식”입니다. 에이전트가 각 행동을 결정하고 각 결과를 해석하며, 샌드박스는 실행만 담당합니다.
  • 설치된 에이전트는 컨테이너 이미지에 설치되어 헤드리스 서브프로세스로 실행됩니다(BaseInstalledAgent 확장). Harbor는 샌드박스 내에서 에이전트를 시작하고, 실행 후 그 트래젝터리 파일을 파싱합니다(populate_context_post_run). 에이전트는 자체 추론을 통해 자율적으로 실행됩니다.

TRL의 통합은 external-agent 패턴이며, 현재 이 패턴만 지원됩니다. RL 학습은 trainer가 rollout를 턴 단위로 직접 제어해야 합니다. 학습 중인 policy model이 각 턴을 생성하고, TRL은 해당 토큰과 log-probs를 수집한 뒤 environment mask를 적용합니다. 이는 black-box rollout_func 위에 environment_factory가 제공하는 것과 정확히 동일한 동작입니다. 설치된 에이전트는 이 과정에 대해 불투명합니다. 컨테이너 내부에서 자체 모델을 사용하여 실행되며, 사후에 trajectory만 출력하므로 trainer가 최적화할 policy 토큰이나 log-probs가 없고, 학습 대상 모델은 호출되지 않습니다. 따라서 HarborEnv는 external agent입니다. 도구 메서드가 exec를 통해 샌드박스에 진입하지만, 루프와 학습 대상 모델은 TRL에 남아 있습니다.

기본 에이전트(하네스) 선택

기본 에이전트는 하네스입니다. env가 어떤 도구 메서드를 노출하고 어떻게 제출하는지를 정의합니다. 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

내장 "bash" 하네스(HarborBashEnv)는 bash 도구 하나를 노출하고 /workdir/answer.txt에 작성하여 제출합니다. 더 풍부한 두 가지 하네스가 예시로 제공되며, 각 하네스는 도구가 나열된 README와 함께 examples/grpo_harbor/harnesses/ 아래에 별도의 폴더로 포함되어 있습니다:

  • jupyter/ (JupyterEnv) — 상태가 유지되는 Python 커널(변수가 셀 간에 유지됨) + 셸 도구.
  • terminal_notes/ (TerminalNotesEnv) — 6개의 셸 도구(백그라운드 프로세스 포함) + 4개 도구로 구성된 영속적 노트 툴킷.
HarborSpec(dataset, agent="examples/grpo_harbor/harnesses/jupyter/env.py:JupyterEnv")
HarborSpec(dataset, agent="examples/grpo_harbor/harnesses/terminal_notes/env.py:TerminalNotesEnv")

자체 harness를 작성하려면 HarborEnv를 서브클래스로 상속하고 tool 메서드를 추가하세요. 모든 public 메서드가 tool이 되므로(TRL은 inspect.getmembers로 이를 발견합니다), 각 메서드에 타입이 지정된 시그니처와 docstring(tool schema를 구성하는 데 사용됨)을 부여하세요. 헬퍼 메서드는 밑줄로 시작하는 이름을 사용하세요. 샌드박스에서 shell 명령을 실행하려면 self._exec(cmd)를 사용하고, PROMPT_SUFFIX를 설정하여 작업 지침에 harness 지침을 추가하세요:

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

샌드박스 백엔드

environment_type은 TRL에서 검증되지 않고 Harbor로 그대로 전달됩니다:

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는 클러스터 학습에 권장됩니다. environment.exec만 클라우드 샌드박스로 전달되므로 GPU는 정책 학습에 전념할 수 있으며, 여러 롤아웃을 동시에 실행할 수 있습니다.

보상 함수

spec.reward_funcs의 기본값은 결과 보상(outcome reward)입니다. 각 롤아웃마다 Harbor 검증기의 스칼라 값(env.reward)을 읽으며, 이는 롤아웃 완료 후 샌드박스에서 해당 작업의 tests/ 검증기를 실행하여 한 번만 계산됩니다. 사용자 정의 보상을 사용하려면 일반적인 TRL 보상 함수를 작성하세요:

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

API

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

매개변수

  • dataset (str) — Harbor 태스크 트리를 포함하는 Hugging Face 데이터셋 저장소 ID(예: "AdithyaSK/data_agent_rl_environment_train") 또는 tasks/ 서브트리를 포함하는 로컬 디렉터리 경로입니다. 각 태스크는 instruction.md / task.toml / environment/ / tests/를 포함하는 디렉터리입니다.
  • agent (str 또는 type, 선택 사항, 기본값 "bash") — 기본 에이전트/하네스, 즉 env가 노출하는 도구 인터페이스입니다. 다음 중 하나여야 합니다: 내장 이름("bash"), import 경로 "package.module:ClassName", 파일 경로 "path/to/file.py:ClassName", 또는 HarborEnv 하위 클래스를 직접 지정하는 것.
  • environment_type (str, 선택 사항, 기본값 "docker") — Harbor 샌드박스 백엔드로, Harbor로 그대로 전달됩니다(Harbor가 지원하는 값 — "docker", "e2b", "daytona", "gke", "modal", "runloop", …). 여기서는 검증되지 않으며 Harbor에서 검증합니다. "docker"는 Harbor의 기본값입니다. 샌드박싱을 클라우드에 위임하려면 "e2b"를 선택하세요.
  • num_tasks (int, 선택 사항) — 데이터셋에 가져올 작업 수의 상한입니다. None을 사용하면 트리 내의 모든 작업을 사용합니다.
  • indices (list[int], 선택 사항) — 정렬된 작업 목록에 대한 특정 작업 인덱스입니다. num_tasks와 상호 배타적입니다.
  • include_metadata (bool, 선택 사항, 기본값 True) — 태스크별 task.toml 메타데이터(gold_answer, difficulty, …)를 데이터셋 행에 포함합니다.

Harbor 작업 스위트를 TRL 트레이너에 연결하는 단일 spec 객체입니다.

class trl.experimental.harbor.HarborEnv

< >

( environment_type: str = 'docker' )

매개변수

  • environment_type (str, 선택 사항, 기본값 "docker") — Harbor 샌드박스 백엔드로, Harbor에 그대로 전달됩니다("docker", "e2b", "daytona", …).

Harbor 샌드박스 + 검증기로 뒷받침되는 기본 TRL 환경.

Subclasses는 도구 메서드(하네스)를 정의합니다. TRL이 각 rollout마다 구동하는 라이프사이클: reset(task_dir) (작업의 샌드박스를 시작하고 그 지시문을 반환) -> 도구 메서드 (샌드박스로 exec) -> reward (rollout 이후에 검증기를 지연 방식으로 한 번 실행).

class trl.experimental.harbor.HarborBashEnv

< >

( environment_type: str = 'docker' )

bash 단일 도구 하네스; /workdir/answer.txt에 작성하여 제출합니다.

bash

< >

( command: str )

매개변수

  • command — 실행할 셸 명령입니다.

샌드박스에서 셸 명령을 실행하고 stdout과 stderr를 결합하여 반환합니다. 셸은 호출 사이에 상태를 유지하지 않습니다. 파일 탐색(ls, head, cat), Python 실행(python3 -c "..."), 답변 제출(echo -n "<value>" > /workdir/answer.txt)에 사용하세요.

한계

  • 통합은 trl.experimental에 있습니다 — API가 변경될 수 있습니다. CI 로그에서 경고를 비활성화하려면 TRL_EXPERIMENTAL_SILENCE=1을 설정하세요.
  • Harbor의 비동기 샌드박스 클라이언트는 하나의 이벤트 루프에 바인딩되므로, 각 env는 자체 루프에서 start/exec/verify를 동기적으로 실행합니다. 따라서 샌드박스 프로비저닝은 세대 배치 내에서 순차적으로 수행됩니다(클라우드 백엔드인 e2b와 같은 경우 샌드박스당 비용을 완화합니다).
  • HarborSpec 1개는 태스크 스위트 1개 + 하네스 1개를 처리하며, 아직 여러 스위트에 대한 학습은 지원되지 않습니다.

참고

Update on GitHub