# RAG evaluation kit

本入口复用的是检索与决策评测合同，不是一个已经部署的知识库服务。调用方提供带稳定 ID 的 corpus、查询标签和权限字段，评测器输出排序、拒答、ACL、状态转移与成本工作量。

## 模块

| 模块               | 入口                                | 命令                           | 适用问题                                        |
| ------------------ | ----------------------------------- | ------------------------------ | ----------------------------------------------- |
| 词法检索与 RRF     | `labs/rag-retrieval-eval/README.md` | `npm run lab:rag:test`         | tokenizer、query expansion、字符检索与融合回归  |
| Agentic RAG 状态机 | `labs/agentic-rag-eval/README.md`   | `npm run lab:agentic-rag:test` | 路由、改写、ACL、拒答、预算与单位 accepted 成本 |

## 可替换输入

```bash
npm run lab:rag:capture -- --corpus /absolute/path/corpus.json --queries /absolute/path/queries.json
npm run lab:agentic-rag:capture -- --corpus /absolute/path/corpus.json --queries /absolute/path/queries.json
```

这两个 package script 分别固定写入 `/tmp/younis-ai-lab-rag-results.json` 和 `/tmp/younis-ai-lab-agentic-rag-results.json`。需要自定义输出路径时，按对应 lab README 直接调用 evaluator 并传入唯一的 `--out`；重复参数会 fail closed。

基础 corpus 至少需要稳定 `id`、`title`、`body` 和可选 tags；查询需要稳定 `id`、`text` 与 `relevant`。Agentic 数据还需要 tenant/route/facts、认证租户和期望 answer/abstain 合同。输入 schema 与完整示例见两个模块 README。

## 验收边界

决定性输出包括 Recall@3、MRR@10、逐查询失败、答案决策、相关文档 micro recall、ACL leakage、停止原因和工作量。合成数据上的提升不能直接外推到真实知识库；接入 embedding、reranker 或 LLM 后必须增加模型/索引 identity、答案 rubric、真实延迟和 token 成本。