RAG on 男娘教主

W8-Day4：RAG 混合检索——Dense、BM25 与 RRF

Mon, 05 Oct 2026 06:34:40 +0800

W8-Day4：RAG 混合检索——Dense、BM25 与 RRF

前面几天已经把 RAG 最基本的一条链路跑通了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


文档
 ↓
Chunk
 ↓
Embedding
 ↓
Chroma
 ↓
Dense Retrieval
 ↓
Top-K
 ↓
LLM

到这里已经可以根据“语义相似度”找到相关文档。

但今天要解决的问题是：

语义相似，不代表一定能把“必须精确命中的东西”找出来。

因此今天没有推翻 Dense Retrieval，而是在它旁边增加了一条 Sparse Retrieval，最后再把两条检索路线的结果融合起来。

最终结构变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 Query
 │
 ┌─────────────┴─────────────┐
 │ │
 ↓ ↓
 Dense Retrieval Sparse Retrieval
 Embedding BM25
 │ │
 语义相似 词项精确匹配
 │ │
 └─────────────┬─────────────┘
 ↓
 RRF
 排名融合
 ↓
 Top-K
 ↓
 LLM

今天真正需要理解的就是这张图。

一、为什么 Dense Retrieval 还不够

Dense Retrieval 做的事情可以简单理解为：

1
2
3
4
5
6
7
8
9


Query
 ↓
Embedding
 ↓
Query Vector
 ↓
和文档 Vector 比较
 ↓
找距离最近的文档

它最大的优势是：

不要求 Query 和文档使用完全相同的词，只要意思接近就可能找到。

例如：

1
2
3


Query：弄翻了一杯拿铁

Document：咖啡洒了

虽然字面不同，但 Embedding 可以把它们映射到相近的语义空间。

这正是 Dense Retrieval 的价值。

但它也带来一个问题。

假设用户查询：

1

ERR_4517

或者：

1
2


ZQ-7781
GB/T 22239

这时候用户根本不需要“意思差不多”。

他要的是：

就是这个编号。

例如：

1
2


ERR_4517
ERR_4518

从自然语言意义上看，它们可能非常接近——都是某种错误码。

但对于业务系统来说：

1

4517 != 4518

差一个字符可能就是完全不同的问题。

所以 Dense 擅长回答：

1

“这大概是在说什么？”

却不天然擅长回答：

1

“到底是不是这个？”

这就是为什么还需要 Sparse Retrieval。

二、Sparse Retrieval：BM25

Sparse Retrieval 更接近传统搜索。

今天使用的是：

1

BM25

它主要依赖词项匹配。

可以先粗略理解成：

1
2
3
4
5
6
7
8
9


Query
 ↓
分词
 ↓
找到包含这些词的文档
 ↓
根据词的重要程度计算分数
 ↓
排序

但 BM25 并不只是简单地：

1

if keyword in document:

它还考虑三个重要问题。

1. TF：一个词出现很多次，不应该无限加分

假设某篇文章疯狂重复：

1

RAG RAG RAG RAG RAG RAG RAG……

如果简单按照出现次数计算：

1
2
3
4
5


出现 100 次
>
出现 10 次
>
出现 1 次

那么只要不断堆关键词，就可以把搜索排名刷上去。

BM25 对 TF 做了饱和处理。

核心思想不是公式，而是：

1
2
3
4


第一次出现 很有价值
第二次出现 还有价值
第十次出现 增益已经很小
第一百次出现 基本没什么额外价值

也就是：

词频有价值，但价值不会无限增长。

2. IDF：越罕见的词越重要

例如一份公司文档中：

1
2
3


系统
接口
用户

这些词到处都是。

它们对定位某一篇文档帮助很小。

但如果出现：

1

ERR_4517

而整个知识库只有一篇文档包含它，那么这个词就具有非常强的定位能力。

所以：

1
2
3


高频公共词 → 权重低

稀有词 → 权重高

这就是 IDF 的核心思想。

这也是 Sparse Retrieval 在错误码、型号、条款号、人名、专有名词等场景中的优势。

3. 文档长度归一化

还有一个问题。

假设：

1
2


文档 A：100 字
文档 B：10000 字

文档 B 因为特别长，自然更容易包含 Query 中的词。

如果不处理这个问题，长文档可能仅仅因为：

“话多”

就更容易获得高分。

所以 BM25 还会根据文档长度进行修正。

最终可以把 BM25 先记成：

1
2
3
4
5
6
7
8
9


BM25
 =
词项匹配
+
TF 饱和
+
IDF
+
文档长度修正

不用背公式，但要知道这些机制分别解决什么问题。

三、Dense 和 Sparse 为什么要同时存在

现在两条路线的边界就清楚了。

1
2
3
4
5


Dense
│
├─ 擅长语义
├─ 可以没有相同词
└─ “意思像”

而：

1
2
3
4
5


Sparse / BM25
│
├─ 擅长词项
├─ 稀有词定位能力强
└─ “就是这个”

例如：

1
2
3
4
5


“弄翻拿铁”
 ↓
Dense 更有优势
 ↓
“咖啡洒了”

而：

1
2
3
4
5


“ERR_4517”
 ↓
Sparse 更有优势
 ↓
包含 ERR_4517 的文档

所以 Hybrid Search 并不是：

两种高级技术叠起来一定更强。

而是：

两种检索方式的失败模式不同，所以让它们互相补盲区。

这是今天最重要的一句话。

四、为什么不能直接把两个 Score 相加

现在又出现一个问题。

Dense 会返回自己的分数：

1
2
3


Document A 0.82
Document B 0.76
Document C 0.65

BM25 也会返回：

1
2
3


Document A 8.4
Document D 6.7
Document B 4.2

最直觉的想法可能是：

1

final_score = dense_score + bm25_score

但这样做存在问题。

因为：

1
2
3


Dense Score
和
BM25 Score

不是同一种东西。

可以类比：

1
2
3


80 摄氏度
+
80 公里

两个数字都叫 80，不代表可以直接相加。

Dense 的分数表达的是向量空间里的相似关系。

BM25 的分数表达的是词项匹配强度。

两边的尺度、范围和意义都不同。

因此今天采用另一个办法：

RRF

Reciprocal Rank Fusion。

它的核心思想非常简单：

既然两个系统的分数不能直接比较，那我干脆不比较分数，只比较排名。

五、RRF：只看你排第几

假设 Dense 返回：

1
2
3
4
5


Dense

1. A
2. B
3. C

Sparse 返回：

1
2
3
4
5


Sparse

1. B
2. D
3. A

RRF 不关心：

1
2


A 的 Dense Score 是多少
B 的 BM25 Score 是多少

它只看：

1
2
3
4
5


A 在 Dense 第 1
A 在 Sparse 第 3

B 在 Dense 第 2
B 在 Sparse 第 1

然后按照：

1

1 / (k + rank)

给每次排名贡献一个分数。

因此：

1
2
3
4
5


A
=
Dense 第1的贡献
+
Sparse 第3的贡献

B：

1
2
3
4
5


B
=
Dense 第2的贡献
+
Sparse 第1的贡献

最后重新排序。

六、今天最值得看的代码：RRF

完整工程代码很多，但 Hybrid Search 真正新的核心算法其实非常短：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


def rrf_fuse(ranked_id_lists, k=60, weights=None, top_n=None):
 score = defaultdict(float)

 for i, ids in enumerate(ranked_id_lists):
 w = 1.0 if weights is None else weights[i]

 for rank, did in enumerate(ids, 1):
 score[did] += w / (k + rank)

 order = sorted(
 score.items(),
 key=lambda x: (-x[1], str(x[0]))
 )

 return order[:top_n] if top_n else order

先不看 Python 语法细节，把它还原成流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


准备一个 score 表
 ↓
遍历每一条检索路线
 ↓
遍历这条路线中的每个文档
 ↓
根据 rank 计算贡献
 ↓
累加到这个文档
 ↓
全部完成后重新排序

也就是：

1
2
3


Dense ranking ───┐
 ├──→ 累加排名分数 → 排序
Sparse ranking ──┘

这里真正重要的是：

1

score[did] += w / (k + rank)

同一个 did 如果同时被 Dense 和 Sparse 找到，就会被累计两次。

所以：

两个检索器都认为不错的文档，会获得更高的融合排名。

七、完整 Hybrid 主调用链

真正把 Dense、Sparse 和 RRF 串起来的是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


def hybrid(self, query: str, k: int, weights=None):
 d = self.dense(query, self.n_per_route)

 s = self.sparse_search(
 query,
 self.n_per_route
 )

 fused = rrf_fuse(
 [[i for i, _ in d],
 [i for i, _ in s]],
 k=self.rrf_k,
 weights=weights,
 top_n=k,
 )

 return fused, d, s

把代码压缩成数据流：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


query
 │
 ├──→ dense()
 │ ↓
 │ Dense Ranking
 │
 └──→ sparse_search()
 ↓
 Sparse Ranking
 │
 ↓
 rrf_fuse()
 │
 ↓
 Final Top-K

以后重新看这份代码，首先找这个函数。

因为它就是整个 Hybrid Retrieval 的主链。

其他代码基本都是围绕这条主链提供能力。

八、为什么两条路线必须使用相同的 ID

Hybrid Search 还有一个非常重要的工程条件：

1
2
3
4
5


Dense 找到的 Document A

和

Sparse 找到的 Document A

系统必须知道：

这是同一个 Document A。

所以两边必须共享同一套文档 ID。

代码因此从 Chroma 中读取：

1
2
3
4
5
6


data = self.vs.get(
 include=["documents", "metadatas"]
)

self.ids = data["ids"]
self.docs = data["documents"]

然后 BM25 直接使用：

1
2
3
4
5


self.sparse = SparseIndex(
 self.ids,
 self.docs,
 TOKENIZERS[tok]
)

也就是：

1
2
3
4
5
6
7
8
9


 Chroma
 │
 ids + documents
 │
 ┌────────┴────────┐
 ↓ ↓
 Dense BM25
 │ │
 └──── 同一 ID ────┘

否则可能出现：

1

Dense 的 id=1

代表文档 A，

但：

1

Sparse 的 id=1

代表文档 B。

这时候 RRF 虽然还能计算：

1

score[1] += ...

但这个结果已经没有意义。

所以：

融合之前首先要保证两条路线处在同一个 ID 空间。

这是一个很典型的工程边界。

九、为什么中文 BM25 还需要分词

Dense 使用 Embedding。

BM25 使用的是词项。

所以：

1

“接口返回 ERR_4517 怎么办”

必须先被拆成 token。

例如：

1
2
3
4


接口
返回
ERR_4517
怎么办

代码里因此提供：

1

tok_jieba()

和：

1

tok_bigram()

这里真正需要理解的不是两个 tokenizer 的所有实现。

而是：

Sparse Retrieval 的效果依赖“系统认为一个词是什么”。

特别是：

1
2


ERR_4517
ZQ-7781

这种标识符。

如果被错误拆成：

1
2
3


ERR
_
4517

原本一个非常稀有、定位能力极强的 token 就被破坏了。

所以代码额外使用正则保护标识符。

这也是为什么：

中文 Sparse Retrieval 中，分词不是一个无关紧要的预处理步骤，而是检索系统的一部分。

十、Retriever 和 Reranker 不是一回事

今天还有一个概念只需要知道位置：

1

Retriever

负责：

1
2
3


10 万条
 ↓
找 20～50 条候选

然后：

1

Reranker

负责：

1
2
3
4
5


50 条
 ↓
重新精细判断
 ↓
5 条

所以完整结构可以变成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 Query
 │
 ┌───────────┴───────────┐
 ↓ ↓
 Dense Sparse
 │ │
 └──────────┬────────────┘
 ↓
 RRF
 ↓
 候选 20～50 条
 ↓
 Reranker
 ↓
 Top-5

今天不需要实现复杂 Reranker。

只需要知道：

Retriever 负责大范围粗筛，Reranker 负责小范围精排。

十一、一个很容易踩的坑：RRF Score 不是相似度

Day3 使用 Dense Retrieval 时，可以根据相似度设置拒答阈值。

例如：

1
2
3


similarity < threshold
 ↓
 拒答

但进入 RRF 后：

1

RRF Score

已经不再表示：

Query 和 Document 有多相似。

它表示的是：

这个 Document 在多个 ranking 中综合排得怎么样。

所以：

1

Dense similarity

和：

1

RRF score

不能共用一个 threshold。

这其实是一个很重要的工程原则：

数据经过一层转换以后，要重新确认这个数字的语义，不能因为它还叫 score 就继续沿用上一层的规则。

十二、什么时候不需要 Hybrid

Hybrid 并不是默认正确答案。

如果：

1

语料很小

或者：

1

Query 几乎全部是自然语言问题

又或者：

1
2


文档中根本没有
错误码 / 型号 / 条款号 / 人名 / 专有标识符

那么 Dense Retrieval 可能已经足够。

增加 Hybrid 意味着同时增加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Dense Index
+
Sparse Index
+
Tokenizer
+
ID 一致性
+
RRF 参数
+
额外延迟
+
更多测试

所以它真正的取舍是：

1
2
3
4
5
6
7
8
9


 Hybrid Search

 更好的互补召回
 ↑
 │
 ───────────────────
 │
 ↓
 更高的系统复杂度

只有 Dense 和 Sparse 的互补价值足够大时，这笔复杂度成本才值得付。

十三、今天最终要记住什么

今天不用记住所有代码。

只需要把下面这条链留下来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 Query
 │
 ┌───────────┴───────────┐
 ↓ ↓
 Dense Sparse
 语义相似 BM25
 │ │
 ↓ ↓
 Ranking A Ranking B
 └───────────┬───────────┘
 ↓
 RRF
 只使用排名融合
 ↓
 Final Top-K

Dense 解决：

“意思像不像？”

Sparse / BM25 解决：

“是不是这个词？”

RRF 解决：

“两套分数不能直接比较，那怎么把两个排名合起来？”

Hybrid Search 解决的则是更上一层的问题：

当真实 Query 同时存在“语义型”和“精确词项型”需求时，单一 Retriever 的失败模式无法覆盖全部查询，因此让两种具有互补盲区的 Retriever 并行召回，再进行融合。

这就是今天真正需要掌握的知识骨架。

面试时至少要能沿着这条链回答

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


为什么需要 Hybrid？
 ↓
Dense 有什么盲区？
 ↓
BM25 为什么能补？
 ↓
BM25 为什么不只是关键词 contains？
 ↓
为什么不能直接加两个 score？
 ↓
为什么选择 RRF？
 ↓
RRF 到底做了什么？
 ↓
为什么两路 ID 必须一致？
 ↓
什么时候反而不应该使用 Hybrid？

如果这条链能自己解释下来，今天的核心知识就已经掌握了。

至于完整工程代码，不要求闭卷重新写出来。

但应该能够重新找到：

1
2
3
4


dense()
sparse_search()
rrf_fuse()
hybrid()

并根据这四个函数恢复整个系统的数据流。

RAG ：检索、生成与两道拒答闸

Sat, 03 Oct 2026 09:08:39 +0800

W8-D3 · RAG ：检索、生成与两道拒答闸

零、今天往前跨了两段

1
2
3
4
5


Day1: 手册 → 200 字一块 （切）
Day2: 每块 → 向量 → 落盘 （记）
Day3: 提问 → 向量 → 找最近的块 → 照着书答 （查 + 答）← 今天
Day4-5: 换检索策略 / 优化
Day6: 把它挂成 Agent 的一个工具

今天这一段要立住四个能力：

能力	判据
可交互问答	输入问题 → 输出答案
检索独立可测	`retrieve()` 只做 query → chunks，不碰 LLM，能脱离生成层单测
带引用回答	答案里标出 [1][2] 对应哪条资料
拒答机制	资料里没有 → 明确说"资料未提及"，而不是编一个

第二行那四个字是关键：独立可测。 检索和生成必须能分开测——整条链路一起测，出了问题你分不清是"没搜到"还是"搜到了但模型答歪了"。这两个病，诊断方式和修法完全不同。

类比：检索是开卷考试的"翻书"。你不用背，但必须翻对页——翻错页，你抄的答案再工整也是错的。这就是"检索质量决定回答质量"的直译：生成层救不了检索层。 模型再强，喂进去的资料是错的，它只会把错的资料组织得更通顺。

一、三个类比，把三段钉死

类比 1：检索 = 翻书。 翻错页 → 抄得再工整也是错的。

类比 2：生成 = “只许照着书答”。 不做约束，模型会用自己脑子里的知识答——然后你的 RAG 就白做了：它看着像在引用资料，其实在自由发挥。

类比 3：拒答 = 开卷考但书里没有 → 写"本卷未涉及"。 考生最常见的失分方式是"书里没有就自己编"，模型的默认倾向也是这样。所以拒答不是"能力不足"，是必须显式实现的机制。

二、开工前的三个预判

2.1 生成也需要模型，而且要选"数据出不出门"

Day2 把嵌入放到本地了，今天生成同样要一个模型。两条路：

	云端 API（如 DeepSeek）	本地（Ollama）
成本	按 token（很便宜）	0
数据	文档内容要发出去	全本地
上手	立刻（OpenAI 兼容接口）	要装 Ollama + 拉模型
速度	快	看机器

这里有一个必须摆出来的自相矛盾：如果 Day2 选本地嵌入的理由之一是"数据不出门"，今天生成却把资料发到云端——同一份文档，一半留在本地、一半发出去，“数据不出门"就只对了一半。

这是真的矛盾，不是小事。文档不敏感，就明确接受它；敏感，今天就该上 Ollama。别糊弄过去。

2.2 检索分数是"距离”：越小越像，方向别搞反

1
2


hits = vs.similarity_search_with_score(query, k=4)
# hits = [(Document, distance), ...] ← distance 越小越像

函数名里写着 similarity，返回值却是距离——这是 Chroma 的历史包袱。方向搞反是和 Day1 那个 endswith 判据同一类的错：指标方向搞反，然后为了"让测试变绿"去改本来正确的代码。

所以第一件事是把它换算成"像的程度"，让方向和直觉一致：

1
2
3


def to_similarity(distance: float) -> float:
 """hnsw:space=cosine 时 cosine_distance = 1 - cos_sim，所以 sim = 1 - distance"""
 return 1.0 - float(distance)

2.3 query 前缀必须和建库时一致

如果嵌入模型（比如 BGE 系列）对 query 有专用前缀，检索时忘了加——不报错，只是召回变差。典型的静默劣化：测试全绿，答案慢慢变烂。

三、段④ 检索：`retrieve()` 为什么必须"独立可测"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


import re
from pathlib import Path

import build_index as bi # 复用 Day2 的嵌入 / 落盘 / 防线
from langchain_chroma import Chroma

DEFAULT_K = 4
DEFAULT_MIN_SIM = 0.35 # ★ 临时值，必须用标定脚本换成实测值（见第七节）


def to_similarity(distance: float) -> float:
 """Chroma 返回【距离】，越小越像；换算成【相似度】，越大越像。

 hnsw:space=cosine 时 cosine_distance = 1 - cos_sim，
 所以 sim = 1 - distance（大致落在 [0, 1]，异常时可能到 2）。
 换库时若 space 不是 cosine，这个换算不成立——靠自检里
 "自己搜自己 distance≈0" 来验证方向没反。
 """
 return 1.0 - float(distance)


def retrieve(query: str, k: int = DEFAULT_K, vs: Chroma | None = None):
 """段④：query → [(Document, similarity)]

 ★ 这个函数【不碰 LLM】，所以能脱离生成层单独测——
 "独立可测"靠的就是这条边界。
 """
 if vs is None:
 raise ValueError("retrieve() 需要显式传入 Chroma 实例（便于测试时替换）")
 raw = vs.similarity_search_with_score(query, k=k)
 return [(doc, to_similarity(dist)) for doc, dist in raw]


def filter_by_score(hits, min_sim: float):
 return [(d, s) for d, s in hits if s >= min_sim]

retrieve() 的签名里那个 vs 不是多余的：把向量库变成参数，测试时就能塞假实现、也能在不启动 LLM 的情况下反复调用。

3.1 一条断言同时验两件事

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


def self_test(vs: Chroma):
 """检索层自检——不花钱，每次启动都跑"""
 snap = vs.get(limit=1)
 if not snap["documents"]:
 raise SystemExit("库是空的")
 text = snap["documents"][0]
 probe = text[:30]

 hits = retrieve(probe, k=3, vs=vs)
 for i, (d, s) in enumerate(hits, 1):
 hit = " ← 就是它" if d.page_content[:30] == probe else ""
 print(f" top{i} sim={s:.4f}{hit}")

 assert hits[0][1] > 0.95, (
 f"自己搜自己相似度只有 {hits[0][1]:.3f}（期望 ≈1.0）\n"
 " → 要么 hnsw:space 不是 cosine，要么 to_similarity 方向反了"
 )

“拿库里第一条文本的前 30 字去搜它自己”，理论上相似度应接近 1.0。一个断言覆盖两种病：

报 0.05 → 方向反了（1 - 0.95 的镜像）
报 -0.x → 空间不是 cosine

这是最省事的自检——不需要标注数据，也不需要花一分钱。

四、段⑤ 生成：两道拒答闸

4.1 系统提示词

1
2
3
4
5
6
7


SYSTEM_PROMPT = """你是知识库问答助手。严格遵守以下规则：

1) 只能依据【资料】回答。不得使用你自己的知识，不得推测、不得补充。
2) 每个事实后面必须标注来源编号，格式如 [1] 或 [1][2]。
3) 如果【资料】不足以回答问题，只回答这一句：资料未提及。不要解释，不要猜测。
4) 回答简洁直接，不要复述这些规则。
"""

第 1 条治"自由发挥"，第 2 条让答案可溯源，第 3 条是模型侧的兜底拒答，第 4 条防它把规则念一遍。

4.2 编号上下文：引用的载体

1
2
3
4
5
6
7
8


def build_context(hits) -> str:
 """把 chunks 编号成 [1][2][3]——编号是引用溯源的载体"""
 parts = []
 for i, (doc, sim) in enumerate(hits, 1):
 src = Path(str(doc.metadata.get("source", "?"))).name
 off = doc.metadata.get("start_index", "-")
 parts.append(f"[{i}] 来源: {src} 偏移: {off} 相似度: {sim:.3f}\n{doc.page_content}")
 return "\n\n".join(parts)

编号必须显式写在资料前面——否则模型没有可引用的对象，第 2 条规则就落空了。

4.3 两道闸：便宜的前置 + 兜底的后置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


def answer(query: str, k: int = DEFAULT_K, min_sim: float = DEFAULT_MIN_SIM,
 vs: Chroma | None = None, llm=None) -> dict:
 """两道闸的完整问答。

 闸1（前置，便宜）：最像的那块都没过阈值 → 直接拒答，【不调模型】
 闸2（后置，兜底）：让模型看资料够不够 → 它自己说"资料未提及"
 """
 raw = retrieve(query, k=k, vs=vs)
 best = raw[0][1] if raw else -1.0

 # ---- 闸1：分数不过线 → 拒答，一次 LLM 都不调 ----
 if not raw or best < min_sim:
 return {
 "status": "refused_by_score",
 "text": "资料未提及。",
 "best": best, "hits": raw, "cites": None,
 "note": f"最高相似度 {best:.3f} < 阈值 {min_sim}",
 }

 hits = filter_by_score(raw, min_sim)
 resp = llm.invoke(build_messages(query, hits))
 text = resp.content if hasattr(resp, "content") else str(resp)
 cites = check_citations(text, len(hits))

 refused = "资料未提及" in text
 return {
 "status": "refused_by_model" if refused else "ok",
 "text": text, "best": best, "hits": hits, "cites": cites,
 "note": ("模型判定资料不足" if refused else
 (f"无效引用 {cites['invalid']}" if cites["invalid"] else "")),
 }

为什么两道闸都要：前置阈值只能拦**“完全无关”，拦不住“沾边但答不了”**——后者要靠模型看着资料说"不够"。

为什么闸1 必须在模型之前：

便宜：没必要为一个注定拒答的问题付 token 和延迟；
可测：阈值是个数字，能写断言；“模型判断得准不准"没法写断言；
安全：模型在"没资料"时恰恰是它最容易编的时候——你把资料递到它面前说"资料不足就说未提及”，它仍可能觉得"我其实知道"。前置阈值不给它这个机会。

4.4 引用校验：能查出什么，查不出什么

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


CITE_RE = re.compile(r"\[(\d+)\]")


def check_citations(text: str, n_hits: int) -> dict:
 """引用校验：模型会编出不存在的编号（比如只有 3 条资料却引用 [5]）。

 ★ 只能查出【编号越界】，查不出【编号张冠李戴】——后者只能人工看。
 这是验证缺口，不是已解决。
 """
 nums = [int(x) for x in CITE_RE.findall(text)]
 invalid = sorted({x for x in nums if x < 1 or x > n_hits})
 return {"cited": sorted(set(nums)), "invalid": invalid, "has_cite": bool(nums)}

把"这个校验测不到什么"直接写进 docstring——比事后被它骗一次强。

五、完整代码 1：`w8/rag_qa.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250


"""
W8-Day3 RAG 第④⑤段：检索 + 生成（带引用 + 拒答）

运行：
 python w8/rag_qa.py # 交互式
 python w8/rag_qa.py -q "手册里XX是什么" # 单问
 python w8/rag_qa.py --k-only -q "XX" # ★ 只看检索，不调模型
 python w8/rag_qa.py --topk 6 --min-sim 0.45
 set OLLAMA=1 && python w8/rag_qa.py # 全本地（Ollama），文档不出机器
"""
from __future__ import annotations

import argparse
import os
import re
import sys
from pathlib import Path

os.environ.setdefault("HF_ENDPOINT", "https://hf-mirror.com") # 必须在 import 前

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

from langchain_chroma import Chroma

import build_index as bi # 复用 Day2 的嵌入 / 落盘 / 防线

# ---------------------------------------------------------------- 参数
DEFAULT_K = 4
DEFAULT_MIN_SIM = 0.35 # ★ 临时值，用 calibrate_threshold.py 换成实测值
GENERATION_BACKEND = "deepseek" # deepseek | ollama


# ================== 段④ 检索（独立可测） ==================
def to_similarity(distance: float) -> float:
 """Chroma 返回【距离】，越小越像；换算成【相似度】，越大越像。

 hnsw:space=cosine 时 cosine_distance = 1 - cos_sim，所以 sim = 1 - distance。
 换库时若 space 不是 cosine，这个换算不成立——靠自检里
 "自己搜自己 distance≈0" 来验证方向没反。
 """
 return 1.0 - float(distance)


def retrieve(query: str, k: int = DEFAULT_K, vs: Chroma | None = None):
 """段④：query → [(Document, similarity)]

 ★ 不碰 LLM，所以能脱离生成层单独测。
 """
 if vs is None:
 raise ValueError("retrieve() 需要显式传入 Chroma 实例（便于测试时替换）")
 raw = vs.similarity_search_with_score(query, k=k)
 return [(doc, to_similarity(dist)) for doc, dist in raw]


def filter_by_score(hits, min_sim: float):
 return [(d, s) for d, s in hits if s >= min_sim]


# ================== 段⑤ 生成（带引用 + 拒答） ==================
SYSTEM_PROMPT = """你是知识库问答助手。严格遵守以下规则：

1) 只能依据【资料】回答。不得使用你自己的知识，不得推测、不得补充。
2) 每个事实后面必须标注来源编号，格式如 [1] 或 [1][2]。
3) 如果【资料】不足以回答问题，只回答这一句：资料未提及。不要解释，不要猜测。
4) 回答简洁直接，不要复述这些规则。
"""


def build_context(hits) -> str:
 """把 chunks 编号成 [1][2][3]——编号是引用溯源的载体"""
 parts = []
 for i, (doc, sim) in enumerate(hits, 1):
 src = Path(str(doc.metadata.get("source", "?"))).name
 off = doc.metadata.get("start_index", "-")
 parts.append(f"[{i}] 来源: {src} 偏移: {off} 相似度: {sim:.3f}\n{doc.page_content}")
 return "\n\n".join(parts)


def build_messages(query: str, hits):
 return [
 ("system", SYSTEM_PROMPT),
 ("human", f"【资料】\n{build_context(hits)}\n\n【问题】{query}"),
 ]


CITE_RE = re.compile(r"\[(\d+)\]")


def check_citations(text: str, n_hits: int) -> dict:
 """引用校验：能查【编号越界】，查不出【编号张冠李戴】（只能人工看）。"""
 nums = [int(x) for x in CITE_RE.findall(text)]
 invalid = sorted({x for x in nums if x < 1 or x > n_hits})
 return {"cited": sorted(set(nums)), "invalid": invalid, "has_cite": bool(nums)}


def get_llm():
 if GENERATION_BACKEND == "ollama" or os.getenv("OLLAMA"):
 from langchain_ollama import ChatOllama
 return ChatOllama(model=os.getenv("OLLAMA_MODEL", "qwen2.5:7b"), temperature=0)

 from langchain_openai import ChatOpenAI
 key = os.getenv("DEEPSEEK_API_KEY")
 if not key:
 raise SystemExit(
 "\n没找到 DEEPSEEK_API_KEY。\n"
 " 用云端： set DEEPSEEK_API_KEY=sk-xxxx\n"
 " 用本地： set OLLAMA=1（需先装 Ollama 并 ollama pull qwen2.5:7b）\n"
 " 只看检索：加 --k-only，不调模型\n"
 )
 return ChatOpenAI(model="deepseek-chat", api_key=key,
 base_url="https://api.deepseek.com/v1",
 temperature=0) # 0 提高确定性，但 LLM 输出仍非完全确定


def answer(query: str, k: int = DEFAULT_K, min_sim: float = DEFAULT_MIN_SIM,
 vs: Chroma | None = None, llm=None) -> dict:
 """两道闸的完整问答：闸1 前置拒答（不调模型），闸2 模型兜底拒答"""
 raw = retrieve(query, k=k, vs=vs)
 best = raw[0][1] if raw else -1.0

 if not raw or best < min_sim: # ---- 闸1 ----
 return {
 "status": "refused_by_score",
 "text": "资料未提及。",
 "best": best, "hits": raw, "cites": None,
 "note": f"最高相似度 {best:.3f} < 阈值 {min_sim}",
 }

 hits = filter_by_score(raw, min_sim)
 resp = llm.invoke(build_messages(query, hits))
 text = resp.content if hasattr(resp, "content") else str(resp)
 cites = check_citations(text, len(hits))

 refused = "资料未提及" in text
 return {
 "status": "refused_by_model" if refused else "ok",
 "text": text, "best": best, "hits": hits, "cites": cites,
 "note": ("模型判定资料不足" if refused else
 (f"无效引用 {cites['invalid']}" if cites["invalid"] else "")),
 }


# ================== 展示 ==================
def show_hits(hits, title="检索结果"):
 print(f"\n--- {title} ---")
 for i, (doc, sim) in enumerate(hits, 1):
 src = Path(str(doc.metadata.get("source", "?"))).name
 snippet = doc.page_content.replace("\n", " ")[:60]
 print(f" [{i}] sim={sim:.3f} {src} {snippet}...")


def show_result(r):
 show_hits(r["hits"])
 print(f"\n--- 回答 ---\n{r['text']}")
 print(f"\n状态: {r['status']} 最高相似度: {r['best']:.3f}"
 + (f" {r['note']}" if r["note"] else ""))
 if r.get("cites"):
 c = r["cites"]
 print(f"引用编号: {c['cited'] if c['cited'] else '（没有标引用！）'}")
 if c["invalid"]:
 print(f"⚠️ 无效引用（资料里没有这些编号）: {c['invalid']} ← 模型编的")


def load_vs(kind: str) -> Chroma:
 info = bi.read_info()
 if not info:
 raise SystemExit("没找到索引信息文件 → 先跑 python w8/build_index.py --reset")
 bi.guard_backend(kind) # ★ 模型对不上就不让启动（Day2 的防线，今天继续用）
 emb = bi.get_embeddings(kind)
 vs = Chroma(collection_name=bi.COLLECTION,
 embedding_function=emb,
 persist_directory=bi.PERSIST_DIR)
 print(f"[加载] 模型={info.get('model_name')} dim={info.get('dim')} 条数={info.get('count')}")
 return vs


# ================== 自检 ==================
def self_test(vs: Chroma):
 """检索层自检——不花钱，每次启动都跑"""
 print("\n" + "=" * 60 + "\n检索层自检\n" + "=" * 60)
 snap = vs.get(limit=1)
 if not snap["documents"]:
 raise SystemExit("库是空的")
 text = snap["documents"][0]
 probe = text[:30]

 hits = retrieve(probe, k=3, vs=vs)
 for i, (d, s) in enumerate(hits, 1):
 hit = " ← 就是它" if d.page_content[:30] == probe else ""
 print(f" top{i} sim={s:.4f}{hit}")

 assert hits[0][1] > 0.95, (
 f"自己搜自己相似度只有 {hits[0][1]:.3f}（期望 ≈1.0）\n"
 " → 要么 hnsw:space 不是 cosine，要么 to_similarity 方向反了"
 )
 print(" → 自己搜自己 ≈ 1.0 ✅（方向没反 + cosine 空间成立）")


# ================== 主流程 ==================
def main():
 ap = argparse.ArgumentParser()
 ap.add_argument("--embed", default="bge-small")
 ap.add_argument("--topk", type=int, default=DEFAULT_K)
 ap.add_argument("--min-sim", type=float, default=DEFAULT_MIN_SIM)
 ap.add_argument("-q", "--question")
 ap.add_argument("--k-only", action="store_true",
 help="只跑检索不调模型（= 检索层的独立可测接口）")
 args = ap.parse_args()

 vs = load_vs(args.embed)
 self_test(vs)

 k, min_sim = args.topk, args.min_sim
 llm = None if args.k_only else get_llm()

 def once(q):
 if args.k_only:
 hits = retrieve(q, k=k, vs=vs)
 show_hits(hits, f"检索结果 (top-{k}, 不调模型)")
 ok = [(d, s) for d, s in hits if s >= min_sim]
 print(f"\n超过阈值 {min_sim} 的: {len(ok)}/{len(hits)} 块")
 print("→ 若过线为 0，正式流程会走【拒答】")
 return
 show_result(answer(q, k=k, min_sim=min_sim, vs=vs, llm=llm))

 if args.question:
 once(args.question)
 return

 print("\n输入问题; :k N 改 topk, :sim X 改阈值, :q 退出\n")
 while True:
 try:
 q = input("问> ").strip()
 except (EOFError, KeyboardInterrupt):
 print()
 break
 if not q:
 continue
 if q in (":q", "quit", "exit"):
 break
 if q.startswith(":k "):
 k = int(q[3:]); print(f"topk = {k}"); continue
 if q.startswith(":sim "):
 min_sim = float(q[5:]); print(f"min_sim = {min_sim}"); continue
 once(q)


if __name__ == "__main__":
 main()

5.1 这段复用了 Day2 的哪些接口

rag_qa.py 不重建索引，它只读Day2 留下的东西。依赖的接口一共五个：

接口	作用
`bi.COLLECTION`	collection 名（读写必须一致，否则读的是另一个库）
`bi.PERSIST_DIR`	落盘目录
`bi.get_embeddings(kind)`	造嵌入器（必须和建库时同一个类，否则 query 前缀对不上）
`bi.guard_backend(kind)`	校验"当前要用的模型"和"建库时用的模型"是否一致，不一致直接拒绝启动
`bi.read_info()`	读索引信息（模型名、维度、条数），启动时打印出来对账

guard_backend 这一条值得单独说：它是 Day2 留下的防线——如果检索时用的嵌入模型和建库时不是同一个，它不让程序启动。因为这种情况不会报错，只会让召回悄悄变差（第二节说的"静默劣化"）。

把"模型一致性"做成启动检查，而不是靠人记得——这类检查成本极低，收益却是一次事故。

六、完整代码 2：`w8/test_rag.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169


"""
W8-Day3 检索层断言 —— 全部离线，不花一分钱，不需要 API Key。
生成层【无法自动断言】，见文件末尾的说明。
运行：python w8/test_rag.py
"""
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

import build_index as bi
import rag_qa as rq
from langchain_chroma import Chroma

CASES = []


def case(fn):
 CASES.append(fn)
 return fn


VS = None


def vs():
 global VS
 if VS is None:
 VS = Chroma(collection_name=bi.COLLECTION,
 embedding_function=bi.get_embeddings("bge-small"),
 persist_directory=bi.PERSIST_DIR)
 return VS


# ---------- 假的 LLM：记录调用次数，用来证明"拒答时不调模型" ----------
class FakeLLM:
 def __init__(self, body="这是资料里的答案 [1]"):
 self.body, self.calls = body, []

 def invoke(self, messages):
 self.calls.append(messages)

 class M:
 pass

 m = M()
 m.content = self.body
 return m


class BoomLLM:
 """一被调用就炸——用来证明某条路径【不该走到模型】"""

 def invoke(self, messages):
 raise AssertionError("这条分支不该调用模型！")


@case
def t_to_similarity_direction():
 """方向：距离越小 → 相似度越大。搞反了后面全是错的。"""
 assert rq.to_similarity(0.0) == 1.0
 assert rq.to_similarity(0.2) > rq.to_similarity(0.8)
 print(" 0 距离→1.0，0.2 距离比 0.8 距离更相似 ✅")


@case
def t_self_search_tops():
 """自己搜自己：必须排第一，且相似度≈1 —— 同时验方向 + 空间"""
 text = vs().get(limit=1)["documents"][0]
 probe = text[:30]
 hits = rq.retrieve(probe, k=3, vs=vs())
 print(f" top1 sim={hits[0][1]:.4f}（期望≈1.0）")
 assert hits[0][1] > 0.95, f"self-search 只到 {hits[0][1]:.3f} → 方向或空间有问题"
 assert any(d.page_content[:30] == probe for d, _ in hits), "自己的块没进 top3"


@case
def t_topk_grows_monotonically():
 """k 变大 → 结果不减少，且 top-1 不变。
 防的是"调 k 把最好那条挤掉了"这种直觉错误。"""
 text = vs().get(limit=1)["documents"][0]
 q = text[:30]
 h2 = rq.retrieve(q, k=2, vs=vs())
 h6 = rq.retrieve(q, k=6, vs=vs())
 print(f" k=2→{len(h2)}条 k=6→{len(h6)}条 top1: {h2[0][1]:.4f} vs {h6[0][1]:.4f}")
 assert len(h6) >= len(h2), "k 变大结果反而变少 → 实现有问题"
 assert abs(h2[0][1] - h6[0][1]) < 1e-6, "k 变了 top-1 也变了 → 排序不稳定"


@case
def t_irrelevant_query_scores_lower():
 """★ 对照实验：无关问题的最高分，必须低于相关问题的最高分。
 没有这条，阈值就无从谈起——你得先证明"分数能区分好坏"。"""
 text = vs().get(limit=1)["documents"][0]
 good = rq.retrieve(text[:30], k=1, vs=vs())[0][1]
 bad = rq.retrieve("红烧肉怎么炖才软烂", k=1, vs=vs())[0][1]
 print(f" 相关问题 top1 sim={good:.4f} 无关问题 top1 sim={bad:.4f} "
 f"差距={good - bad:.4f}")
 assert good > bad, "无关问题分更高 → 阈值无法区分，检索层是坏的"


@case
def t_refusal_is_before_llm():
 """★★ 拒答的核心：阈值卡死 → 拒答，且【一次模型都不调】。
 用 BoomLLM（一调就炸）证明这个分支真的前置。"""
 llm = BoomLLM()
 r = rq.answer("红烧肉怎么炖才软烂", k=4, min_sim=1.1, vs=vs(), llm=llm)
 print(f" status={r['status']} text={r['text']!r} 模型调用=0")
 assert r["status"] == "refused_by_score", f"该拒答却走了 {r['status']}"
 assert "资料未提及" in r["text"]


@case
def t_model_refusal_path():
 """闸2：分数过线但模型说资料不足 → 状态也是拒答，别和闸1 混成一类"""
 r = rq.answer("红烧肉怎么炖才软烂", k=4, min_sim=-1.0, vs=vs(),
 llm=FakeLLM("资料未提及。"))
 print(f" status={r['status']}")
 assert r["status"] == "refused_by_model"


@case
def t_citation_check_catches_invented():
 """引用校验：只有 3 条资料却引用 [5] → 必须被认出来"""
 c = rq.check_citations("答案见 [1] 和 [5]", n_hits=3)
 print(f" cited={c['cited']} invalid={c['invalid']}")
 assert c["invalid"] == [5], "编造的引用没被识别"
 assert rq.check_citations("没有任何引用", 3)["has_cite"] is False
 # ★ 已知缺口：张冠李戴查不出来
 assert rq.check_citations("咖啡偏好见 [2]", 3)["invalid"] == []


@case
def t_fake_llm_gets_numbered_context():
 """塞给模型的资料必须带 [1][2] 编号——否则模型没法引用"""
 hits = rq.retrieve(vs().get(limit=1)["documents"][0][:30], k=3, vs=vs())
 msgs = rq.build_messages("测试问题", hits)
 body = msgs[1][1]
 for i in range(1, len(hits) + 1):
 assert f"[{i}]" in body, f"资料里缺编号 [{i}]"
 print(f" 资料编号 [1]..[{len(hits)}] 齐全 ✅")


def main():
 print(f"共 {len(CASES)} 个断言\n")
 passed, failed = 0, []
 for fn in CASES:
 try:
 fn()
 print(f"PASS {fn.__name__}")
 passed += 1
 except Exception as e:
 print(f"FAIL {fn.__name__}\n {type(e).__name__}: {e}")
 failed.append(fn.__name__)
 print(f"\n{passed}/{len(CASES)} 通过")
 if failed:
 print("失败: " + ", ".join(failed))

 print("\n--- 本文件【测不到】的 ---")
 print(" · 引用编号是否【张冠李戴】（只查越界）")
 print(" · 答案是否忠实于资料（模型可能答得通顺但偏离）")
 print(" · 拒答的【比例】是否合理（全靠阈值标定）")
 print(" → 这三项必须人工看 3~5 个真实问题。别当成已通过。")
 sys.exit(1 if failed else 0)


if __name__ == "__main__":
 main()

6.1 为什么要造一个"一调就炸"的假模型

BoomLLM 的 invoke() 直接抛异常。如果拒答逻辑写在模型之后，这条测试必炸。它证明的是"前置"这个性质，而不是"结果看着对"。

这是"验证设计"里很实用的一招：当一个性质无法从输出上直接观察时，就构造一个"违反它就会爆炸"的输入。

七、完整代码 3：`w8/calibrate_threshold.py`

DEFAULT_MIN_SIM = 0.35 是临时值。不标定它，拒答机制就是靠猜在工作。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


"""
把【拍】的阈值换成【算】的。

做法：拿"该答的"和"该拒的"各若干问题，各跑一遍检索，看两组分数的分布，
 找一个能分开两堆的切点。
运行：python w8/calibrate_threshold.py
"""
import statistics as st
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

import build_index as bi
import rag_qa as rq
from langchain_chroma import Chroma

# ★★ 照着 w8/docs/ 里的文档，手抄 4~5 个"文档里能答出来"的问题
GOOD_Q = [
 "把这里换成手册里真有的问题1",
 "手册里真有的问题2",
 "手册里真有的问题3",
 "手册里真有的问题4",
]

# 这些是"文档肯定答不出"的——拒答的对照组
BAD_Q = [
 "红烧肉怎么炖才软烂",
 "今天北京天气怎么样",
 "Python 的 GIL 是什么",
 "如何申请信用卡",
 "周杰伦最新专辑叫什么",
]


def main():
 vs = Chroma(collection_name=bi.COLLECTION,
 embedding_function=bi.get_embeddings("bge-small"),
 persist_directory=bi.PERSIST_DIR)

 def best_scores(qs):
 out = []
 for q in qs:
 top = rq.retrieve(q, k=4, vs=vs)
 out.append(top[0][1] if top else -1.0)
 return out

 g = best_scores(GOOD_Q)
 b = best_scores(BAD_Q)

 print("【该答的】问题 → top1 相似度")
 for q, s in zip(GOOD_Q, g):
 print(f" {s:.4f} {q}")
 print("\n【该拒的】问题 → top1 相似度")
 for q, s in zip(BAD_Q, b):
 print(f" {s:.4f} {q}")

 print(f"\n该答组: min={min(g):.4f} median={st.median(g):.4f} max={max(g):.4f}")
 print(f"该拒组: min={min(b):.4f} median={st.median(b):.4f} max={max(b):.4f}")

 gap_lo, gap_hi = max(b), min(g)
 print(f"\n该拒组的最高分 = {gap_lo:.4f}")
 print(f"该答组的最低分 = {gap_hi:.4f}")

 if gap_lo < gap_hi:
 mid = (gap_lo + gap_hi) / 2
 print(f"\n✅ 两组可分。切点取中位 → min_sim ≈ {mid:.3f}")
 print(f" 理由：该拒组全在 {gap_lo:.3f} 以下，该答组全在 {gap_hi:.3f} 以上。")
 print(f" ★ 把 rag_qa.py 的 DEFAULT_MIN_SIM 改成 {mid:.2f}")
 else:
 print(f"\n❌ 两组【不可分】：该拒组最高分 {gap_lo:.3f} 反而 >= "
 f"该答组最低分 {gap_hi:.3f}")
 print(" 含义：单靠绝对阈值分不开。可能原因：")
 print(" · 该答组里有问题文档里其实答不了（数据错）")
 print(" · 该拒组里有问题和文档内容意外沾边（选了不合适的对照）")
 print(" · 阈值这一招不够 → 需要 rerank 或混合检索（W8 后段）")
 print(" ★ 别硬凑一个数字让它'看起来能分'——那是自欺。")


if __name__ == "__main__":
 main()

这个脚本最关键的地方是最后的 else 分支：如果两组分不开，它明确说"分不开"，而不是硬挤一个数字。

因为最容易发生的事是：你调半天，终于找到个让 8/9 都对的阈值，然后以为搞定了——实际上那可能只是过拟合到你自己挑的那 9 个问题上。

八、跑的顺序：先测确定性，再测智能性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# ① 先只跑检索，不花一分钱
python w8/rag_qa.py --k-only -q "手册里真有的问题"

# ② 离线断言（不花钱、不用 key）
python w8/test_rag.py

# ③ 标定阈值（把拍的 0.35 换成算的）
python w8/calibrate_threshold.py
# → 按输出改 rag_qa.py 里的 DEFAULT_MIN_SIM，重跑 ②

# ④ 设 key，跑生成
set DEEPSEEK_API_KEY=sk-xxxx
python w8/rag_qa.py -q "手册里真有的问题"
python w8/rag_qa.py -q "红烧肉怎么炖才软烂" # 应该拒答

第 ① 步是今天最重要的设计：--k-only 让你在花任何 token 之前先确认检索是对的。顺序永远是——先测确定性，再测智能性。

⚠️ 注意 --k-only 和 test_rag.py 不是一回事：前者只是"打印过线数量"，后者才是真正的独立断言集。别把两个当一回事。

九、三个值得想清楚的问题

9.1 top-k 调大调小分别有什么影响

k	后果
太小（1~2）	漏召回：答案在某块里，但没进 top-k → 模型看不到 → 拒答
太大（10+）	噪声进 prompt：弱相关的块挤进上下文，模型容易被带偏、甚至引用错块；token 和延迟一起涨

还有一个副作用是**“中间塌陷”**：上下文太长时，夹在中间的资料容易被模型忽略（这一点属于经验判断，可以用 :k 2 vs :k 12 实测对比）。

一句话：k 是在"漏"和"杂"之间权衡，不是越大越好。 而且它不该是拍的——把 k 换成 1/2/4/8 各跑一遍，看不同的召回与噪声。

9.2 引用溯源为什么是 RAG 的关键优势

三层价值，一层比一层硬：

可核验：用户能自己翻回原文——这是对抗幻觉唯一有效的手段（没有出处的陈述，你没法验证）；
可定位故障：答错了，看引用就知道是检索错（引用了不相关的块）还是生成错（引用的块是对的，但答案歪了）。没有引用，这两种病分不出来；
暴露边界：引用少 = 这个答案根基浅，用户自己会打折扣。

第 2 层最容易被忽略——它把"答错了"从一团模糊变成两个可分别诊断的问题。

9.3 拒答为什么要"没检索到就不调模型"

便宜：没必要为一个注定拒答的问题付 token 和延迟；
可测：阈值是个数字，能写断言；“模型判断得准不准”没法写断言；
安全：模型在"没资料"时恰恰最容易编——递资料给它说"不足就说未提及"，它仍可能觉得"我其实知道"。前置阈值不给它这个机会。

但要说清楚：前置阈值只能拦**“完全无关”，拦不住“沾边但答不了”**。所以两道闸都要——闸1 是确定性的门，闸2 是智能性的门。

Embedding + Chroma，把文档变成可以按语义检索的向量库

Thu, 24 Sep 2026 06:00:58 +0800

W8D2：Embedding + Chroma，把文档变成可以按语义检索的向量库

一、先把今天放回整条链路里

W8D1 做的是：

1
2
3
4
5
6
7


原始文档
 ↓
读取
 ↓
切分
 ↓
Document 块

W8D2 做的是：

1
2
3
4
5
6
7
8
9


Document 块
 ↓
Embedding
 ↓
向量
 ↓
Chroma 向量库
 ↓
落盘

W8D3 才会真正做：

1
2
3
4
5
6
7
8
9


用户问题
 ↓
Embedding
 ↓
查询向量
 ↓
向量库寻找相近向量
 ↓
返回相关文档块

所以今天其实不是单纯在学一个 Chroma API。

我今天真正要建立的模型是：

Day1 解决“文档怎么变成块”，Day2 解决“这些块怎么变成可以比较语义距离的数字，并且保存下来”，Day3 再解决“怎么拿问题去找这些数字”。

整个过程可以先记成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


文字
 ↓
Chunk
 ↓
Embedding
 ↓
Vector
 ↓
Vector Store
 ↓
Persistence
 ↓
Query

今天主要停在 Vector Store + Persistence。

二、Embedding 到底在解决什么问题

我之前容易把 Embedding 理解成：

“把文字变成数字。”

这个说法没错，但其实不够。

真正需要理解的是：

Embedding 是把文字映射成一个向量，让原本不能直接进行数值比较的文本，进入一个可以计算“距离”的空间。

例如：

1
2


“我想喝咖啡”
“给我来一杯美式”

如果做普通关键词匹配，它们的字面差异很大。

但 Embedding 的目标不是比较“字长得像不像”，而是希望：

1
2
3


意思接近
 ↓
向量空间中的位置也更接近

所以可以把它想象成给每个文本一个“语义坐标”。

1
2
3
4
5
6
7
8


 美食
 ↑
 │ “咖啡”
 │ ●
 │ ●
 │ “美式”
 │
 └────────────→

这样到了 Day3，用户的问题也会被变成一个向量：

1
2
3
4
5
6


问题 → 向量

文档块1 → 向量
文档块2 → 向量
文档块3 → 向量
...

然后就可以比较：

1
2
3
4
5


问题向量
 ↓
谁离它最近？
 ↓
把这些文档块找出来

所以我现在对 Embedding 的理解是：

它不是为了“存数字”，而是为了把文本转换成一种可以计算相似程度的表示。

三、向量库又是在干什么

到这里还有一个容易混的地方：

Embedding 已经把文字变成向量了，为什么还需要 Chroma？

因为：

Embedding 负责“算出向量”，Chroma 负责“把这些向量和原文保存起来，并提供检索能力”。

所以两者职责并不是一回事。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Embedding Model
 │
 │ 文本 → 向量
 ↓
[0.02, -0.18, 0.42, ...]
 │
 ↓
Chroma
 │
 ├── 向量
 ├── 原始文本
 └── metadata

可以把它简单理解成：

1
2


Embedding = 翻译器
Chroma = 仓库

Embedding 把“人类语言”翻译成“机器可以比较的坐标”。

Chroma 则负责把这些坐标、对应文本和 metadata 存起来，以后查。

这也是为什么 W8D2 的核心不是只有 Embedding。

真正完整的是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


文本块
 ↓
Embedding
 ↓
向量
 ↓
向量 + 文本 + metadata
 ↓
Chroma
 ↓
持久化

四、今天代码里最值得看的部分：HashEmbeddings

今天没有一上来就直接调用真正的 Embedding API，而是先写了一个 HashEmbeddings。

这个设计其实很值得学。

关键代码只有这一小段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


def _vec(self, text: str) -> list[float]:
 v = [0.0] * self.dim

 for i in range(len(text) - 1):
 gram = text[i:i + 2]
 h = int(
 hashlib.md5(
 gram.encode("utf-8")
 ).hexdigest()[:8],
 16
 )
 v[h % self.dim] += 1.0

 norm = sum(x * x for x in v) ** 0.5 or 1.0
 return [x / norm for x in v]

我不需要记住这一套算法，只需要理解它在干什么。

1. 先准备一个固定长度的向量

1

v = [0.0] * self.dim

默认：

1

dim = 256

所以每段文字最后都会得到：

1

256维向量

无论原文是 20 个字还是 200 个字，最终表示长度都是一样的。

2. 把文本拆成两个字一组

1

gram = text[i:i + 2]

比如：

1

“我喜欢咖啡”

大致会得到：

1
2
3
4


我喜
喜欢
欢咖
咖啡

然后每一个二元组经过 hash，被映射到 256 个位置中的某一个位置。

所以最后会得到一个类似：

1

[0, 0, 2, 0, 1, 0, ..., 3, 0]

的向量。

这里最重要的不是 Hash 算法本身，而是理解：

代码正在把文本中的局部特征，映射到固定维度的数字空间。

3. 为什么还要归一化

最后：

1
2


norm = sum(x * x for x in v) ** 0.5 or 1.0
return [x / norm for x in v]

就是把向量做 L2 归一化。

目的可以先简单理解成：

把不同长度、不同大小的向量调整到统一尺度，方便后面的距离/相似度计算。

所以这段代码的完整链路其实是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


文本
 ↓
切成 2-gram
 ↓
hash
 ↓
映射到 256 维
 ↓
累计
 ↓
归一化
 ↓
最终向量

这就是今天代码里我真正需要理解的一段。

不是为了让我以后手写一个 Hash Embedding，而是为了让我看到：

“Embedding”在程序里最终就是一个“文本 → 向量”的过程。

五、为什么还专门做了一个假的 Embedding

这部分是今天我觉得最有工程意味的地方。

代码里有：

1
2
3
4
5
6
7
8
9


def get_embeddings(kind: str) -> Embeddings:
 if kind == "smoke":
 return HashEmbeddings(dim=256)

 if kind == "openai":
 ...

 if kind == "bge":
 ...

也就是说，同一个向量库构建流程，可以替换不同的 Embedding 后端：

1
2
3
4
5


 ┌── HashEmbeddings
 │
文本 → Embedding ── BGE
 │
 └── OpenAI

为什么不直接用真正的 BGE？

因为今天首先要证明的是：

这套系统的“管道”到底通不通。

而不是马上判断：

“这个模型的语义效果到底好不好。”

这两个问题其实完全不同。

链路问题

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


文本
 ↓
Embedding
 ↓
Chroma
 ↓
落盘
 ↓
重新加载
 ↓
查询

这里任何一步写错，都可能导致整个程序失败。

模型质量问题

即使整条链路完全正确，也可能出现：

1
2
3
4
5


查询：
“我想喝咖啡”

结果：
完全不相关的文档

这时候不一定是 Chroma 有问题，也可能只是 Embedding 模型本身不适合当前数据。

所以 --smoke 的价值就是：

1
2
3


先把“系统有没有坏”验证掉
 ↓
再研究“模型聪不聪明”

这其实是一个很重要的测试思想：

不要把工程故障和模型能力混成一个问题。

六、今天第二个真正重要的概念：Persistence

假设现在有 100 个文档块。

第一次运行：

1
2
3
4
5


100 个 Chunk
 ↓
100 次 Embedding
 ↓
存进 Chroma

如果程序结束以后，下一次启动又重新做：

1
2
3
4
5


100 个 Chunk
 ↓
重新 Embedding
 ↓
重新建库

那前一次做的工作就没有真正被复用。

所以今天有一个非常重要的工程思想：

建一次，落盘，以后加载。

代码里的核心就是：

1

PERSIST_DIR = str(HERE / "chroma_db")

然后：

1
2
3
4
5


vs = Chroma(
 collection_name=COLLECTION,
 embedding_function=emb,
 persist_directory=PERSIST_DIR
)

这里真正重要的并不是记住 persist_directory 这个参数。

而是理解：

1
2
3
4
5
6
7
8
9


内存中的对象
 ↓
持久化
 ↓
磁盘上的数据库
 ↓
下次程序启动
 ↓
重新打开

于是向量库就从：

1

“这次程序运行期间的变量”

变成：

1

“可以跨程序运行复用的数据”

这才是今天“入库 + 落盘”的真正意义。

七、所以代码为什么要先判断库存不存在

这个分支是今天主流程最值得理解的地方：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if index_exists() and not reset:
 vs = Chroma(
 collection_name=COLLECTION,
 embedding_function=emb,
 persist_directory=PERSIST_DIR
 )

 n = count_of(vs)

 return vs, 0, []

整个逻辑其实非常简单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


程序启动
 ↓
检查 chroma_db 是否存在
 │
 ├── 有
 │ ↓
 │ 直接加载
 │
 └── 没有
 ↓
 读取文档
 ↓
 分块
 ↓
 Embedding
 ↓
 Chroma
 ↓
 落盘

这里最重要的是：

“有没有库”决定后面走哪条路。

这其实已经不是单纯的 API 使用了，而是在写一个有状态的程序。

第一次运行：

1
2
3
4


build
→ create
→ embed
→ persist

第二次运行：

1
2
3


build
→ detect existing
→ load

这和之前我学过的很多“运行一次就结束”的脚本不太一样。

程序开始需要考虑：

系统上一次运行留下了什么？

这就是持久化系统开始出现后的一个重要思维变化。

八、为什么 `--reset` 也很重要

既然“存在就直接加载”，那旧库有问题怎么办？

比如：

1
2
3


旧 Embedding
 ↓
旧向量库

现在我把模型换了：

1

新 Embedding

但程序发现 chroma_db 已经存在，于是直接加载旧库。

这样就可能出现：

1
2


现在用的是模型 B
但是库里存的是模型 A 生成的向量

所以代码提供：

1

python w8\build_index.py --reset

它做的事情就是：

1
2
3
4
5
6
7


删除旧 chroma_db
 ↓
重新读取文档
 ↓
重新 Embedding
 ↓
重新建库

因此 reset 可以理解成：

“放弃旧状态，从头构建一份新的向量库。”

所以我现在可以把两个参数理解成：

1
2
3
4
5


默认运行
→ 尽量复用已有状态

--reset
→ 明确放弃旧状态重新建立

这已经很接近真实工程里的缓存、索引、数据库重建问题了。

九、入库前为什么还要过滤 Chunk

Day1 留下了一个问题。

之前的分块结果里有：

1

[190, 200, 200, 200, 1]

最后一块只有：

1

“。”

Day1 里它只是一个“不太好看的分块”。

到了今天，它开始真的产生后果。

因为如果它进入向量库：

1
2
3
4
5
6
7


“。”
 ↓
Embedding
 ↓
向量
 ↓
进入检索库

那么以后查询时，它也有可能参与召回。

于是：

1
2
3


真正有用的文档块
+
一个只有“。”的垃圾块

一起进入向量空间。

所以今天增加了：

1
2
3
4
5
6


MIN_CHARS = 20

kept = [
 c for c in chunks
 if len(c.page_content.strip()) >= MIN_CHARS
]

这里我学到的不是：

“以后都设置 20 字。”

这个 20 本身只是这次代码里的一个工程取值。

真正值得记住的是：

数据清洗发生在进入向量库之前。

也就是说：

1
2
3
4
5
6
7
8
9


原始文档
 ↓
分块
 ↓
清洗
 ↓
Embedding
 ↓
入库

而不是：

1
2
3
4
5


原始文档
 ↓
直接全部 Embedding
 ↓
再想办法补救

十、metadata 为什么还需要单独处理

Chunk 不只有正文。

它通常还会带：

1
2


page_content
metadata

例如：

1
2
3
4


{
 "source": "xxx.md",
 "start_index": 200
}

这些 metadata 对后面定位来源很重要。

但代码里又专门做了一步：

1
2
3
4
5
6


def clean_meta(m: dict) -> dict:
 return {
 k: v
 for k, v in m.items()
 if isinstance(v, (str, int, float, bool))
 }

我需要理解的不是这个字典推导式，而是一个边界：

进入 Chroma 的 metadata 不能随便塞任意 Python 对象。

所以这里实际上又经历了一次“边界转换”：

1
2
3
4
5


Python 中的 metadata
 ↓
清洗
 ↓
Chroma 能接受的 metadata

这也是今天比较典型的一种工程工作：

上一个组件允许的东西，不一定就是下一个组件允许的东西。

所以在系统串联时，中间经常需要做：

1
2
3
4


转换
清洗
裁剪
适配

十一、为什么要分批 `add_texts`

真正入库的关键代码是：

1
2
3
4
5


for i in range(0, len(texts), BATCH):
 vs.add_texts(
 texts=texts[i:i + BATCH],
 metadatas=metas[i:i + BATCH]
 )

这里的核心并不是 Python 的 range。

而是：

不要一次把所有文本都塞进去，而是按批次处理。

今天：

1

BATCH = 64

于是：

这样做的工程意义主要是：

1
2
3
4
5
6
7


避免一次处理的数据过大
 ↓
控制请求 / 内存 / 任务规模
 ↓
更容易观察进度
 ↓
更容易处理失败

今天的数据量很小，所以这个设计看起来可能有些“多余”。

但数据量一大，这种批处理就会变成很自然的工程需要。

十二、Chroma 这里还有一个我容易忽视的概念：距离

今天最后真正开始碰到“检索”了：

1

hits = vs.similarity_search_with_score(probe, k=k)

这里的 score 不应该简单理解成：

1

分数越大越好

因为当前 Chroma 返回的是：

距离（distance）

所以这里是：

1
2
3


距离越小
→ 越接近
→ 越相似

当前代码创建集合时还指定：

1

collection_metadata={"hnsw:space": "cosine"}

所以这里采用的是 cosine distance 的空间。

今天不用深入 HNSW 内部算法。

我现在只需要建立这个关系：

1
2
3
4
5
6
7
8
9


Embedding
 ↓
向量
 ↓
向量之间可以计算距离
 ↓
距离近
 ↓
认为更相似

这一步非常关键，因为它把前面的 Embedding 和后面的 Retrieval 真正接上了。

十三、今天的 `self_check` 为什么比“程序没报错”重要

以前我容易觉得：

1
2


程序运行结束
没有异常

≈

1

程序做对了

今天这个观点被进一步打破。

代码最后专门做了四层检查：

1
2
3
4
5
6
7


① 文件真的落盘了吗？
 ↓
② 库里的数量对吗？
 ↓
③ 重新打开之后数量还一样吗？
 ↓
④ 查询真的能把自己的数据找回来吗？

对应：

1

assert "chroma.sqlite3" in files

然后：

1

assert n == n_added

再：

1
2
3
4


vs2 = Chroma(...)
n2 = count_of(vs2)

assert n2 == n

最后：

1

hits = vs.similarity_search_with_score(...)

看自己的 Chunk 能不能被找回来。

这里我觉得最值得记住的是第三层：

1
2
3
4
5
6
7


写入
 ↓
关闭程序
 ↓
重新打开
 ↓
还能看到原来的数据

因为这才真正证明：

我不是刚刚把数据放在内存里，而是真的完成了持久化。

十四、为什么“自己搜自己”不能代表语义质量

这里又有一个很容易误解的地方。

代码最后会拿自己的文本做查询：

1
2


probe = texts[0][:30]
hits = vs.similarity_search_with_score(probe, k=k)

然后检查：

1

自己的块有没有被召回

这个测试能证明：

1
2
3
4
5
6
7


Embedding 能跑
 ↓
向量写进库了
 ↓
查询能执行
 ↓
向量检索链路基本通了

但它不能证明：

1

“咖啡”真的能找到“美式”

因为今天的 HashEmbeddings 本来就不是为了理解语义。

所以必须区分：

1
2
3


链路正确性
≠
模型语义质量

这两个问题要分开测。

今天：

1
2


--smoke
→ 测链路

Day3：

1
2


真实问题
→ 测召回效果

这个思维以后不只是 RAG 能用。

任何 AI 系统都可以拆成：

1

系统有没有正常运行？

和：

1

系统运行出来的结果好不好？

前者是工程正确性，后者才是能力质量。

十五、把今天所有知识重新串起来

现在再回头看 build_index.py，它其实没有那么复杂。

整个程序就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


启动
 ↓
选择 Embedding
 ↓
检查旧向量库
 │
 ├── 已存在
 │ ↓
 │ 直接加载
 │
 └── 不存在 / --reset
 ↓
 读取 Day1 文档
 ↓
 切成 Chunk
 ↓
 过滤无效 Chunk
 ↓
 清洗 metadata
 ↓
 Embedding
 ↓
 变成向量
 ↓
 分批写入 Chroma
 ↓
 持久化
 ↓
 自检

所以如果让我现在用一句自己的话总结 W8D2：

今天是在把 Day1 得到的一堆文本块，经过 Embedding 转成可以计算距离的向量，再连同文本和 metadata 一起放入 Chroma，并把结果持久化，这样下一次运行时可以直接加载，而不是重新做一遍 Embedding。

十六、今天真正学到的，其实不只是 RAG

这一天表面上是在学：

1
2
3
4


Embedding
Chroma
Vector Store
Persistence

但我觉得更重要的是开始出现几个工程思维：

1. 一个组件解决一个问题

1
2
3
4
5
6
7
8


Embedding
→ 负责表示

Chroma
→ 负责存储与检索

Persistence
→ 负责跨运行复用

不要把它们混成一个东西。

2. 先把“系统正确”与“结果优秀”分开

1
2
3
4
5


先证明：
链路通

再证明：
效果好

3. 数据进入下一个系统前，要注意边界

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Chunk
 ↓
过滤

metadata
 ↓
清洗

text
 ↓
Embedding

vector
 ↓
Chroma

每一步都有自己的输入输出约束。

4. 程序开始处理“历史状态”

今天第一次明显感觉到：

1

程序不是只处理当前输入

而是开始处理：

1
2
3


当前输入
+
过去运行留下的数据

这就是为什么会出现：

1
2
3


存在 → 加载
不存在 → 创建
reset → 重建

这其实已经开始进入真正工程系统的思维了。

十七、W8D2 最终留下的知识骨架

最后不记代码，记这张图就够了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


 W8D2
 │
 ┌─────────┴─────────┐
 ↓ ↓
 Embedding Persistence
 │ │
 ↓ ↓
 文本 → 向量 建一次 → 落盘
 │ │
 ↓ ↓
 可以计算距离 下次直接加载
 │
 ↓
 Chroma
 │
 ├── vector
 ├── text
 └── metadata
 │
 ↓
 similarity search

而整个 W8 到这里可以串成：

1
2
3
4
5
6
7
8


D1
文档 → Chunk
 ↓
D2
Chunk → Embedding → Vector Store → Persistence
 ↓
D3
Query → Embedding → Similarity Search → Relevant Chunks

所以我现在终于可以把 RAG 前半段看成一条完整的数据流，而不是几个零散的 API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


文档
 ↓
Chunk
 ↓
Embedding
 ↓
Vector
 ↓
Vector Store
 ↓
Query
 ↓
Distance
 ↓
Retrieval

这条链真正跑通之后，后面才开始进入：

1
2
3
4
5


Retrieved Context
 ↓
 LLM
 ↓
 Answer

也就是 RAG 真正“把检索结果交给模型”的部分。

W8-D1 · RAG 地基代码详解：加载与分块

Wed, 23 Sep 2026 08:24:34 +0800

W8-D1 · RAG 地基代码详解：加载与分块

零、今天这份代码在做什么

RAG 全链路七段，今天只做前两段：

1
2
3


① 加载 ──► ② 分块 ──► ③ 嵌入 ──► ④ 入库 ──► ⑤ 检索 ──► ⑥ 生成
 Load Split Embed Store Retrieve Generate
 └─今天─┘

一份文件 w8/day1_load_split.py，结构是这样的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


day1_load_split.py
├── 配置区 CHUNK_SIZE / CHUNK_OVERLAP / SEPARATORS / HEADERS
├── 加载段 load_text_file / load_pdf_file / check_text_layer
├── 分块段 make_splitter / split_documents / split_one_text
│ split_by_headers / split_markdown_two_stage / drop_tiny_chunks
├── 度量段 measure_actual_overlap / expansion_ratio / formula_expansion
│ cut_at_punctuation
├── 报告段 report_split
├── 样例文档 SAMPLE_MD / SAMPLE_TXT / ensure_sample_docs
├── 三种模式 run_demo / run_real / run_compare
└── 入口 if __name__ == "__main__"

1
2
3
4


跑法：
 python w8/day1_load_split.py # demo：自动造样例，0 准备
 python w8/day1_load_split.py real # real：读 w8/docs/ 里的真实文件
 python w8/day1_load_split.py compare # compare：chunk_size 选型对照

下面按这份结构逐块讲：代码 → 这块的坑 → 可优化 → 方法。

一、配置区：那几个拍脑袋的数字

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from pathlib import Path

HERE = Path(__file__).resolve().parent
DOCS_DIR = HERE / "docs"

CHUNK_SIZE = 300 # 上限，不是固定值
CHUNK_OVERLAP = 50 # 约 size 的 15%
OVERLAP_RATIO = 0.15
SEPARATORS = ["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""]
HEADERS = [("#", "h1"), ("##", "h2"), ("###", "h3")]
ENDS = ("。", "！", "？", "；", "，")

1.1 坑

坑 1：SEPARATORS 结尾必须留 ""。

这个空字符串是"实在没辙就一个字一个字切"的兜底。如果列表里没有它，遇到"完全没有分隔符"的内容（比如一长串无标点文本、base64 串、压缩包里的字符串），引擎无处可切，整块直接突破 chunk_size：

1
2
3
4
5


text = "A" * 800 # 800 字符，零分隔符
no_fb = ["\n\n", "\n", "。", "，"] # 故意不留 ""
# → 1 块，长度 800 ❌ 超预算 8 倍
# 加上 [""] 兜底后：
# → 8 块，最长 100 ✅

为什么这条特别值得记：超预算的块会安静地流进后续流程——嵌入时可能超模型输入上限、检索时噪声爆炸，但任何一步都不会报错。

坑 2：中文标点必须自己补。

RecursiveCharacterTextSplitter 的默认 separators 是给英文设计的（["\n\n", "\n", " ", ""]）。中文段落里没有空格，只给这些等于"退无可退就按字符硬切"，句子会被从中间砍断。

坑 3：CHUNK_SIZE / CHUNK_OVERLAP 是经验值，不是实测值。

300 来自"中文常见段落约 200-400 字"这个行业感觉。它不是针对你的语料测出来的。 合同/法条（一句话就是要点）可能太大，FAQ（一问一答很短）可能太小——所以这份代码里专门有一个 compare 模式来还这笔账。

1.2 可优化

现状	优化	收益
常量散在模块顶层	抽成 `@dataclass Config`	多套配置（不同语料）可切换、便于单测
`ENDS` 与 `SEPARATORS` 里的标点重复写	用 `ENDS` 生成 `SEPARATORS`	单一来源，改一处生效
中文标点只列了 6 个	补 `：`、`」`、`）`、`——` 等	更少硬切
`len` 数字符	换 token 计数（`tiktoken` / 模型自带）	中英混合语料下预算更准

1.3 方法

配置集中 + 单一来源：注意 SEPARATORS 与 ENDS 是有关系的（前者是"切分退让顺序"，后者是"句末标点集合"）。重复维护两处，早晚会不一致——能推导的就别手写两份。

二、加载段

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


from langchain_core.documents import Document


def load_text_file(path: Path) -> Document:
 """读文本/Markdown。显式 encoding，避免中文乱码"""
 text = path.read_text(encoding="utf-8")
 return Document(page_content=text, metadata={"source": path.name})


def load_pdf_file(path: Path) -> list[Document]:
 """PDF：一页 = 一个 Document，metadata 里带 page"""
 from langchain_community.document_loaders import PyPDFLoader # pip install pypdf
 return PyPDFLoader(str(path)).load()


def check_text_layer(pages: list[Document], min_chars: int = 20) -> list[int]:
 """扫描件探测：返回疑似没有文字层的页码（空列表 = 正常）"""
 return [i for i, d in enumerate(pages)
 if len(d.page_content.strip()) < min_chars]

整个 RAG 只围绕一个数据结构转：

1
2
3
4


Document(
 page_content="这一段正文……", # 内容
 metadata={"source": "手册.md", "page": 3} # 从哪来 ★
)

2.1 坑

坑 4：encoding 不写，中文可能乱码。

read_text() 不传 encoding 时用的是平台默认编码——它随机器/环境而变。同一份代码在自己的机器上正常、换一台就出一堆 \ufffd，根源都在这。读写文本一律显式 encoding="utf-8"。

坑 5：扫描件会"加载成功但内容为空"。

PDF 分两种：带文字层的（能直接抽文本）和扫描件（本质是图片）。后者用 PyPDFLoader 读出来是空字符串——不报错、不抛异常，你后面所有环节都在处理空气。

所以加载完必须探测一次，而不是假设：

1
2
3
4


pages = load_pdf_file(Path("manual.pdf"))
bad = check_text_layer(pages)
if bad:
 print(f"⚠️ 第 {bad} 页疑似扫描件，需要 OCR")

判据是"字符数"而不是"有没有报错"——加载器成不成功，和有没有文字层没关系。

坑 6：metadata 里只放 path.name 会重名。

两个不同目录下的 README.md 会撞成同一个 source。做引用回溯时，你分不清是哪一份。

2.2 可优化

现状	优化	收益
`if suffix == ".pdf" else ...` 的 if/else 分发	用注册表 `{".md": ..., ".pdf": ...}`	加新格式只改一处
返回 `list[Document]`	返回 `Iterator[Document]`（生成器）	大目录不吃内存
`source` 只记文件名	记相对路径 + 文件 `hash`	避免重名、能判断文件有没有更新
空内容直接进入流程	加载后统一 `if not d.page_content.strip(): skip`	早失败，别让空气流下去
无日志	用 `logging` 替代 `print`	可控级别、能进文件

2.3 方法

“探测而不是假设”是这一段的核心思想：check_text_layer 只有三行，但它把"这份 PDF 到底能不能用"从祈祷变成了判断。

metadata 是契约，不是装饰：source / page 在第一天写进去，是因为第六段要"带引用回答"、第四段入库时 metadata 会跟着向量一起存。第一天没留，后面回填等于整个库重跑。

三、分块段

3.1 切分器工厂

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from langchain_text_splitters import RecursiveCharacterTextSplitter, MarkdownHeaderTextSplitter


def make_splitter(size=CHUNK_SIZE, overlap=CHUNK_OVERLAP, separators=None):
 return RecursiveCharacterTextSplitter(
 chunk_size=size,
 chunk_overlap=overlap,
 separators=separators if separators is not None else SEPARATORS,
 keep_separator=True,
 length_function=len,
 add_start_index=True,
 )

四个参数各自的分量：

参数	作用	要点
`chunk_size`	块长上限	引擎会尽量在分隔符处断，不会硬凑到满
`chunk_overlap`	相邻块重叠	是下限，不是精确值（切分点会吸附到分隔符）
`keep_separator`	分隔符归谁	`True` → 归下一块开头；`"end"` → 归上一块末尾；`False` → 丢弃
`add_start_index`	记录每块在原文的起始位置	做引用、做定位、做判据都靠它

坑 7：overlap >= chunk_size 会出问题（报错或切不动），经验值取 10~15%。

坑 8：keep_separator 的语义会坑掉你的判据。

keep_separator=True 时，标点归下一块的开头，所以：

1
2


块1 = "...到这里就结束了" ← 结尾是"了"，不是标点
块2 = "。下一句从这里开始..." ← 开头是句号

只有最后一块可能以标点结尾——所以"块以句号结尾"这个判据，在结构上就不可达。判据必须和实现的语义对齐（3.4 给了解法）。

3.2 三种切法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


def split_documents(docs, *, size=CHUNK_SIZE, overlap=CHUNK_OVERLAP, separators=None):
 """切多个 Document —— metadata 会自动复制到每一块"""
 return make_splitter(size, overlap, separators).split_documents(docs)


def split_one_text(text: str, *, size=CHUNK_SIZE, overlap=CHUNK_OVERLAP,
 metadata=None, separators=None) -> list[Document]:
 """切一段纯文本 —— 要手动传 metadata"""
 return make_splitter(size, overlap, separators).create_documents(
 [text], metadatas=[metadata or {}])


def split_by_headers(md_text: str) -> list[Document]:
 """Markdown 一级切：按标题切章节，标题信息进 metadata"""
 sp = MarkdownHeaderTextSplitter(headers_to_split_on=HEADERS, strip_headers=False)
 return sp.split_text(md_text)


def split_markdown_two_stage(md_text: str, *, size=CHUNK_SIZE, overlap=CHUNK_OVERLAP):
 """两级切：先按标题，再按长度（heading metadata 会继承到每块）"""
 return split_documents(split_by_headers(md_text), size=size, overlap=overlap)

split_documents 与 split_one_text 的关键差别：前者继承原 Document 的 metadata（切完每块都带 source），后者丢弃（你不传 metadata 就没有）。这是"metadata 跟着每块走"最容易踩空的地方。

两级切为什么值得：

1
2
3


一级：按标题切（# / ## / ###） → 保证语义边界 + 章节归属
二级：超长章节再按长度递归切 → 保证不超预算
要求：二级切完，一级的 h1/h2/h3 必须还在

切完的每一块自带 h1/h2/h3——检索出来的块知道自己属于哪一章。这在生成阶段直接变成引用来源，在调试阶段直接告诉你是哪一节出了问题。

strip_headers=False 让标题留在正文里：块被单独拿出来看，也知道自己讲的是什么。

3.3 碎块过滤

1
2
3


def drop_tiny_chunks(docs: list[Document], min_len: int = 10) -> list[Document]:
 """过滤碎块：切分可能产出 1 个字符的块（例如一个孤立句号），进库就是噪声"""
 return [d for d in docs if len(d.page_content.strip()) >= min_len]

坑 9：会切出 1 个字符的块。

按标点切分时，如果某段的残余正好是一个标点（比如末尾那个 。），它会单独成块。这种块进向量库是纯噪声——任何人检索都可能召回一个句号。

这是产品缺陷，不是测试问题：断言不会替你发现它，只有你亲眼扫一遍块列表才会看到。

坑 10：两级切之后，start_index 的坐标基准变了。

二级切分是对每个 section 单独做的，所以每块的 start_index 是"相对该 section 开头"的偏移，不是相对整篇原文。要做精确定位（比如"引用原文第几段"），需要自己把一级的偏移加回去。

3.4 可优化

现状	优化	收益
`start_index` 只有一层坐标	两级切时累加一级偏移	引用能精确到原文位置
`min_len=10` 写死	提到配置里	不同语料可调
只按字符判空	同时 strip 首尾空白再切	少一批"全是空格"的块
切完不校验	加一句"拼接能复原原文"的自检	早发现丢字（`keep_separator=False` 会丢）
一次全量切	生成器逐块产出	大文档内存友好

四、度量段：把"拍脑袋"变成"算账"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


def measure_actual_overlap(chunks: list[str]) -> list[int]:
 """实测相邻块的真实重叠字符数"""
 out = []
 for a, b in zip(chunks, chunks[1:]):
 n = 0
 for k in range(min(len(a), len(b)), 0, -1):
 if a[-k:] == b[:k]:
 n = k
 break
 out.append(n)
 return out


def expansion_ratio(original_len: int, chunks: list[str]) -> float:
 """冗余膨胀率 = 所有块字符数 / 原文字符数 - 1"""
 return 0.0 if not original_len else sum(len(c) for c in chunks) / original_len - 1


def formula_expansion(size: int, overlap: int) -> float:
 """理论膨胀率 ≈ overlap / (size - overlap)"""
 return float("inf") if size <= overlap else overlap / (size - overlap)

4.1 方法：三个数把经验变成证据

① 实测重叠：chunk_overlap 是下限。

设定 30 字符重叠，实测往往大于 30——因为切分点会被吸附到分隔符上。你设的是"至少重叠这么多"，不是"恰好这么多"。

② 膨胀率：直接乘到嵌入账单上。

1

50 / (300 - 50) ≈ 20%

你多切出来的这 20% 字符，下一篇就变成 20% 的嵌入调用量。overlap 翻一倍，嵌入成本大致也翻一倍。

③ 选型对照：没有"最优 size"，只有取舍。

compare 模式打出来的那张表，读法是：

观察	含义
块数涨得快	召回的碎片更多、待嵌入的条数更多（贵）
平均块长小	单块上下文少，可能丢掉"这句话在讲什么"
膨胀率	直接乘到嵌入账单上

4.2 坐标判据：绕开实现细节

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


def cut_at_punctuation(chunks: list[Document], original: str,
 ends: tuple[str, ...] = ENDS) -> float | None:
 """切分点是否落在标点上——用原文坐标判断，与 keep_separator 取值无关。

 keep_separator=True → 标点在下一块开头（original[o]）
 keep_separator="end" → 标点在上一块末尾（original[o-1]）
 """
 offs = [c.metadata.get("start_index") for c in chunks]
 if len(offs) < 2 or any(o is None for o in offs):
 return None # 坐标缺失 → 交给调用方报错
 hit = 0
 for o in offs[1:]:
 if o <= 0:
 continue
 if original[o - 1:o] in ends or original[o:o + 1] in ends:
 hit += 1
 return hit / (len(offs) - 1)

这就是"判据与实现解耦"的写法。 与其去猜"标点归前块还是后块"，不如回到原文坐标：看这个切分点（start_index）前后那一个字符是不是标点。

好处有三个：

不受 keep_separator 取值影响——改实现不改判据；
判据有区分度——加了中文标点的切分，切分点落在标点上接近 100%；去掉标点的对照组接近 0%；
坐标缺失会显式失败（返回 None 而不是 0 分），避免"什么都没测到还显示通过"。

用切片取值（original[o-1:o]）而不是索引取值（original[o-1]），是为了防越界——切片越界返回空串，索引越界直接抛异常。

4.3 可优化

现状	优化	收益
`measure_actual_overlap` 从 `min(len(a), len(b))` 全量比对，最坏 O(n²)	只比对前 `max_overlap*2` 个字符	长块下快一个量级
`expansion_ratio` 只按字符	同时报 token 口径	和嵌入账单口径一致
`cut_at_punctuation` 返回 `float \| None`	返回一个小的结果对象（比例+命中数+样本）	排查时能看到"哪几个切分点没命中"

五、报告与三种模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


def report_split(label: str, original: str, docs: list[Document]) -> None:
 lens = [len(d.page_content) for d in docs]
 chunks = [d.page_content for d in docs]
 print(f"\n=== {label} ===")
 if not docs:
 print(" 0 块（原文为空？）")
 return
 print(f" 原文 {len(original)} 字符 -> {len(docs)} 块")
 print(f" 块长：最短 {min(lens)} 最长 {max(lens)} 平均 {sum(lens) // len(lens)}")
 print(f" 超预算的块：{[l for l in lens if l > CHUNK_SIZE] or '无'}")
 print(f" 切分点落在标点上：{cut_at_punctuation(docs, original)}")
 print(f" 膨胀率 实测 {expansion_ratio(len(original), chunks):.1%}"
 f" 公式预测 {formula_expansion(CHUNK_SIZE, CHUNK_OVERLAP):.1%}")
 print(" --- 前 2 块预览 ---")
 for i, d in enumerate(docs[:2]):
 print(f" #{i} ({len(d.page_content)}字) "
 f"{d.page_content[:60]}".replace("\n", " ") + "...")
 print(f" metadata[0] = {docs[0].metadata}")

报告函数不是"打印调试信息"，而是把关键指标固化成每次都能看到的体检单：块数、块长分布、超预算的块、切分点命中率、膨胀率、每块 metadata。

“超预算的块"这一行要单独列出来——因为它是唯一一个"静默出错"的指标（3.1 的坑 1）。

三种模式的定位：

模式	用途
`demo`	自动造样例文档，0 准备先证明代码是活的
`real`	读真实文件，逐文件打印加载结果与 metadata 检查
`compare`	同一份文本跑三组 `chunk_size`，看成本差异

demo 模式是这份代码里我很推荐的一个习惯：不依赖你手上有任何文档，先跑通再说。没有 demo 模式的脚本，往往会卡在"我还没有 PDF"这一步。

5.1 坑与可优化

坑 11：run_real 一次把目录全读进内存。

1
2


all_docs: list[Document] = []
for p in files: ...

十来个文件没事，几百个就是内存问题。可优化：改成生成器逐文件处理、切完即丢。

可优化：目录遍历用 Path.rglob 收子目录；跳过隐藏文件与大文件；断点续跑时记录已处理文件的 hash。

六、入口：一行不能少

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


if __name__ == "__main__":
 mode = sys.argv[1] if len(sys.argv) > 1 else "demo"
 if mode == "demo":
 ensure_sample_docs()
 run_demo()
 elif mode == "real":
 run_real()
 elif mode == "compare":
 run_compare()
 else:
 print(f"未知模式：{mode}（用法：python w8/day1_load_split.py [demo|real|compare]）")

坑 12：漏了 if __name__ == "__main__": 就是"零输出”。

这类脚本常见的事故——文件能跑、不报错、什么都不打印。原因就是入口没执行：模块被 import 时上面的函数只定义不调用，你没有入口就等于只声明不执行。

坑 13：模式名不做兜底。

传了个拼错的模式名（comapre），如果直接落到 run_demo 或静默退出，你会一脸疑惑"怎么没输出"。未知输入要显式报错并打印用法——错误要响，不要哑。

七、坑位汇总（对着自查）

#	坑	后果	防线
1	`SEPARATORS` 结尾没留 `""`	无分隔符内容整块超预算（静默）	保留 `""`；报告里单列"超预算的块"
2	中文标点没进 `separators`	长句被按字符硬切，语义断裂	`SEPARATORS` 含 `。！？；，`
3	`CHUNK_SIZE/OVERLAP` 抄经验值	与语料不匹配	`compare` 模式算给你看
4	`encoding` 不写	中文乱码（换机器才暴露）	一律 `encoding="utf-8"`
5	扫描件静默空内容	后续环节全在处理空气	`check_text_layer` 探测
6	`metadata` 只记文件名	重名文件撞 `source`	记相对路径 + hash
7	`overlap >= chunk_size`	报错或切不动	取 10~15%，并断言它真报错
8	用 `endswith("。")` 当判据	结构上不可达，且指标反向	用 `start_index` 坐标判据
9	切出 1 字符碎块	进库就是噪声	`drop_tiny_chunks` 过滤
10	两级切后 `start_index` 基准变了	引用定位错位	累加一级偏移
11	`run_real` 全量读入内存	大目录吃光内存	生成器逐文件处理
12	漏 `__main__` 入口	零输出	入口 + 未知模式报错
13	`split_one_text` 忘了传 metadata	块没有 `source`	优先用 `split_documents`（自动继承）

八、这份代码里三个可复用的方法

方法一：探测而不是假设。

check_text_layer 只有三行，但思路值得抄——凡是"外部输入可能悄悄为空/失效"的地方，都值得加一个显式探测：扫描件、空文件、编码不对、被截断的下载。它们的共同点是不报错。

方法二：把经验值变成度量。

300 / 50 / 0.15 这些数，写死在任何项目里都会变成"祖传参数"。这份代码的做法是给它们配三样东西：实测函数（measure_actual_overlap）、理论公式（expansion_ratio）、对照实验（compare 模式）。参数还是那几个参数，但从此有依据。

方法三：判据锚在稳定坐标上，别锚在实现细节上。

endswith("。") 依赖"标点归哪一块"这个实现细节，而 start_index 回原文坐标不依赖它。写判据时问一句：这个判据成立的前提，是"业务语义"还是"当前实现"？ 后者一变，判据就失效——更糟的是可能反向失效（坏数据得分更高）。

九、速查卡片

加载

目标	写法
读文本	`Document(p.read_text(encoding="utf-8"), {"source": p.name})`
读 PDF	`PyPDFLoader(str(p)).load()`（一页一 Doc，带 `page`）
扫描件探测	`[i for i,d in enumerate(pages) if len(d.page_content.strip()) < 20]`

分块

目标	写法
递归切（批量）	`splitter.split_documents(docs)` ← metadata 自动继承
递归切（单文本）	`splitter.create_documents([text], metadatas=[md])`
Markdown 两级切	`MarkdownHeaderTextSplitter(...)` → 再 `split_documents`
关键参数	`chunk_size` 上限 / `chunk_overlap` 下限 / `add_start_index=True`
兜底	`separators` 结尾留 `""`
过滤碎块	`[d for d in docs if len(d.page_content.strip()) >= 10]`

度量

目标	公式 / 方法
实测重叠	逐字符比对"前串后缀 == 后串前缀"的最大 k
膨胀率	`块字符总数 / 原文字符数 - 1`
理论膨胀率	`overlap / (chunk_size - overlap)`
切分点质量	用 `start_index` 回原文坐标判断，不查 `endswith`

三句口诀

能按句子切，就绝不按字符切——separators 含中文标点，结尾留 ""。
metadata 第一天就要管——source / page / h1-h3 缺一个，后面就得整库重跑。
判据锚在坐标上——别让实现细节（标点归谁）决定你的指标。

十、一句话总结 + 下一篇预告

今天这份代码只做两件事：把文档读成带 metadata 的 Document（source/page 第一天就得有、扫描件必须先探测），再把它切成 chunk（递归切分含中文标点并以 "" 兜底、Markdown 两级切保住章节归属、碎块要过滤）。而它真正值得带走的是三个习惯：探测而不是假设、把经验值配上一个度量、判据锚在稳定坐标上。切分是 RAG 的地基——向量库里存的就是你切出来的那些块，切得烂，检索永远救不回来。

下一篇 Day2 · 嵌入 + 入库：把这些 chunk 变成向量存进 Chroma 并落盘，实现"一次入库、反复复用"，同时把嵌入模型选型与成本算清楚——今天算出来的膨胀率，到那天就变成真金白银。

魔鬼代言人：这份代码全部跑通，也只证明"结构对、配置生效"，完全不证明"切得好"。切得好不好只有你能判：打开输出，读前 5 块，问一句——“这块单独拿出来，还看得懂它在讲什么吗？” 如果一块被切成"……因此 Agent 需要"（后半句跑下一块去了），说明 size 或 separators 还得调。这件事任何断言都测不出来，只能靠眼睛。

自查三问：① SEPARATORS 结尾那个 "" 删掉会发生什么？为什么它是"静默出错"？② split_documents 和 split_one_text 在 metadata 上有什么差别？这会导致什么常见疏漏？③ 为什么"块以句号结尾"不能当切分质量判据？换成什么判据就不受实现细节影响？

RAG on 男娘教主

W8-Day4：RAG 混合检索——Dense、BM25 与 RRF

W8-Day4：RAG 混合检索——Dense、BM25 与 RRF

一、为什么 Dense Retrieval 还不够

二、Sparse Retrieval：BM25

1. TF：一个词出现很多次，不应该无限加分

2. IDF：越罕见的词越重要

3. 文档长度归一化

三、Dense 和 Sparse 为什么要同时存在

四、为什么不能直接把两个 Score 相加

RRF

五、RRF：只看你排第几

六、今天最值得看的代码：RRF

七、完整 Hybrid 主调用链

八、为什么两条路线必须使用相同的 ID

九、为什么中文 BM25 还需要分词

十、Retriever 和 Reranker 不是一回事

十一、一个很容易踩的坑：RRF Score 不是相似度

十二、什么时候不需要 Hybrid

十三、今天最终要记住什么

面试时至少要能沿着这条链回答

RAG ：检索、生成与两道拒答闸

W8-D3 · RAG ：检索、生成与两道拒答闸

零、今天往前跨了两段

一、三个类比，把三段钉死

二、开工前的三个预判

2.1 生成也需要模型，而且要选"数据出不出门"

2.2 检索分数是"距离”：越小越像，方向别搞反

2.3 query 前缀必须和建库时一致

三、段④ 检索：retrieve() 为什么必须"独立可测"

3.1 一条断言同时验两件事

四、段⑤ 生成：两道拒答闸

4.1 系统提示词

4.2 编号上下文：引用的载体

4.3 两道闸：便宜的前置 + 兜底的后置

4.4 引用校验：能查出什么，查不出什么

五、完整代码 1：w8/rag_qa.py

5.1 这段复用了 Day2 的哪些接口

六、完整代码 2：w8/test_rag.py

6.1 为什么要造一个"一调就炸"的假模型

七、完整代码 3：w8/calibrate_threshold.py

八、跑的顺序：先测确定性，再测智能性

九、三个值得想清楚的问题

9.1 top-k 调大调小分别有什么影响

9.2 引用溯源为什么是 RAG 的关键优势

9.3 拒答为什么要"没检索到就不调模型"

Embedding + Chroma，把文档变成可以按语义检索的向量库

W8D2：Embedding + Chroma，把文档变成可以按语义检索的向量库

一、先把今天放回整条链路里

二、Embedding 到底在解决什么问题

三、向量库又是在干什么

四、今天代码里最值得看的部分：HashEmbeddings

1. 先准备一个固定长度的向量

2. 把文本拆成两个字一组

3. 为什么还要归一化

五、为什么还专门做了一个假的 Embedding

链路问题

模型质量问题

六、今天第二个真正重要的概念：Persistence

七、所以代码为什么要先判断库存不存在

八、为什么 --reset 也很重要

九、入库前为什么还要过滤 Chunk

十、metadata 为什么还需要单独处理

十一、为什么要分批 add_texts

十二、Chroma 这里还有一个我容易忽视的概念：距离

十三、今天的 self_check 为什么比“程序没报错”重要

十四、为什么“自己搜自己”不能代表语义质量

十五、把今天所有知识重新串起来

十六、今天真正学到的，其实不只是 RAG

1. 一个组件解决一个问题

2. 先把“系统正确”与“结果优秀”分开

3. 数据进入下一个系统前，要注意边界

4. 程序开始处理“历史状态”

十七、W8D2 最终留下的知识骨架

W8-D1 · RAG 地基代码详解：加载与分块

W8-D1 · RAG 地基代码详解：加载与分块

零、今天这份代码在做什么

一、配置区：那几个拍脑袋的数字

1.1 坑

1.2 可优化

三、段④ 检索：`retrieve()` 为什么必须"独立可测"

五、完整代码 1：`w8/rag_qa.py`

六、完整代码 2：`w8/test_rag.py`

七、完整代码 3：`w8/calibrate_threshold.py`

八、为什么 `--reset` 也很重要

十一、为什么要分批 `add_texts`

十三、今天的 `self_check` 为什么比“程序没报错”重要