garrytan/gbrain-evals

# gbrain-evals [gbrain](https://github.com/garrytan/gbrain) 的测试套件，AI agent 读取和写入的长期记忆。 这里的所有内容都是公开的，在你自己的机器上运行，并且可以通过 commit hash 复现。我们测试了 agent 记忆必须处理好的整个层面，而不仅仅是那些在推文中看起来很漂亮的数据：查找相关内容、记住谁是谁、理清时间顺序、不自相矛盾、引用事实来源，以及在脑部存储容量达到数十万页时保持快速。我们将那些我们并不引以为傲的数据与引以为傲的数据并列公布，因为一个你打算基于其构建的记忆系统，必须诚实地面对自己的弱点。 如果你正在考虑是否可以将 agent 的记忆托付给 gbrain，这个仓库就是你检验我们工作成果的途径，而不是仅仅听信我们的一面之词。 ## 这些 benchmark 的工作原理（60秒简述） 这里的 benchmark 包含三部分： 1. **语料库** — 一堆真实的内容（聊天记录、会议笔记、电子邮件、个人传记页面）。有些是我们生成的虚拟生活，有些是其他研究人员使用的公开数据集。 2. **带有封闭答案的问题** — 每个问题都有一个已知正确的答案，存放在被测系统永远看不到的单独文件中。gbrain 必须仅从内容中找到答案。它无法偷看答案，因此无法作弊。 3. **评分** — 我们提出问题，查看返回的结果，并将其与封闭答案进行比较。 有两种通俗易懂的衡量标准随处可见： - **召回率** — “我们得到的结果中包含正确的内容吗？” 97% 的 Recall@5 意味着在 100 次测试中，有 97 次正确的记忆出现在前 5 个结果中。 - **精确率** — “在返回的结果中，有多少是真正相关的？” 高精确率意味着其中混入的垃圾信息很少。 大多数问题希望高召回率（不要漏掉答案）。有些问题则希望高精确率（不要让答案被淹没在无关信息中）。一个真正的记忆系统必须在这两方面都表现出色，并根据所问的问题达到恰当的比例。我们测试的是这种平衡能力，而不是牺牲一个指标来换取另一个指标。 ## gbrain 目前的表现 | 测量项目 | 结果 | 通俗解释 | 报告 | |---|---|---|---| | **LongMemEval**（公开数据集，基于长聊天记录的 500 个问题） | **97.6% recall@5** | 97.6% 的情况下，正确的记忆都出现在前 5 个结果中。这是该测试中已发表的最佳得分，且在检索循环中没有使用任何 LLM。 | [报告](docs/benchmarks/2026-05-07-longmemeval-s.md) | | **关系型问题**（基于 240 页虚拟生活档案的“是谁把 X 介绍给 Y 的？”） | **97.9% recall@5, 49.1% precision@5** | 精确率比普通的向量搜索高出 38 个百分点。仅图谱层（记录人际关系）一项就贡献了约 30 个百分点。 | [报告](docs/benchmarks/2026-04-23-brainbench-v0.20.0.md) | | **跨越 20 个版本的稳定性**（v0.20.0 → v0.40.6.0） | **零回归** | 核心数据在一次又一次的发布中保持完全一致。新功能并没有在暗地里降低检索质量。 | [报告](docs/benchmarks/2026-05-23-v0.40.6.0-snapshot.md) | | **PrecisionMembench**（一项外部仅测试精确率的基准测试） | **第 2 名，以及一个诚实的‘默认第一’的故事** | 请参阅下方的诚实声明。 | [报告](docs/benchmarks/2026-05-29-precisionmembench.md) | | **SkillOpt**（技能能否在不作弊的情况下自我提升？） | **4/4 项技能从 0 提升至 1.00；拦截作弊；能力可迁移** | 表现不佳的技能在留出任务上自我重写至完美状态；关键词堆砌作弊行为被独立评审机制抓取；在一个模型上优化过的技能可以在另一个模型上运行。 | [报告](docs/benchmarks/2026-06-03-skillopt.md) | 一个动态的跨系统对比文档存放在 [docs/comparison-systems.md](docs/comparison-systems.md) 中。 ## 我们同样公布糟糕的数据 关于我们的思考方式，最清晰的例子就是 PrecisionMembench，这是一项外部测试，它仅对检索的*精确率*进行评分，并惩罚任何返回多个结果而让模型自己去排序的系统。 - gbrain 的**默认设置**在该测试中得分**0.076 precision**。这看起来很糟糕，我们也将其公之于众。*在这个特定的测试中*它确实糟糕，因为 gbrain 的默认配置被调优为绝不漏掉答案（召回率保持在 0.99），这对于一般情况来说是正确的权衡。 - 这一结果促成了一个真正的功能：一个可选设置，当问题只需要一个答案时，它会收紧返回结果的数量。开启该功能后，gbrain 达到了 **0.582 precision**，而延迟仅为最接近的通用系统的三分之一，仅次于专为该单一 benchmark 打造的工具。 我们故意在 README 中保留了诚实的 0.076 默认值。一个你赖以构建的系统应该针对真实的问题分布进行优化，而不是为了在某个狭隘的测试中拔得头筹，并且当一个数据源自边缘情况时，它应该坦诚地告知你。 防作弊机制已内置于测试框架中：处于边界隔离状态的密封答案、基于多次运行的误差容限、锁定的评审版本，以及随机化的问题顺序。 ## 我们进行的端到端测试 下表中的每一行都是一个真实的测试，并设定了代码提交层面的通过/失败阈值。“Shipping”意味着它已在 CI 中运行，并作为发布门禁。 | 领域 | 检查内容 | 达标线 | 状态 | |------|----------------|-----|--------| | 检索 | 在大规模的丰富文本中找到相关页面 | recall@5 > 0.83 | shipping | | 身份识别 | 将别名、用户名、电子邮件解析为同一个人 | recall > 0.80 | shipping | | 时间 | “截至去年三月”，时间点/范围/时效性问题 | as-of recall > 0.80 | shipping | | 出处 | 引用事实来源于哪个数据源 | accuracy > 0.90 | shipping | | 关联 | 连接相关页面，且不产生错误关联 | precision > 0.95 | shipping | | 速度 | 在负载下保持快速 | p95 < 200ms | shipping | | 技能 | Agent 行为符合其声明 | all > 0.90 | shipping | | 工作流 | 完整的多步骤任务，由规则进行评判 | 80% pass | shipping | | 鲁棒性 | 22 项对抗性输入测试，从不崩溃或损坏 | 100% | shipping | | 多模态 | 正确摄取 PDF + 音频 + HTML | text > 0.95, audio WER < 0.15 | shipping | | 信任边界 | 面向 agent 的 API 无法被诱骗导致静默数据损坏 | no corruption | shipping | ## 自行运行测试 ``` git clone https://github.com/garrytan/gbrain-evals.git cd gbrain-evals bun install # pulls gbrain in as a library ``` **公开数据集（LongMemEval，500 个问题）：** ``` mkdir -p ~/datasets/longmemeval curl -Lo ~/datasets/longmemeval/longmemeval_s.json \ https://huggingface.co/datasets/xiaowu0162/longmemeval/resolve/main/longmemeval_s export OPENAI_API_KEY="sk-..." # embeddings export ANTHROPIC_API_KEY="sk-ant-..." # only for the query-expansion variant bash eval/runner/longmemeval-batch.sh # all variants, parallel, resumable bun eval/runner/longmemeval.ts --stratify 10 # fast 10-per-type sample ``` 首次运行在 embedding 上的花费约为 2 美元；后续运行会命中本地缓存， 成本基本为零。 **我们自己的测试套件（我们称之为 BrainBench；无需 API 密钥，完全离线）：** ``` bun run eval:run # the full retrieval + behavior suite, about 15 min bun run eval:run:dev # one-shot smoke test bun run eval:world:view # browse the fictional corpus the tests run against ``` **精确率测试：** ``` bun eval/runner/precisionmembench.ts --mode gbrain-hybrid # the honest default (0.076) bun eval/runner/precisionmembench.ts --mode gbrain-adaptive --entity-max 1 --other-max 1 # 0.582 ``` ## 语料库 我们使用可以公开的内容进行测试，因此任何人都可以在不接触 私有数据的情况下复现结果。 - **一份 240 页的虚拟生活档案**（2.0MB，已提交至仓库）：包含 80 个人物、80 家公司、50 次会议、30 个概念，由 Opus 生成。每一页都附带一份密封的答案，该答案绝不会进入被测系统。 - **杂乱无章的一周虚拟生活**（2.1MB，已提交至仓库）：包含 50 封电子邮件、300 条聊天记录、20 个日历事件、8 份文字记录、40 条笔记，其中故意设置了矛盾信息、过时的事实和垃圾信息，以便我们测试当输入真实且充满噪音时，记忆系统能否保持清醒。使用 `bun run eval:generate-amara-life`（种子值为 42）可以确定性地重新生成。 ## 仓库布局 ``` gbrain-evals/ ├── eval/ │ ├── data/ the corpora + sealed answer keys + public datasets │ ├── runner/ one file per benchmark (our suite, LongMemEval, ...) │ ├── reports/ transient run output (gitignored) │ └── cli/ browse + validate the corpus ├── docs/ │ ├── benchmarks/ the published scorecards, with their data and charts │ └── comparison-systems.md └── test/eval/ unit tests for the harness itself ``` ## 许可证 MIT。虚拟语料库纯属虚构，可自由重新分发。内置的 precision-test 工件采用 MIT 许可证（归 tenurehq 所有）；请参阅 `eval/precisionmembench/ATTRIBUTION.md`。 ## 与 gbrain 的关系 这个仓库使用 gbrain 的方式与你一样：它将 gbrain 作为库进行安装，并调用其公开接口。在这里 gbrain 是被测的参考系统，但测试框架会对任何实现了适配器接口的系统进行评分，从而确保比较的公平性。

标签：AI智能体, Petitpotam, 准确率与召回率, 后端开发, 性能评估, 测试套件, 记忆系统