向量数据库手册

一套按「产品」拆分的向量检索手册，16 篇，分 4 组。事实核实时间：2026-11。

与根目录的《XX 常用运维指令手册》互补：那边按系统/数据库讲「这台机器怎么管」，这套按向量检索链路讲「该选谁、怎么接进来、检索为什么不准、上线怎么运维」。每篇统一结构：定位与选型 → 版本与许可 → 安装 → 数据模型 → 完整 CRUD → 索引与检索进阶 → 生产运维 → 故障排障 → 避坑清单 → 速查表 → 参考。

重要：向量数据库是近三年变化最快的品类之一，SDK 方法名几乎每年都会换一轮。凡涉及版本、方法名、参数的命令，执行前请以对应产品官方文档复核；本册中标注「未核实 / 官方未明确」的事项，见文末证据标注约定。

怎么用

先分类：你需要的到底是不是「向量数据库」

选型第一步不是比性能，是先确定品类。四类东西都常被叫做「向量数据库」，但运维责任完全不同：

三条最常被忽略的判断：

1. 已有 PostgreSQL 且数据量在百万级以内，通常不需要新引入一套向量库 —— 直接 CREATE EXTENSION vector 的运维收益往往大于性能差异；见 pgvector.md。
2. Faiss 不是数据库。它不保存业务数据、不处理并发写入、不认识「用户权限」。拿它做 RAG 后端，意味着这些能力都得自己写；见 Faiss.md。
3. 托管服务没有「稳定版本号」，只有 API version 与控制台配额。升级节奏不由你控制，SDK 升级可能带来控制面 breaking change；见 Pinecone.md。

分类索引

01 专用向量数据库（6 篇）

02 融合型向量能力（5 篇）

03 向量索引库（2 篇）

04 云托管服务（3 篇）

核心概念速通

一条 RAG 检索链路，向量库只占中间一格

文档 → 切分 chunk → embedding 模型 → 向量 + 元数据
                                      ↓
                        【写入向量库：建集合 / 建索引】
                                      ↓
用户问题 → 同一个 embedding 模型 → 查询向量
                                      ↓
        【向量库：相似度检索 + 标量过滤 → top-k 候选】
                                      ↓
                     重排 / RRF 融合 → 拼 context → LLM

向量库不负责生成 embedding、不负责最终排序、不负责答案生成。检索效果差时，先怀疑切分策略与 embedding 模型，再调索引参数——这是排查顺序，反过来会浪费大量时间。

必须分清的八个词

HNSW 与 IVF 的取舍（经验性）

内存与容量估算（经验公式，务必用自己的数据压测）

原始向量      = 条数 × 维度 × 4 字节            # float32
半精度 halfvec= 条数 × 维度 × 2 字节
HNSW 图开销   ≈ 条数 × M × 2 × 4 字节 + 链接与元数据（经验量级，各实现差异大）
总内存        ≈ 原始向量 + 索引结构 + 副本数 × (以上) + 30% 以上增长余量

举例（经验估算，非官方承诺）：100 万条 × 768 维 float32 ≈ 2.9 GB 原始向量；再叠加 HNSW 图、payload 索引、操作系统页缓存与副本，规划时按原始向量的 2～4 倍起算是比较稳妥的起点。

pre-filter 与 post-filter：过滤后结果变少的根因

各库行为不一致，且同一库不同版本会变。已知要点：ES 的 knn query filter 是 pre-filter，而 bool.filter 是 post-filter；pgvector 的 ANN 索引默认扫描后过滤，需开 hnsw.iterative_scan；OpenSearch ANN 的 filter 官方文档明确为检索后过滤。具体见各分册第 6 章。

混合检索与 RRF

关键词检索（BM25）擅长专有名词、编号、精确匹配；向量检索擅长语义。生产 RAG 通常需要两者融合，常见做法是 RRF（Reciprocal Rank Fusion）——不比较两路分数绝对值，只按名次加权合并，避免不同量纲的分数难以归一：

RRF_score(d) = Σ  1 / (rank_constant + rank_i(d))       # rank_constant 常用 60

ES 的 retriever.rrf、Weaviate 的 near_text + BM25、Redis 8.4 的 FT.HYBRID、百度自研引擎的 RRF 都是这个思路的不同实现。

选型决策表

表格是缩小 PoC 候选用的，不是替代实测。务必用你自己的数据分布、过滤条件、并发量压测：三份第三方对比结论互相矛盾时，只信自己跑出来的 recall@10 与 P99。

横向对比总表

端口列中「沿用 XX」表示沿用宿主实例端口，未在向量能力文档中单独核实；「未核实 / 官方未明确」的条目请勿写进方案评审材料当作确定结论。

版本与 API 变动对照：最容易被旧教程坑的地方

这张表是本册最值得先读的部分。向量库教程的半衰期很短，搜到的老博客几乎必然踩中其中一条。

通用避坑十二条

1. 换 embedding 模型 = 全量重灌。维度、归一化方式、语义空间都变了，旧向量与新查询向量不可混查；换模型前先规划双写与灰度。
2. 建集合时就要定死维度和度量，多数产品不支持改；改了要新建集合再迁数据。
3. 归一化与度量要配套。cosine 与 dot 在向量已归一化时等价，未归一化时结果完全不同；写入前统一 L2 归一化是最省事的做法。
4. 高危：删除集合/索引没有回收站。向量库普遍不提供 recyclebin，drop_collection / DROP TABLE / 删除集群前必须先有可恢复备份；Zilliz Free 集群删除后明确不可从回收站恢复。
5. 高危：不要只备份向量不备份元数据与索引配置。恢复后维度、度量、过滤字段索引对不上，等于白备；Milvus 需同时覆盖 etcd 元数据与对象存储。
6. ANN 索引是异步构建的居多。写入返回成功 ≠ 立刻可检索；Chroma Cloud 的文档、Pinecone 的 index.documents.upsert 都有可见性等待，LanceDB 追加行不会自动进索引。
7. 过滤字段要单独建索引。多数专用库未建标量索引的字段不能过滤或退化成全扫；腾讯云 VectorDB 明确「未建 Filter 索引的字段不可过滤」。
8. 别用厂商 benchmark 做容量决策。用真实数据分布、真实过滤选择率、真实并发压测，记录 recall@10 与 P99；过滤条件越严，各库差异越大。
9. 量化与索引参数改动通常要重建索引。ES 改 index_options.type 不会重索引已有向量；pgvector 改 HNSW 建索引参数需 REINDEX；ClickHouse 加索引只对新写入生效、存量必须 MATERIALIZE INDEX。
10. 版本线要分清。Milvus 的服务端 / PyMilvus / Lite、LanceDB 的 SDK / Lance 格式、Weaviate 的最新 tag / 官方维护线，都是不同口径，别拿 SDK 版本推断服务端能力。
11. 托管服务先算 egress 与配额。Pinecone 自 2026-09-01 起计量读返回流量且额度用尽可能阻断读；Zilliz Free 集群 7 天无操作自动挂起、最多 5 个 collection；把回显字段（output_fields / include_fields）开成 * 会直接推高成本。
12. 合规先于性能。embedding 是原文派生数据，同样受数据出境与等保约束；政企场景优先评估国产关系库内置向量能力或国内云托管，再考虑自建 Milvus。

上线前检查清单

1. 写入与查询是否同一个 embedding 模型、同一维度、同一归一化策略。
2. 距离度量与 SDK 返回值的方向是否已实测确认（越大越相似还是越小越相似）。
3. 是否用真实过滤条件测过 pre/post-filter 下的返回条数与 recall@10。
4. 索引构建是否完成、写入可见性等待是否处理、load / refresh 是否到位。
5. 备份是否覆盖元数据 + 原始向量 + 索引配置，并做过一次真实恢复演练。
6. 认证、TLS、RBAC、网络暴露面是否关掉匿名访问（Weaviate 的 AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED 是本地示例配置，勿带上生产）。
7. 监控是否覆盖存活、写入失败率、查询 P99、内存/磁盘水位、索引构建状态；日志是否接了轮转。
8. 容量是否按「原始向量 + 索引 + 副本 + 30% 增长余量」估算并留了扩容路径。
9. SDK 版本是否 pin 死，升级前是否查过 release notes 的 breaking changes。
10. 托管服务：配额、计费告警、密钥轮换、数据驻留区域、退出与迁移方案是否确认。

证据标注约定

本册的事实来自 2026-11 对官方文档、GitHub Releases、PyPI 元数据的联网核查，核查记录留存在工作区 .workbuddy/向量数据库事实核查-2026-11.md。为了不把推测写成事实，正文使用以下标注：

各分册第 11 章都集中列出了本篇的「未核实」清单，落地前建议通读一遍。

与现有手册的关系

维护建议

• 与具体环境强相关的部分（内网端点、VPC、配额、密钥、计费口径、备份路径）建议替换成团队实际值，沉淀为内部 SOP。
• 向量库 SDK 更新频繁，建议每季度复核一次版本与 API 变动对照，并把踩过的新坑补进对应分册第 9 章。
• 涉及商用/闭源产品的功能与价格，仅以厂商官网为准；本册刻意不列举未经官方核实的定价数字。
• 后续可按需增补：Vald、Marqo、Typesense、Voyager、Astra DB、SingleStore、腾讯云/阿里云具体实例规格与压测报告、以及各库 recall/P99 的横向实测数据。