RAG 链路入门

速览 · 3 分钟

1. 准备一次：ingest.py 把 637 篇笔记做成 6696 张卡片 + 一张索引表。改了切分或换模型才重跑。
2. 每次提问：cli.py 把问题也变成向量，跟 6696 张卡片比相似度，取前 5 张。
3. 只有前 3 张真正塞给大模型（max_hits=3），第 4、5 张只是打印给你看。
4. 考试：evaluate.py 跟「回答」无关，只是把 50 道题批量丢进检索，然后对答案路径。
5. 最该先学会的不是写代码，是判断数字能不能信：改一处，前后各量一次，看分数涨没涨。

左上是目录，点标题跳转；右上角可切深色；代码块右上角有复制按钮；手机上目录会自动横排。整份文件不联网、不依赖任何 CDN，双击就能开。

1 一句话理解 RAG

你有一柜子自己的笔记。现在问：「MySQL 建联合索引的时候，等值条件和范围条件谁该放前面」。

如果没有 RAG，模型只能凭训练时记住的通用知识答，答不出「你自己那篇笔记里怎么写的」。RAG 的做法笨但可靠：

1. 把每篇笔记切成小卡片，每张卡片算出一个「意思向量」（1024 个数字）。
2. 把问题也算出同样格式的向量，跟所有卡片比方向，翻出最像的 5 张。
3. 把这 5 张里的前 3 张原文，连同问题一起发给大模型，让它只许照着资料答。

项目里 generator.py 的系统提示词就是这么写的：「只根据 <资料> 回答，资料里没有就直接说没找到，每句话标注来源编号」。

2 三条命令 = 三条不同的路

初学者最容易混的就是这个：它们根本不是同一条流程，跑的时机也完全不同。

还有一条本地辅助命令 scripts/serve_ui.py + web/index.html：一个只读的可视化页面，用来肉眼看检索命中的卡片。它不建索引、不调 LLM，看的同样是检索层。

3 六步数据流

点下面的步骤，一次只看一步。这六步根本不在同一条路上：前两步是「准备一次」（ingest.py，建好就不动），中间三步是「每次提问」（cli.py，问一句走一遍），最后一步是「考试时」（evaluate.py，只跟检索对答案）。每步都给了输入 → 输出的真实数据和对应代码。

note/docs/ 下 637 篇 md
纯文本约 3 MB
（目录 113 MB 里其余是图片，不参与检索）

CORPUS_DIR =
  D:/_work/cqlql-notes/docs

heading / size=512 / overlap=51
637 篇 → 6696 块，平均 367 字/块
碎片块（<50 字）166 块 · 耗时 0.4s

meta.jsonl 第一行：
{ "id": "ai/AI实时语音.md#0-598186d4",
  "source": "ai/AI实时语音.md",
  "heading": "# WebRTC API",
  "text": "# WebRTC API\n..." }

6696 块文字
+ BAAI/bge-m3（本地缓存，离线加载）
模型权重常驻约 2.2 GB

data/index/
  vectors.npy    27 MB (6696,1024) float32
  meta.jsonl     6696 行 {id,text,source,heading}
  manifest.json  heading/512/51 · bge-m3 · dim 1024

向量已归一化：第一行范数 = 1.0
→ 点积就是余弦，不用再除模长

MySQL 建联合索引的时候，
等值条件和范围条件谁该放前面

（一句自然语言，不加任何指令前缀）

query 向量 · shape (1024,) · float32
范数 1.0，与库里的向量同一口径

接下来只需一次矩阵点积

query 向量 (1024,)
× vectors.npy (6696, 1024)
TOP_K = 5

0.7000 / 0.6186 / 0.6095
0.5868 / 0.5831
检索 355ms（50 题平均 188ms）

第 1 张原文就含：
「等值在前，范围在后」

前 3 张卡片（实测 555 字）
+ 问题 + system prompt

格式：
[1] 来源：路径（标题）
    卡片原文

带 [1][2][3] 来源编号的中文回答
先给结论，再给细节
资料里没有就说「笔记里没找到」

data/eval/queries.jsonl · 50 行
{ "query": "你会怎么问的一句话",
  "expected": ["相对语料目录的路径"] }

query 按口语写，避开标题术语

命中        45 / 50
recall@5    0.900
MRR         0.801
检索耗时    平均 188ms · P95 230ms
未命中      5 条（清单见 §5）

全程约 20 秒，不调 LLM

4 一次真实提问

问题：「MySQL 建联合索引的时候，等值条件和范围条件谁该放前面」。下面 5 张卡片是终端里打印的原值，不是示意图。

指着卡片看四件事

1. 第 1 张直接命中。原文就写着「等值在前，范围在后」—— 答案第一张就翻到了。这就是检索的全部含义：不靠模型背书，靠翻到对的那一页。
2. 0.7000 是相似度分数，条长就是这个数。算法只是「问题向量 · 6696 个块向量，从大到小排」，没有玄学。
3. 5 张里 4 张来自同一篇笔记。因为 heading 策略把一篇 md 按标题切成了多块，所以「5 条结果」≠「5 篇笔记」。
4. 第 3、4、5 张分数只低一点（0.61 / 0.59 / 0.58），内容却明显偏题（索引≠约束、什么时候建索引）。分数高不等于内容对 —— 这句以后会反复用到。

5 评估到底是什么

把上一节的抽象话落到地上：「评估」就是一份考卷 + 对答案。

考卷长什么样

data/eval/queries.jsonl 一行一题，共 50 条：

{"query": "实时音频为什么不用长连接那套，抖动和丢包靠什么兜",
 "expected": ["ai/AI实时语音.md"]}

query 要按「你会怎么问」写，不要照抄文档标题；expected 是相对语料目录的路径，答案分散在多篇时可以写多个。

对答案的核心只有三行

sources = [h["source"] for h in hits]        # 检索返回的 5 个路径
rank = next((i+1 for i,s in enumerate(sources) if s in expected), None)
hit_count += 1 if rank else 0                 # 有就算命中
# recall@5 = 命中数 / 50      MRR = 各题 1/rank 的平均值

就这么多。它只查「有没有翻到那篇笔记」，完全没看最后那句回答对不对。

本次 baseline（2026-11-11 快照）

5 道没翻到的题，比分数更值得看

共同特征很清楚：用口语提问，答案文件却叫术语名。语义上「像」，但不是标准答案那篇。这正是「query 要按你会怎么问写」为什么值那一小时 —— 也是日后做混合检索 / rerank 的真实动机，不是凭感觉加模块。

「改一处，前后各量一次」现在有具体含义了

比如让 AI 只把那 166 个碎片块丢掉：改之前是 0.900，改完 重跑 ingest.py 重建索引，再跑一次 evaluate.py，看变成多少。这个数字就是判断依据，而不是「感觉好像更干净了」。

6 四个静默的坑

这几个都不会抛异常、lint 照过、数字照样打印，但结论全错。只有懂口径的人能抓出来 —— 这也是「先学验收」的真正原因。

① 改了切分，没重建索引

meta.jsonl / vectors.npy 还是旧的，evaluate.py 读它算出来的分数看起来完全正常。cli.py 的告警只比对 chunk_size 和 chunk_strategy 两项，改了 chunker.py 本身不会提醒。

② 考卷太小，天花板效应

项目里真的发生过：12 条试水集上曾判定 heading 策略掉点，补齐到 50 条后结论直接反转，heading 反超并被拍板设为默认。差的就是那么一两条命中。（具体数字与归因见 learning/实验台账.md §0.5） 换评估集 = 换标准，旧数字作废。

③ 把 recall@5 当成答案正确率

它只查路径命中。生成层的「对不对 / 有没有编 / 该拒答时拒答」尚未实现，AGENTS.md §3 明确禁止把 recall 写成答案正确率。

④ 环境坑：这三个会让你以为「代码坏了」

本机当前实际是 CPU 版 torch，没有 NVIDIA GPU；AGENTS.md §4 记的 CUDA 加速不在这台环境里。CPU/GPU 向量逐块余弦 1.000000、recall/MRR 一致，所以跨设备建索引不破坏可比性 —— 但耗时不可直接比，看 P95，别把 CUDA 冷启动写进指标。

7 命令速查

先 cd 到 D:/_work/cqlql-notes-branches/cqlql-notes.rag。所有命令都带离线变量 —— 这台机器上不带就会挂在 HuggingFace 校验上。

建索引（只在改切分 / 换模型后）

复制HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 HF_HUB_DISABLE_TELEMETRY=1 \
OMP_NUM_THREADS=8 MKL_NUM_THREADS=8 OPENBLAS_NUM_THREADS=8 \
PYTHONIOENCODING=utf-8 \
uv run --no-sync python scripts/ingest.py

问一句，看命中的卡片

复制HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 OMP_NUM_THREADS=2 \
PYTHONIOENCODING=utf-8 \
uv run --no-sync python -m notes_rag.cli "你的问题" --show-chunks

没填 LLM_API_KEY 时，卡片会先打印出来，之后才报 Missing credentials —— 不影响看检索结果。想看完整答案先填 key。

考试（改完代码量一次）

复制HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 OMP_NUM_THREADS=2 \
PYTHONIOENCODING=utf-8 \
uv run --no-sync python scripts/evaluate.py

每个变量为什么

HF_HUB_OFFLINE=1
TRANSFORMERS_OFFLINE=1

强制离线读本地模型缓存，一次网络请求都不发。绕开代理导致的 502。

OMP_NUM_THREADS 等

限制计算线程数。想一边跑一边干别的事就调小（2 = 很省但慢，8 = 约 1.5 小时）。

PYTHONIOENCODING=utf-8

Windows 下中文输出不乱码。

--no-sync

阻止 uv 把 .venv 同步回 lock 里的 CPU 版 torch。

--show-chunks

打印命中卡片的原文与分数，最短的冒烟测试。

--top-k 10

改召回条数。注意它和 max_hits=3 是两回事。

8 名词速查

9 该按什么顺序学

能落地的学习顺序

1. 先能指出「这次回答用的是哪几张卡片」。换 5 句自己的问题跑 --show-chunks，看答案在第几张、来自哪篇笔记、有没有翻错页。这一步不需要懂任何数学。
2. 再能回答「这个数字量的是哪一层」。跑一次 evaluate.py，能说出 0.900 是怎么算出来的、以及它没量什么。
3. 然后能指挥 AI 干活。把需求翻译成「只改一处、固定项不动、前后各量一次」，由你判断数字能不能信，再决定合不合。
4. 最后才碰优化。rerank、pgvector / HNSW、生成层评测、拒答率 —— 每一项都应该先有 baseline 数字再动。

明确不该先碰的

transformer 内部结构、HNSW 数学推导、PagedAttention 细节、训练 / 微调。这些按需查就行；learning/能力清单.md 里「没做过也能答」那一类已经排过序了。

只学到「能读懂 + 敢质疑」就停

Python 基本语法、向量与余弦、top-k、search() 的返回形状。够 review diff、看懂报错、定位 AI 跑偏在哪一层即可，不用练到能默写。