Reef

面向自我进化 Agent 的持续学习基础设施

[![CI](https://github.com/Human-Agent-Society/reef/actions/workflows/ci.yml/badge.svg)](https://github.com/Human-Agent-Society/reef/actions/workflows/ci.yml) [![PyPI package: reef-infra](https://img.shields.io/pypi/v/reef-infra?label=PyPI%3A%20reef-infra&logo=pypi&logoColor=white)](https://pypi.org/project/reef-infra/) [![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](pyproject.toml) [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) [English](README.md) | 中文
Reef 是首个面向持续自我进化 Agent 的开源基础设施。它连接 Agent 推理、反馈、学习与 版本化交付。你可以用它配合 Slime 和 SGLang 训练模型权重，也可以改进 Agent 的 harness，包括提示词、规则和技能。
**🚀 [快速上手](https://reefinfra.ai/docs/getting-started/quickstart/) | 🗺️ [路线图](https://github.com/Human-Agent-Society/reef/issues/25) | 📣 [发布文章](https://x.com/ao_qu18465/status/2094867930081337730) | 💬 [加入 Discord](https://discord.gg/5y8e5f937k) | 📱 [加入微信群](docs/community/wechat.md)**
## 🎯 何时使用 Reef 如果你希望 Agent 通过与你的日常交互不断学习、持续进化，就适合使用 Reef。 | 你的目标 | 学习路径 | 所需条件 | |---|---|---| | 持续获得更贴合自身需求的强大模型 | 模型权重训练 | 可训练模型、受支持的 GPU 栈，以及 recipe 可利用的反馈 | | 让 harness 自我进化 | Harness 优化 | 模型端点、有代表性的任务和评估器；无需本地训练 GPU | | 进行科学发现 | 测试时训练 | 执行环境、正确性检查器和可度量的目标 | ## 🧩 Reef 在技术栈中的位置 | 能力 | 推理引擎（vLLM、SGLang…） | RL 训练框架（Slime、veRL、AReaL…） | **Reef** | |---|:---:|:---:|:---:| | 承接线上流量 | ✅ | ❌ | ✅ | | 训练权重 | ❌ | ✅ | ✅ | | 版本管理 | ❌ | ❌ | ✅ | | 更新期间持续服务 | ❌ | ❌ | ✅ | | 可进化权重以外的部分（技能、harness） | ❌ | ❌ | ✅ | ## 🔄 工作原理
Reef 响应请求、记录反馈、产出更新，并将通过的更新提交至版本历史。
Reef 的每个学习周期分为四步，下表同时列出各步骤对应的模块。 | 步骤 | 说明 | 对应模块 | |---|---|---| | **1 · Serve** | 响应 Agent 请求，记录每次交互。 | [`service/`](reef/service) — Agent 请求与交互记录
[`runtime/`](reef/runtime) — 推理与 artifact 更新 | | **2 · Observe** | 将反馈匹配到已记录的交互。 | [`storage/records.py`](reef/storage/records.py) — 已存储的交互与反馈
[`train/processors/`](reef/train/processors) — 反馈匹配与条件判定 | | **3 · Grow** | 从符合条件的记录中产出一次更新。 | [`recipe/`](reef/recipe) — recipe 接入
[`train/`](reef/train) — 批次与更新任务 | | **4 · Commit** | 应用配置的选择策略并发布通过的更新。 | [`train/evaluation/`](reef/train/evaluation) — 候选评估
[`artifact/`](reef/artifact) — 版本历史
[`surface/`](reef/surface) — artifact 分发 | ## 📦 安装 > 💡 **注意** > > Reef 的 artifact 和 checkpoint 功能依赖系统的 `git-lfs` 包。Reef 会在本地为自身的 > artifact 仓库初始化 Git LFS。 推荐使用 [uv](https://docs.astral.sh/uv/) 管理依赖，下文命令均基于 uv。 ### 通过 PyPI 安装 ```bash uv venv && source .venv/bin/activate uv pip install reef-infra python3 -c "import reef; print(reef.__version__)" ``` ### 通过源码安装 ```bash 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__)" ``` 开发或运行下文的训练示例时，请使用源码安装。 ## 🔧 使用 Reef Reef 支持两类学习载体：模型**权重**和 Agent 的 **harness**。每个部署使用的 recipe 决定其 scenario 更新哪一种载体。 作为最小示例，将 Reef 启动为纯推理服务： ```bash uv run reef serve --inference.model-path Qwen/Qwen2.5-1.5B-Instruct ``` ### 模型权重训练部署 #### 启动部署 下面的示例启动 SAO（arXiv:2607.07508）示例部署。请在 Reef 源码目录下运行，并确保 运行环境满足[进化你的模型](https://reefinfra.ai/docs/user-guide/evolve-your-model/)中的 GPU 要求。 ```bash 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 \ --inference.model-path "$MODEL_PATH" \ --reef.port "8900" curl -f http://127.0.0.1:8900/healthz # ready to serve ``` #### 发送推理请求并上报反馈 将推理请求发送至 Reef，并为每个响应上报分数。SAO recipe 使用每条符合条件的带分 rollout 执行一次训练。 Reef 的推理端点兼容 OpenAI 和 Anthropic：`/v1/chat/completions` 与 `/v1/messages` 直接接收相应模型提供商的请求体。请求需包含 `x-reef-scenario` 请求头；新的名称会使用 部署配置的 recipe 创建 scenario。请求本身不选择 recipe。 响应体使用模型提供商的 OpenAI 兼容格式。Reef 会添加 `x-reef-agent-record-id` 响应头， 其值是后续报告用来标识本次交互的**回执**。报告可以包含数值 `score`、文本或结构化 `feedback`，以及它所评估的回执。下面的示例同时上报分数和简短说明。 ```python 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, ) # Send a provider-compatible inference request response = reef.post( "/v1/chat/completions", json={ "model": os.environ["MODEL_PATH"], "messages": [{"role": "user", "content": "Return exactly: reef is ready"}], }, ) response.raise_for_status() 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() ``` 部分 recipe 需要的不止一个分数，`feedback` 用于承载更丰富的信号，可以是纯文本或 结构化对象。端点会校验**上报 schema**（[`reef/core/reports/`](reef/core/reports)）。 #### 观察学习与进化 反馈积累到一定数量后，recipe 会执行一次训练，并将更新后的权重同步至推理运行时。 后续推理请求直接使用当前版本，无需重启 Reef。 ### Harness 进化部署 使用模型 API 改进 harness 技能，无需 GPU。 harness 进化 recipe 自带 profile，只需指定 provider URL 和模型。在 Reef checkout 和已激活的 Python 环境中： ```bash reef serve --recipe harness-evolve \ --inference.upstream-url http://127.0.0.1:11434 \ --inference.upstream-model gemma4:26b ``` 该示例连接本地 Ollama 服务。使用其他 provider 时，修改 `--inference.upstream-url` 和 `--inference.upstream-model`；需要认证时设置 `REEF_UPSTREAM_API_KEY`。 该 profile 监听 `127.0.0.1:8900`，不设 token，状态保存在 `.reef/harness-evolve/`。 需要修改其他内容时，复制[该 profile](reef/service/profiles/harness-evolve.yaml) 并用 `-c` 传入你的副本。 在另一个已激活同一 Python 环境的终端中（安装会把该终端的 `python3` 写入 `reef-pi`）安装 harness 并运行任务： ```bash curl -fsS 'http://127.0.0.1:8900/reef/harness/install?adapter=pi' | bash reef-pi -p "fix the failing test in auth.py" # After running your tests, report the actual result: reef-pi report --score 0 --feedback "missed the empty-token case" ``` 要更换模型，用另一个 `--inference.upstream-model` 重启 `reef serve`，并在 `reef-pi` 之前重新执行安装命令： 安装过程会将模型 ID 写入本地 harness 配置。 失败报告会触发候选技能更新。Reef 会在教程的三个编程任务上对候选技能和当前 harness 进行评估，仅在候选胜出时才发布。如何自定义任务和评估方式，请参阅 [教程](tutorials/evolve-your-harness/README.md)。 要用一句话向 harness 提出修改需求，并看到从提出到安装的完整流程，请运行 [Reefine 教程](tutorials/reefine/README.md)。 Reefine 随 `reef-infra` 内置提供：运行 `reef serve --recipe reefine --model ollama/gemma4:26b` 即可启动。 ## 📚 Recipes 与示例 根据工作负载的**任务类型**和希望**进化的对象**（模型权重或 Agent 的 harness）来选择 recipe。进化权重的 recipe 需要 GPU 训练栈，而 harness recipe 只需要一个模型端点。下表中每个 recipe 链接到其指南，每个已测 benchmark 链接到其结果页，[Recipe 目录](https://reefinfra.ai/docs/user-guide/recipes/) 还列出了每个 recipe 的代码和示例。Reefine 随 `reef-infra` 内置提供，其他实现位于本仓库的 `recipes/` cookbook 中，通过带点号的类路径指定，不随 Reef wheel 发布。 | 任务类型 | 任务形状 | 进化模型 | 进化 harness | 标准 benchmark | |---|---|---|---|---| | 科学发现 | 对一个有可度量目标的难题反复尝试 | [TTT-Discover](https://reefinfra.ai/docs/user-guide/recipes/tttd/)、[Guidance-TTT](recipes/tttd/examples/guidance_ttt/README.md) | 暂无 | 已测：[TriMul](recipes/tttd/examples/guidance_ttt/results/README.md)、[圆填充](recipes/tttd/examples/tttd/README.md#formal-8x64-results)、[Erdős 最小重叠](recipes/tttd/examples/tttd/README.md#formal-8x64-results)。 | | 任务流上的持续学习 | 由校验器逐个打分的独立任务流 | [SAO](https://reefinfra.ai/docs/user-guide/recipes/sao/) | [Meta-Harness](recipes/meta_harness/README.md)、[GEPA](https://reefinfra.ai/docs/user-guide/recipes/gepa/) | 已测：[AIME 2025](recipes/gepa/examples/aime/README.md)、[IMOAnswerBench](recipes/sao/examples/sao/README.md#results)、Terminal-Bench（[示例](recipes/meta_harness/examples/terminal_bench/README.md)、[结果](recipes/meta_harness/RESULTS.md)）。 | | 从使用中学习 | 没有人上报分数或反馈延迟到达的真实交互 | [OpenClaw-RL](https://reefinfra.ai/docs/user-guide/recipes/openclawrl/) | [SkillClaw](https://reefinfra.ai/docs/user-guide/recipes/skillclaw/)、[Reefine](docs/user-guide/recipes/reefine.rst) | 已测：[GSM8K 任务流上的模拟学生](recipes/openclawrl/examples/openclawrl/README.md#results)、[WildClawBench](recipes/skillclaw/README.md#the-2026-08-29-results-glm-53-flash-preliminary)。 | [`recipes/basic/`](recipes/basic/) 是只记录、不学习的起始栈，不在目录之内。如果想快速了解 反馈、候选修改和发布流程，可以从[编程 harness 教程](tutorials/evolve-your-harness/README.md)开始。 每个结果页面都会说明任务、评估设置、测量结果和局限性。 ## 📐 架构
Reef 架构：Harness 请求经 Scenario 转发到推理服务；通过 receipt 关联的反馈进入记录与 recipe 训练，候选产物经评估和选择后发布新版本。候选被拒绝时，继续使用当前版本。
## 📖 进一步了解 [文档](https://reefinfra.ai/docs/)按以下顺序组织： - [快速上手](https://reefinfra.ai/docs/getting-started/quickstart/)：安装 Reef，接入客户端，查看版本历史 - [HTTP API](https://reefinfra.ai/docs/reference/http-api/)：使用 HTTP API 并上报反馈 - [编写 recipe](https://reefinfra.ai/docs/developer-guide/write-a-recipe/)：配置 Reef 如何处理数据、产出更新 - [进化你的 harness](https://reefinfra.ai/docs/user-guide/evolve-your-harness/)：不训练权重，改进 harness - [进化你的模型](https://reefinfra.ai/docs/user-guide/evolve-your-model/)：配置并运维训练部署 - [Recipes](https://reefinfra.ai/docs/user-guide/recipes/)：按任务类型整理的 cookbook recipe 目录，含各自的代码、文档、示例和结果 - [核心循环](https://reefinfra.ai/docs/getting-started/core-loop/)：Reef 的核心循环 - [术语表](https://reefinfra.ai/docs/reference/glossary/)：文档所用术语的解释 ## 🤝 社区与贡献 你是否也在研究持续自我进化的 Agent？ - 加入 [Discord](https://discord.gg/5y8e5f937k)，分享 recipe、交流实现细节、讨论新功能。 - [加入微信群](docs/community/wechat.md)：群已满，扫码添加小助手拉你进群。 - 在 [GitHub Discussions](https://github.com/orgs/Human-Agent-Society/discussions) 提问、分享想法、与社区交流。 - 参与开发请从[贡献指南](CONTRIBUTING.md)开始。 - 设计方案请通过 [RFC issue](https://github.com/Human-Agent-Society/reef/issues/new?template=rfc.yml) 提出。 - 发现疑似漏洞请按[安全策略](SECURITY.md)私下反馈。 如果 Reef 对你有帮助，欢迎点个 Star ⭐，让更多人发现并参与进来。 ## 👥 团队 Reef 汇聚了一群探索 Agent 如何从经验中学习、持续进化的人。以下成员共同将这一想法 变成可用的基础设施。 这份名单并未列尽所有团队成员，以下按姓氏字母顺序排列： [Wenhao Chai](https://github.com/wenhaochai), [Shuangrui Ding](https://github.com/Mark12Ding), [Hao He](https://github.com/hehaodele), [Haoze He](https://github.com/HectorHHZ), [Chonghe Jiang](https://github.com/Chonghe-Jiang), [Nan Jiang](https://github.com/nanjiangwill), [Xuan Jiang](https://github.com/Xuan-1998), [Xiaochen Li](https://github.com/SeuperHakkerJa), [Paul Liang](https://github.com/pliang279), [Bo Liu](https://github.com/Benjamin-eecs), [Boyuan Long](https://github.com/BoyuanLong), [Qiuyang Mang](https://github.com/joyemang33), [Zhenting Qi](https://github.com/zhentingqi), [Ao Qu](https://github.com/quao627), [Mingruo Qu](https://github.com/workhardforcoding), [Zhaokai Wang](https://github.com/wzk1015), [Xuezhi Yan](https://github.com/yanxz), [Hanfei Yu](https://github.com/hanfeiyu), [Haofei Yu](https://github.com/lwaekfjlk), [Simon Yu](https://github.com/simonucl), [Han Zheng](https://github.com/MikeZheng777), [Kaichen Zhou](https://github.com/kaichen-z), [Zijian Zhou](https://github.com/BobbyZhouZijian), [Jiacheng Zhu](https://github.com/Jiacheng-Zhu-AIML), [Dingyi Zhuang](https://github.com/ZhuangDingyi). ## ⭐ Star History Reef Star 增长历史图 ## 🙏 致谢 以下项目支撑了 Reef 的关键部分，在此感谢： - [SGLang](https://github.com/sgl-project/sglang) — 高性能推理 - [slime](https://github.com/THUDM/slime) — 模型权重训练 - [cordis](https://github.com/cordiverse/cordis) — harness 进化