Reef: 에이전트가 서비스되는 동안 모델 가중치와 하네스를 계속 갱신하는 지속 학습 인프라

9bow · 9월 7, 2026, 12:00오후

Reef 소개

에이전트를 배포하고 나면 그 뒤로는 대체로 아무것도 학습하지 않습니다. 사용자가 답변을 고쳐 쓰거나 그대로 넘어가는 반응이 매일 쌓이지만, 그 신호를 모아 모델을 다시 학습시키고 새 가중치를 배포하는 일은 서비스를 세우고 파이프라인을 따로 돌려야 하는 별개의 작업입니다. 추론 엔진은 트래픽을 받는 데까지만 책임지고, 강화학습(reinforcement learning) 프레임워크는 학습 작업까지만 책임지기 때문에, 그 사이를 잇는 부분은 팀마다 매번 새로 만들게 됩니다.

Human-Agent-Society가 공개한 Reef는 그 사이를 채우는 인프라입니다. Reef는 표준화된 HTTP 엔드포인트를 노출해 두 가지 일을 한꺼번에 합니다. 하나는 에이전트의 모델 요청을 공급자 대신 자신의 추론(inference) 엔드포인트로 받는 것이고, 다른 하나는 그렇게 받은 상호작용과 뒤따르는 피드백을 근거로 백엔드에서 모델 가중치와 하네스(harness)를 갱신해 다시 서빙하는 것입니다. 프로젝트가 내세우는 사용자 경험은 에이전트를 쓰는 쪽에서 따로 할 일 없이 결과가 계속 좋아진다는 것입니다.

Reef는 Python 3.10 이상에서 동작하는 패키지이며 PyPI에 reef-infra라는 이름으로 올라와 있습니다. 추론에는 SGLang, 가중치 학습에는 slime, 하네스 진화에는 cordis를 활용한다고 밝히고 있고, 산출물과 체크포인트 기능이 Git LFS를 쓰기 때문에 git-lfs 시스템 패키지가 필요합니다.

Reef와 기존 추론 엔진, 강화학습 프레임워크의 차이

Reef는 자신의 위치를 추론 엔진과 강화학습 프레임워크 사이로 설명하며 다음 표를 제시합니다:

능력	추론 엔진(vLLM, SGLang 등)	강화학습 프레임워크(slime, veRL, AReaL 등)	Reef
실시간 트래픽 서빙	가능	불가	가능
가중치 학습	불가	가능	가능
버전 관리	불가	불가	가능
갱신 중에도 서비스 유지	불가	불가	가능
가중치 외의 대상 진화(스킬, 하네스)	불가	불가	가능

세 번째와 네 번째 행이 실제로 손이 많이 가는 부분입니다. 학습이 끝난 뒤 어느 버전을 서빙 중인지 추적하고, 새 버전으로 넘어가는 동안에도 요청을 계속 받으려면 별도의 배포 장치가 필요합니다. Reef는 갱신본을 Git 기반 버전 이력에 쌓고 서빙 런타임과 동기화하는 방식으로 이 부분을 안에 넣었습니다.

Reef는 누구에게 맞는가

자체 모델을 직접 서빙하면서 사용자 반응이나 자동 채점기의 점수를 이미 모으고 있는 팀에게 Reef가 잘 맞습니다. 점수를 붙일 수 있는 트래픽이 있다면 별도 학습 파이프라인을 세우지 않고도 서빙 경로 안에서 학습 주기를 돌릴 수 있고, 갱신본이 기존 버전을 이겼을 때만 공개되는 절차가 레시피에 들어 있어서 회귀 위험을 관리하기 쉽습니다.

반대로 상용 API 모델만 호출하는 팀에게는 Reef가 적절한 선택지가 아닙니다. 가중치를 갱신하는 레시피는 자신이 들고 있는 모델을 전제로 하며, 문서가 요구하는 GPU 환경도 필요합니다. 가중치 대신 하네스만 진화시키는 skillclaw 레시피는 GPU가 필요 없다고 명시되어 있으므로, 자체 모델이 없다면 이쪽부터 보는 편이 현실적입니다. 저장소가 2026년 8월 말에 처음 공개되었고 로드맵이 아직 이슈 하나로 관리되고 있다는 점도 도입 시점을 정할 때 감안할 부분입니다.

Reef의 학습 사이클

Reef는 학습 주기 하나를 네 단계로 나눠 처리하고, 각 단계가 저장소의 어느 모듈에 있는지까지 문서에 적어 두었습니다:

단계	하는 일	구현 위치
1. 서빙(Serve)	에이전트 요청을 처리하고 상호작용을 기록합니다.	`service/`, `runtime/`
2. 관찰(Observe)	들어온 피드백을 기록된 상호작용에 대응시킵니다.	`records.py`, `train/processors/`
3. 성장(Grow)	자격을 갖춘 기록으로 갱신본을 만듭니다.	`recipe/`, `train/`
4. 반영(Commit)	갱신본을 평가하고 통과한 것만 공개합니다.	`train/evaluation/`, `artifact/`, `surface/`

저장소가 공개한 구조도를 보면 요청 평면(request plane)이 OpenAI와 Anthropic 호환 형식으로 요청을 받아 추론 런타임으로 넘기고, 같은 요청을 시나리오별 기록 저장소에 남기는 흐름이 드러납니다:

실제 호출은 평범한 채팅 완성 요청과 거의 같습니다. 요청에 x-reef-scenario 헤더를 붙이면 되고, 처음 보는 이름이면 배포 설정에 지정된 레시피로 시나리오가 새로 만들어집니다. 요청 쪽에서 레시피를 고르지는 못합니다. 응답에는 x-reef-agent-record-id 헤더가 붙어 오는데, 이 값이 나중에 그 상호작용을 지목할 때 쓰는 영수증(receipt) 역할을 합니다:

import os
import httpx

reef = httpx.Client(
    base_url="http://127.0.0.1:8900",
    headers={"Authorization": f"Bearer {os.environ['REEF_TOKEN']}", "x-reef-scenario": "hello-reef"},
    timeout=300,
)

# Inference using Open-AI compatible format
response = reef.post(
    "/v1/chat/completions",
    json={
        "model": os.environ["MODEL_PATH"],
        "messages": [{"role": "user", "content": "Return exactly: reef is ready"}],
    },
)

receipt = response.headers["x-reef-agent-record-id"]
answer = response.json()["choices"][0]["message"]["content"]

# Sending report about the inference
matched = answer.strip() == "reef is ready"

reef.post(
    "/reef/report",
    json={"score": float(matched), "feedback": "matched" if matched else "wrong answer", "references": [receipt]},
).raise_for_status()

보고에는 숫자 점수만이 아니라 텍스트나 구조화된 피드백도 함께 담을 수 있고, 스칼라 값 하나보다 풍부한 신호를 읽는 레시피는 이쪽을 활용합니다.

Reef의 두 가지 학습 대상과 레시피

Reef가 갱신할 수 있는 대상은 모델 가중치와 에이전트 하네스 두 가지이며, 어느 쪽을 갱신할지는 배포에 설정한 레시피가 정합니다. 하네스를 갱신하는 harness_evolve 레시피는 규칙, 스킬, 설정, 프롬프트, 확장으로 이루어진 하네스 트리를 대상으로 삼습니다. 보고된 상호작용에서 후보를 만들고, 현재 하네스와 후보 하네스를 설정된 작업으로 평가한 뒤 후보가 이겼을 때만 공개합니다.

하네스는 코딩 에이전트를 설치하듯 내려받습니다. 시나리오를 헤더로 지정하면 그 시나리오에서 진화한 하네스를 받을 수 있습니다:

curl -fsS -H "Authorization: Bearer $REEF_TOKEN" \
  'http://localhost:8900/reef/harness/install?adapter=pi' | bash

reef-pi -p "fix the failing test in auth.py"
reef-pi report --score 0 --feedback "missed the empty-token case"

저장소의 recipes/ 요리책에 들어 있는 구현은 다음과 같습니다:

대상 작업	레시피 모듈	갱신 대상
테스트나 검증기가 채점하는 작업 흐름	`recipes.sao.recipe:SAORecipe`	모델 가중치
명시적 보고 없이 다음 상태 신호만 있는 에이전트 트래픽	`recipes.openclawrl.recipe:OpenClawRLRecipe`	모델 가중치
한 문제를 반복해서 채점하며 푸는 작업	`recipes.tttd.recipe:TTTDRecipe`	모델 가중치
채점되는 코드 탐색, 학습 가능한 안내 모델과 고정된 실행기	`recipes.tttd.recipe:TTTDRecipe`	안내 모델 가중치
에이전트 피드백으로 스킬 묶음을 진화	`recipes.skillclaw.recipe:SkillClawRecipe`	스킬 묶음(하네스 트리), GPU 불필요

이 레시피들은 Reef 배포 패키지(wheel)에 포함되지 않고 저장소의 요리책에만 있으며, 점으로 구분된 클래스 경로로 지정해 사용합니다. openclawrl 레시피는 사용자의 평소 사용 기록만으로 에이전트를 학습시키는 OpenClaw-RL ( OpenClaw-RL: 대화를 통해 학습하는 개인화 자율 에이전트 강화학습 프레임워크 (feat. Gen-Verse)) 방식을 옮긴 것으로, 별도의 보고 호출 없이 Reef가 이미 기록한 트래픽에서 세션을 복원해 학습 신호를 만듭니다.

Reef가 공개한 학습 곡선

저장소는 SAO 레시피의 실행 결과를 원본 차트로 함께 공개하고 있습니다. SAO는 Single-Rollout Asynchronous Optimization 방식이며, 아래 차트는 Qwen3-30B-A3B 모델로 IMOAnswerBench의 문제 3개(problem_idx 4, 8, 12)를 대상으로 삼아 각 조건마다 채점된 롤아웃 48회를 돌리고, 학습하지 않은 기준 모델 및 GRPO(Group Relative Policy Optimization) 계열 기법과 비교한 결과입니다:

48회 시점의 누적 평균 보상은 학습하지 않은 기준 모델이 0.458, SAO가 0.479, 비교 대상인 GRPO(+DIS)가 0.417입니다. SAO는 기준선을 0.021만큼 웃돌았고 GRPO(+DIS)는 기준선 아래로 내려갔습니다. 문제 3개와 롤아웃 48회라는 규모에서 나온 값이므로, 이 차트는 학습 주기가 실제로 돌아간다는 것을 보여주는 예시에 가깝고 레시피 사이의 우열을 결론짓기에는 표본이 작습니다.

Reef 설치와 사용

패키지 관리에는 uv를 권장하고 있습니다. PyPI에서 받는 방법과 소스에서 받는 방법 모두 문서에 있으며, 아래 예제들을 돌려보려면 소스 체크아웃 쪽이 필요합니다:

git lfs install
git clone https://github.com/Human-Agent-Society/reef.git
cd reef
uv venv && source .venv/bin/activate
uv pip install -e .
python3 -c "import reef; print(reef.__version__)"

SAO 예제 배포를 띄우는 명령은 다음과 같습니다:

uv pip install -e ".[slime]" && uv pip install --no-deps --group runtime

export MODEL_PATH="Qwen/Qwen2.5-1.5B-Instruct"
export REEF_TOKEN="reef-local"

reef serve -c recipes/sao/examples/sao/serve.yaml \
  --reef.model_path "$MODEL_PATH" \
  --reef.port "8900"

curl -f http://127.0.0.1:8900/healthz          # ready to serve

Reef의 라이선스

Reef는 Apache 라이선스 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

Reef 문서 사이트

Reef 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 글은 파이토치 한국 사용자 모임이 직접 정리한 글입니다. 새 글을 놓치지 않으시려면 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로 알림을 받으시고, 회원으로 가입하시면 주요 글들을 이메일로도 보내드립니다!

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~