RAG 答不全的时候，先想什么

01 · Baseline · 基础

一套刻意保持简单的 RAG

后面要查的是 failure，不是调参，所以每一环都尽量简单。读完这一节，你只需要记住这条线：

1. 官方文档
2. 按结构切成 chunk
3. embedding
4. cosine 检索
5. Top-5 作为证据
6. Qwen 生成
7. 引用校验

语料

26 页 Cloudflare 官方文档（Pages、Workers、R2、D1、Wrangler、绑定、变量与 secret、限额与价格），snapshot v1-2026-10-04

切分

336 个 chunk，其中 334 个有正文可以 embed（另外 2 个只有标题）；中位长度 827 字符

检索

bge-m3（1024 维）+ 平铺 cosine，取 Top-5 交给生成

生成

qwen3.8-flash：只能用给它的证据，回答要引用 chunk，并逐字引用原文；系统校验引用是否真的存在

够不够

证据够不够答，由一份手写的「证据清单」判断，不够就拒答、不调用模型（这份清单只为单个 case 写过，不通用）

chunk 怎么切、用了哪些模型、环境是什么，放在最后的「复现笔记」，这里不展开。

02 · 正常工作的样子 · 基础

一个成功的 case：Q5

问题怎么给 Pages Functions 配置 R2 bucket 绑定，并在代码里访问它？

先看它正常工作时是什么样，这样后面出现的失败，你才知道不是整套系统没跑起来。

第 1 名这一个 chunk 就同时讲了「怎么给 Pages 项目配置 R2 binding」「要重新部署」和「用 context.env 访问」，所以证据状态是 sufficient（够用）。 Qwen 引用了排名 1、2、3、4 的 chunk 共 4 处，每处引用的原文都逐字存在，校验通过。

即使是成功的 case 也有一条缝：写 Pages 的 Wrangler 配置语法的那个 chunk 排在第 8，在 Top-5 之外。这条缝我们记录了，但没有去补。

03 · 没有证据的时候 · 基础

Q9a：问一件语料里根本没有的事

问题Workers KV 的免费额度是多少？超出后如何计费？

先查语料：这份 snapshot 里有 34 个 chunk（13 页）提到 KV，但全部是 binding 或配置用法，没有免费额度，也没有计费。这不是检索失败——没有任何一个 chunk 是检索「漏掉」的。

检索照样返回了 5 个 chunk，分数 0.574–0.593，内容是 Workers、Pages、R2 的限额和免费额度。 Q5 的第 5 名分数是 0.608：光看分数，分不开「有证据」和「没证据」。

• 正常路径：证据状态 insufficient，系统拒答，不调用模型。
• 实验里故意绕过这道闸门，让 Qwen 面对同样的 5 个干扰 chunk，它的回答是：「提供的证据中未包含 Workers KV 的免费额度及超出后的计费信息。」没有数字，没有把别的产品的额度说成 KV 的，也没有引用。

「提供的证据中没有」，不能写成「Cloudflare 文档里没有」。语料里没有 ≠ 检索没找到 ≠ 官方没有。这一次只调用了一次模型，说明这次没越界，不说明模型稳定；整件事缺失，也是最容易拒答的一种。

04 · 真正麻烦的问题 · 进阶

Q7：看起来全相关，却答不全

问题环境变量、secret 和普通配置应该分别怎么设置？本地开发和线上部署有什么区别？

一个完整的回答，需要这四块材料：

先看 Top-10。读标题，你会觉得检索做得不错：

全是 secrets、本地开发、环境变量，没有一条跑题。但它只覆盖了需要的四块里的 1/4：只有 C4。 C1、C2、C3 其实就在语料里，在前 60 名里，只是排在 52、36、36 名。

semantic similarity ≠ evidence sufficiency。「和问题相关」与「足够回答问题」是两件事。检索做的是前者。

一个标注上的未决点：「Compare secrets and environment variables」这类 chunk 在 benchmark 里被标成无关，但从人读的角度它对 C1/C2 有帮助。是否算证据，是作者尚待复核的 Gold 问题，这里没有改动，也没有为它调整任何分数。

05 · 依次怀疑什么 · 进阶

六个假设，每一个都真的跑了

每一步都是：假设 → 实验 → 结果 → 判断。没有提升的实验也写在这里，因为这篇文章最大的价值就在于：技术不是加上去就有效，每个机制对应的是不同的 failure。

中文术语版：Cloudflare Workers 里的 environment variables、secrets 和普通配置（vars）应该分别怎么设置？本地开发（Wrangler）和线上部署（production）有什么区别？

对齐文档的英文版：How do I configure plain text environment variables in the Wrangler configuration file, add encrypted secrets with wrangler secret put for production, and use .dev.vars or .env files for local development in Cloudflare Workers and Pages?

放在一起看

下面是每一次尝试之后，C1、C2、C3 第一次出现的位置。绿色是进了 Top-10 的。

六种办法，没有一个让 C1–C3 都进入 Top-10。每一种机制对应的是不同的 failure；这个问题的 failure 不在它们对应的那一层。

06 · Recovery Loop · 综合

搜不到的时候，帮用户继续

到这里，Q7 可以停在「搜不到，所以不知道」。但还有另一条路：系统承认证据不够，并帮用户把问题改成更容易回答的样子。

1. 原问题证据不完整
2. Qwen 给 3 个更窄的问题
3. 用户选一个当作新的普通 query
4. 重新检索
5. 有依据的回答+ 引用校验

模型只看到原问题和当前的 Top-5 证据，规则是通用的：不回答原问题、不补 Cloudflare 的事实、只给 2–3 个更窄的问题。没有告诉它类别、哪些 chunk 排名低、之前做过哪些实验，也没有告诉它「正确的拆法」。参数和之前一致：qwen3.8-flash，temperature 0，不开 thinking，只调用一次，建议一旦生成就冻结，不重试、不润色，之后才去检索。

它给出的理由是：「原问题同时询问了环境变量、secret和普通配置的设置方法，以及本地与线上部署的区别，涉及多个独立主题且当前证据主要聚焦于本地开发中的 secret 处理。」建议的问题是：

• S1在 Cloudflare Workers 中，如何区分设置普通环境变量（vars）和敏感信息（secrets）？
• S2线上部署时，如何通过 Wrangler CLI 或 Dashboard 为 Worker 添加 secrets？
• S3本地开发和线上部署在加载 .dev.vars/.env 文件与生产环境配置时有何具体区别？

假设用户点了 S2。这就是一次新的普通 query，用的还是同一套 bge-m3，什么都没有改。三个建议各自的结果：

它的前三名是 Via the dashboard、Via Wrangler、Upload secrets alongside code：dashboard 的路径、wrangler secret put，以及随代码上传 secrets 的 --secrets-file。

S2：C3 从第 36 名到第 2 名。原问题里排在第 36 名的那一块，换成一个只问「线上怎么设置 secret」的问题之后，进了前 3。

只对 S2 做一次最终回答（用 S2 自己的 Top-5，同样的引用规则）：

在线上部署时，可以通过以下两种方式添加 Worker secrets：

1. **通过 Dashboard**：
   - 在 Cloudflare dashboard 中进入 **Workers & Pages** 页面 [1]。
   - 选择你的 Worker > **Settings** [1]。
   - 在 **Variables and Secrets** 下选择 **Add** [1]。
   - 选择类型 **Secret**，输入 **Variable name** 和 **Value**（值将在 Wrangler 和 dashboard 中隐藏）[1]。
   - 可选地，选择 **Add variable** 以添加更多 secrets [1]。
   - 最后选择 **Deploy** 以实施更改 [1]。

2. **通过 Wrangler CLI**：
   - 使用 `wrangler secret put <KEY>` 命令。这会创建一个新的 Worker 版本并立即部署 [2]。
   - 如果使用 gradual deployments，则使用 `wrangler versions secret put <KEY>` 命令。这仅创建新版本，随后需使用 `wrangler versions deploy` 进行部署 [2]。
   - 注意：Wrangler 3.73.0 之前的版本需要指定 `--x-versions` 标志 [2]。
   - 此外，可以使用 `--secrets-file` 标志在部署代码的同时上传 secrets，例如 `npx wrangler deploy --secrets-file .env.production` 或 `npx wrangler versions upload --secrets-file secrets.json` [3]。

同时保留限制，recovery 不是万能的：

• S1（普通变量和 secret 的区别）没有解决：C1 提前到第 31 名、C2 到第 16 名，仍在 Top-10 之外。Q7 里最基础的那一块，依然没有被找回来。
• S3（本地开发与线上配置）基本只是覆盖了原来就能找到的 C4，没有新进展。
• 只有一个 case，一组建议，一次调用；最终回答没有用「证据清单」闸门，因为这个问题没有为它写过清单。

好的 RAG 不一定一次回答所有问题，但应该知道什么时候证据不够，并帮助用户继续。这里的结果是 partial：一个子问题被完整、有依据地回答了，另一个仍然没有。

07 · 结论

碰到 RAG failure，这样想

1. 相关 ≠ 足够Q7 的 Top-10 没有一条跑题，却只覆盖了需要的四块里的 1/4。
2. 高 cosine ≠ 能回答语料里没有 KV 额度时，Top-5 的分数是 0.574–0.593；有答案的 Q5 的第 5 名是 0.608。用分数阈值挡不住。
3. 语料里没有 ≠ 检索没找到先查语料，再怪检索；回答里也只能说「提供的证据中没有」，不能说「官方文档里没有」。
4. reranker、去重、改写、拆问题，各有适用条件Q8 的问题靠 k=6 就补上了；Q7 上，这几样都没能让缺的证据进 Top-10。先判断失败发生在哪一层，再选机制。
5. 别为了一个 query 去过拟合 baselinenomic 在 Q7 上局部更好，但整个 benchmark 上 bge-m3 仍更强；换基线要用整个 benchmark 做，而不是一个 case。
6. 复合问题的 recovery 可以是产品能力，不必继续堆检索让系统说清证据不够，并给出更窄的问题，S2 就把 C3 从第 36 名带到第 2 名，并得到一个有引用的回答。

读完你应该能回答的是：面对 retrieval failure，下一步先判断什么——是证据不在语料里，还是在前 k 之外，还是在那里但排得深，以及这时系统能不能先承认不够、帮人继续。

08 · 复现笔记

如果你想自己复现，大概需要什么

这不是一份完整的 setup guide。它告诉有经验的工程师：材料从哪来，用了什么，实验在哪里。代码和语料在作者的仓库里，目前没有公开，页面上没有下载入口。

数据

Cloudflare 官方文档，每页取它的 Markdown 导出（index.md），共 26 页，snapshot 批次 v1-2026-10-04，在 2026-10-04 一个很短的时间窗里取完，逐文件记录 sha256。它是一段取数据的区间，不对应官方仓库的某一个 commit；之后再更新，要新建一个批次，不覆盖这个。三层的关系：raw（原样保存的响应）→ normalized（只去掉文档记录的界面元素，对 6 个主题混杂的长页只保留相关章节）→ chunk。

切分

按结构切：标题、段落、列表项、表格、代码块、<details> 各是一个块；标题和它下面紧跟的说明绑在一起；一个 chunk 不跨标题；每个 chunk 尽量不超过约 2400 个字符，相邻 chunk 之间零重叠；表格和代码块不拆开。整个语料只有一个 chunk 超过上限（5759 字符，一张兼容性矩阵表），整张保留。chunk 的 id 里带正文的哈希。

Embedding

输入 = 文档标题 + 标题路径 + chunk 正文。基线是 bge-m3（1024 维）；对比过 nomic-embed-text-v1.5、snowflake-arctic-embed-l-v2.0。更早的 bake-off 里还跑过 bge-small-en-v1.5（512 token 窗口，会截断 57 个 chunk）。当前 baseline 仍然是 bge-m3。

Reranker

BAAI/bge-reranker-v2-m3，只在 Q7 的实验里用，没有进入 baseline；通过第三方的 ONNX 导出在 CPU 上运行。

生成

qwen3.8-flash（阿里云 Model Studio 的 OpenAI 兼容接口），temperature 0，enable_thinking=false，JSON 输出；密钥和地址只从环境变量读取：DASHSCOPE_API_KEY、DASHSCOPE_BASE_URL。

环境

Python 3.11、ONNX Runtime 1.30.0、numpy 2.4.6，4 个 CPU 线程，没有 GPU；模型文件在本地缓存里，不进仓库。

experiments/rag/cloudflare-docs-practice-03/
  snapshots/            语料 snapshot（raw、normalized、manifest）
  ingest/               切分规则与 chunk
  embedding/            embedding bake-off 与 benchmark
  case-01/              Q5 的完整流程、Q9a 边界测试
  q8-decomposition/     手写拆问题
  topk-sensitivity/     Top-k
  q7-diversity/         去重与 MMR
  q7-reranker/          reranker
  q7-query-split/       按句拆分
  q7-query-rewrite/     改写
  q7-embedding-comparison/  embedding 对比
  q7-recovery-loop/     建议、再检索与最终回答

每个实验目录里都有它自己的 report.md，和一个离线检查脚本；这页上的数字来自那里的 results.json。