تكامل Harbor لتدريب نماذج اللغة الكبيرة مع بيئات

Harbor هو إطار عمل لتشغيل المهام الوكيلية في بيئات معزولة. يفصل بين المهمة (التعليمات + صورة البيئة المعزولة + المُتحقِّق)، والإطار/الوكيل (سطح الأدوات + الحلقة)، والبيئة المعزولة (docker، e2b، daytona، gke، …) بحيث يمكن خلطها بحرية. وهذا يجعله مناسبًا بشكل طبيعي لتعلم التعزيز: فبإمكانك تدريب نفس مجموعة المهام باستخدام أسطح أدوات مختلفة، وعلى أي خلفية بيئة معزولة تفضلها.

يتناول هذا الدليل كيفية دمج Harbor مع TRL. أما بخصوص Harbor نفسه، فراجع وثائق Harbor.

توجد عملية التكامل في trl.experimental.harbor وهي محمية خلف الإضافة trl[harbor] (تُستورد بشكل كسول — غير المستخدمين لا يدفعون شيئاً).

متى تستخدم بيئات Harbor

يدعم GRPOTrainer التدريب القائم على البيئة عبر فتحة environment_factory — راجع OpenEnv لمعرفة العقد العام. استخدم Harbor عندما ترغب في التدريب مقابل حزمة مهام Harbor: وهي شجرة من المجلدات تحتوي على مهام، كل منها عبارة عن صندوق رمل مستقل + مُتحقق (على سبيل المثال، حزمة وكيل لتحليل البيانات حيث يستكشف النموذج الملفات داخل صندوق رمل ويكتب إجابة يتحقق منها مُقيّم).

التثبيت

pip install trl[harbor]

يعمل Harbor على توليد النصوص عبر vLLM ويستخدم environment_factory، والذي يتطلب vllm وtransformers>=5.2.0.

تم النسخ

pip install vllm

يُثبّت هذا الأمر إطار harbor (Python >= 3.12). تستورد التكامل harbor بشكل كسول وتشغّله داخل العملية، لذا لا يتأثر المستخدمون الذين لا يتعاملون مع trl.experimental.harbor.

يجب أيضًا تثبيت واجهة خلفية للبيئة المعزولة (sandbox backend) وجعلها قابلة للوصول في وقت التدريب. يحتفظ Harbor بواجهات الخلفية السحابية خلف إضافاته الخاصة، لذا ثبّت تلك التي تنوي استخدامها وفّر بيانات اعتمادها:

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 — من خلال كشف خصائص تُطابق تلك أسماء المعاملات 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 عند الحاجة) ويبني datasets.Dataset يحتوي على prompt (فارغ — حيث يُضاف تعليم البيئة عند reset)، وtask_dir، وtask_index، بالإضافة إلى أعمدة بيانات وصفية لكل مهمة من task.toml.
2. spec.environment_factory: يُرجع دالة قابلة للاستدعاء بدون معاملات تُنتج نسخة جديدة من HarborEnv لكل تمريرة. عند استدعاء reset(task_dir)، يبدأ بيئة Harbor المعزولة الخاصة بالمهمة ويُرجع تعليماتها؛ تُنفَّذ طرق الأدوات داخل البيئة المعزولة؛ بينما يُنفَّذ env.reward مرة واحدة بعد انتهاء التمريرة.
3. spec.reward_funcs: مكافأة نتيجة تقرأ القيمة العددية لكل تمريرة من مُتحقّق Harbor.

مجموعة البيانات

dataset هو إما معرف مستودع بيانات من Hugging Face يحتوي على شجرة مهام Harbor، أو مسار محلي يحتوي على شجرة فرعية 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

الوكلاء: خارجي مقابل مثبّت

يدعم Harbor طريقتين لتوجيه الوكيل (agent) للمهمة، ويحدد هذا التمييز ما يمكن تدريبه باستخدام التعلم المعزز (RL):

• يعمل الوكلاء الخارجيون خارج بيئة العزل ويتحكمون في الحلقة بأنفسهم، حيث يصدر أوامر إلى الحاوية عبر واجهة بيئة Harbor (عادةً من خلال تنفيذ أوامر bash عبر طريقة exec). يقرر الوكيل كل إجراء ويفسر كل نتيجة؛ بينما تقتصر بيئة العزل على التنفيذ فقط.
• الوكلاء المثبتون يتم تثبيتهم داخل صورة الحاوية ويعملون هناك كعملية فرعية بلا واجهة (مع توسيع BaseInstalledAgent). يقوم Harbor بتشغيل الوكيل داخل بيئة العزل ثم يحلل ملف مساره لاحقًا (populate_context_post_run)؛ ويعمل الوكيل بشكل مستقل باستخدام استنتاجه الخاص.

تكامل TRL هو نمط الوكيل الخارجي، وهذا النمط فقط هو المدعوم حاليًا. يتطلب تدريب التعزيز القوي أن يقود المدرب دورة التوليد خطوة بخطوة: حيث يولّد نموذج السياسة قيد التدريب كل خطوة، وتلتقط TRL رموزه واحتمالات السجلات الخاصة به وتطبق قناع البيئة — وهو بالضبط ما يوفره environment_factory فوق rollout_func الصندوق الأسود. الوكيل المثبّت معتم عن هذا: فهو يعمل داخل الحاوية مع نموذجه الخاص ولا يُصدر مسارًا إلا بعد انتهاء العملية، لذا لا توجد رموز سياسة أو احتمالات سجلات يمكن للمدرب تحسينها، ولا يُستدعى النموذج قيد التدريب أبدًا. لذلك فإن HarborEnv هو وكيل خارجي — فطرقه الأداة exec إلى صندوق الرمل، لكن الحلقة، والنموذج قيد التدريب، تبقى في TRL.

اختيار الوكيل الأساسي (الإطار)

يُعدّ الوكيل الأساسي هيكل التشغيل — أي طرق الأدوات التي يعرضها البيئة وكيفية إرسالها. اختره باستخدام 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) — نواة بايثون ذات حالة (تبقى المتغيرات محفوظة عبر الخلايا) + أداة shell.
• 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")

لكتابة إطار عمل خاص بك، قم بإنشاء فئة فرعية من HarborEnv وأضف طرق الأدوات — فكل طريقة عامة تصبح أداة (تكتشفها TRL باستخدام inspect.getmembers)، لذا امنح كل منها توقيعًا مُنمَّطًا ووصفًا توثيقيًا (يُستخدم لبناء مخطط الأداة). حافظ على بادئة الشرطة السفلية للمساعدات. استخدم self._exec(cmd) لتنفيذ أوامر shell داخل بيئة العزل، واضبط PROMPT_SUFFIX لإضافة إرشادات الإطار إلى تعليمات المهمة:

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 مباشرة إلى Harbor (بدون تحقق من قِبل 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 لتدريب العناقيد: إذ لا يعبر environment.exec إلى صندوق الرمل السحابي إلا هو، مما يُبقي وحدات معالجة الرسوميات مخصصةً للسياسة، ويتيح تنفيذ العديد من عمليات التمرير بالتوازي.

دوال المكافأة

spec.reward_funcs افتراضيًا مكافأة نتيجة — في كل تمريرة يقرأ القياس العددي (env.reward) الخاص بمُتحقِّق Harbor، ويُحسب مرة واحدة بعد التمريرة عبر تشغيل مُتحقِّق tests/ الخاص بالمهمة داخل بيئة العزل. لمكافأة مخصصة، اكتب دالة مكافأة TRL عادية:

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

واجهة برمجة التطبيقات

القيود

• التكامل موجود في trl.experimental — قد تتغير واجهات برمجة التطبيقات. اضبط TRL_EXPERIMENTAL_SILENCE=1 لكتم التحذير في سجلات CI.
• عميل Harbor غير المتزامن للبيئة المعزولة مرتبط بدورة أحداث واحدة، لذا يقود كل env عمليات البدء/التنفيذ/التحقق بشكل متزامن على دورته الخاصة؛ وبالتالي تكون تهيئة البيئات المعزولة تسلسلية عبر دفعة التوليد (تخفف الخوادم السحابية مثل e2b من التكلفة لكل بيئة معزولة).
• يغطي HarborSpec واحد مجموعة مهام واحدة + إطار عمل واحد؛ ولا يُدعم التدريب متعدد المجموعات بعد.

مرجع

• إطار Harbor
• وثائق تدريب Harbor RL