TRL documentation

Tích hợp Harbor để huấn luyện LLM với các môi trường

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Tích hợp Harbor để huấn luyện LLM với các môi trường

Harbor là một framework để chạy các tác vụ agentic trong các sandbox. Nó tách biệt task (lệnh + ảnh sandbox + verifier), harness/agent (bề mặt công cụ + vòng lặp) và sandbox (docker, e2b, daytona, gke, …) để chúng có thể được kết hợp tự do. Điều này khiến nó trở thành lựa chọn tự nhiên cho RL: cùng một bộ task có thể được huấn luyện với các bề mặt công cụ khác nhau, trên bất kỳ backend sandbox nào bạn ưa thích.

Hướng dẫn này bao gồm cách tích hợp Harbor với TRL. Đối với chính Harbor, hãy xem tài liệu Harbor.

Tích hợp này nằm tại trl.experimental.harbor và được đặt sau extra trl[harbor] (nhập theo kiểu lazy — người dùng không sử dụng sẽ không phải trả thêm chi phí gì).

Khi nào nên sử dụng môi trường Harbor

GRPOTrainer hỗ trợ huấn luyện dựa trên môi trường thông qua slot environment_factory — xem OpenEnv để biết về hợp đồng chung. Sử dụng Harbor khi bạn muốn huấn luyện đối với một bộ nhiệm vụ Harbor: một cây thư mục các nhiệm vụ, mỗi nhiệm vụ là một sandbox + verifier tự chứa (ví dụ: một bộ tác nhân phân tích dữ liệu, trong đó mô hình khám phá các tệp trong sandbox và viết ra câu trả lời để trình chấm điểm kiểm tra).

Cài đặt

pip install trl[harbor]

Harbor điều khiển quá trình tạo thông qua vLLM và sử dụng environment_factory, yêu cầu vllm và transformers>=5.2.0.

pip install vllm

Điều này cài đặt framework harbor (Python >= 3.12). Tích hợp này import harbor một cách lười (lazy) và chạy nó trong tiến trình, nên người dùng không đụng đến trl.experimental.harbor sẽ không bị ảnh hưởng.

Một backend sandbox cũng phải được cài đặt và có thể truy cập được vào thời điểm huấn luyện. Harbor giữ các backend cloud phía sau các extras riêng của nó, vì vậy hãy cài đặt backend bạn định sử dụng và cung cấp thông tin xác thực của 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

Bắt đầu nhanh

HarborSpec kết nối một bộ nhiệm vụ Harbor duy nhất vào ba vị trí của trình huấn luyện TRL — train_dataset, environment_factory, reward_funcs — bằng cách phơi bày các thuộc tính ánh xạ 1:1 với các tên tham số đó:

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

Bên trong, HarborSpec thực hiện ba việc, được thực hiện một cách lười biếng khi truy cập lần đầu:

  1. spec.train_dataset: phân giải bộ bài toán thành các thư mục bài toán cục bộ (tải bộ dữ liệu HF nếu cần) và xây dựng một datasets.Dataset với prompt (trống — chỉ dẫn của môi trường sẽ được thêm vào khi reset), task_dir, task_index, cùng các cột metadata task.toml cho từng bài toán.
  2. spec.environment_factory: trả về một callable không tham số tạo ra một HarborEnv mới cho mỗi lần rollout. Khi gọi reset(task_dir), nó khởi động sandbox Harbor của task và trả về instruction của nó; các phương thức tool thực thi lệnh bên trong sandbox; env.reward chạy verifier một lần sau khi rollout hoàn tất.
  3. spec.reward_funcs: phần thưởng kết quả đọc giá trị vô hướng của bộ xác minh Harbor cho mỗi lượt rollout.

Bộ dữ liệu

dataset là id của kho dataset Hugging Face chứa cây task Harbor, hoặc là đường dẫn cục bộ chứa cây con tasks/. Mỗi task là một thư mục:

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

Chọn một tập con bằng num_tasks hoặc indices (loại trừ lẫn nhau):

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

Agents: bên ngoài so với đã cài đặt

Harbor hỗ trợ hai cách một agent điều khiển một tác vụ, và sự khác biệt này quyết định những gì có thể được huấn luyện bằng RL:

  • Các tác nhân bên ngoài chạy bên ngoài sandbox và tự điều khiển vòng lặp, phát hành các lệnh vào container thông qua giao diện môi trường của Harbor (“thường bằng cách thực thi các lệnh bash qua phương thức exec”). Tác nhân quyết định từng hành động và diễn giải từng kết quả; sandbox chỉ thực thi.
  • Các agent đã cài đặt được cài đặt vào ảnh container và chạy ở đó dưới dạng tiến trình con không giao diện (mở rộng BaseInstalledAgent). Harbor khởi chạy agent bên trong sandbox và phân tích tệp trajectory của nó sau đó (populate_context_post_run); agent chạy tự chủ với suy luận của riêng nó.

Tích hợp của TRL là mô hình tác nhân bên ngoài, và hiện tại chỉ hỗ trợ mô hình này. Huấn luyện RL yêu cầu trainer điều khiển rollout theo từng lượt: mô hình chính sách đang được huấn luyện tạo ra mỗi lượt, và TRL thu thập các token và log-probs của nó rồi áp dụng environment mask — đúng những gì environment_factory cung cấp trên một rollout_func dạng hộp đen. Một tác nhân đã cài đặt là mờ nhạt đối với điều này: nó chạy bên trong container với mô hình riêng của nó và chỉ phát ra một quỹ đạo sau đó, nên không có token chính sách hay log-probs nào cho trainer để tối ưu, và mô hình đang được huấn luyện không bao giờ được gọi. Do đó, một HarborEnv là một tác nhân bên ngoài — các phương thức công cụ của nó exec vào sandbox, nhưng vòng lặp, và mô hình đang được huấn luyện, vẫn nằm trong TRL.

Chọn tác nhân cơ sở (harness)

base agent là bộ khung — xác định các phương thức công cụ mà env phơi bày và cách nó gửi đi. Chọn nó bằng 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

Bộ khung "bash" tích hợp (HarborBashEnv) cung cấp một công cụ bash và gửi kết quả bằng cách ghi vào /workdir/answer.txt. Hai bộ khung phong phú hơn được cung cấp dưới dạng ví dụ — mỗi bộ nằm trong một thư mục riêng kèm README liệt kê các công cụ của nó — tại examples/grpo_harbor/harnesses/:

  • jupyter/ (JupyterEnv) — một kernel Python có trạng thái (biến được giữ nguyên giữa các cell) + một công cụ shell.
  • terminal_notes/ (TerminalNotesEnv) — 6 công cụ shell (bao gồm các tiến trình nền) + bộ công cụ ghi chú bền vững gồm 4 công cụ.
HarborSpec(dataset, agent="examples/grpo_harbor/harnesses/jupyter/env.py:JupyterEnv")
HarborSpec(dataset, agent="examples/grpo_harbor/harnesses/terminal_notes/env.py:TerminalNotesEnv")

Để tự viết harness, hãy kế thừa HarborEnv và thêm các phương thức tool — mọi phương thức công khai đều trở thành một tool (TRL phát hiện chúng bằng inspect.getmembers), vì vậy hãy gán cho mỗi phương thức một chữ ký có kiểu và một docstring (được dùng để xây dựng schema của tool). Giữ các hàm phụ trợ có tiền tố gạch dưới. Dùng self._exec(cmd) để chạy lệnh shell trong sandbox, và đặt PROMPT_SUFFIX để thêm hướng dẫn của harness vào chỉ thị của tác vụ:

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

Hậu端 sandbox

environment_type được truyền trực tiếp đến Harbor (không được TRL kiểm tra):

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 được khuyến nghị cho việc huấn luyện cụm: chỉ environment.exec chạy trong sandbox trên cloud, nên các GPU được dành riêng cho policy và bạn có thể chạy nhiều rollout đồng thời.

Hàm phần thưởng

spec.reward_funcs mặc định là phần thưởng kết quả — cho mỗi lần rollout, nó đọc giá trị vô hướng (env.reward) của bộ xác minh Harbor, được tính một lần sau rollout bằng cách chạy bộ xác minh tests/ của tác vụ trong sandbox. Để dùng phần thưởng tùy chỉnh, hãy viết một hàm phần thưởng TRL thông thường:

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 )

Tham số

  • dataset (str) — Id của kho dataset Hugging Face chứa cây task Harbor (ví dụ "AdithyaSK/data_agent_rl_environment_train"), hoặc đường dẫn cục bộ đến thư mục chứa cây con tasks/. Mỗi task là một thư mục có instruction.md / task.toml / environment/ / tests/.
  • agent (str hoặc type, tùy chọn, mặc định là "bash") — Agent / harness cơ sở — tức là bề mặt công cụ mà env phơi bày. Một trong các lựa chọn: tên tích hợp sẵn ("bash"), đường dẫn import "package.module:ClassName", đường dẫn tệp "path/to/file.py:ClassName", hoặc trực tiếp một lớp con của HarborEnv.
  • environment_type (str, tùy chọn, mặc định là "docker") — Backend sandbox của Harbor, được truyền trực tiếp đến Harbor (bất kỳ giá trị nào mà nó hỗ trợ — "docker", "e2b", "daytona", "gke", "modal", "runloop", …). Không được kiểm tra ở đây; Harbor sẽ kiểm tra. "docker" là giá trị mặc định của chính Harbor; chọn "e2b" để chuyển việc sandbox sang đám mây.
  • num_tasks (int, tùy chọn) — Giới hạn số lượng tác vụ được đưa vào bộ dữ liệu. None sử dụng mọi tác vụ trong cây.
  • indices (list[int], tùy chọn) — Các chỉ số tác vụ cụ thể (trong danh sách tác vụ đã sắp xếp). Loại trừ lẫn nhau với num_tasks.
  • include_metadata (bool, tùy chọn, mặc định là True) — Gộp metadata của task.toml cho từng tác vụ (gold_answer, difficulty, …) vào các dòng của dataset.

Đối tượng spec đơn lẻ kết nối bộ bài tập Harbor vào trình huấn luyện TRL.

class trl.experimental.harbor.HarborEnv

< >

( environment_type: str = 'docker' )

Tham số

  • environment_type (str, tùy chọn, mặc định là "docker") — Backend sandbox của Harbor, được truyền trực tiếp đến Harbor ("docker", "e2b", "daytona", …).

Môi trường TRL cơ bản được hỗ trợ bởi sandbox Harbor + verifier.

Các lớp con định nghĩa các phương thức công cụ (khung chạy). Chu kỳ sống mà TRL điều khiển cho mỗi lượt rollout: reset(task_dir) (khởi động sandbox của tác vụ, trả về hướng dẫn của nó) -> các phương thức công cụ (thực thi trong sandbox) -> reward (chạy trình xác minh một lần, theo kiểu lười, sau lượt rollout).

class trl.experimental.harbor.HarborBashEnv

< >

( environment_type: str = 'docker' )

Khung công cụ chỉ có một bash; gửi bằng cách ghi vào /workdir/answer.txt.

bash

< >

( command: str )

Tham số

  • command — Lệnh shell cần chạy.

Chạy lệnh shell trong sandbox và trả về kết hợp stdout+stderr của nó. Shell không giữ trạng thái giữa các lần gọi. Sử dụng nó để khám phá tệp (ls, head, cat), chạy Python (python3 -c "...") và gửi câu trả lời (echo -n "<value>" > /workdir/answer.txt).

Hạn chế

  • Tích hợp này nằm trong trl.experimental — API có thể thay đổi. Đặt TRL_EXPERIMENTAL_SILENCE=1 để tắt cảnh báo trong nhật ký CI.
  • Client sandbox bất đồng bộ của Harbor được gắn với một vòng lặp sự kiện, do đó mỗi env sẽ điều khiển start/exec/verify một cách đồng bộ trên vòng lặp của riêng nó; việc cấp phát sandbox vì vậy là tuần tự trên toàn bộ lô sinh (các backend đám mây như e2b giúp giảm chi phí cho từng sandbox).
  • Một HarborSpec duy nhất bao phủ một bộ bài tập + một harness; việc huấn luyện đa bộ bài tập hiện chưa được hỗ trợ.

Tham khảo

Update on GitHub