跳转至

尚无译文的页面会以英语打开,并标注为英语。

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

评估 Loom

评估时应围绕你需要做出的决策,而不是仓库中的每一个测试框架。本指南先从无需成本的产品冒烟测试开始,再进行针对具体工作负载的质量测试。只有在需要审计或复现已发布的结论时,才进入最后一步,即公开基准测试套件。

选择评估方式

决策 数据 提供方 典型输出
Loom 能否正确安装并连接? 四条测试事实和一份文档 自带的 fake provider 即可 事实在新会话中依然存在;控制台中出现来源、历史和审计记录
记忆对我们的 agent 是否有用? 25–50 个带有预期记忆键的真实问题 真实 embedder;用于提取或 memory.ask 的真实 LLM recall@k、rank@1、弃答、回答准确率、延迟和成本
代码智能对我们的代码仓库是否有用? 有代表性的符号、调用方集合和类似 issue 的问题 真实 embedder;已建立索引的代码仓库 精确定义、调用方 F1、文件召回率、弃答、token 和延迟
我们能否复现已发布的结果? 指定的公开数据集和已提交的结果产物 固定版本的模型或文档中说明的替代模型 使用相同切片、reader、judge 和搜索模式的可比运行

不要使用 fake embedder(checkout 中的 .env)或 fake LLM 来判断质量:它们的作用是让整套服务在没有凭据的情况下也能启动,并使集成测试具有确定性。已发布的整套服务中的本地 embedder 会真实地进行检索,因此可以用它对搜索做初步评估;回答和提取的质量则应使用真实的 LLM 来判断。

运行之前

先写下这五件事:

  1. 工作负载。 该决策所涵盖的用户、代码仓库和问题类型。
  2. 基线。 没有 Loom 时,同一用户或 agent 的做法:完整上下文、grep、BM25、其他记忆系统,或不做检索。
  3. 精度门槛。 你能接受的最低召回率、回答准确率或任务成功率。质量优先于成本。
  4. 经济性门槛。 最大 p95 延迟、token 数、模型成本、索引时间和存储空间。
  5. 环境记录。 Loom commit、ClickHouse 部署、提供方模型、模型参数、硬件、数据集版本和随机种子。

预先登记这些门槛,可以避免在运行之后,让某个方便的指标或数据切片变成最终结果。失败和弃答都要保持可见;请求错误应单独报告,不要悄悄地把它们算作检索未命中,也不要直接丢弃。

1. 产品冒烟测试

这个测试大约需要 15 分钟,用于验证连通性、持久化和可见性,不用于验证语义质量。

  1. 启动本地服务栈,并确认 /v1/health 返回 status: ok。
  2. 写入并搜索一条事实。
  3. 连接一个编码 agent,告诉它一条需要长期保留的偏好,然后打开一个新会话并询问这条偏好。
  4. 修正这条事实,然后确认控制台显示了它的来源和版本历史。
  5. 使用一份文档运行 loom demo,并确认返回的分块引用了该文档(文档冒烟测试)。

只有同时满足以下条件才算通过:新会话能够回忆起该事实,修正后的内容取代了当前答案,无关问题会弃答,并且控制台显示了写入者和历史记录。只要健康检查报告 fake_embedding 或 fake_llm,测试结果就不能说明生产环境中的召回效果。

2. 评估你的工作负载

配置真实的提供方,如果向量维度发生变化,请重置数据或重新生成 embedding,并从 /v1/health 记录解析出的模型。使用独立的命名空间,并让每个配对组使用相同的已索引数据。

记忆与 RAG

根据真实任务构建至少 25–50 个问题的集合,其中应包括:

  • 直接事实、同义改写、多跳问题和有时效性的更新;
  • 答案本应已被取代的问题;
  • 看似合理但无法回答的问题,用于衡量错误回答和拒答情况;
  • 近似重复的干扰项,它们只在关键取值上有所不同。

对每个可回答的记忆问题,在运行之前标注期望的 memory_key。对于文档 RAG,标注期望的文档和 chunk,查询 knowledge.search,并用相同的检索指标对这些标识符打分。分别衡量检索和合成:

  • 检索:recall@k、rank@1、MRR、误报率,以及拒答的精确率/召回率。
  • 回答:在固定的同一个 reader 和 judge 下的正确性,以及引用的正确性。
  • 成本:p50/p95 延迟、输入/输出 token、模型成本、构建成本和已存储的行数。

对于已有的记忆语料,请按以下结构保存一个 JSON 数据集(所附的测试工具针对 memory.search;对 knowledge.search 请使用等效的打分器):

{
  "org": "acme",
  "namespace": "support-eval",
  "questions": [{ "query": "When can we deploy?", "gold_keys": ["deploy_window"] }]
}

然后在不改动语料的情况下运行检索:

export PYTHONPATH=$PWD LOOM_API_KEY=<token>
.venv/bin/python bench/retrieval_recall.py \
  --dataset /path/to/retrieval_qa.json --base-url http://localhost:7777 \
  --top-k 10 --out /tmp/loom-retrieval.csv

只能根据你预先登记的门槛来设置 --min-recall 和 --min-mrr。对相同的问题使用 memory.ask 或你的生产 reader 来衡量回答准确率;召回率与回答准确率是不同的度量。

代码智能

为一个与你的生产仓库相似的仓库建立索引。不要只从 Loom 调优时使用的那个仓库开始。标注:

  • 定义,包含期望的文件和限定符号;
  • 调用方,包含完整的期望调用方集合;
  • 概念性问题和 issue 形式的问题,以及前 5 和前 10 中可接受的文件;
  • 应当拒答的仓库外问题;
  • 影响分析查询所期望得到的测试或依赖方。

针对已建立索引的仓库运行代码 agent 验收报告:

export PYTHONPATH=$PWD
.venv/bin/python bench/acceptance/code_agent.py \
  --base-url http://localhost:7777 --token-file /path/to/token \
  --namespace <code-namespace>

内置的测试夹具针对 ClickHouse,适合用来检查部署。若要做产品决策,请替换或扩充为你自己标注的问题,并将同样的 agent 任务与仅使用普通仓库工具的情况进行比较。首先报告任务成功率,然后是轮次、token、成本和耗时。工具 schema 的开销取决于客户端,因此请记录它是否延迟加载 MCP 工具定义。

保持比较公平

  • 在配对组中使用相同的模型、提示词、数据快照和问题顺序。
  • 将抽取/索引构建成本与单个问题的成本分开,然后说明需要多少个问题才能摊销构建成本。
  • 关闭评估读取带来的学习(auto_touch: false、reinforce: false),避免早先的查询改善后面的查询。
  • 报告样本量、各类别的结果和不确定性。不要把小规模的冒烟测试切片提升为一般性结论。
  • 保存每个问题的输出,包括错误和未命中,而不仅仅是汇总分数。

3. 审计或复现已发布的结果

README 只是一份计分卡,不是证据账本。对于每一个已发布的数字:

  1. 打开基准测试结果中对应的章节。
  2. 检查其在 bench/results/ 下已提交的产物。
  3. 确认数据集切片、Loom 提交、模型、reader、judge、搜索模式和种子。
  4. 运行结果章节中给出的完整复现命令。
  5. 参照方法论解读差异,包括 judge 校准、bootstrap 区间和已知偏差。

并非所有第三方数据集都由本仓库再分发。其来源和许可证列在数据集下。完整的公开运行可能需要数小时,并产生服务提供方的费用;请先从文档中的冒烟切片开始,再在发布对比结果之前运行完整的协议。

发布哪些内容

只有当结果具有代表性、一行即可看懂,并且有已提交的产物和复现命令作为支撑时,才将其发布到 README 中。完整的类别表、模型、提示词、不确定性、成本、失败分析和局限性,请放入结果台账。稳定的评估规则放入方法论,命令和数据集获取方式放入运行指南。

每一项公开声明都应说明:

  • 任务和样本量;
  • 指标,以及它衡量的是检索、回答质量还是端到端成功率;
  • 基线和配对差值(如果存在);
  • 模型和评判器,或者说明未使用 LLM 评判器;
  • 不确定性,或者单个问题变化所对应的粒度;
  • 分别列出构建成本和查询成本;
  • 已提交的产物和确切的复现命令;
  • 重要的负面发现,以及该结果不适用于哪些情形。

不要把所有可用的数字都发布在 README 中。过长的成绩表会掩盖产品层面的决策,容易引发无效的跨基准比较,也让过时的声明难以被发现。README 应当引导读者找到证据,而证据本身应放在文档中。

下一步