数据截至 (上游 commit 081bc084a5bc)
嵌入层:一套接口收编 11 种向量库
30 秒导读: 上一章(02)把文档切成了一颗颗 block 存进文本库。这一章讲 LLMware 怎么把这些 block 嵌入成向量、塞进你选的任意向量数据库(Milvus / FAISS / Pinecone / …),并且始终能凭一个
block_id把命中的向量倒查回原始文本。核心只有一个类:EmbeddingHandler。
本章聚焦 RAG 的「语义索引」这一环:如何把文本变成向量、如何统一管理十来种向量后端。不讲查询编排(那是 04 检索引擎)——这里只把 search_index 的返回约定交代清楚,作为 04 的输入。
1. 这是什么(零基础也能懂)
-
一句话定义:
EmbeddingHandler是一个向量后端的统一遥控器——你告诉它"用哪个模型、存到哪个向量库",它就把库里的文本块逐批变成向量、写进去,查询时再帮你从向量库找回最相近的文本块。 -
它解决什么问题: 向量数据库有一大堆(Milvus、FAISS、Pinecone、Redis、Qdrant、PGVector、Chroma…),每家 SDK 的建表、插入、检索 API 都长得不一样。如果每换一个库就要重写一遍嵌入逻辑,RAG 应用会被后端绑死。LLMware 把这层差异焊死在 10 个适配器类里,对上只暴露三个动作:建嵌入、搜、删。
-
给谁用: 想搭 RAG 但不想被某个向量库锁死的工程师。今天用本地 FAISS 做原型,明天换 Pinecone 上生产,业务代码一行不用改——只改一个
vector_db="..."字符串。 -
用起来什么样: 用户几乎从不直接碰
EmbeddingHandler,而是调Library.install_new_embedding(见 01):# 示意,非源码:一行给整个库装上语义索引library.install_new_embedding(embedding_model_name="mini-lm-sbert", # 用哪个嵌入模型vector_db="milvus", # 存到哪个向量后端batch_size=500,)# 之后就能做语义检索了(见第 04 章) -
一句话直觉: 把它想成快递分拣中心。包裹(block)都长一样,分拣中心(
EmbeddingHandler)按你写的地址(vector_db)把它送进对应的仓库(Milvus/FAISS…);每个包裹贴着一张回执单号(block_id),将来凭单号就能从仓库把原件调回来。
2. 顶层全景(它大概怎么转)
2.1 三层结构
嵌入层就三层:一个门面、一堆共用工具、十个适配器。
Library.install_new_embedding() ← 业务侧调用(library.py:783)
│ (vector_db="milvus", model=...)
▼
┌─────────────────────────────┐
│ EmbeddingHandler │ 门面 / 路由器 (embeddings.py:78)
│ create_new_embedding :104 │
│ search_index :129 │
│ delete_index :143 │
└─────────────┬───────────────┘
│ _load_embedding_db :155
│ 查 VectorDBRegistry,动态 import 对应类
┌──────────────┼───────────────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ …十个同构适配器… ┌───────────┐
│EmbedMilvus│ │EmbedFAISS │ │EmbedChroma│
│ :346 │ │ :656 │ │ :2544 │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ 每个适配器都用同一套 _EmbeddingUtils
└──────────────┴──────────────┬─ ────────────────┘
▼
┌──────────────────────────┐
│ _EmbeddingUtils │ 共用逻辑 (:198)
│ 取块游标 get_blocks_cursor│
│ 倒查文本 lookup_text_index│
│ 汇总 generate_..summary│
└────────────┬─────────────┘
▼
文本集合库(Mongo/SQLite/Postgres,见 01)
怎么读这张图: 从上往下是一次"建嵌入"的调用;门面只做路由,真正干活的是某个适配器,而所有适配器把重复逻辑(取哪些块、怎么倒查文本、怎么汇总)都甩给中间那层 _EmbeddingUtils。
2.2 部件一句话职责
| 部件 | 干什么 | 位置 |
|---|---|---|
EmbeddingHandler | 门面:接收 vector_db 名,路由到对应适配器 | embeddings.py:78 |
_load_embedding_db | 查注册表、动态 import 并实例化适配器 | embeddings.py:155 |
VectorDBRegistry | 名字 → {module, class} 的路由表 | configs.py:474 |
_EmbeddingUtils | 所有适配器共用:命名、取块、倒查文本、汇总 | embeddings.py:198 |
Embedding{Milvus…Chroma} | 10 个适配器,把统一契约翻译成各家 SDK | embeddings.py:346 起 |
| 文本集合库 | 存原始 block 文本 + 嵌入标记 | 见 01 |
2.3 一句话主线
一次 install_new_embedding:业务侧传入模型 + 向量库名 → 门面据名加载对应适配器 → 适配器分批从文本库拉出 block、调模型算向量、连同 block_id 写进向量库,同时在文本库给每个 block 打上"已嵌入"标记 → 返回一份汇总字典(建了多少条、维度、时间戳)。查询时反过来:向量库返回命中的 block_id → _EmbeddingUtils 凭 id 从文本库取回整块文本 → 打包成 (block, distance) 交给上层。
3. 核心原理
3.1 路由:一个字符串决定用哪个后端
要解决的小问题: 上层只想说一句 vector_db="milvus",不想知道 Milvus 的类叫什么、在哪个模块。
思路: 用一张注册表把名字映射到"模块 + 类名",门面拿到名字后动态 import——所以没装 pymilvus 的用户也能正常 import embeddings 模块,只有真正用到 Milvus 时才去加载它的驱动。
注册表就是一个字典(configs.py:478,VectorDBRegistry.vector_db_list):
# 真实源码 configs.py:478 VectorDBRegistry.vector_db_list
vector_db_list = {"milvus": {"module": "llmware.embeddings", "class": "EmbeddingMilvus"},
"chromadb":{"module": "llmware.embeddings", "class": "EmbeddingChromaDB"},
...
"postgres":{"module": "llmware.embeddings", "class": "EmbeddingPGVector"},
"pg_vector":{"module": "llmware.embeddings", "class": "EmbeddingPGVector"},
...}
这里有个诚实的小账:表里有 11 个名字,但 postgres 和 pg_vector 指向同一个 EmbeddingPGVector 类——所以是 10 个适配器类、11 个可选后端名。"收编 11 种向量库"说的是这 11 个可选项。
门面的路由发生在 _load_embedding_db(embeddings.py:155):它查表拿到 module/class,importlib.import_module 后 getattr 取出类,直接实例化返回。找不到就抛 LLMWareException。三个公开方法(create_new_embedding:104、search_index:129、delete_index:143)全靠它拿到具体适配器,自己不含任何后端逻辑。
一个巧妙细节 —— query_vector 归一化(search_index:129,行 137-138):Transformer 出来的向量有时是 [[...]](多一层),有时是 [...]。门面在分发前统一剥成一维,让每个适配器不必各自处理这个坑。
3.2 共用逻辑:适配器为什么都这么"薄"
要解决的小问题: 10 个适配器如果各写各的"取哪些块、怎么命名、怎么倒查",就会有 10 份重复且易出 bug 的代码。
思路: 把与后端无关的公共动作全抽进 _EmbeddingUtils(embeddings.py:198)。每个适配器在 __init__ 里 new 一个 self.utils,把脏活外包出去。
_EmbeddingUtils 的公共动作:
| 方法 | 干什么 | 位置 |
|---|---|---|
create_safe_collection_name | 拼 账号_库名_模型 的安全集合名 | :241 |
create_db_specific_key | 生成 embedding_<db>_<model> 这个嵌入标记键 | :264 |
get_blocks_cursor | 从文本库取"还没嵌入的块"的游标 + 数量 | :274 |
update_text_index | 给每个 block 写入"已嵌入 + 序号"标记 | :304 |
lookup_text_index | 凭 _id 从文本库取回整块(倒查主力) | :317 |
lookup_embedding_flag | 凭嵌入标记值取回块(FAISS 专用倒查) | :326 |
generate_embedding_summary | 汇总"建了几条/共几块/维度/时间戳" | :287 |
unset_text_index | 删嵌入时清掉块上的标记 | :336 |
关键在 get_blocks_cursor(:274):它调 CollectionRetrieval.embedding_job_cursor(collection_key, ...),只捞尚未打上该 collection_key 标记的块。这就是增量嵌入的实现——重复调 install_new_embedding 只会嵌入新增的块,不会重算旧块。
3.3 block_id ↔ vector 的双向映射(全章的命门)
要解决的小问题: 向量库里只有一堆浮点数组。命中一个向量后,怎么知道它对应哪一段原文?
思路: 嵌入时,把每个 block 的 _id 当作载荷和向量一起写进向量库;检索时向量库连载荷一起还回来,拿这个 id 去文本库 lookup_text_index 取回整块。向量库只管"哪个 id 最像",文本永远住在文本库里。
写入侧(以 Milvus 为例,create_new_embedding:490,行 522-536):每条记录带三样——block_mongo_id(即 str(block["_id"]))、block_doc_id、embedding_vector。Redis 更直白(:1661),载荷里同时塞 block_mongo_id / block_doc_id / block_id / text。
读取侧(Milvus search_index:562,行 613-615):从命中里取出 block_mongo_id,交给 self.utils.lookup_text_index(_id) 换回原始 block。
用一张图看 这条回路:
嵌入时 检索时
block["_id"] ──┐ 向量库命中 ──→ block_mongo_id
▼ │
向量库记录: {block_mongo_id, vector} ──────────────────┘
▼
lookup_text_index(_id) ──→ 原始 block
(CollectionRetrieval.lookup "_id")
FAISS 是唯一的例外,值得单讲。faiss.IndexFlatL2 只按插入顺序给向量编号(0,1,2…),存不下任意字符串 id。于是 FAISS 走一条"反向"路子:
- 嵌入时(
:791),用update_text_index把当前 FAISS 位置序号(self.index.ntotal,行 767)当作嵌入标记写回文本库每个 block 上。 - 检索时(
search_index:811,行 828),FAISS 返回的是位置序号,于是改用lookup_embedding_flag(collection_key, index_int)—— 拿序号当键去文本库倒查。注释(行 825-826)明说:"FAISS is unique in that it requires a 'reverse lookup'"。
所以 _EmbeddingUtils 才需要两个倒查函数:lookup_text_index(按 _id,九家用)和 lookup_embedding_flag(按序号,仅 FAISS)。
4. 十个适配器的统一对比
每个适配器都实现同一组方法(create_new_embedding / search_index / delete_index),差异只在"用哪家 SDK、载荷字段叫什么、相似度是距离还是分数"。下面不逐行抄代码,只做契约对比。
4.1 类与关键行号
| 适配器类 | 建嵌入 | 检索 | 后端类型 |
|---|---|---|---|
EmbeddingMilvus（:346） | :490 | :562 | 独立/嵌入式(lite) |
EmbeddingFAISS（:656） | :733 | :811 | 本地文件索引 |
EmbeddingLanceDB（:850） | :959 | :1019 | 嵌入式文件 |
EmbeddingPinecone（:1049） | :1154 | :1221 | 托管云 |
EmbeddingMongoAtlas（:1246） | :1360 | :1471 | 托管云(Atlas) |
EmbeddingRedis（:1515） | :1626 | :1705 | 服务端 |
EmbeddingQdrant（:1747） | :1843 | :1914 | 服务端/嵌入式 |
EmbeddingPGVector（:1942） | :2099 | :2239 | Postgres 扩展 |
EmbeddingNeo4j（:2300） | :2427 | :2502 | 图库 |
EmbeddingChromaDB（:2544） | :2650 | :2708 | 嵌入式/服务端 |
4.2 create_new_embedding 的统一契约
签名一致: create_new_embedding(self, doc_ids=None, batch_size=...),返回 _EmbeddingUtils.generate_embedding_summary(...) 出来的汇总字典。所有适配器的骨架是同一套(以 Milvus :490 / FAISS :733 为范本):
1. self.utils.get_blocks_cursor() → 拿"未嵌入块"游标 + 总数
2. Status(...).new_embedding_status() → 起进度条
3. while 未取完:
攒一批 block_ids + text_search
vectors = self.model.embedding(sentences) ← 调嵌入模型
<各家 SDK 的 insert/upsert,把 block_id 当载荷>
self.utils.update_text_index(block_ids, ...) ← 回写"已嵌入"标记
4. self.utils.generate_embedding_summary(...) → 返回汇总
差异只在第 3 步的写入:
| 适配器 | 默认 batch | 写入方式(要点) |
|---|---|---|
| Milvus | 500 | collection.insert([ids, doc_ids, vectors]);lite 版逐行 dict |
| FAISS | 100 | index.add(np.array(vectors)),id 靠位置序号回写文本库 |
| Pinecone | 100 | 分块 upsert,vector 带 metadata 载荷 |
| Redis | 500 | pipe.hset 每条哈希含 vector bytes + 4 个 id 字段 |
| 其余 | 500 | 各家 upsert/add,载荷含 block_mongo_id |
共性: 向量 永远由 self.model.embedding(sentences) 现算;文本永不进向量库(只进载荷的 id);增量性由 get_blocks_cursor + update_text_index 这对操作保证。
4.3 search_index 的统一契约(04 章的输入)
这是本章要交给 04 的关键约定。 每个适配器的 search_index(query_embedding_vector, sample_count=10) 都返回同一种形状:
# 所有适配器的 search_index 返回值
block_list = [ (block, distance), (block, distance), ... ] # 长度 ≤ sample_count
# block : 从文本库倒查回来的完整 block 字典(含 text_search、doc_ID…)
# distance : 第二个元素,相似度标量(越小越近 / 或越大越像,见下方警告)
统一流程(对照各家 block_list.append 行):向量库检索 → 取出每条命中的 block_id → self.utils.lookup_text_index(id) 换回 block → block_list.append((block, 分数))。
⚠ 一个必须交代的语义坑 —— 第二个元素不全是"距离"。 元组第二位的含义随后端而变:有的是 L2 距离(越小越近),有的是相似度分数(越大越像)。04 章在排序/取阈值时必须知道这点。
| 适配器 | 第二元素来源 | 语义(越小/越大更相关) |
|---|---|---|
| Milvus | hit.distance (:624) | L2 距离,越小越近 |
| FAISS | distance_list[0][i] (:833) | L2 距离,越小越近 |
| PGVector | distance (:2267) | 距离,越小越近 |
| Neo4j | result["score"] (:2517) | 相似度分数(queryNodes 的 score),越大越像 |
| LanceDB | score (:1032) | 距离/分数(按建索引度量) |
| MongoAtlas | 1 - score (:1501) | 已转成距离,越小越近 |
| Redis | float(res["score"]) (:1732) | KNN 分数 |
| Qdrant | res.score (:1927) | 相似度分数,越大越像 |
| Pinecone | match["score"] (:1232) | 相似度分数,越大越像 |
| ChromaDB | results['distances'][0][idx] (:2722) | 距离,越小越近 |
Neo4j 的分数来自 db.index.vector.queryNodes(...) YIELD node, score(search_index:2502,append 在 :2517),是未归一的相似度分数,越大越像,和 Milvus/FAISS 的 L2 距离方向恰好相反。MongoAtlas 则特意做了 distance = 1 - score(:1501,注释"Atlas returns a score from 0 to 1.0"),想把语义拉回"距离"这一侧,但 Neo4j / Qdrant / Pinecone / Redis 这些"分数型"后端并未统一。这就是为什么框架把这一位统称 (block, distance) 却在不同后端语义不齐——04 章消费时要留意。
4.4 delete_index 的共性
每个 delete_index 都做两件事:删掉向量库里的集合/索引,再调 self.utils.unset_text_index()(:336)清掉文本库里 block 上的嵌入标记。注意:只删向量,不删原文——文本集合库里的 block 原封不动(门面 delete_index:143 的 docstring 明说 "does not delete the underlying text collection")。这样同一个库可以挂多个不同模型/后端的嵌入,互不干扰(EmbeddingHandler 文档串,:84-85)。
5. 联动:调用侧从哪进来
业务几乎总是从 Library.install_new_embedding(library.py:783)进入,而不是直接 new EmbeddingHandler。那个方法负责前置装配:
- 按
embedding_model_name从ModelCatalog把嵌入模型加载好(HF / SentenceTransformer / 目录内置,行 833-852)。 - 校验
vector_db在支持列表内(行 863-865),没传就用配置默认。 - 把加载好的模型交给门面:
EmbeddingHandler(self).create_new_embedding(vector_db, my_model, batch_size=batch_size)(library.py:871)。
也就是说:Library 负责"选模型",EmbeddingHandler 负责"选后端并落地",职 责干净分开。门面拿到的是一个已加载的 model 对象,适配器内部只管调 model.embedding(sentences),不关心模型怎么来的。
6. 巧妙之处(值得带走的设计)
-
延迟导入驱动:模块顶部把每个后端驱动都设成
None+GLOBAL_*_IMPORT=False(embeddings.py:38-71),只有实例化对应适配器时才importlib.import_module。好处:装了 llmware 不必装齐 10 个向量库的 SDK,用哪个装哪个。 -
注册表驱动的路由:加后端只需往
VectorDBRegistry(configs.py:474)加一行,门面代码零改动。VectorDBRegistry.add_vector_db(configs.py:496)甚至允许运行时注册第三方后端。 -
公共逻辑单点化:命名、取块、倒查、汇总全在
_EmbeddingUtils,让 10 个适配器薄到"只剩 SDK 翻译"。改倒查策略只改一处。 -
增量嵌入天然成立:
get_blocks_cursor只捞未打标记的块 +update_text_index嵌完即打标,使"重复安装嵌入"变成幂等的"只补新块"。 -
FAISS 反向查找:面对"存不下任意 id"的索引,用文本库里的嵌入标记序号搭了一条桥(
:791/:828),让它也能塞进统一的(block, distance)契约里。
7. 边界与局限(诚 实说)
-
search_index第二元素语义不统一(见 4.3):距离型 vs 分数型混在一起,只有 MongoAtlas 做了归一。跨后端比较绝对分数没有意义。 -
文本与向量分居两库:倒查每命中一条就查一次文本库(
lookup_text_index),海量结果时是 N 次单点查询,没有批量倒查。 -
FAISS 位置序号的脆弱性:FAISS 的 id 是插入顺序位置,依赖文本库标记与索引文件严格同步;若索引文件被外部重建/顺序变动,倒查会错位(源码未见对此的一致性校验)(inferred)。
-
门面不校验维度一致性:换嵌入模型若维度不同,需要新的 collection;是否冲突由各后端 SDK 自行报错,门面层不预检(inferred)。
8. 横向对比(同章导航)
- 上游 block 数据模型怎么来的 → 02 解析与分块
- 文本集合库(倒查落点)与双存储底座 → 01 知识库容器
search_index返回的(block, distance)如何被组织成一次语义查询 → 04 检索引擎- 检索结果如何变成带源回答 → 05 RAG 生成与证据
9. 代码地图(导航索引)
| 主题 | 文件路径 | 符号名 |
|---|---|---|
| 门面 / 路由 | llmware/embeddings.py:78 | EmbeddingHandler |
| 建嵌入分发 | llmware/embeddings.py:104 | EmbeddingHandler.create_new_embedding |
| 检索分发 + 向量归一化 | llmware/embeddings.py:129 | EmbeddingHandler.search_index |
| 删嵌入(不删原文) | llmware/embeddings.py:143 | EmbeddingHandler.delete_index |
| 动态加载适配器 | llmware/embeddings.py:155 | EmbeddingHandler._load_embedding_db |
| 索引名生成 | llmware/embeddings.py:179 | EmbeddingHandler.generate_index_name |
| 共用工具 | llmware/embeddings.py:198 | _EmbeddingUtils |
| 取未嵌入块游标(增量) | llmware/embeddings.py:274 | _EmbeddingUtils.get_blocks_cursor |
| 回写已嵌入标记 | llmware/embeddings.py:304 | _EmbeddingUtils.update_text_index |
| 倒查文本(按 _id) | llmware/embeddings.py:317 | _EmbeddingUtils.lookup_text_index |
| 倒查文本(FAISS 序号) | llmware/embeddings.py:326 | _EmbeddingUtils.lookup_embedding_flag |
| 嵌入汇总字典 | llmware/embeddings.py:287 | _EmbeddingUtils.generate_embedding_summary |
| Milvus 适配器 | llmware/embeddings.py:346 | EmbeddingMilvus |
| FAISS 适配器(反向查找) | llmware/embeddings.py:656 | EmbeddingFAISS |
| LanceDB 适配器 | llmware/embeddings.py:850 | EmbeddingLanceDB |
| Pinecone 适配器 | llmware/embeddings.py:1049 | EmbeddingPinecone |
| MongoAtlas 适配器(1-score) | llmware/embeddings.py:1246 | EmbeddingMongoAtlas |
| Redis 适配器 | llmware/embeddings.py:1515 | EmbeddingRedis |
| Qdrant 适配器 | llmware/embeddings.py:1747 | EmbeddingQdrant |
| PGVector 适配器 | llmware/embeddings.py:1942 | EmbeddingPGVector |
| Neo4j 适配器(score,越大越像) | llmware/embeddings.py:2300 | EmbeddingNeo4j |
| ChromaDB 适配器 | llmware/embeddings.py:2544 | EmbeddingChromaDB |
| 向量库路由表 | llmware/configs.py:474 | VectorDBRegistry |
| 运行时注册第三方后端 | llmware/configs.py:496 | VectorDBRegistry.add_vector_db |
| 调用侧入口 | llmware/library.py:783 | Library.install_new_embedding |