Ortamlarla LLM'leri Eğitmek İçin OpenReward Entegrasyonu

OpenReward, Open Reward Standard (ORS) üzerine kurulu, RL ortamları için açık bir ekosistemdir — ORS, bir ortamın görevlerini, araçlarını, oturumlarını ve ödülleri nasıl sunduğunu tanımlayan herkese açık, dil bağımsız bir HTTP/SSE protokolüdür. ORS yalnızca bir protokol olduğu için, aynı ortam OpenReward platformu üzerinde, herhangi bir konteyner servisinde kendi kendine barındırılarak veya geliştirme için localhost üzerinde yerel olarak çalıştırılabilir. Hazır kullanıma uygun ortamların bir kataloğu openreward.ai adresinde mevcuttur.

Bu kılavuz, OpenReward'ın TRL ile nasıl entegre edileceğini kapsar. Standart hakkında daha fazla bilgi için ORS belgelerini inceleyin.

Entegrasyon trl.experimental.openreward konumundadır ve trl[openreward] ek özelliği arkasında kapalıdır (tembel içe aktarma — kullanıcı olmayanlar hiçbir şey ödemez).

OpenReward ortamlarının ne zaman kullanılacağı

GRPOTrainer, environment_factory yuvası üzerinden ortam tabanlı eğitimi destekler — genel sözleşme için OpenEnv'e bakın. ORS konuşan bir ortama karşı eğitim yapmak istediğinizde OpenReward kullanın: OpenReward kataloğu (ör. Eigent/SETA, kanishk/EndlessTerminals, nebius/SWE-rebench-V2), kendi altyapınızda barındırdığınız bir ortam veya üzerinde çalıştığınız yerel bir sunucu.

Kurulum

pip install trl[openreward]

Bu, openreward Python SDK'sını yükler. Entegrasyonun kendisi openreward paketini tembel (lazy) olarak içe aktarır, bu nedenle trl.experimental.openreward modülüne dokunmayan kullanıcılar etkilenmez.

Hızlı başlangıç

OpenRewardSpec sınıfı, tek bir ORS ortamını üç TRL eğitimci yuvasına — train_dataset, environment_factory, reward_funcs — bağlar; bu yuva adlarıyla birebir eşleşen özellikler sunar:

from trl import GRPOConfig, GRPOTrainer
from trl.experimental.openreward import OpenRewardSpec

spec = OpenRewardSpec("Eigent/SETA", num_tasks=64)

trainer = GRPOTrainer(
    model="Qwen/Qwen3-4B",
    args=GRPOConfig(
        num_generations=2,
        max_steps=5,
        max_tool_calling_iterations=20,
        log_completions=True,
    ),
    train_dataset=spec.train_dataset,
    environment_factory=spec.environment_factory,
    reward_funcs=spec.reward_funcs,
)
trainer.train()

Arka planda OpenRewardSpec, ilk erişimde tembelce üç şey yapar:

1. spec.train_dataset: env’in görev listesinden bir datasets.Dataset türetir (SDK üzerinden tek bir HTTP gidiş-dönüşü). En azından prompt, task_index ve görev başına metadata sütunlarını içerir.
2. spec.environment_factory: her çağrıda yeni bir rollout başına adapter üreten, argüman almayan bir callable döndürür. Adapter, ORS araçlarının her biri için bir Python metodu sunar; imza ve docstring, env’in JSON Schema’sından otomatik olarak oluşturulur. TRL’nin tool collector’ı bunları inspect.getmembers üzerinden alır.
3. spec.reward_funcs: yalnızca sonuç odaklı bir ödül fonksiyonu (yörüngedeki son null olmayan ödül), SETA gibi seyrek ödüllü ortamlar için uygundur.

Bir hub ortamı kullanma

Hedef olarak bir openreward.ai kataloğu adı geçin. SDK, kimlik doğrulama için ortamdan OPENREWARD_API_KEY değerini okur.

spec = OpenRewardSpec("Eigent/SETA", num_tasks=64)

Kendi barındırdığınız bir ortamı kullanma

URL'yi doğrudan iletin. Sunucunuz bir API anahtarı zorlamıyorsa API anahtarı gerekmez.

spec = OpenRewardSpec("https://my-org-my-env.hf.space", env_name="my_env")

openreward SDK varsayılan olarak iki alt alan adlı bir platform düzeni bekler (durumsuz çağrılar için api.<host> ve SSE tabanlı oturum çağrıları için sessions.<host>). tek ana makine tabanlı kendi kendine barındırılan sunucular için (her şeyi tek bir URL üzerinden sunan), OpenRewardSpec oluşturulmadan önce aşağıdaki geçersiz kılma ortam değişkenlerini ayarlayın:

Kopyalandı

import os

URL = "https://my-org-my-env.hf.space"
os.environ["OPENREWARD_API_URL"]     = URL
os.environ["OPENREWARD_SESSION_URL"] = URL

spec = OpenRewardSpec(URL, env_name="my_env")

Yerel olarak minimal bir ortam çalıştırma

Harici bağımlılıklar olmadan entegrasyonu uçtan uca denemenin en hızlı yolu, openreward SDK’sının Environment + Server iskeletiyle tanımlanmış küçük bir ORS sunucusudur. Aşağıdaki örnek, tam bir echo ortamıdır — model, görevin hedef dizisini echo(text=...) ile çağırarak kazanır.

# server.py
from pydantic import BaseModel
from openreward.environments import Environment, JSONObject, Server, TextBlock, ToolOutput, tool


class EchoTaskSpec(BaseModel):
    target: str

class EchoParams(BaseModel):
    text: str


class EchoEnvironment(Environment):
    def __init__(self, task_spec: JSONObject = {}, secrets: dict[str, str] = {}):
        super().__init__(task_spec)
        self.config = EchoTaskSpec.model_validate(task_spec)

    @classmethod
    def list_splits(cls) -> list[str]:
        return ["train"]

    @classmethod
    def list_tasks(cls, split: str) -> list[JSONObject]:
        return [{"target": "hello"}, {"target": "world"}]

    def get_prompt(self) -> list[TextBlock]:
        return [TextBlock(type="text", text=f"Echo '{self.config.target}' to win.")]

    @tool
    async def echo(self, params: EchoParams) -> ToolOutput:
        """Submit a string. Reward 1.0 + finished if it matches the target.

        Args:
            text: The string to echo back.
        """
        correct = params.text == self.config.target
        return ToolOutput(
            blocks=[TextBlock(type="text", text="match" if correct else "no match")],
            reward=1.0 if correct else 0.0,
            finished=correct,
        )


if __name__ == "__main__":
    Server([EchoEnvironment]).run(host="0.0.0.0", port=8000)

Çalıştırın:

pip install openreward fastapi uvicorn pydantic
python server.py     # listens on :8000

Ardından OpenRewardSpec'i buna yönlendirin (yukarıda açıklanan URL geçersiz kılma ayarlarıyla):

import os
URL = "http://127.0.0.1:8000"
os.environ["OPENREWARD_API_URL"]     = URL
os.environ["OPENREWARD_SESSION_URL"] = URL

from trl.experimental.openreward import OpenRewardSpec
spec = OpenRewardSpec(URL, env_name="echoenvironment")
print(spec.train_dataset)        # 2 rows, task_index + target columns

Bu, TRL’nin kendi testlerinde de kullanılan sabit (fixture) desenidir — dağıtılmış Space için trl-internal-testing/openreward-echo-env adresine bakın.

Görev seçimi

OpenRewardSpec bir sayı veya açık bir indeks listesi kabul eder:

spec = OpenRewardSpec("Eigent/SETA", num_tasks=10)                      # first 10 tasks
spec = OpenRewardSpec("Eigent/SETA", indices=[0, 5, 13, 27])            # specific indices
spec = OpenRewardSpec("Eigent/SETA", indices=list(range(50, 100)))      # range

num_tasks ve indices birbirini dışlar ve her ikisi de yalnızca ihtiyaç duydukları görevleri getirir (tam görev listesi taraması yapılmaz).

Araç bağlama nasıl çalışır

Oluşturma sırasında spec, araç özelliklerinin (her biri bir ad, açıklama ve argümanlar için JSON Schema içeren) listesini almak için env’in /tools uç noktasını çağırır. Her araç için, şemadan türetilmiş bir docstring’e ve tipli bir imzaya sahip bir Python metodu, rollout başına adapter üzerinde oluşturulur. Yöntemler, TRL’nin araç toplayıcısının onları bulduğu adapter sınıfına ayarlanır; böylece transformers.utils.get_json_schema ve TRL’nin inspect.getmembers(type(env), isfunction) çağrıları, env başına sarmalayıcı kodu gerektirmeden model için doğru araç şemasını üretir.

Bir araç açıklaması, Python kaynak koduna güvenli bir şekilde eklenemeyecek karakterler içeriyorsa, binder gerçek ortamlarda bağlama işlemi asla başarısız olmaz diye bir temizlenmiş biçime geri düşer.

Ödül işlevleri

spec.reward_funcs varsayılan olarak yalnızca sonuç odaklı bir ödül kullanır — her rollout için, yörünge boyunca gözlemlenen son null olmayan ödülü döndürür. Bu, seyrek ödüllü ortamlar (ör. yalnızca submit_solution null olmayan ödül döndüren SETA) için doğru varsayılandır.

Hiçbir araç null olmayan bir ödül döndürmezse, varsayılan ödül fonksiyonu 0.0 değil, None döndürür. Bu, araç çağrısı içermeyen, yalnızca puanlanmamış araç çağrıları içeren veya yalnızca başarısız araç çağrıları içeren rollout'ları da kapsar. Gözlemlenen 0.0 veya negatif bir ödül geçerli bir puan olarak kalır. Daha sonraki bir puanlanmamış veya başarısız araç çağrısı, önceki bir puanı silmez.

GRPO, ödül tabanından, tüm ödül fonksiyonlarının None döndürdüğü rollout'ları hariç tutar ve bunlara sıfır avantaj verir. Bu, token'ların kayıp normalizasyonundan çıkarılmasını veya KL düzenlemesi gibi diğer terimleri devre dışı bırakmaz. Başka bir ödül fonksiyonu rollout'a puan verirse, yine de sıfır olmayan bir avantaj alabilir.

Eksik puanlar, bir bölümün neden sonlandığını belirlemez. Vazgeçme veya araç çağrısı sınırına ulaşma durumları bir görev başarısızlığı olarak sayılacaksa, ortamınızdan veya özel ödül işlevinizden açık bir başarısızlık ödülü döndürün. Altyapı veya değerlendirici hataları ise puanlanamaz olarak kalabilir; ortalama ödülün yanı sıra puanlama kapsamını da izleyin.

Özel bir ödül istiyorsanız, standart bir TRL ödül fonksiyonu yazın ve doğrudan iletin:

def my_reward(environments, **kwargs) -> list[float | None]:
    rewards = spec.reward_funcs(environments=environments)
    return [2.0 * reward if reward is not None else None for reward in rewards]

trainer = GRPOTrainer(
    ...,
    reward_funcs=my_reward,
)

Rollout başına adaptör, TRL'in ihtiyaç duyduğu çalışma durumunu — env.reward, env.rewards, env.metadata, env.finished, env.last_output — keyfi sonradan ödül şekillendirme için açığa çıkarır.

OpenRewardSpec

Kısıtlamalar

• Entegrasyon trl.experimental içinde — API'ler değişebilir. CI günlüklerindeki uyarıyı susturmak için TRL_EXPERIMENTAL_SILENCE=1 değerini ayarlayın.
• Şu anda tek bir OpenRewardSpec maruz bırakır ve tek bir ortamı kapsar; çoklu ortam eğitimi (OpenEnv “meta-ortam” deseni tarzında) henüz desteklenmemektedir.
• Uzun süreli rollouts (epizot başına >15 dk) bir keepalive ping gerektirir — henüz bağlanmadı.

Referans

• Açık Ödül Standardı
• OpenReward platformu
• openreward Python SDK'sı
• Echo env Space — trl-internal-testing/openreward-echo-env