RAG Part 2:向量化与存储

Catalogue
  1. 1. Embedding 把一段文字变成什么
    1. 为什么两种说法能够靠近
    2. 文档和问题的向量为什么要用配套的模型生成
  2. 2. 怎样比较向量:余弦相似度与归一化
  3. 3. 读取上一篇的文本块,生成真实向量
    1. 准备示例与环境
    2. 读取正文,并单独保留来源
    3. 检查输入长度,再批量编码
  4. 4. 用 FAISS 找到最相关的文本块
    1. 先将问题转换成向量
    2. 用 FAISS 存入向量,再取回相关原文
      1. 第一步:创建索引,存入 9 条文档向量
      2. 第二步:比较问题向量,取分数最高的 3 条
      3. 第三步:按行号取回原文
  5. 5. 保存 FAISS 时,原文和配置也要保存
  6. 6. 用 Chroma 一起保存向量、原文和元数据
    1. 第一步:创建本地集合
    2. 第二步:把向量和原文一起存入集合
    3. 第三步:用问题向量查询,直接取得原文
    4. 按来源筛选:只查 PDF 中的记录
  7. 7. 退出程序后,确认索引仍能使用
  8. 8. 检查找到的原文能否回答问题

上一篇《RAG 文档加载与文本分块》把 PDF 和 Markdown 整理成了 chunks.jsonl:每一行保存一个文本块,以及文件名、章节或页码。现在有了可以检索的资料,还缺少一步:用户问“退款什么时候到账?”,程序怎样找到讲到账时间的那几段?

直接匹配文字能解决一部分问题,但“钱多久能退回来”和“退款到账时间”可能使用不同的说法。本篇先解释 Embedding 怎样把文字转换成可以比较的向量,再用同一批向量分别构建 FAISS 和 Chroma 本地索引,最后退出程序,重新读取已保存的数据并查询。

可以先把“向量索引”理解为用来组织和查找文本向量的一套结构。例如,用户问“退款什么时候到账?”,程序把问题也转成向量,再找出相近的文档向量,取回对应的退款说明。FAISS 和 Chroma 提供了两种实现方式,帮助程序完成向量的存储与查找;本文会分别演示,实际项目可以选择其中一种。具体用法会在第 4、6 节展开。

完成后得到的是一个能返回相关原文与来源信息的检索程序。如何将检索结果交给大模型生成回答,将在下一篇《用 FastAPI 和 LangChain 构建文档问答 API》中讲解。本篇沿用上一篇的虚构退款资料,无需 API Key。

1. Embedding 把一段文字变成什么

Embedding 在这里指文本的向量表示:把一句话或一个文本块输入模型,得到固定数量的浮点数。这串数组成一个向量;其中有多少个数,就称为多少维。

例如,本文使用的中文模型会把每个文本块转换成 512 维向量。短问题和较长的段落都得到 512 个数,长度不会随着汉字数量增加。维度由模型及其输出配置决定,不是“一个汉字对应一维”。

单独看这些数字,很难读出原句。通常也不能把某一维解释为“退款”、另一维解释为“物流”。它们需要作为一个整体参与比较;向量本身无法代替完整原文,所以后面存储时还要保留文本和来源。

为什么两种说法能够靠近

用于检索的 Embedding 模型经过训练,目标之一是让相关问题与资料的向量更接近,让不相关的内容更容易区分。例如,训练数据可以包含“多久能收到退款”与退款到账说明这样的相关配对。这里的“接近”具体怎么算,下一节会用两个数的向量说明。

生成一个文本向量,大致经历以下过程:

  1. 分词:分词器把文字转换成模型使用的 token 编号。token 可以是一个字、一个词或词的一部分,取决于分词器。
  2. 编码:本文模型使用 Transformer 神经网络,结合上下文,将每个 token 转换成一个反映其含义的向量。
  3. 汇聚(pooling):根据各个 token 的向量,得到一个代表整段文字的固定长度向量。不同模型采用的汇聚方式可以不同。

Sentence Transformers 是加载和调用 Embedding 模型的 Python 库,本文使用的 BAAI/bge-small-zh-v1.5 是 BGE 系列中的小型中文 Embedding 模型。BGE 的全称是 BAAI General Embedding,即“智源通用嵌入”,该系列由北京智源人工智能研究院(BAAI)推出。BGE 模型说明

本文模型采用 CLS pooling:取序列开头的特殊 token [CLS] 的向量,作为整段文字的向量。库会按模型已有配置完成这一步。Sentence Transformers 模型结构说明;BGE 模型用法

本篇使用已经训练好的 Embedding 模型,把 PDF、Markdown 切分后得到的文本块转换成向量,这个过程称为模型推理。向量索引是组织和查找这些向量的数据结构。将生成的向量写入索引,不会重新训练 Embedding 模型。 具体写入方法将在本文第 4 节(FAISS)和第 6 节(Chroma)中介绍。

文档和问题的向量为什么要用配套的模型生成

表示空间是机器学习中的术语,这里指 Embedding 向量所在的空间,可以理解为表示文字的一套坐标规则。文档和问题的向量要遵循同一套规则,才能比较相似度。

入库时先计算各个文本块的向量。查询时,再用配套的模型把问题转成向量,与已保存的文档向量比较:

1
2
3
4
5
文本块 ── Embedding 模型 ── 文档向量 ── 存入索引
↑ 比较
用户问题 ── 配套的 Embedding 模型 ── 问题向量
↓
找到对应文本块及来源

本文的文档和问题使用同一个模型、同一个模型版本。即使两个模型都输出 512 维,也不能把它们的向量混在一起检索:维数相同不代表各个坐标的含义相同。

同一个模型也可以对文档和问题采用不同的输入格式。本例的文档直接输入原文,问题前按 BGE 的推荐用法添加检索指令。例如,问题“退款什么时候到账?”送入模型时会变成:

为这个句子生成表示以用于检索相关文章:退款什么时候到账?

这里的“这个句子”指冒号后的用户问题。“表示(representation)”是机器学习中的常用术语,在这里具体指问题的向量,也就是模型生成的一组数字。整句话可以理解为:“把‘退款什么时候到账?’转换成一个向量,用它查找相关资料。”

具体拼接和编码代码见本文第 4 节。更换模型时,应核对新的输入规则,并重新生成文档向量。

2. 怎样比较向量:余弦相似度与归一化

先用二维向量理解计算。下面这些数是手工构造的教学数据,不是模型的实际输出。

设问题向量为 q = [1, 0],两个候选向量分别为 a = [0.8, 0.6]、b = [0, 1]。它们的长度都是 1:例如 a 的长度等于 sqrt(0.8² + 0.6²) = 1,其中 sqrt 表示开平方。

内积是把相同位置的数相乘,再相加。对于这些长度为 1 的向量:

1
2
q 与 a 的内积 = 1 × 0.8 + 0 × 0.6 = 0.8
q 与 b 的内积 = 1 × 0 + 0 × 1 = 0

余弦相似度用内积除以两个向量长度的乘积,比较的是方向的接近程度:

1
余弦相似度 = 两个向量的内积 /(第一个向量的长度 × 第二个向量的长度)

这里三个向量的长度都是 1,因此余弦相似度就是内积。a 与问题的方向更接近,分数为 0.8;b 与问题垂直,分数为 0。对于非零向量,余弦相似度在 -1 到 1 之间,越大表示方向越接近。

实际模型输出的向量不一定具有单位长度。归一化就是将一个非零向量除以自己的长度,使长度变为 1、方向保持不变。例如 [3, 4] 的长度为 5,归一化后变为 [0.6, 0.8]。

本文会同时归一化文档向量和问题向量。这样,后面就能用内积计算余弦相似度。只选择“内积索引”而没有满足归一化条件,不能直接把返回值叫作余弦相似度。FAISS 相似度与距离说明

还有一个容易误读的地方:相似度 0.8 不表示回答有 80% 的概率正确。相似度用于排序,是否命中了能回答问题的资料,仍要打开原文检查。尤其是“支持退款”和“不支持退款”,主题接近却含义不同,不能只凭一个分数做业务判断。

3. 读取上一篇的文本块,生成真实向量

准备示例与环境

下载本文完整示例包,解压后进入 rag-part2-example 目录:

1
2
3
4
5
6
7
rag-part2-example/
├── chunks.jsonl # 上一篇教学资料的一次分块结果,共 9 块
├── build_and_search.py # 生成向量,构建两种索引并查询
├── query_saved.py # 在新进程中读取索引、查询
├── requirements.txt
├── requirements-lock.txt
└── README.md

包内已经包含那 9 个文本块,可以直接运行;也可以用上一篇生成的 chunks.jsonl 替换它。JSONL 表示一行一个 JSON 对象,每条记录包含 id、text、metadata、ref_doc_id。分别对应块标识、正文、来源信息,以及来源 Document 的标识。

这里直接读取 JSONL,不需要重新安装 LlamaIndex。前一阶段已经完成的加载与切分,不必在每次检索时重做。

创建 Python 3.12 虚拟环境并安装依赖:

1
2
3
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Windows PowerShell 可使用 py -3.12 -m venv .venv 创建环境,再用 .venv\Scripts\Activate.ps1 激活。本文固定的直接依赖为:

1
2
3
4
sentence-transformers==6.1.0
faiss-cpu==1.15.1
chromadb==1.5.9
numpy==2.5.3

示例在 macOS Apple Silicon、Python 3.12.7、CPU 上运行验证,使用 PyTorch 2.14.1、Transformers 5.18.0。requirements-lock.txt 记录该次验证的完整依赖版本;不同系统的安装兼容性仍取决于对应软件包。

安装依赖和首次下载模型需要联网。本例使用公开模型,无需付费模型 API;模型完整缓存后可以在本地推理。

接下来按执行顺序拆解 build_and_search.py。下面各段追加在同一个文件里,后文沿用前面定义的变量;下载包已包含完整脚本。

读取正文,并单独保留来源

先读取每一行,再整理成三个顺序一致的列表:texts 保存正文,ids 保存块 ID,metadatas 保存来源。第 i 个位置始终属于同一个文本块。

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
import json
from pathlib import Path

import numpy as np
from sentence_transformers import SentenceTransformer

MODEL_ID = "BAAI/bge-small-zh-v1.5"
MODEL_REVISION = "7999e1d3359715c523056ef9478215996d62a620"
QUERY_PREFIX = "为这个句子生成表示以用于检索相关文章:"

records = []
with Path("chunks.jsonl").open(encoding="utf-8") as source:
for line in source:
if line.strip():
records.append(json.loads(line))
if not records:
raise ValueError("chunks.jsonl 没有文本块")

texts = []
ids = []
metadatas = []
for record in records:
if not record["text"].strip():
raise ValueError("发现空文本块,请先检查加载和分块结果")
texts.append(record["text"])
ids.append(record["id"])
metadata = dict(record["metadata"])
metadata["ref_doc_id"] = record["ref_doc_id"]
metadatas.append(metadata)
if len(set(ids)) != len(ids):
raise ValueError("文本块 ID 不能重复")

MODEL_REVISION 固定本次使用的模型版本,QUERY_PREFIX 是留给第 4 节的问题输入指令。dict(...) 复制一份来源字典,再将原记录中的 ref_doc_id 放进去,便于后面一起存入 Chroma;原始 records 仍保留完整记录。

本例只将 record["text"] 送入 Embedding 模型。文件名、页码等元数据保存下来,用于展示和筛选,不自动拼入模型输入。上一篇提到的 LlamaIndex 元数据拼接规则不会在这里自动执行,因为现在调用的是普通 Python 代码和 Sentence Transformers。

检查输入长度,再批量编码

先加载模型,用这个模型自己的分词器检查长度,再计算向量。上一篇分块使用的 token 计数与这个模型可能不同,不能仅凭原来的 chunk_size 判断是否超长。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
model = SentenceTransformer(MODEL_ID, revision=MODEL_REVISION, device="cpu")
token_lengths = []
for text in texts:
token_ids = model.tokenizer(text, truncation=False)["input_ids"]
token_lengths.append(len(token_ids))
if max(token_lengths) > model.max_seq_length:
raise ValueError("文本块超过模型输入上限,请回到分块步骤调整")
print("块数 / 维度 / 输入上限:", len(texts),
model.get_embedding_dimension(), model.max_seq_length)
print("各块 token 数:", token_lengths)

vectors = model.encode(texts, normalize_embeddings=True, show_progress_bar=False)
vectors = np.ascontiguousarray(vectors, dtype="float32")
print("文档向量:", vectors.shape, vectors.dtype)
print("首向量长度:", round(float(np.linalg.norm(vectors[0])), 6))

model.tokenizer(...) 调用模型的分词器,truncation=False 表示不截断文本。返回结果类似字典,其中 "input_ids" 是 Hugging Face Transformers 分词器接口约定的字段名,保存各个 token 在词表中的数字编号,调用时由分词器自动生成。Transformers 分词器接口

循环中的取值语句可以拆成两步理解:

1
2
result = model.tokenizer(text, truncation=False)
token_ids = result["input_ids"]

["input_ids"] 是 Python 按键取值的语法;result、token_ids 是自定义变量名,可以更改,字段名 "input_ids" 则要按接口约定使用。len(token_ids) 得到 token 数量,用来检查输入是否超长。这些编号还不是向量,下面的模型编码才生成向量。

model.encode() 接收字符串列表,返回 NumPy 二维数组。每一行是一段文字的向量,normalize_embeddings=True 将每行向量归一化;show_progress_bar=False 只关闭编码进度条。

np.ascontiguousarray(..., dtype="float32") 把数组整理成连续存放的 32 位浮点数,供后面的 FAISS 使用。np.linalg.norm(vectors[0]) 计算第一条向量的长度,用于观察归一化是否生效。Sentence Transformers 编码接口

这部分的实测输出为:

1
2
3
4
块数 / 维度 / 输入上限: 9 512 512
各块 token 数: [70, 192, 152, 180, 138, 219, 70, 237, 70]
文档向量: (9, 512) float32
首向量长度: 1.0

print("文档向量:", vectors.shape, vectors.dtype) 打印提示文字、数组形状和数据类型。vectors.shape 的值为 (9, 512),表示 9 条向量,每条包含 512 个数字;vectors.dtype 的值为 float32,表示每个数字使用 32 位浮点数保存。.shape 和 .dtype 都是 NumPy 数组的属性,直接读取即可,无需加调用方法用的 ()。

输出中的两个 512 恰好相同,但含义独立:512 维指每条输出向量包含的数字个数,512 token 是模型可接受的输入长度上限。

输入上限还要计入分词器自动添加的特殊 token。本例分词器会在正文前添加 [CLS]、末尾添加 [SEP],分别标记开头和结束,各占一个 token。因此,正文分词后若有 510 个 token,加上这两个标记就是 512,刚好达到输入上限。代码中的 len(token_ids) 已包含这些标记,无需手动再加。

超过模型上限的输入通常会被截断。即使还能得到形状正确的向量,末尾的例外条件也可能没有参与编码。因此本例先检查并报错,让超长块回到分块步骤处理。Sentence Transformers 输入长度说明

4. 用 FAISS 找到最相关的文本块

先将问题转换成向量

文档向量已经生成,问题也要经过模型编码。本例按 BGE 的检索用法,在问题前添加 QUERY_PREFIX 中的中文指令,文档正文不添加。这是所选模型的输入约定,不能直接套给所有 Embedding 模型。BGE 的问题指令说明

继续在主脚本中追加:

1
2
3
4
5
6
7
8
9
10
question = "退款什么时候到账?"
query_text = QUERY_PREFIX + question
query_tokens = model.tokenizer(query_text, truncation=False)["input_ids"]
if len(query_tokens) > model.max_seq_length:
raise ValueError("问题连同指令超过模型输入上限")
query_vector = model.encode(
[query_text], normalize_embeddings=True, show_progress_bar=False
)
query_vector = np.ascontiguousarray(query_vector, dtype="float32")
print("问题向量:", query_vector.shape)

query_text 包含“指令+问题”,模型会把整段输入一起编码。传入 [query_text],即只有一个元素的列表,输出形状为 (1, 512)。FAISS 的搜索接口接受一批问题向量,即使只有一个问题,也保留这个二维形状。

问题向量同样归一化,才能与前面归一化的文档向量通过内积计算余弦相似度。到这里,文档和问题都已经变成数值数组,才轮到索引处理。

用 FAISS 存入向量,再取回相关原文

FAISS 是向量相似度搜索库。前面的 Embedding 模型把文字变成向量,FAISS 负责在这些向量中查找与问题向量最接近的几条。它返回相似度分数和向量的行号,程序再按行号从 records 中取回原文。

下面分三步追加到主脚本:存入文档向量、查询相似向量、取回原文。

第一步:创建索引,存入 9 条文档向量

先创建一个索引对象,用它保存和搜索向量。本例选择 IndexFlatIP:

  • Flat:查询时逐条比较全部文档向量,按分数排序,称为精确搜索。数据越多,需要比较的次数越多。
  • IP:inner product,即第 2 节介绍的内积。本文已将文档和问题向量归一化,所以内积就是余弦相似度,分数越大越接近。

这个索引无需先训练,创建后就能加入向量。FAISS 入门教程

1
2
3
4
5
import faiss

dimension = vectors.shape[1]
index = faiss.IndexFlatIP(dimension)
index.add(vectors)

vectors.shape 为 (9, 512),其中 [1] 取第二个数 512,所以 dimension 是每条向量的维度。IndexFlatIP(dimension) 创建接收 512 维向量的索引,index.add(vectors) 再把 9 条向量按原顺序加入。

第二步:比较问题向量,取分数最高的 3 条

query_vector 是上一小节生成的问题向量。用它与索引中的文档向量比较,取分数最高的 k 条,这种取法称为 Top-k;本例取 Top-3。

1
2
3
k = min(3, index.ntotal)
scores, rows = index.search(query_vector, k)
print("FAISS 向量数:", index.ntotal)

index.ntotal 是索引中的向量总数,本例为 9。min(3, index.ntotal) 取两个数中较小的一个:有 9 条就取 3 条,若只有 2 条就取 2 条,避免请求数量超过已有数量。

index.search(query_vector, k) 的两个参数分别是问题向量和返回条数。它返回两份结果,分别赋给 scores 和 rows:

  • scores:按从高到低排列的相似度分数。
  • rows:与这些分数一一对应的文档向量行号。

FAISS 支持一次查询多个问题,所以结果先按问题分组。本文只有一个问题,两份数组的形状都是 (1, 3):scores[0] 取这个问题的 3 个分数,rows[0] 取对应的 3 个行号。

第三步:按行号取回原文

行号从 0 开始,表示向量加入索引时的位置,不是 JSONL 中的块 ID。 例如,示例包中“退款到账”是第 4 条记录,向量行号为 3。检索命中行号 3 时,用 records[3] 就能取回这段正文及来源信息。

1
2
3
4
5
for rank in range(k):
row = int(rows[0][rank])
record = records[row]
print("FAISS", rank + 1, f"{scores[0][rank]:.4f}", record["metadata"])
print(record["text"][:80].replace("\n", " "))

rank 依次为 0、1、2。rows[0][rank] 取这个问题当前名次的行号,int(...) 将它转换成 Python 整数,再通过 records[row] 取得原始记录。scores[0][rank] 则取得同一名次的分数。

打印时,rank + 1 显示第 1、2、3 名,:.4f 将分数显示为四位小数,record["metadata"] 显示来源。最后一行取正文的前 80 个字符,将换行替换为空格,方便预览。

这依赖一个条件:**vectors 和 records 的顺序必须对应。** 单独打乱 records 后,行号仍能取到一条记录,却可能是错误的原文。第 5 节会将索引和对应记录一起保存。

同一问题的实测结果整理如下,分数保留四位小数:

名次 FAISS 余弦相似度 命中位置 原文中可观察的内容
1 0.6764 refund.md,退款到账 仓库检查通过后发起退款,通常三个工作日,节假日可能顺延
2 0.6620 policy.pdf,第 2 页的第一个块 退款原路返回,三个工作日及查询说明
3 0.6400 refund.md,退款说明 对整份退款资料的概述

前两条包含到账时间说明,第三条只是退款资料的概述。Top-3 返回的是分数最高的三条,不保证每条都能回答问题。 目前程序只找出原文,尚未生成回答。不同环境的分数可能有末位差异,更换数据或模型也可能改变排名。

选读:官方教程中的 IndexFlatL2 有什么不同?

对照官方入门教程时,会看到它使用 IndexFlatL2。这种索引也逐条比较向量,但计算的是平方欧氏距离:将对应坐标的差平方后相加,越小越接近。例如,第 2 节中 q 与 a 的距离为 (1 - 0.8)² + (0 - 0.6)² = 0.4。

两边向量都归一化时,平方欧氏距离等于 2 - 2 × 内积,上例为 2 - 2 × 0.8 = 0.4。因此,此时 IndexFlatL2 按距离从小到大排序,与 IndexFlatIP 按内积从大到小排序对应,但两种分数不能混用。FAISS 距离说明

5. 保存 FAISS 时,原文和配置也要保存

目前的 index、records 都在进程内存里。为了退出后还能使用,需要将它们写入磁盘,也就是持久化。

faiss.write_index() 保存向量索引,但不会替程序保存外部的 records 列表。本文将三份文件配套保存:索引、按原顺序排列的文本记录,以及向量化配置。

继续追加以下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
output = Path("storage")
output.mkdir(exist_ok=True)
faiss.write_index(index, str(output / "chunks.faiss"))
(output / "records.json").write_text(
json.dumps(records, ensure_ascii=False, indent=2), encoding="utf-8"
)
manifest = {
"model_id": MODEL_ID,
"model_revision": MODEL_REVISION,
"query_prefix": QUERY_PREFIX,
"normalize_embeddings": True,
"dimension": dimension,
"document_input": "record.text",
"faiss_metric": "inner_product",
"chroma_metric": "cosine",
"collection_name": "refund_bge_small_zh_v1",
}
(output / "manifest.json").write_text(
json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
)

manifest 是本例自定义的配置字典,FAISS 不会自动读取它。后面的查询脚本将读取其中的模型名称、版本、问题指令与归一化设置,继续使用与建库时配套的编码方式。字典末尾两个 Chroma 字段为下一节准备:分别指定距离计算方式,以及存放记录的集合名称。

6. 用 Chroma 一起保存向量、原文和元数据

FAISS 返回行号后,需要程序去 records 中找原文。Chroma 是向量数据库,可以把向量、原文、块 ID 和来源信息一起保存,查询时直接返回原文。

Chroma 用 collection(集合) 存放一组有名称的记录,例如“退款资料集合”。同一集合中的向量维度必须一致。本节沿用第 3、4 节算好的 vectors 和 query_vector,按以下步骤追加到主脚本。

第一步:创建本地集合

先指定数据保存在哪里,再创建退款资料集合。第 5 节的 output 指向 storage,所以这里的保存位置是 storage/chroma。

1
2
3
4
5
6
7
8
import chromadb

client = chromadb.PersistentClient(path=str(output / "chroma"))
collection = client.get_or_create_collection(
name=manifest["collection_name"],
embedding_function=None,
configuration={"hnsw": {"space": manifest["chroma_metric"]}},
)

PersistentClient(...) 创建访问本地数据的客户端 client,数据会自动保存到指定目录,无需单独启动数据库服务器。get_or_create_collection() 按名称查找集合,没有就创建,有就返回已有集合。

创建集合时,三个参数分别控制:

参数 本例设置及作用
name 读取第 5 节配置中的 refund_bge_small_zh_v1,作为集合名称
embedding_function=None 使用前面算好的向量,Chroma 不再调用模型生成向量
configuration 其中的 hnsw 是本地向量索引的配置项,space 设为 "cosine",按余弦距离搜索;距离的含义在第三步说明

manifest 是第 5 节定义的配置字典,manifest["chroma_metric"] 取出的值就是 "cosine"。Chroma 集合配置

第二步:把向量和原文一起存入集合

调用 upsert(),一次写入 9 个文本块的记录:

1
2
3
4
5
6
collection.upsert(
ids=ids,
embeddings=vectors.tolist(),
documents=texts,
metadatas=metadatas,
)

四个参数对应一条记录的四部分,数据都来自第 3 节:

参数 保存的内容
ids 文本块 ID,用来区分和更新记录
embeddings 文本块的向量,用来搜索
documents 文本块的原文,用来查看结果
metadatas 文件名、页码等来源信息,用来展示和筛选

vectors.tolist() 将 NumPy 数组转换成 Python 嵌套列表。四份数据按位置一一对应:第一条向量、第一段正文、第一个 ID 和第一份来源信息属于同一个文本块。已提供向量,Chroma 就直接保存,不会再编码原文。写入数据

upsert() 按 ID 决定如何写入:ID 已存在就更新,不存在就新增。它不会根据正文是否相同来判断是不是已有记录。更新规则

正文没变,ID 也可能变。 上一篇的 prepare_chunks.py 每次分块都会创建新的节点,node.text 保存正文,node.node_id 默认生成随机编号(UUID),再作为 id 写入 chunks.jsonl。这个编号不是根据正文计算出来的,所以原文件和分块设置没变,重新分块也会生成新的 ID。LlamaIndex 的 ID 生成实现

因此,两种重复运行的结果不同:

  • **只重跑 build_and_search.py,读取原来的 chunks.jsonl**:ID 不变,更新已有记录,本例仍为 9 条。
  • 先重跑 prepare_chunks.py,再运行建库脚本:ID 重新生成,写入原来的 Chroma 集合时,会新增一批记录,旧记录仍然保留。

例如,同一句“退款通常三个工作日到账”,第一次 ID 是 aaa-111,第二次是 bbb-222(编号为简化示意)。Chroma 会把它们存成两条记录,搜索时可能返回重复内容,占用结果名额;如果正文也已修改,还可能返回旧规定。本文练习重新分块后,应在新的练习目录建库,第 8 节会说明操作。

第三步:用问题向量查询,直接取得原文

用同一个问题“退款什么时候到账?”继续查询,k 沿用第 4 节的值 3:

1
2
3
4
5
result = collection.query(
query_embeddings=query_vector.tolist(),
n_results=k,
include=["documents", "metadatas", "distances"],
)

query_embeddings 传入问题向量,n_results 指定返回条数,include 指定同时取回原文、来源和距离。第一步关闭了自动生成向量,因此这里必须提供问题向量。

result 是保存查询结果的字典。结果也按问题分组:result["documents"][0] 取第一个问题的正文列表,再加一个 [0] 就取到第一名的原文。Chroma 已经返回正文,无需再按 FAISS 行号查找 records。 ids 会自动返回,其余字段由 include 选择。Chroma 查询接口

这里的 distances 是余弦距离,等于 1 - 余弦相似度,越小越接近。例如,FAISS 相似度为 0.6764,对应的 Chroma 距离是 1 - 0.6764 = 0.3236。

接着打印记录总数和查询结果:

1
2
3
4
5
print("Chroma 记录数:", collection.count())
for rank in range(len(result["ids"][0])):
distance = result["distances"][0][rank]
print("Chroma", rank + 1, f"{distance:.4f}", result["metadatas"][0][rank])
print(result["documents"][0][rank][:80].replace("\n", " "))

collection.count() 返回集合中的记录总数,本例为 9。循环中,[0][rank] 取第一个问题当前名次的结果,原文预览和分数格式的写法与 FAISS 示例相同。

本次实测返回与 FAISS 相同的三个块,分数对照如下:

命中位置 FAISS 相似度,越大越好 Chroma 距离,越小越好
refund.md,退款到账 0.6764 0.3236
policy.pdf,第 2 页的第一个块 0.6620 0.3380
refund.md,退款说明 0.6400 0.3600

记住本例的判断方向:FAISS 相似度越大越好,Chroma 余弦距离越小越好。 更换距离设置后,要按新的分数定义解释结果。

按来源筛选:只查 PDF 中的记录

若只想查 policy.pdf,在主脚本末尾追加以下查询。where 指定来源,只在符合条件的记录中搜索;问题向量不需要重新计算。

1
2
3
4
5
6
7
pdf_result = collection.query(
query_embeddings=query_vector.tolist(),
n_results=2,
where={"source": "policy.pdf"},
include=["documents", "metadatas", "distances"],
)
print(pdf_result["metadatas"][0])

where={"source": "policy.pdf"} 表示只查元数据中 source 为 policy.pdf 的记录,n_results=2 表示取其中最接近的两条。因此,输出的两份元数据中,source 都应为 policy.pdf。元数据筛选说明

选读:Chroma 与前面的 FAISS 搜索有何不同?

Chroma 本地集合使用 HNSW 索引。它将距离较近的文档向量连接起来,搜索时从一些向量开始,沿这些连接寻找与问题向量更接近的文档向量,通常无需逐条比较全部向量。

这样能减少比较次数,但可能漏掉最接近的向量,因此称为近似搜索。它的结果可能与 FAISS IndexFlatIP 的逐条比较不同。本次 9 个文本块的结果一致,不代表所有数据集都会一致。

配置里的 hnsw 指定这类索引的设置,space 指定距离计算方式。本地集合默认使用平方 L2 距离,本例显式改为 "cosine",才能用 1 - 余弦相似度 解释返回的距离。索引与距离配置

7. 退出程序后,确认索引仍能使用

在示例包解压后的 rag-part2-example 目录运行主脚本,生成并保存索引:

1
python build_and_search.py

输出应包含 FAISS 向量数: 9、Chroma 记录数: 9,并生成以下文件:

1
2
3
4
5
storage/
├── chunks.faiss # FAISS 索引
├── records.json # 与索引行序对应的完整记录
├── manifest.json # 本例的模型与检索配置
└── chroma/ # Chroma 保存的向量、原文和元数据

主脚本结束后,在同一目录运行示例包中的查询脚本。引号内是要查询的问题:

1
python query_saved.py "退款什么时候到账?"

这次会启动一个新程序。它按 manifest.json 中的配置加载模型,只计算新问题的向量,再查询磁盘上已有的数据:FAISS 用 read_index() 读取索引,并读取 records.json;Chroma 打开原目录,用 get_collection() 取得已有集合,找不到就报错。

实测中,两边仍为 9 条,前三个结果的原文、来源和四位小数分数与建库时一致,说明保存的数据可以继续使用。脚本会打印完整正文,便于检查“退款三个工作日到账”的适用条件。

注意两个运行条件:

  • 从同一目录启动:storage 是相对路径,换目录会找错数据位置。Chroma 的 PersistentClient 自动保存,本版本无需调用 .persist()。本地客户端说明
  • 保留相同模型版本:索引不包含模型文件。换电脑时也要准备原模型,才能编码新问题。

8. 检查找到的原文能否回答问题

检索成功只说明找到了相近的向量,还要检查原文有没有答案。先用示例资料测试两类问题:

1
2
python query_saved.py "定制商品能无理由退款吗?"
python query_saved.py "今天北京天气怎么样?"

资料里有答案:看关键条款是否找到。 “定制商品”问题应找到“不适用无理由退款”的说明。实测中,含该条款的文本块排第三,FAISS 相似度为 0.5679;第一名是概述,分数为 0.6131。只取第一名就会漏掉答案。

资料里没答案:看是否仍返回无关内容。 天气问题也返回了退款资料,第一名相似度为 0.3016。向量检索会找现有资料中最接近的内容,不会自动判断资料有没有答案。

可设置相似度门槛过滤低分结果,但要用自己的“有答案、无答案”问题验证,不能照搬示例分数。本篇先通过阅读原文检查,未设置自动过滤。

检索结果不对时,可以按下面五种情况排查:

  1. 文本块里就缺了文字。 例如,原文有“定制商品除外”,但 chunks.jsonl 中没有。先检查文档读取和分块,模型无法找回已经丢失的文字。
  2. 文字完整,但输入模型时太长。 超出上限的末尾可能被截掉,没有参与生成向量。用模型分词器检查实际输入的 token 数,添加的标题或指令也要计入。本文代码超限会报错,提醒重新分块。
  3. 换了模型,文档向量却没重新生成。 旧模型生成文档向量,新模型生成问题向量,两者不配套。核对模型、版本和输入规则,更换模型后重新生成文档向量。
  4. FAISS 找到了向量,却取错原文。 例如,返回行号 3,但 records.json 顺序变过,第 4 条记录已不是原来那段文字。检查索引与记录是否来自同次构建,顺序是否对应。
  5. Chroma 中新旧记录混在一起。 检查是否重新运行了 prepare_chunks.py,又将生成的新 ID 写入原集合。正文即使相同,旧记录也不会自动删除;第 6 节解释了原因。本文练习可在新的目录重新建库。

用自己的资料练习时,将示例包解压到新的练习目录,用自己的 chunks.jsonl 替换示例文件,再运行 build_and_search.py。这样新索引保存在新目录,不会与原来的退款示例混用。

例如,假设资料是公司请假规定,可以这样检查:

  1. 先人工找到答案。 问“请假需要提前几天申请?”,先在文本块中找到“提前三天申请”的规定。
  2. 再让程序检索。 把同一个问题传给 query_saved.py,检查返回结果中有没有这段原文。
  3. 再问资料没讲的内容。 例如“今天北京天气怎么样?”,观察程序是否仍返回无关的请假规定。

下一篇《用 FastAPI 和 LangChain 构建文档问答 API》将讲解如何把检索原文交给大模型,生成回答并通过 API 返回。