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

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

이 가이드는 **Harbor를 TRL에 통합하는 방법**을 다룹니다. Harbor 자체에 대해서는 [Harbor 문서](https://www.harborframework.com/docs)를 참고하세요.

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

## Harbor 환경을 사용할 때

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

## 설치

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

> [!IMPORTANT]
> Harbor는 vLLM을 통해 생성을 구동하며, `vllm`과 `transformers>=5.2.0`이 필요한 `environment_factory`를 사용합니다.
>
> ```bash
> pip install vllm
> ```

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

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

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

## 빠른 시작

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

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

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

1. **`spec.train_dataset`**: 태스크 스위트를 로컬 태스크 디렉터리로 해석합니다(필요한 경우 HF 데이터셋을 다운로드) 그리고 `prompt`(비어 있음 — env의 지시문이 `reset` 시점에 추가됨), `task_dir`, `task_index`, 그리고 태스크별 `task.toml` 메타데이터 컬럼을 포함하는 `datasets.Dataset`를 생성합니다.
2. **`spec.environment_factory`**: 롤아웃마다 새로운 [HarborEnv](/docs/trl/v1.18.2/ko/harbor#trl.experimental.harbor.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`(서로 배타적)를 사용하여 부분 집합을 선택합니다:

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

## 에이전트: 외부 vs 설치

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

- [**외부 에이전트**](https://www.harborframework.com/docs/agents#external-agents)는 샌드박스 *외부*에서 실행되며 루프를 직접 제어합니다. Harbor의 환경 인터페이스를 통해 컨테이너에 명령을 발행하며, "일반적으로 `exec` 메서드를 통해 bash 명령을 실행하는 방식"입니다. 에이전트가 각 행동을 결정하고 각 결과를 해석하며, 샌드박스는 실행만 담당합니다.
- [**설치된 에이전트**](https://www.harborframework.com/docs/agents#installed-agents)는 *컨테이너 이미지*에 설치되어 헤드리스 서브프로세스로 실행됩니다(`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](/docs/trl/v1.18.2/ko/harbor#trl.experimental.harbor.HarborEnv)는 external agent입니다. 도구 메서드가 `exec`를 통해 샌드박스에 진입하지만, 루프와 학습 대상 모델은 TRL에 남아 있습니다.

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

**기본 에이전트**는 하네스입니다. env가 어떤 도구 메서드를 노출하고 어떻게 제출하는지를 정의합니다. `agent=`로 선택합니다:

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

내장 `"bash"` 하네스([HarborBashEnv](/docs/trl/v1.18.2/ko/harbor#trl.experimental.harbor.HarborBashEnv))는 `bash` 도구 하나를 노출하고 `/workdir/answer.txt`에 작성하여 제출합니다. 더 풍부한 두 가지 하네스가 예시로 제공되며, 각 하네스는 도구가 나열된 README와 함께 [`examples/grpo_harbor/harnesses/`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor/harnesses) 아래에 별도의 폴더로 포함되어 있습니다:

- [`jupyter/`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor/harnesses/jupyter) (`JupyterEnv`) — 상태가 유지되는 Python 커널(변수가 셀 간에 유지됨) + 셸 도구.
- [`terminal_notes/`](https://github.com/huggingface/trl/tree/main/examples/grpo_harbor/harnesses/terminal_notes) (`TerminalNotesEnv`) — 6개의 셸 도구(백그라운드 프로세스 포함) + 4개 도구로 구성된 영속적 노트 툴킷.

```python
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](/docs/trl/v1.18.2/ko/harbor#trl.experimental.harbor.HarborEnv)를 서브클래스로 상속하고 tool 메서드를 추가하세요. 모든 public 메서드가 tool이 되므로(TRL은 `inspect.getmembers`로 이를 발견합니다), 각 메서드에 타입이 지정된 시그니처와 docstring(tool schema를 구성하는 데 사용됨)을 부여하세요. 헬퍼 메서드는 밑줄로 시작하는 이름을 사용하세요. 샌드박스에서 shell 명령을 실행하려면 `self._exec(cmd)`를 사용하고, `PROMPT_SUFFIX`를 설정하여 작업 지침에 harness 지침을 추가하세요:

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

## 샌드박스 백엔드

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

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

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

## 보상 함수

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

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

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

**매개변수:**

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](/docs/trl/v1.18.2/ko/harbor#trl.experimental.harbor.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 객체입니다.

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

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

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

**매개변수:**

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

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

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

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

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

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

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

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

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

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

**매개변수:**

command : 실행할 셸 명령입니다.

**반환값:**

명령어의 결합된 stdout 및 stderr입니다.

Run a shell command in the sandbox and return its combined stdout+stderr. The shell is non-stateful between calls. Use it to explore files (ls, head, cat), run Python (`python3 -c "..."`), and submit the answer (`echo -n "" > /workdir/answer.txt`).

## 한계

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

## 참고

- [Harbor 프레임워크](https://www.harborframework.com)
- [Harbor RL 학습 문서](https://www.harborframework.com/docs/training-workflows/rl)

