Human-Agent-Society/reef · 上手攻略

  • 仓库：Human-Agent-Society/reef
  • 链接：https://github.com/Human-Agent-Society/reef
  • 分类：AI Infra · Continual Learning
  • 作者：Jay
  • 更新：2026-09-03

是什么

Reef 是持续学习基础设施，让 AI Agent 在真实任务中不断自我改进。它在推理端点之上叠加了「记录 → 反馈 → 训练 → 发布」四步闭环：模型每次响应都被记录为"收据"（receipt），外部评判系统（测试套件、验证器、人工评分等）可以针对收据提交报告（report），Reef 的配方（recipe）消费足够报告后触发训练步骤，产出新模型权重或 Agent 工具链（harness），并通过发布链（release chain）无感推送到服务层——后续请求自动使用新版本，无需重启服务。

核心定位：Reef 不替代推理提供商，而是作为中间编排层，统一管理场景隔离、训练信号与模型/工具链迭代。

解决什么问题

主流 Agent 开发中，模型微调和工具链改进需要独立流程：导出数据 → 离线训练 → 重新部署。Reef 将这一流程内嵌到推理循环中，解决三个痛点：

  1. 反馈回路太长：人工导出、标注、训练、部署周期以天计；Reef 将此压缩到秒级（取决于配方配置）。
  2. 场景数据隔离缺失：多任务 Agent 的反馈数据混在一起导致负迁移；Reef 每个场景（scenario）独立管理记录、训练状态和发布链，天然隔离。
  3. 无法增量更新工具链：不只是模型权重，harness（规则、技能、提示词、配置）也可作为学习 surface；harness_evolve 配方专门做这件事。

快速安装

Reef 推荐使用 uv 管理 Python 环境：

# 方式一：从 PyPI（仅安装运行时依赖）
uv venv && source .venv/bin/activate
uv pip install reef-infra

# 方式二：从源码（包含训练示例，推荐开发者）
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 的 artifact 和 checkpoint 功能依赖 git-lfs，安装前需确保系统已装好 git-lfs。

核心用法

四步循环：Serve → Observe → Grow → Commit

Reef 每个学习周期经过四步，对应模块如下：

步骤 做什么 所在模块
1· Serve 接收 Agent 请求并记录交互 reef/service（请求+记录）、reef/runtime（推理+artifact 更新）
2· Observe 将反馈匹配到已记录交互 reef/records.py、train/processors/
3· Grow 从合格记录产出更新 recipe/（配方集成）、train/（批处理+训练任务）
4· Commit 评估并发布接受的更新 train/evaluation/、artifact/、surface/

启动本地 Reef 服务（笔记本电脑，无需 GPU）

使用 external-provider.yaml 配方，对接外部 OpenAI 兼容 API（无 GPU 需求）：

export REEF_TOKEN=reef-local
export REEF_UPSTREAM_API_KEY=sk-...   # 你的 API key

reef serve -c recipes/basic/external-provider.yaml
# 服务保持在前台，按 Ctrl-C 停止

# 另一个终端：健康检查
curl -f http://127.0.0.1:8900/healthz   # 返回 {"ok": true}

发送推理请求 + 提交报告

import httpx

reef = httpx.Client(
    base_url="http://127.0.0.1:8900",
    headers={"Authorization": "Bearer reef-local", "x-reef-scenario": "hello-reef"},
    timeout=300,
)

# 发送推理请求（OpenAI 兼容格式）
response = reef.post(
    "/v1/chat/completions",
    json={
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "Return exactly: reef is ready"}],
    },
)
response.raise_for_status()

# 从响应头获取 receipt（收据）
receipt = response.headers["x-reef-agent-record-id"]

# 用 receipt 提交反馈报告
matched = response.json()["choices"][0]["message"]["content"].strip() == "reef is ready"
report = reef.post(
    "/reef/report",
    json={
        "score": float(matched),
        "feedback": "matched" if matched else "wrong answer",
        "references": [receipt],
    },
)
print(report.json())

Reef 端点与 /v1/chat/completions 完全兼容（OpenAI 和 Anthropic 格式均支持），只额外多了一个 x-reef-scenario 请求头和一个 x-reef-agent-record-id 响应头。

使用 reef-client（更简洁的 stdlib-only 客户端）

pip install reef-client

from reef_client import ReefClient

client = ReefClient("http://127.0.0.1:8900", token="reef-local")
body, receipt = client.inference_with_record(
    "hello-reef",
    "/v1/chat/completions",
    {"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},
)
answer = body["choices"][0]["message"]["content"]

# ... 判断结果 ...
client.report("hello-reef", {"score": 1.0}, references=[receipt])

安装和运行进化后的 harness（类似安装 Claude Code）

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

# 使用下载的 harness 执行任务
reef-pi -p "fix the bug in auth.py"

Reef 的两种学习 surface

Reef 支持两种 artifact 类型：

  • Model weights（模型权重）：配方消费报告 → 训练步 → 更新权重 → 推送到推理运行时。需要 GPU（见 Evolve your model）。
  • Agent harness（Agent 工具链）：harness_evolve 配方从报告构建候选 harness，在配置任务上对比候选与当前 harness，只发布胜者。无需 GPU，适合笔记本电脑。

配方（Recipe）

配方决定：哪些记录合格 → 如何成批 → 如何产生训练信号 → 候选是否足够好值得发布。开发者可自定义配方，见 Write a recipe。

典型适用场景

  1. 需要 Agent 在真实任务上持续改进的团队：Reef 将「反馈 → 训练 → 部署」闭环自动化，无需人工介入。
  2. 多场景隔离的 Agent 产品：例如同时服务代码审查、文档生成、数据分析的同一个基础模型，每个场景独立进化不互相污染。
  3. 工具链（harness）快速迭代：无需重训模型就能通过 harness_evolve 改进 prompt/规则/技能，尤其适合无 GPU 的个人开发者。
  4. 作为 MCP Server 的推理层：Reef 服务可被 Claude Code、Cursor 等 Agent 直接调用，同时记录每一次交互用于后续学习。

坑与注意

  • ⚠️ Git LFS 强制依赖：artifact/checkpoint 功能需要 git lfs install，未装则 Reef 初始化 artifact 仓库会失败。
  • ⚠️ Scenario 永久绑定：第一次请求携带新的 x-reef-scenario 值即创建对应场景，绑定到当前部署的配方，不可更改。设计场景时要提前规划。
  • ⚠️ 模型权重训练需要 GPU：reef serve 可以纯 CPU 跑，但配方若更新 model weights 则必须配合 GPU 环境（见官方文档 GPU 需求章节）。
  • ⚠️ Report 消费一次：每个 report 只能被配方消费一次，重试或延迟到达不会被重复计算；如果需要幂等语义需在客户端自行处理。
  • ⚠️ Release chain 非内存持久化：Runtime load ID 保存在引擎内存中，重启后丢失；Git-backed durable releases 可被 pin 或 rollback，但运行时状态不跨重启恢复。
  • 当前版本： Reef 依赖 reef-infra（PyPI）和 reef（源码 pip install -e .），版本号通过 python3 -c "import reef; print(reef.__version__)" 确认，具体语义版本号未在文档中明确标注，需以实际查询为准。

与同类对比

项目 定位 学习 surface 依赖 适用场景
Reef 持续学习基础设施 weights + harness Python, git-lfs, 可选 GPU 需要完整学习闭环的 Agent 产品
AgentEval（微软） 评估驱动改进 评估信号 Python 单次评估驱动微调
DSPy 可编程 LM 优化 prompt/weight Python 自动优化 prompt 和 weight
OpenAI Fine-tuning 经典微调 model weights 云端 需要集中化训练的团队
harness_evolve 单独用 工具链进化 harness only 无 GPU 纯 CPU 环境的 prompt/规则迭代

Reef 的独特价值：在推理原地完成学习闭环，无需数据导出、无需独立训练服务，且 harness 和 weights 两条 surface 并存。

一句话推荐结论

Reef 将「Agent 反馈 → 持续改进」的闭环嵌入推理层，适合需要真实任务中不断进化的 AI 产品团队，尤其值得在 harness 进化方向探索（无需 GPU，笔记本即可跑）。

⚠️ 备注：Reef 仍处于活跃开发阶段，API 和配置格式可能在 minor version 发生破坏性变更；生产使用前建议关注 GitHub Releases 和 Roadmap Issue #25。