TRL documentation
Intégration d'OpenReward pour l'entraînement de LLMs avec des environnements
Intégration d'OpenReward pour l'entraînement de LLMs avec des environnements
OpenReward est un écosystème ouvert pour les environnements de RL, construit sur le Open Reward Standard (ORS) — un protocole HTTP/SSE public et indépendant du langage, définissant la manière dont un environnement expose ses tâches, outils, sessions et récompenses. Étant donné que l’ORS n’est qu’un protocole, le même environnement peut s’exécuter sur la plateforme OpenReward, en auto-hébergement sur n’importe quel service de conteneurs, ou localement sur localhost pour le développement. Un catalogue d’environnements prêts à l’emploi est disponible sur openreward.ai.
Ce guide explique comment intégrer OpenReward avec TRL. Pour en savoir plus sur la norme elle-même, consultez la documentation ORS.
L’intégration se trouve dans
trl.experimental.openrewardet est conditionnée par l’extratrl[openreward](import paresseux — les non-utilisateurs n’ont rien à payer).
Quand utiliser les environnements OpenReward
GRPOTrainer prend en charge l’entraînement basé sur des environnements via le slot environment_factory — voir OpenEnv pour le contrat général. Utilisez OpenReward lorsque vous souhaitez vous entraîner contre un environnement parlant ORS : le catalogue OpenReward (par ex. Eigent/SETA, kanishk/EndlessTerminals, nebius/SWE-rebench-V2), un environnement que vous hébergez vous-même sur votre propre infrastructure, ou un serveur local que vous développez.
Installation
pip install trl[openreward]
Cela installe le SDK Python openreward. L’intégration elle-même importe openreward de manière différée, de sorte que les utilisateurs qui n’utilisent pas trl.experimental.openreward ne sont pas affectés.
Démarrage rapide
La classe OpenRewardSpec connecte un environnement ORS unique aux trois emplacements du formateur TRL — train_dataset, environment_factory, reward_funcs — en exposant des propriétés qui correspondent 1:1 à ces noms de mots-clés :
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()Sous le capot, OpenRewardSpec fait trois choses, de manière paresseuse au premier accès :
spec.train_dataset: dérive undatasets.Datasetà partir de la liste de tâches de l’environnement (un seul aller-retour HTTP via le SDK). Contient au minimumprompt,task_index, ainsi que des colonnes de métadonnées spécifiques à chaque tâche intégrées.spec.environment_factory: renvoie un appelable sans argument qui génère un nouvel adaptateur par déroulement à chaque appel. L’adaptateur expose une méthode Python par outil ORS, avec une signature typée et une docstring générées automatiquement à partir du schéma JSON de l’environnement. Le collecteur d’outils de TRL les récupère viainspect.getmembers.spec.reward_funcs: une fonction de récompense basée uniquement sur le résultat (dernière récompense non nulle de la trajectoire), adaptée aux environnements à récompense sparse comme SETA.
Utiliser un environnement de hub
Passez un nom de catalogue openreward.ai comme cible. Le SDK lit OPENREWARD_API_KEY depuis l’environnement pour l’authentification.
spec = OpenRewardSpec("Eigent/SETA", num_tasks=64)Utiliser un environnement auto-hébergé
Transmettez l’URL directement. Aucune clé API n’est requise si votre serveur n’en impose pas.
spec = OpenRewardSpec("https://huggingface.co/proxy/my-org-my-env.hf.space", env_name="my_env")Par défaut, le SDK
openrewards’attend à une configuration de plateforme à deux sous-domaines (api.<host>pour les appels sans état etsessions.<host>pour les appels de session basés sur SSE). Pour les serveurs auto-hébergés monohôte (une seule URL servant tout), définissez les variables d’environnement de substitution ci-dessous avant de construireOpenRewardSpec:import os URL = "https://huggingface.co/proxy/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")
Exécuter un environnement minimal en local
La méthode la plus rapide pour tester l’intégration de bout en bout sans dépendances externes est un petit serveur ORS défini à l’aide de l’armature Environment + Server du SDK openreward. L’exemple ci-dessous est un environnement echo complet — le modèle gagne en appelant echo(text=...) avec la chaîne cible de la tâche.
# 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)Lancez-le :
pip install openreward fastapi uvicorn pydantic
python server.py # listens on :8000Puis, pointez OpenRewardSpec vers ce fichier (avec les substitutions d’URL décrites ci-dessus) :
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 columnsC’est également le motif de fixture utilisé par les propres tests de TRL — voir trl-internal-testing/openreward-echo-env pour le Space déployé.
Sélection des tâches
OpenRewardSpec accepte soit un nombre, soit une liste d’indices explicite :
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))) # rangenum_tasks et indices sont mutuellement exclusifs et ne récupèrent que les tâches dont ils ont besoin (aucun balayage de la liste complète des tâches).
Fonctionnement de la liaison d'outils
À la construction, la spécification appelle le point de terminaison /tools de l’env pour récupérer une liste de spécifications d’outils (chacune avec un nom, une description et un JSON Schema pour les arguments). Pour chaque outil, elle génère une méthode Python sur l’adaptateur par rollout avec une signature typée et une docstring dérivée du schéma. Les méthodes sont définies sur la classe de l’adaptateur, où le collecteur d’outils de TRL les trouve, de sorte que transformers.utils.get_json_schema et inspect.getmembers(type(env), isfunction) de TRL produisent tous deux le bon schéma d’outil pour le modèle, sans code d’emballage spécifique à l’env.
Si la description d’un outil contient des caractères non sûrs à insérer dans du code source Python, le binder bascule sur une forme assainie afin que le binding ne rate jamais dans des environnements réels.
Fonctions de récompense
spec.reward_funcs est par défaut une récompense uniquement de résultat — pour chaque déroulement, elle renvoie la dernière récompense non nulle observée au cours de la trajectoire. C'est le comportement par défaut approprié pour les environnements à récompense creuse (par ex. SETA, où seule submit_solution renvoie une récompense non nulle).
Si aucun outil ne renvoie une récompense non nulle, la fonction de récompense par défaut renvoie None, et non 0.0. Cela inclut les déroulements sans appels d’outils, avec uniquement des appels d’outils non notés, ou avec uniquement des appels d’outils en échec. Une récompense observée de 0.0 ou négative reste un score valide. Un appel d’outil non noté ou en échec survenant plus tard n’efface pas un score antérieur.
GRPO exclut du calcul de la référence de récompense les déroulements pour lesquels toutes les fonctions de récompense renvoient None et leur attribue un avantage nul. Cela ne supprime pas leurs jetons de la normalisation de la perte ni ne désactive d'autres termes tels que la régularisation KL. Si une autre fonction de récompense évalue le déroulement, celui-ci peut toujours recevoir un avantage non nul.
L’absence de score ne permet pas d’identifier la raison pour laquelle un épisode s’est terminé. Si l’abandon ou l’atteinte d’une limite d’appels d’outils doit être comptabilisé comme un échec de la tâche, renvoyez une récompense d’échec explicite depuis votre environnement ou votre fonction de récompense personnalisée. Les pannes d’infrastructure ou du correcteur peuvent, en revanche, rester non notables ; surveillez la couverture de la notation en parallèle de la récompense moyenne.
Si vous souhaitez utiliser une récompense personnalisée, écrivez une fonction de récompense TRL classique et transmettez-la directement :
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,
)L'adaptateur par déroulement expose l'état courant dont TRL a besoin — env.reward, env.rewards, env.metadata, env.finished, env.last_output — pour un façonnage a posteriori arbitraire de la récompense.
OpenRewardSpec
classe trl.experimental.openreward.OpenRewardSpec
< source >( target: strnum_tasks: int | None = Nonesplit: str = 'train'indices: list[int] | None = Noneapi_key: str | None = Nonesecrets: dict[str, str] | None = Noneenv_name: str | None = Noneinclude_metadata: bool = Truediscover_task_tools: bool = Truetask_tools_discovery_index: int | None = None )
Paramètres
- target (str) — Soit un nom du catalogue openreward.ai (“Eigent/SETA”), soit une URL pointant vers n’importe quel serveur ORS (”https://huggingface.co/proxy/you-seta.hf.space”, “http://localhost:8080”). La détection est automatique, basée sur la présence de :// dans la chaîne de caractères.
- num_tasks (int, facultatif) —
Limite le nombre de tâches intégrées au jeu de données.
Noneutilise toutes les tâches exposées par l'environnement. - split (str, optionnel, par défaut “train”) — Le split dont la liste de tâches est tirée.
- indices (list[int], facultatif) —
Indices de tâches spécifiques sur lesquelles entraîner. Mutuellement exclusif avec
num_tasks. Utile pour le débogage ou les sous-ensembles de curriculum. - api_key (str, facultatif) —
Remplacement de
OPENREWARD_API_KEY. Utilisé uniquement lorsquetargetest un nom de catalogue. - secrets (dict[str, str], facultatif) —
Secrets par session transmis à
env.session(secrets=). - env_name (str, facultatif) — Substitution du nom d'environnement à rechercher sur le serveur. Rarement nécessaire.
- include_metadata (bool, facultatif, valeur par défaut True) —
Intègre les métadonnées par tâche (difficulty, category, tags, …) dans les lignes du jeu de données afin que les fonctions de récompense puissent
les lire via l’argument
inputsde TRL. - discover_task_tools (bool, facultatif, valeur par défaut True) —
Si
True, ouvre une session ORS de courte durée et utilisesession.list_tools()afin que les outils spécifiques à la tâche (GET …/task_toolsselon ORS — par ex.@tool(shared=False)etlist_task_tools()) soient liés pour GRPO. En cas d’échec de la sonde, bascule uniquement surenvironment.list_tools(). DéfinissezFalsepour ignorer la session supplémentaire (outils partagés uniquement / particularités hors ligne). - task_tools_discovery_index (int, facultatif) —
Index de tâche utilisé uniquement pour la session de découverte lorsqu’il est défini ; remplace la sonde multi-index ci-dessous. Lorsqu’il est
omis et que
indices=est défini, la découverte ouvre une session de sonde par entrée distincte deindices(triées) et fusionne les spécifications d’outils par nom afin que les outils spécifiques à chaque tâche listée soient liés. Lorsqu’il est omis et que le modenum_tasks/ liste complète est utilisé, seule la tâche0est sondée. Ignoré lorsquediscover_task_tools=False.
Objet de spécification unique qui connecte un environnement ORS à un formateur TRL.
Limites
- L'intégration se trouve dans
trl.experimental— les API peuvent changer. DéfinissezTRL_EXPERIMENTAL_SILENCE=1pour supprimer l'avertissement dans les journaux CI. - Expose actuellement une seule
OpenRewardSpeccouvrant un environnement ; l’entraînement multi-environnements (selon le motif « méta-environnement » d’OpenEnv) n’est pas encore pris en charge. - Les rollouts de longue durée (>15 min par épisode) nécessitent un ping de maintien de connexion — pas encore implémenté.
Référence
- Open Reward Standard
- plateforme OpenReward
- SDK Python
openreward - Environnement Echo —
trl-internal-testing/openreward-echo-env