Адаптеры окружения: Безопасное обучение с подкреплением для эффективной разработки агентов

Небольшие LoRA-адаптеры, обученные с помощью обучения с подкреплением (RL) в средах pi, opencode и hermes, работают на базе одной модели, причем каждый вызов инструментов моделью проверяется с помощью safeagents перед его выполнением. Следите за ходом обучения на интерактивной панели управления.

Кратко

• Мы выпускаем несколько «адаптеров окружения» (harness adapters). Это один LoRA-адаптер для каждой модели и окружения, обученный с помощью RL на проверяемых задачах в неизмененных средах агентов (pi, opencode и hermes).
• Адаптеры окружения могут сделать локальную разработку агентов более эффективной и точной. На отложенных тестовых задачах в наших пробных тестах обучения они делают меньше вызовов инструментов по сравнению с базовой моделью, сохраняя или повышая ее точность.
• Новые среды создаются на основе сеансов открытого программирования, опубликованных на Hub: Repo2RLEnvs превращает их в проверяемые задачи, которые смешиваются в процессе обучения с SmolDataEnvs.
• , прокси-сервер между средой агента и моделью, проверяет каждый вызов инструментов с помощью детекторов на основе правил. Попытки взлома функции награды (reward-hacking) блокируются и получают оценку 0.
• TwIL-8B, модель рассуждений, никогда не обучавшаяся как агент, тоже учится. Финальные прогоны транслируются в прямом эфире.

Эволюция адаптеров окружения

Одна и та же модель ведет себя по-разному в различных средах агентов, где каждая имеет свои собственные инструменты, промпт и поток управления. В исчерпывающем руководстве по многосредовому RL было показано, как обучать модель непосредственно внутри самих сред без их изменения.

Здесь мы применяем другой подход: мы обучаем небольшой LoRA-адаптер для каждой среды поверх базовой модели. Пользователи могут заменить модель своего локального агента на адаптер, обученный для этой среды.

Ранние попытки

Сначала мы выпустили начальные адаптеры окружения только для LFM2.5-24B-A2B, обученные в pi, hermes и claude-code. Они показали положительные результаты как в отношении эффективности вызовов инструментов, так и в точности на отложенных задачах. Учитывая их принятие сообществом, мы решили продвинуться дальше в этом направлении и добавить новые компоненты в обучение RL, чтобы сделать нашу первоначальную работу более полной.

LoRA — естественный выбор для адаптеров окружения

LoRA-адаптеры экономически эффективны для обучения и оценки, так как один сервер может обслуживать политику для всех сред одновременно. На этапе инференса любой пользователь может загрузить адаптер для выбранной среды, чтобы сделать базовую модель более эффективной для своей задачи. В разделе «Одна базовая модель, множество адаптеров» мы подробно описываем, как именно мы используем LoRA-адаптеры для обучения и оценки.

Диверсификация задач RL

Мы увеличили разнообразие и сложность наших предыдущих задач RL, создав синтетические среды RL на основе сеансов работы агентов с открытым исходным кодом (сеанс представляет собой полные логи работы агента: запросы пользователя, ответы модели и каждый вызов инструментов с его выводом) в качестве исходных данных. Мы выделили четыре типа сред RL:

• repair: исправление ошибки в существующей кодовой базе.
• qa: ответ на вопрос, основанный на фактах.
• build: создание чего-либо нового с нуля, оцениваемое по доле пройденных скрытых тестов. Первоначальная реализация служит оракулом, проверяющим задачу.
• extend: внесение последующих изменений в существующую кодовую базу.

Эта анимированная демонстрация показывает, как выглядит каждый тип задачи:

Информация о том, как эти среды создаются, проверяются и оцениваются, находится в разделе Environments.

Безопасное RL: минимизация взлома функции награды с помощью safeagents

RL также позволяет модели взламывать функцию награды, находя короткие пути для решения поставленной задачи. Поэтому мы интегрируем на этап обучения с подкреплением. Она проверяет вызовы инструментов моделью и блокирует те из них, которые явно являются попытками взлома функции награды. Заблокированный вызов заменяется текстом с объяснением причины блокировки, что побуждает модель исследовать другой путь. О том, как работают проверки и какой вызов был заблокирован, рассказано в разделе «Говорим 🙅 коротким путям агента».

Обучение на большем количестве моделей

По отзывам сообщества, мы расширили набор моделей для обучения до LFM2.5-24B-A2B и LFM3-1.7B, а также добавили TwIL-8B в качестве эксперимента. В карточке модели указано, что она не обучалась на данных агентов, и мы хотим узнать, дает ли такая модель положительные сигналы и способна ли тоже создавать адаптеры окружения. Модели и их настройки описаны в разделе Trained models.

Настройка

Обученные модели

Кодовая база для обучения и основные гиперпараметры

Мы обучаем модели с помощью алгоритма GRPO, используя AsyncGRPOTrainer из библиотеки TRL в сочетании с древовидным вниманием (tree attention) для эффективного обучения. Наши адаптеры окружения представляют собой LoRA-адаптеры с рангом 32, прикрепленные к каждому линейному слою (all-linear). Модели выполняют 8 прогонов (rollouts) на задачу, и для всех видов обучения мы используем скорость обучения (learning rate) 1e-5.

Каждый запуск объединяет задачи SmolDataEnvs с акцентом на средние и сложные, а также 230 задач из 270 задач Repo2RLEnvs. Остальные 40 задач Repo2RLEnvs и 150 задач SmolDataEnvs отложены для оценки и никогда не используются в обучении.

Некоторые общие параметры: температура выборки 0.8, до 32 768 токенов вывода за один ход, прогоны устаревают не более чем после 4 обновлений весов, 4 шага накопления градиента и сохранение контрольной точки каждые 10 шагов с оценкой каждой из них. TwIL получает 30 шагов агента за сеанс и тайм-аут 20 минут, так как ей требуется больше шагов для задач (поскольку она не обучалась на данных агентов).

• Награда: собственный верификатор задачи плюс небольшой бонус за решение с меньшим количеством вызовов инструментов: 0.1 × (1 — вызовы / 15), только для правильных прогонов. Вес был выбран в ходе абляционного исследования.
• Режим размышлений (thinking mode): мы оставляем режим размышлений для всех наших моделей как при обучении, так и при оценке. Рассуждения с предыдущих шагов сохраняются в контексте.
• Среды агентов выполняются в неизмененном виде, каждая в собственной изолированной среде для каждого прогона благодаря интеграции Harbor от OpenEnv. Запросы моделей направляются в vLLM тренера, а обучение использует ровно те токены, которые видела среда, без повторной токенизации.

Инфраструктура

Мы обучаем модели на HF Jobs: 2×H200 для LFM3-1.7B и 4×H200 для остальных запусков. Общая стоимость каждого запуска обучения указана на интерактивной панели управления для заданий обучения.

Одна базовая модель, множество адаптеров

Адаптеры приносят пользу в двух аспектах, оба из которых показаны ниже: переключение между режимами обучения и оценки. В следующих разделах каждый из них рассмотрен подробно.

Обучение

Каждая модель обслуживается одним экземпляром vLLM. Три ее тренера (по одному на каждую среду) отправляют прогоны в vLLM, причем каждый запрос указывает свой собственный адаптер, поэтому базовые веса загружаются один раз для всех трех. После шага градиента тренер загружает свой новый адаптер в vLLM по имени, рядом с текущим. Запросы, которые уже выполняются на старой версии, завершаются на ней, поэтому ничего не приостанавливается.

Для LFM3-1.7B три тренера даже делят один графический процессор: прогон агента большую часть времени проводит в песочнице, а не за генерацией, поэтому тренеры в основном ждут. В предыдущих запусках тренер тратил около 35 с на шаг на проходы вперед и назад (forward и backward passes) по сравнению с несколькими минутами ожидания прогонов. Трое из них сменяют друг друга, а не простаивают в одиночку.

Из чего состоит один шаг обучения

Обучение является асинхронным, то есть прогоны и шаги градиента не ждут друг друга. Каждый тренер поддерживает до 48 одновременно работающих сеансов агента — около 6 задач с 8 прогонами в каждой (12 сеансов для TwIL-8B, чьи длинные рассуждения быстрее заполняют память vLLM). Задача попадает в очередь обучения после того, как все 8 ее прогонов получат оценки, так как GRPO сравнивает их друг с другом.

Один шаг градиентного спуска упаковывает завершенные прогоны в 4 микробатча, каждый из которых ограничен токеновым бюджетом: 131 072 токена для LFM2.5-24B-A2B, 65 536 для LFM3-1.7B и TwIL-8B. Таким образом, количество задач за шаг не фиксировано: короткие сессии вмещают много задач, а длинные — мало. Наши предыдущие запуски LFM2.5-24B-A2B обучались примерно на 8 задачах (64 прогона) за шаг, а пробный запуск TwIL-8B — примерно на одной. После шага новая версия адаптера загружается в vLLM, а прогоны, запущенные более чем на 4 версии раньше, отбрасываются, поэтому модель никогда не обучается на политике, которая слишком сильно отстает от текущей.

Панель управления записывает оба показателя для каждого запуска: batch/groups_per_step (задачи) и batch/samples_per_step (прогоны). Они также определяют частоту возврата задачи: при 8 задачах за шаг 200 шагов для LFM2.5-24B-A2B проходят по его 530 задачам примерно 3 раза.

Оценка

Тот же трюк позволяет оценивать все контрольные точки одновременно. Один экземпляр vLLM загружает базовые веса, а затем каждая контрольная точка загружается как адаптер, причем для каждой контрольной точки выделяется один песосочный сервер (sandbox server), выполняющий свои отложенные задачи параллельно. Девять контрольных точек LFM2.5-24B-A2B (всего 1350 агентских сессий) выполнили запуск на одном узле H200 менее чем за час, что обошлось примерно в 5 долларов процессорного времени GPU. Объединение каждой контрольной точки в полные веса и их обслуживание по отдельности стоило бы около 90 долларов. А оценка измеряет адаптер именно в том виде, в каком он обучался (ничего не объединяется и не конвертируется).

Окружения

• SmolDataEnvs: вопросы по анализу данных из публичных блокнотов Kaggle. Агент получает файлы данных в своей песочнице и пишет один ответ, который оценивается по точному или численному совпадению. Это датасет, используемый в ультимативном руководстве по мультифреймовому RL.
• Repo2RLEnvs: задачи, воссозданные на основе открытых траекторий агентов, опубликованных пользователями на Hub. Траектория становится задачей, когда она содержит проверяемую единицу работы: исправление, сборку, расширение или контроль качества (qa).

Как мы улучшили миксы с помощью RL-окружений, созданных на основе траекторий агентов с открытым исходным кодом

Исходным материалом являются агентские сессии, опубликованные пользователями на Hugging Face Hub из pi, Claude Code, Codex и других фреймворков. Они преобразуются в траектории ATIF, после чего каждая из них проходит через шесть одинаковых этапов. Кандидат, не прошедший хотя бы один из них, отбрасывается с фиксацией причины.

• Фильтрация (Screen): отбрасывает траектории с подменой вознаграждения (reward tampering) или утечкой бенчмарков.
• Воспроизведение (Replay): каждая запись и изменение файла применяются к виртуальной файловой системе, поэтому каждая команда оболочки поставляется с файлами в том виде, в котором они были непосредственно перед ее запуском.
• Поиск работы (Find work): каждое семейство ищет свою единицу работы: проверка, которая завершилась ошибкой, а затем прошла успешно после правок (исправление); проект на Python, завершенный с первого запроса (сборка); последующее изменение, проверки которого проходят успешно (расширение); факт, вычисленный на основе общедоступных данных Hub (контроль качества). Это единственный этап, на котором используется LLM: для задач сборки и расширения модель-учитель (Mistral-Large-4-1T-A52B) пишет контракт интерфейса, заглушку и скрытые тесты (для контроля качества она предлагает вопросы). Задачи исправления не требуют LLM: их проверка берется из самой траектории. В этом релизе 259 из 270 задач содержат тесты, написанные учителем.
• Сборка и проверка (Build and check): окружение собирается в виде образа Docker и проверяется в автономном режиме без участия LLM, поэтому тестам учителя никогда не доверяют без проверки. Исправление должно завершаться ошибкой тем же способом, который был зафиксирован в траектории; тесты сборки должны проходить на эталоне, завершаться ошибкой на заглушке и пустой рабочей области, а также отлавливать большинство внедренных багов (мутационное тестирование).
• Матрица испытаний (Trial matrix): оригинальное решение должно получать полное вознаграждение дважды, в то время как бездействие, использование заглушки или манипуляции с тестами должны приносить 0 баллов.
• Публикация и оценка (Publish and score): образ отправляется в реестр и закрепляется по дайджесту в task.toml после повторного запуска в нем оракула. Затем LFM2.5-24B-A2B (самая большая модель, которую мы обучаем) пытается выполнить каждую задачу несколько раз в качестве эталонного агента (под управлением terminus-2), и процент успешных решений определяет метку сложности: «сложно» при показателе ниже 0,3, «средне» до 0,6, «просто» выше 0,6.

Как определяется тип задачи

Теперь давайте погрузимся в то, как определяется тип задачи (исправление, контроль качества, сборка, расширение). На этом этапе LLM не задействована: воспроизведенная траектория уже записывает каждую команду, выполненную агентом, ее код выхода и файлы до этого, а также места начала каждого запроса пользователя. Каждый тип представляет собой простое правило на основе этих данных, поэтому одна и та же траектория всегда дает одних и тех же кандидатов:

• исправление (repair): проверка (pytest, npm test, tsc...) завершается с ненулевым кодом, а затем та же команда завершается с кодом 0 после правок, причем между ними не выполнялось новых установок, а сами тесты остались нетронутыми.
• сборка (build): ко второму запросу имеется по крайней мере два файла на Python, и последняя проверка Python прошла успешно.
• расширение (extend): более поздний запрос изменяет исходный код существующего проекта на Python, и его проверки завершаются успешно.

LLM подключается только после этого, там, где требуется понимание: написание контракта и тестов для кандидата, чей тип уже определен.

Откуда берется оракул

Каждая задача поставляется с оракулом: эталонным решением в папке solution/, которое должно получить полное вознаграждение в собственном образе задачи, иначе задача отбрасывается. Почти во всех случаях оракул написан не LLM: это собственная работа оригинального агента, взятая из траектории, где она действительно происходила и успешно проходила проверки.

Таким образом, LLM-учитель пишет экзамен, а траектория предоставляет ключ ответов, по которому он проверяется. Для сборки и расширения тест сохраняется только в том случае, если он дважды проходит на оракуле и завершается ошибкой на заглушке (том же интерфейсе без поведения) и на пустой рабочей области, причем сохраненные тесты должны обнаруживать большинство намеренно внедренных ошибок. Неправильный тест завершается ошибкой на оракуле и отбрасывается; слишком слабый тест, неспособный отличить реальный код от заглушки, также отбрасывается.

Изучение нескольких задач

Выберите задачу и файл, чтобы прочитать их так, как их видят агент и верификатор. Эти пять взяты из harness-hub/traj2envs-rl — по одной на каждый тип задачи и уровень сложности в этом релизе.

Распределение со смещением в сторону задач сборки

Релиз далек от сбалансированности: 253 из 270 задач представляют собой задачи сборки (94%), против 11 на исправление, 6 на расширение и ни одной на контроль качества. Мы все же описываем контроль качества, чтобы поделиться полным рецептом создания окружения, и планируем включить больше таких задач в будущие релизы. 243 из 270 задач получены из одного источника — TeichAI/Ox-Alpha-Pi-Traces, и 238 из них являются задачами сборки. Такое смещение обусловлено содержимым общих траекторий и строгостью каждого типа задач:

• Большинство общих сессий представляют собой одноразовые запросы «собрать X»: сессия, завершающая проект на Python с первого запроса, — это именно то, что ищет сборка, поэтому основные датасеты траекторий в основном порождают задачи сборки.
• Для исправления требуется редкий паттерн: проверка, которая завершилась с ошибкой, а затем успешно прошла после правок без промежуточных установок и которая снова завершается с той же ошибкой при пересборке проекта в чистом образе. Лишь немногие сессии фиксируют это, и еще меньше воспроизводят.
• Для расширения требуется второй запрос, который изменяет готовый проект на Python и завершается успешным прохождением проверок. Сессии с несколькими запросами — скорее исключение в этих датасетах.
• Для контроля качества требуется факт, вычисленный из общедоступных данных Hub и процитированный дословно в выводе инструмента. Сессии кодирования редко содержат таковые, и ни одна из них не прошла в этом релизе.

Метки сложности распределяются следующим образом: 179 задач легкие для LFM2.5-24B-A2B, 61 средняя и 30 сложных. Именно поэтому коэффициенты микширования для каждого запуска смещают SmolDataEnvs в сторону средних и сложных задач, и именно поэтому нам нужно больше задач на исправление и доработку: им нужны сессии, где что-то идет не так и исправляется, либо где проект развивается в ходе нескольких запросов. Публикация таких сессий, очищенных с помощью safeagents, является наиболее полезным вкладом.

В каждой задаче фиксируется, как часто эталонный агент решает ее, а обучающий микс отдает предпочтение задачам, которые решаются иногда, но не всегда: GRPO учится только на группах, где одни генерации проходят тесты, а другие нет. переходит на Repo2RLEnv, и ее репозиторий будет отправлен в архив.

Сказываем 🙅 обходным путям агентов

RL находит обходные пути: политика, получающая вознаграждение за прохождение тестов, рано или поздно попытается прочитать тесты, переписать их или получить ответ из того места, откуда взялась задача. Поэтому каждый вызов инструмента проходит через , прежде чем тестовый каркас запустит его.

safeagents — это обратный прокси-сервер: небольшой сервер, установленный перед другим сервером, с которым клиенты общаются так, будто это настоящий сервис. Базовый URL тестового каркаса указывает на safeagents вместо vLLM. Каждый запрос проходит через него без изменений; каждый ответ возвращается обратно через него, а содержащиеся в нем вызовы инструментов проверяются до того, как их увидит каркас. Ни каркас, ни vLLM не знают о его существовании, и он поддерживает как API OpenAI Chat Completions, так и Anthropic Messages, со стримингом и без него. Во время обучения он работает в фоновом потоке тренера.

Проверки на основе правил

Каждая проверка представляет собой правило, а не модель: один и тот же вызов всегда получает один и тот же вердикт примерно за 10–20 мс, и политика не может обойти его путем уговоров. Каждый вызов инструмента проходит три этапа в строгом порядке:

• Сам запрос: вызов должен использовать инструмент, объявленный в запросе, а любой хост, к которому он обращается, должен где-то упоминаться в диалоге. Собственные предыдущие реплики модели не учитываются, поэтому она не может выдумать URL, а затем сослаться на саму себя.
• Детекторы : накопленный диалог преобразуется в трассировку ATIF и сканируется с помощью atif-scan — того же сканера, который проверяет траектории для Repo2RLEnvs. Его встроенные правила охватывают подделку наград, редактирование тестов, поиск по бенчмаркам, обход прокси и многое другое. Обнаружение проблемы высокой степени серьезности или выше блокирует вызов; более мягкие нарушения регистрируются как подозрительные, и вызов выполняется.
• Необязательный судья: модель может просматривать вызовы, которые atif-scan посчитала подозрительными. Она видит запрос пользователя, вызов и результаты проверки, но никогда не видит рассуждения агента, и она может только добавлять блокировки, но не снимать их. Мы оставляем эту функцию отключенной и не исследуем данное направление здесь.

Заблокированный вызов заменяется в ответе текстовым уведомлением: [safeagents] заблокирован вызов `bash`: …, а остановка по причине «использования инструмента» превращается в обычную остановку. Ничего не выполняется. Функция вознаграждения дает 0 любой генерации, содержащей уведомление, а поскольку идентификаторы токенов и логпробы проходят насквозь без изменений, тренер по-прежнему обучается на заблокированных токенах: GRPO подавляет эту попытку.

Пойман с поличным во время пробного запуска

Нам не пришлось долго ждать, чтобы увидеть это в действии. Во время пробного запуска TwIL-8B на шаге 0, до каких-либо обновлений, модель работала над задачей SmolDataEnvs: ответить на вопрос о датасете Kaggle. Вместо того чтобы вычислить ответ, она отправилась на поиски бакета Hugging Face, откуда были взяты данные задачи и где мог находиться оригинальный ноутбук:

Команда называется jupyter-agent-kaggle — это один из источников, перечисленных в нашем плагине SmolDataEnvs. Вызов так и не был выполнен, pi получил уведомление, а генерация получила оценку 0. Модель, которая ищет ответы на шаге 0, — это главная причина, почему защита включена с самого первого шага, а не добавляется после того, как что-то идет не так.

Плагины, с которыми мы обучаем

Встроенные правила atif-scan осведомлены о бенчмарках в целом, но не о том, где хранятся ответы наших задач. Плагин добавляет это: модуль Python, фабрика которого возвращает дополнительные правила обнаружения, загружаемые с помощью --plugin MODULE:FACTORY. Каждый из наших плагинов состоит из трех регулярных выражений, которые сопоставляются только с тем, что пишет агент (команды, аргументы инструментов, содержимое файлов, поисковые запросы и URL), но никогда с тем, что возвращают инструменты:

Правило состоит из нескольких строк:

Поскольку каждый запуск объединяет обе среды, тренер загружает оба плагина:

Их совместная загрузка потребовала одного исправления. Правило SmolDataEnvs изначально сопоставлялось с любым grader.py, а задача сборки Repo2RLEnvs просит агента написать именно его: небольшую библиотеку автоматического тестирования. Из-за этого правило оценивало бы правильную работу нулем. Теперь оно сопоставляется только с /tests/grader, где располагается проверяющий модуль SmolDataEnvs. При повторном сканировании с обоими плагинами 253 сессии агента по задачам Repo2RLEnvs не совпали ни с одним из их правил. Песочницы вообще не получают токен Hugging Face; правила для учетных данных присутствуют на случай их утечки.

В абляции из 50 шагов (pi, LFM2.5-24B-A2B) включение защиты изменило отложенный показатель pass@1 на +0.0 ± 4.1 пункта: она ничего не стоит. Она нужна на случай, если политика проявит креативность, как показал пример TwIL-8B.

Что дальше

Финальные запуски обучают все три модели на всех трех тестовых каркасах: 200 шагов для LFM2.5-24B-A2B, 400 для LFM3-1.7B и 300 для эксперимента TwIL, причем каждый чекпоинт оценивается по мере его появления. Они транслируются на панели управления live: вознаграждение при обучении, отложенный pass@1 для каждого чекпоинта, вызовы инструментов на решенную задачу и каждое событие safeagents.

Все находится в открытом доступе: среды, правила safeagents, рецепт обучения, результаты оценки каждого чекпоинта и каждый заблокированный вызов инструмента. Создано с помощью TRL, OpenEnv, Harbor и vLLM.

Возможности: обучите адаптер для собственного агента

Ничто в этом рецепте не привязано исключительно к нашим каркасам или нашим задачам. Сессии, которые вы уже запускаете со своим агентом, являются сырьем для его следующего адаптера:

• Сохраняйте свои траектории: сохраняйте сессии используемого вами каждый день агента независимо от каркаса (pi, opencode, hermes, Claude Code, Codex…).
• Очищайте и делитесь ими: средство очистки safeagents удаляет учетные данные, секреты, электронные письма и домашние директории, а публикация safeagents отправляет на Hub только отредактированную копию. Каждая общая сессия является потенциальной средой для вас и всех остальных.
• Превращайте их в среды: воссоздает каждую сессию в виде проверяемой задачи с ее Docker-образом, скрытыми тестами и оракулом, взятым из самой сессии.
• Обучайте LoRA-адаптер внутри своего каркаса: запустите тот же рецепт RL с , safeagents и собственным небольшим плагином, защищающим каждый вызов инструмента, а затем поместите адаптер за вашим локальным агентом.

Чем больше людей делятся своими сессиями, тем разнообразнее становятся среды, и мы особенно испытываем недостаток в сессиях, где что-то ломается и исправляется или где проект развивается в ходе нескольких запросов. Если вы обучите адаптер для каркаса, который мы еще не охватили, мы будем рады об этом услышать.

Благодарности

Спасибо Aritra Roy Gosthipaty, Shaun Smith, Adithya S Kolavi, Ben Burtenshaw и Amine Dirhoussi за помощь и отзывы об этой работе.