数据截至 (上游 commit 059ecec2eeac)
向量化管线:文本/文档如何变成向量
30 秒导读: 检索系统要"用相似度找东西",前提是先把每段文本变成一串数字(向量)。这一章讲 txtai 的
vectors/目录——输入内容 → 数值向量的这一层。它做三件事:选一个后端模型去编码、对编出来的向量做统一后处理(截断 / 归一化 / 量化)、以及把海量向量流式写盘再内存映射回来以省内存。至于这些向量之后被建成什么索引、怎么打分、怎么融合,分别是03 / 04 的事。
本章属于 txtai 系列的一环。同组还有:index.md(全景与阅读地图)、01-embeddings-database.md(Embeddings 编排类与索引生命周期)、03-indexes-dense-sparse.md、04-search-and-fusion.md、05-sql-and-database.md、06-graph.md。
1. 这是什么(零基础也能懂)
一句话定义: 向量化层就是一台"文本进、数字出"的转换机——把 "the cat sat" 这样的字符串,变成 [0.013, -0.11, 0.42, ...] 这样一个几百维的浮点数组。
为什么需要它。 计算机不会"读懂"文字,但很会算数。只要把每段文字映射成同一空间里的一个点(向量),"语义相近"就能变成"两点距离近 / 夹角小",检索于是退化成一道数学题。这一层的职责,就是可靠、批量、省内存地把内容都摆到这个空间里。
它具体做什么:
- 选后端:根据配置(或从模型路径自动推断)挑一个编码后端——本地 Transformer、sentence-transformers、llama.cpp、外部 API、词向量……
- 编码:调后端把一批文本转成向量。
- 后处理:按需截断维度、做 L2 归一化、做标量量化压缩。
- 落盘与回读:把成批向量流式写到临时文件,再用内存映射(memmap)读回,避免一次性把几百万向量塞进内存。
一句话直觉: 把它当成一台"翻译机 + 流水线"。翻译机(后端模型)负责把语言翻成坐标;流水线(base 类)负责把坐标切齐、摆正、压缩、装箱发货。你换翻译机(后端),流水线不变——这正是这一层的设计核心。
两类产物,先记住区别:
| 稠密向量(dense) | 稀疏向量(sparse) | |
|---|---|---|
| 长什么样 | 定长数组,几乎每一维都非零,如 384/768 维全是小数 | 超高维但绝大多数是 0,只存"非零位置 + 值" |
| 存储结构 | numpy ndarray(memmap) | SciPy csr_matrix(压缩稀疏行) |
| 擅长 | 语义相似("含义接近") | 词面/词项匹配(类似关键词) |
| 本章对应 | vectors/dense/* | vectors/sparse/* |
两者的后处理规则不同:稠密能截断、能量化;稀疏两者都直接报错不支持(见 §6)。
2. 顶层全景(它大概怎么转)
怎么读这张图: 从左到右是一次批量向量化的数据流。中间那条竖线是"每段文本必经的四步管线";下方是可切换的后端;右侧是省内存的落盘/回读机制。
一次 index(documents) 调用
│
┌─────────────────┴────────────── ────┐
│ base.Vectors.index / vectors │ 按 batchsize 切批 + 流式落盘
└─────────────────┬──────────────────┘
│ 每批 documents
▼
prepare ──► ┌──────────────────────────────────────────┐
(分词/加指令)│ vectorize() 每段文本必经四步 │
│ ① encode ② truncate ③ normalize ④ quantize│
└───────────────────┬──────────────────────────┘
│ ① 调后端(可切换)
┌───────────┬─────────────┼─────────────┬───────────┐
▼ ▼ ▼ ▼ ▼
sbert / llama.cpp litellm words external
huggingface (本地GGUF) (远程API) (词向量+权重) (自定义函数)
└───────────┴─────────────┴─────────────┴───────────┘
│ 成批向量(numpy / CSR)
▼
saveembeddings ──► 临时/checkpoint 文件(spool)
▼
vectors(): np.memmap 逐批读回 ──► 交给索引层
部件一句话职责:
| 部件 | 干什么 | 在哪 |
|---|---|---|
Vectors(基类) | 定义整条管线:批处理、prepare、vectorize 四步、落盘/回读 | vectors/base.py:20 |
VectorsFactory | 按 method 或从 path 推断,选出稠密后端 | vectors/dense/factory.py:18 |
SparseVectorsFactory | 选稀疏后端 | vectors/sparse/factory.py:11 |
| 稠密后端 | 各自实现 encode,把文本变数组 | vectors/dense/*.py |
| 稀疏后端 | 实现 encode,把文本变 CSR 稀疏矩阵 | vectors/sparse/*.py |
Recovery | 从 checkpoint 断点续跑,复用已算好的批 | vectors/recovery.py:9 |
Reducer | 词向量场景下的 LSA 降噪(去主成分) | embeddings/index/reducer.py:20 |
主线走一遍(高层): 上游 embeddings/index/transform.py:100 把文档流交给 model.vectors(...);基类 index() 把文档切成批,逐批 prepare → vectorize(四步)→ saveembeddings 写盘;全部写完后 vectors() 用 np.memmap 把盘上的向量映射回来,连同 ids 和维度数一并返回给索引层。
3. 核心原理(逐个机制,由浅入深)
3.1 一段文本进来,先被"预处理":prepare 与 tokens
要解决的小问题: 不同后端要的输入格式不一样——有的要原始字符串,有的要求先分词,有的指令式模型还要在 文本前拼一句"任务说明"。得先把输入摆成后端认识的样子。
prepare 分两步做这件事,见 vectors/base.py:311 prepare:
- 可选分词(
tokens,vectors/base.py:336):若配置了tokenize,用Tokenizer.tokenize把字符串切成词再拼回空格串;若输入本来就是 token 列表,也拼成字符串。 - 可选加指令:若配了
instructions且当前category(如"query"/"data")命中,就把对应指令前缀拼到文本前(vectors/base.py:330)。这对应"查询和文档用不同 prompt"的检索模型。
# 示意,非源码:prepare 的核心逻辑
def prepare(data, category="query"):
data = tokens(data) # 可选分词,列表→空格串
if instructions and category in instructions and isinstance(data, str):
data = f"{instructions[category]}{data}" # 指令前缀
return data
category 这个参数贯穿全程,取值主要是 "query"(查询侧)和 "data"(入库文档侧),让同一个模型对查询和文档走不同处理。
3.2 管线的心脏:vectorize 的四步
要解决的小问题: 无论换哪个后端,编码之后的"整形"步骤应该统一,不该让每个后端各写一遍。
txtai 的做法是把编码与后处理分开:后端只管 encode(抽象方法,vectors/base.py:76),而所有向量都流经基类的 vectorize(vectors/base.py:357),固定走四步。
vectorize(data):
① embeddings = encode(data) # 调后端,唯一由子类实现的一步
② if dimensionality < 维度: truncate # 截断(仅对 MRL 模型有意义)
③ embeddings = normalize(embeddings) # L2 归一化
④ if qbits: embeddings = quantize # 标量量化压缩
为什么这样分层: 换后端 = 换 ①;②③④ 一行不用动。这就是 §1 说的"换翻译机、流水线不变"。稀疏子类通过覆写 ②③④ 来定制自己的规则(见 §6),但入口仍是同一个 vectorize。
batchtransform(vectors/base.py:212)是它的对外包装:先 prepare 每个文档,若发现输入已经是 numpy 数组就直接返回、跳过编码(vectors/base.py:228),否则才调 vectorize。这让"用户已自备向量"的场景零开销通过。
3.3 后端怎么选:VectorsFactory 与从路径推断
要解决的小问题: 用户往往只给一个模型路径,不写 method。系统得自己看出"这是个 GGUF 文件 / 是个 API 名 / 是 HF 模型"。
VectorsFactory.method(vectors/dense/factory.py:75)先看配置里有没有显式 method;没有就按 path 依次探测(vectors/dense/factory.py:92):
若无 method 且有 path,依次问:
LiteLLM.ismodel(path)? → "litellm" (能被识别为某 API provider)
LiteRT.ismodel(path)? → "litert" (以 .tflite 结尾)
LlamaCpp.ismodel(path)? → "llama.cpp" (以 .gguf 结尾)
Model2Vec.ismodel(path)? → "model2vec" (config.json 里 model_type)
WordVectors.ismodel(path)? → "words" (SQLite 库 或 staticvectors)
都不是 → "transformers" (兜底:本地 HF 模型)
create(vectors/dense/factory.py:23)再按算出的 method 实例化对应类;认不出的字符串会走 resolve 当自定义类去动态加载(vectors/dense/factory.py:111)。
3.4 L2 归一化:把"长度"从相似度里剔除
要解决的小问题: 若不归一化,向量长度会掺进相似度里,长文本可能只因"向量更长"而显得更相关。归一化后所有向量落到单位球面上,点积就等价于余弦相似度。
normalize(vectors/base.py:434)对矩阵按行除以其 L2 范数,对单个向量则整体除。它是**就地(in-place)**操作。之所以要归一化,是因为下游 dot(vectors/base.py:233)直接用点积算分——它在注释里明说"假设输入都已归一化"。
3.5 标量量化:用 uint8 把向量压小
要解决的小问题: 一个 768 维 float32 向量占 3072 字节;上百万个就是 GB 级。若能接受一点精度损失,把每维压到几 bit,内存和磁盘能省好几倍。
配置里的 quantize 是想要的 bit 数;构造时被夹到 1–8 之间存为 self.qbits(vectors/base.py:61):
# 源码:vectors/base.py:61 —— 只接受 1..8 的整数,布尔值被排除
self.qbits = max(min(quantize, 8), 1) if isinstance(quantize, int) and not isinstance(quantize, bool) else None
quantize(vectors/base.py:453)的算法(以归一化后的向量为输入):
- 取
factor = 2^(qbits-1)作为量程中点。 - 把浮点值乘以
factor、裁剪到[-factor, factor-1]、再加factor平移到非负,转成uint8(vectors/base.py:468)。 - 用
np.unpackbits把每个 uint8 拆成 8 个 bit,只保留末尾 qbits 位(vectors/base.py:476,例如 3-bit 就丢掉高 5 位)。 - 用
np.packbits把这些有效 bit 重新紧密打包成 uint8 数组返回。
配套地,上游在量化开启时会把 memmap 的 dtype 设为 np.uint8(否则 np.float32),见 embeddings/index/transform.py:97。注意:量化只对稠密向量有效;稀疏子类的 quantize 直接抛错(见 §6)。
3.6 维度截断:只对 MRL 模型有意义
truncate(vectors/base.py:418)就是 embeddings[:, :dimensionality]——砍掉尾部维度。它的注释点明这只对把重要信息放在前面维度的模型有意义(如 Matryoshka Representation Learning,套娃式表征)。对普通模型直接截断会丢信息,所以它由 dimensionality 配置显式触发,且仅当目标维度小于实际维度时才做(vectors/base.py:382)。
4. 深入实现:批处理、落盘与 memmap
这一节讲"几百万文档怎么不撑爆内存"。核心思路一句话:边算边写盘,算完再内存映射读回。
4.1 切批 + 流式落盘:index
index(vectors/base.py:112)把文档流按 batchsize(默认 500)攒批,每满一批就调 batch(vectors/base.py:284)编码并立即写盘,而不是在内存里堆着:
# 示意,非源码:index 的骨架
with spool(checkpoint, vectorsid) as output: # 打开落盘文件
batch = []
for document in documents:
batch.append(document)
if len(batch) == batchsize:
uids, dimensions = self.batch(batch, output, recovery) # 编码 + 写盘
ids.extend(uids); batches += 1
batch = []
if batch: # 收尾最后一批
...
return (ids, dimensions, batches, stream) # 只返回元数据 + 文件路径
注意它返回的不是向量本身,而是 ids、维度、批数、以及落盘文件路径 stream。真正的向量还躺在盘上。
batch(vectors/base.py:284)内部:抽出 ids → prepare 每个文档(category 固定 "data")→ 优先从 recovery 读、否则 vectorize → saveembeddings 追加写盘。读/写盘用的是 numpy 的 np.save/np.load(vectors/base.py:394、vectors/base.py:407)。
4.2 memmap 回读:vectors
vectors(vectors/base.py:155)先跑 index 落盘,再用 np.memmap 分配一块 (总数, 维度) 的磁盘映射数组,然后逐批把盘上向量读回、写进 memmap 的对应切片:
# 源码要点:vectors/base.py:177
embeddings = np.memmap(buffer, dtype=dtype, shape=(len(ids), dimensions), mode="w+")
with open(stream, "rb") as queue:
x = 0
for _ in range(batches):
batch = self.loadembeddings(queue) # 从 spool 读一批
embeddings[x : x + batch.shape[0]] = batch
x += batch.shape[0]
buffer 是外部传入的 memmap 文件路径,dtype 由上游按是否量化决定(uint8 / float32)。用 memmap 的好处:返回的 embeddings 在语义上是个完整大数组,但实际数据在磁盘上,按需分页进内存,索引层可以顺序消费而不必全量驻留。未开 checkpoint 时,临时 spool 文件在读完后被删除(vectors/base.py:186)。
4.3 断点续跑:vectorsid、spool、Recovery
要解决的小问题: 给千万级文档建库要跑很久,中途崩了不该从零再来。
三块拼图:
spool(vectors/base.py:264):决定向量写到哪。开了 checkpoint 就写到{checkpoint}/{vectorsid}这个稳定文件;否则写 临时文件。vectorsid(vectors/base.py:248):把决定"这次向量化身份"的配置项(path、method、tokenizer、maxlength、quantize等)拼成 JSON,算一个确定性 UUID5。配置一样 → id 一样 → 能复用同一个 checkpoint 文件;配置一变(比如换了模型),id 变,旧 checkpoint 自然作废。Recovery(vectors/recovery.py:9):若 checkpoint 文件已存在,构造时把它复制成recovery文件并打开;之后每次batch调recovery()(vectors/recovery.py:39)就从这个副本里读出上次已算好的一批,省去重新编码。读到文件尾(EOFError)就清理并返回None,后续批回落到正常vectorize。
这套设计让重启后的向量化"接着上次的批往下算",而不是从头。
5. 各后端逐一对比(每个一句话)
所有稠密后端都继承 Vectors,只实现自己的 loadmodel / encode;差别全在"用什么去编码"。
| 后端类 | 文件:符号 | 一句话:它用什么编码 |
|---|---|---|
STVectors | dense/sbert.py:18 | sentence-transformers(SBERT);按 category 分别调 encode_query/encode_document,多 GPU 时起进程池 |
HFVectors | dense/huggingface.py:10 | 本地 HF Transformer + 池化层(mean/cls pooling),经 PoolingFactory 构建 |
LiteLLM | dense/litellm.py:21 | 远程 embedding API(OpenAI 等),loadmodel 返回 None,encode 直接发 API 请求,批处理在服务端 |
LlamaCpp | dense/llama.py:23 | 本地 .gguf 模型经 llama.cpp,encode 调 model.embed,批处理靠 n_batch |
LiteRT | dense/litert.py:24 | 本地 .tflite 模型 + tokenizers,自己做定长 padding/截断,手工搬运 tensor buffer 分批推理 |
Model2Vec | dense/m2v.py:19 | Model2Vec 静态蒸馏模型(StaticModel),轻量快速 |
WordVectors | dense/words.py:71 | 词向量:逐 token 查表,再用 scoring 词权重做加权平均得句向量;支持多进程池 |
External | dense/external.py:16 | 用户自带的 transform 函数/API;encode 调它,再统一 cast 成 float32 |
WordVectors 值得单独说两句——它是唯一深度用到 scoring 的后端。encode(dense/words.py:130)对每段文本:查出每个 token 的词向量,用 scoring.weights(tokens) 拿到词权重(类似 TF-IDF 的"这个词多重要"),做加权平均;没有权重就退化成简单平均(dense/words.py:145-148)。它还覆写了 index(dense/words.py:154)用多进程池并行编码,并覆写 tokens(dense/words.py:208)跳过基类分词。
这条线还牵出 LSA 降噪:词向量的句表示常被高频 常用词"污染",Reducer(embeddings/index/reducer.py:20)用 TruncatedSVD 拟合出主成分,再在 __call__(embeddings/index/reducer.py:39)里把这几个主成分从每个向量里减掉,平滑掉"没信息量的common词"带来的噪声。Reducer 属于索引层的一环(呼应 03),这里只点出它和词向量后端的呼应关系。
6. 稀疏向量:同管线,不同规则
稀疏后端 SparseVectors(vectors/sparse/base.py:20)同样继承 Vectors,复用整条批处理/落盘框架,但把和"稠密"绑死的几步覆写掉:
encode(vectors/sparse/base.py:35):先调父类 encode 得到一个 torch 稀疏张量,取出非零的 indices/values,转成 SciPycsr_matrix(压缩稀疏行格式,只存非零)。vectors(vectors/sparse/base.py:47):回读时不用 memmap,而是把每批 CSR 用scipy.sparse.vstack纵向拼起来——稀疏矩阵没法简单 memmap。truncate/quantize:直接raise ValueError(vectors/sparse/base.py:71、:78)——稀疏向量"截断维度""标量量化"都无意义。normalize(vectors/sparse/base.py:74):默认不归一化(defaultnormalize返回 False,vectors/sparse/base.py:81),因为稀疏向量通常 不归一化时检索更好;可配置开启。dot(vectors/sparse/base.py:62):改用safe_sparse_dot算稀疏点积。
具体实现只有一个:SparseSTVectors(vectors/sparse/sbert.py:17),用 sentence-transformers 的 SparseEncoder;它多重继承 SparseVectors 和稠密的 STVectors,复用后者的 GPU/池化装载逻辑,只把 encoder 换成 SparseEncoder,并在余弦相似时默认开归一化(vectors/sparse/sbert.py:32)。工厂 SparseVectorsFactory.create(vectors/sparse/factory.py:16)默认就走 sentence-transformers。
7. 边界与局限(这一章刻意不讲什么)
- 不讲这些向量之后建成什么索引结构(Faiss/HNSW 等 ANN、稀疏 scoring 索引)→ 见 03-indexes-dense-sparse.md。
- 不讲 BM25 / 词项打分的具体公式(词权重
scoring.weights在本章只作为词向量的输入被提及)→ 见 03。 - 不讲稠密/稀疏分数怎么融合成混合检索结果 → 见 04-search-and-fusion.md。
- 量化/截断只适用稠密;稀疏调用会直接抛错(§6),这是刻意的边界。
dot假设输入已归一化(vectors/base.py:233注释),若绕过vectorize自己塞未归一化的向量,相似度会失真。
8. 代码地图(导航索引)
| 主题 | 文件路径 | 符号 |
|---|---|---|
| 向量化基类 / 整条管线 | src/python/txtai/vectors/base.py | Vectors |
| 四步后处理入口 | src/python/txtai/vectors/base.py | vectorize |
| 编码抽象方法(子类实现) | src/python/txtai/vectors/base.py | encode |
| 预处理(分词 + 指令前缀) | src/python/txtai/vectors/base.py | prepare / tokens |
| 对外转换包装 | src/python/txtai/vectors/base.py | batchtransform / transform |
| 切批 + 流式落盘 | src/python/txtai/vectors/base.py | index / batch |
| memmap 回读 | src/python/txtai/vectors/base.py | vectors |
| L2 归一化 | src/python/txtai/vectors/base.py | normalize |
| 标量量化(qbits→uint8) | src/python/txtai/vectors/base.py | quantize(qbits 在 __init__) |
| 维度截断(MRL) | src/python/txtai/vectors/base.py | truncate |
| checkpoint 身份 / 落盘文件 | src/python/txtai/vectors/base.py | vectorsid / spool |
| 读写盘 | src/python/txtai/vectors/base.py | loadembeddings / saveembeddings |
| 断点续跑 | src/python/txtai/vectors/recovery.py | Recovery |
| 稠密后端选择 | src/python/txtai/vectors/dense/factory.py | VectorsFactory.create / method |
| SBERT 稠密 | src/python/txtai/vectors/dense/sbert.py | STVectors |
| 本地 Transformer 稠密 | src/python/txtai/vectors/dense/huggingface.py | HFVectors |
| 远程 API 稠密 | src/python/txtai/vectors/dense/litellm.py | LiteLLM |
| llama.cpp / GGUF | src/python/txtai/vectors/dense/llama.py | LlamaCpp |
| LiteRT / tflite | src/python/txtai/vectors/dense/litert.py | LiteRT |
| Model2Vec 静态 | src/python/txtai/vectors/dense/m2v.py | Model2Vec |
| 词向量 + 权重加权平均 | src/python/txtai/vectors/dense/words.py | WordVectors |
| 自定义/外部函数 | src/python/txtai/vectors/dense/external.py | External |
| LSA 降噪(词向量呼应) | src/python/txtai/embeddings/index/reducer.py | Reducer |
| 稀疏基类 | src/python/txtai/vectors/sparse/base.py | SparseVectors |
| 稀疏 SBERT | src/python/txtai/vectors/sparse/sbert.py | SparseSTVectors |
| 稀疏后端选择 | src/python/txtai/vectors/sparse/factory.py | SparseVectorsFactory.create |
| 上游触发点(dtype 决定) | src/python/txtai/embeddings/index/transform.py | vectors(dtype = uint8 if qbits) |