Elasticsearch / OpenSearch 向量检索手册

适用版本：Elasticsearch 9.5.6（同期维护 9.4.9 / 8.19.24）；OpenSearch 3.9.0（2.x 维护分支 2.19.7），核实于 2026-11 许可与形态：ES = Elastic License 2.0（默认）/ 源码可选 SSPLv1、AGPLv3，客户端 Apache-2.0；OpenSearch = Apache-2.0（官方 LICENSE 正文未直接核验）；均为已有搜索集群上的向量字段 / 插件能力，分布式 一句话定位：在已有 ES / OpenSearch 索引里加一个向量字段，用同一套查询 DSL 同时做全文检索与 kNN 近邻，不新增一套数据库。 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构（按子产品）

Elasticsearch：向量是 dense_vector 字段类型，与倒排索引同处 Lucene 段内；knn query / retriever 在同一查询 DSL 内与全文检索组合，无独立进程、端口或存储，向量索引由 Lucene 段管理。index_options.type 决定 HNSW / 量化 / flat 等索引形态。

OpenSearch：向量能力由 k-NN 插件提供，索引级开关 settings.index.knn: true，字段类型 knn_vector；底层引擎可选 lucene / faiss（HNSW + IVF + PQ）/ nmslib（已弃用），IVF 需 Train API 训练模型。同样复用现有集群的分片、副本与查询 DSL。

1.2 横向对照表：定位差异（第 1 章）

1.3 适合 / 不适合（按子产品）

ES 适合：已有 ES 集群、需 BM25 + 稠密混合检索且要 RRF；已有完善的分片 / 副本 / 快照体系；数据量在搜索集群常规量级；需要 retriever.rrf、ES|QL 等查询语言能力。 ES 不适合：向量规模远超倒排数据、QPS 极高；需要 GPU / 专用分布式向量引擎；许可不接受 Elastic License 2.0 约束。

OpenSearch 适合：已在 OpenSearch / 兼容分支上、希望 Apache-2.0 生态；需要 faiss 的 IVF/PQ 或磁盘模式；维度可到 16000。 OpenSearch 不适合：无法接受 index.knn: true 建后不可改（需 reindex）；依赖已弃用的 nmslib；需要开箱即用的 pre-filter（其 ANN filter 是检索后过滤）。

1.4 规模、链路位置与「何时该换」

链路位置：离线「文档 → Embedding → 写入文档的一个向量字段（与正文、标量字段同文档）」；在线「query → Embedding → knn query（可叠加全文与 filter）→ 取回 _source → 重排 → LLM / 展示」。向量检索只是召回层的一个子句，最大价值是全文与向量在同一 DSL 内融合。

该换专用向量库的信号：向量规模 / QPS 远超搜索集群承载；低命中率过滤导致召回持续不达标；需要十亿级分布式向量优化或 GPU；向量检索要独立扩容而不想拖累搜索集群；需要内核级多向量 / 复杂重排。

2. 版本、许可与官方入口

2.1 版本状态表

2.2 许可与官方入口（按子产品）

• ES：Elastic License 2.0（默认），源码可选 SSPLv1 / AGPLv3；客户端为 Apache-2.0。Serverless 与部分量化默认策略受许可档位影响（见 6.7）。许可变更风险以 https://www.elastic.co/pricing/faq/licensing 为准。
• OpenSearch：Apache-2.0（官方 LICENSE 正文未直接核验，以官方仓库为准）。

2.3 版本识别命令

# 两者通用做法：查集群信息响应里的 version.number（端点与端口以实际部署 / 官方文档为准）
$ curl -s "http://<host>:<port>/" | grep -o '"number"[^,]*'

2.4 近两年重要变更与弃用提醒

ES：9.1 起 float 向量按维度自动量化（<384 维 int8_hnsw、≥384 维 bbq_hnsw）；9.1+ RRF 支持多字段 query；9.2+ 子检索器 weight；9.2 ES|QL 引入 KNN() / FORK / FUSE（tech preview，GA 状态未核实）；Serverless / 9.4+ 许可允许时默认 bbq_disk。

OpenSearch：nmslib 引擎已弃用，应选 lucene / faiss；3.9 提供 knn_vector 动态映射，需开 knn.dynamic_mapping.enabled（默认关闭，只建字段不启用 ANN）。

版本差异：改 dense_vector 的 index_options.type 不会重索引已有向量，已写入的段保持原索引形态；要让新策略作用于存量数据必须 reindex。 避坑：OpenSearch 的 settings.index.knn: true 在建索引后不可改，只能新建索引并 reindex 数据。

3. 安装与启动

3.1 说明与前置条件

本类产品通常已有集群，「安装」实为「在已有索引上启用向量能力」。官方资料未提供两者官方安装命令、镜像 tag 与端口，部署安装请以官方文档为准，勿臆测。

• ES：dense_vector 为内核字段类型，无需额外插件；需确认版本 ≥8.x 且 dense_vector 可用。
• OpenSearch：需 k-NN 插件可用；索引创建时就必须带 settings.index.knn: true，事后无法补。
• 通用前置：JDK / 堆内存 / 分片规划沿用现有搜索集群基线（通用运维见根目录手册）。

3.2 ES：创建带 dense_vector 的索引

ES_HOST="http://<host>:<port>"   # 替换为实际集群地址
curl -s -X PUT "$ES_HOST/knn-demo" -H 'Content-Type: application/json' -d '{
  "mappings": {
    "properties": {
      "content":  { "type": "text" },
      "category": { "type": "keyword" },
      "vec": {
        "type": "dense_vector",
        "dims": 3,
        "index": true,
        "similarity": "cosine",
        "index_options": { "type": "hnsw", "m": 16, "ef_construction": 100 }
      }
    }
  }
}'

示例用 3 维，实际常见 768 / 1024 / 1536；dims ≤4096。以上参数均取自官方 dense-vector 映射文档。

3.3 OpenSearch：创建带 knn_vector 的索引

OS_HOST="http://<host>:<port>"   # 替换为实际集群地址
curl -s -X PUT "$OS_HOST/knn-demo" -H 'Content-Type: application/json' -d '{
  "settings": { "index.knn": true },
  "mappings": {
    "properties": {
      "content":  { "type": "text" },
      "category": { "type": "keyword" },
      "vec": { "type": "knn_vector", "dimension": 3 }
    }
  }
}'

示例用 3 维；dimension 上限 16000。引擎（lucene / faiss，勿用已弃用 nmslib）、space_type、data_type、mode、compression_level 的具体映射结构官方资料未给出逐字写法，按官方文档配置。

3.4 目录与端口表

3.5 健康检查与连通性验证

判定「向量能力就绪」的可靠方式：写入一条带向量的文档，随后执行 knn 检索能返回该文档。ES 用 5.1 的 knn query；OpenSearch 的 knn 查询体官方资料未提供逐字参数，按官方文档构造后验证。仅能建索引、不能 knn 检索，说明 ANN 未真正启用（OpenSearch 尤其要检查 index.knn: true 与动态映射开关）。

3.6 生产最小配置建议

认证 / TLS / RBAC / 网络暴露面沿用搜索集群基线（通用运维见根目录手册）；堆内存与分片数需把向量索引纳入容量评估；索引级设置（尤其 OpenSearch 的 index.knn）建前定稿。

⚠️ 危险：对已有大索引直接改 dense_vector 映射参数或补 index.knn 不会作用于存量数据，误以为已生效会带来召回与容量双重事故。

4. 核心概念与数据模型

4.1 术语对照（按子产品）

4.2 横向对照表：字段 / 索引 / 过滤差异（第 4 章，重点）

避坑：这张表是本篇最容易被旧教程误导的地方——ES 与 OpenSearch 的字段名、索引开关、过滤语义都不通用，把 ES 的 dense_vector 写法照搬到 OpenSearch（或反过来）会直接失败。

4.3 数据模型、距离与方向

两者都是「index → 文档 → 字段（正文 text + 标量 keyword + 向量字段）」，向量与倒排字段同文档，无独立 collection / load 步骤。

• ES：similarity 默认 cosine；l2_norm 越小越相似，dot_product / cosine / max_inner_product 按分数越大越相似（查询侧以 _score 体现）。
• OpenSearch：space_type 决定距离语义，如 l2 / l1 / linf 越小越相似，cosinesimil / innerproduct 越大越相似，hamming / hammingbit 用于二值。

4.4 索引参数表（按子产品）

4.5 生命周期与一致性

写入文档后需经过索引 refresh 才可被检索（搜索集群通用行为）；向量索引随 Lucene 段构建与合并，无「load 集合」步骤。一致性沿用各自集群的刷新 / 副本模型（近实时，非强一致事务），与 pgvector 的事务型语义不同。

5. 快速上手：完整 CRUD 示例

示例统一用 3 维向量便于阅读；实际常见 768 / 1024 / 1536 维。以下 REST 路径为通用形态示意，端点与端口以实际部署 / 官方文档为准。

5.1 Elasticsearch：完整 REST / cURL CRUD

ES_HOST="http://<host>:<port>"          # 替换为实际集群地址
IDX="knn-demo"

# 1) 建索引（若 3.2 已建可跳过）
curl -s -X PUT "$ES_HOST/$IDX" -H 'Content-Type: application/json' -d '{
  "mappings": { "properties": {
    "content":  { "type": "text" },
    "category": { "type": "keyword" },
    "vec": { "type": "dense_vector", "dims": 3, "index": true,
             "similarity": "cosine",
             "index_options": { "type": "hnsw", "m": 16, "ef_construction": 100 } }
  } }
}'

# 2) 插入文档
curl -s -X POST "$ES_HOST/$IDX/_doc/1" -H 'Content-Type: application/json' \
  -d '{"content":"向量检索入门","category":"tech","vec":[1,2,3]}'
curl -s -X POST "$ES_HOST/$IDX/_doc/2" -H 'Content-Type: application/json' \
  -d '{"content":"关系型数据库运维","category":"tech","vec":[4,5,6]}'
curl -s -X POST "$ES_HOST/$IDX/_doc/3" -H 'Content-Type: application/json' \
  -d '{"content":"咖啡拉花教程","category":"life","vec":[7,1,2]}'
curl -s -X POST "$ES_HOST/$IDX/_refresh"

# 3) knn 相似度检索
curl -s -X POST "$ES_HOST/$IDX/_search" -H 'Content-Type: application/json' -d '{
  "knn": { "field": "vec", "query_vector": [3,1,2], "k": 3, "num_candidates": 100 },
  "_source": ["content", "category"]
}'

# 4) 带标量过滤的检索：pre-filter 必须放在 knn 对象的 filter 里
curl -s -X POST "$ES_HOST/$IDX/_search" -H 'Content-Type: application/json' -d '{
  "knn": { "field": "vec", "query_vector": [3,1,2], "k": 3,
           "num_candidates": 100,
           "filter": { "term": { "category": "tech" } } },
  "_source": ["content", "category"]
}'

# 5) 更新  6) 删除  7) 清理
curl -s -X POST "$ES_HOST/$IDX/_doc/1" -H 'Content-Type: application/json' \
  -d '{"content":"向量检索入门(修订)","category":"tech","vec":[1,2,4]}'
curl -s -X DELETE "$ES_HOST/$IDX/_doc/3"
curl -s -X DELETE "$ES_HOST/$IDX"

filter 内的 term 为 ES 标准查询子句（通用 DSL，具体写法以官方文档为准）；关键点不是子句写法，而是 filter 必须位于 knn 对象内部。

5.2 输出怎么读

5.3 OpenSearch：可运行的建索引与写入

OS_HOST="http://<host>:<port>"          # 替换为实际集群地址
IDX="knn-demo"

curl -s -X PUT "$OS_HOST/$IDX" -H 'Content-Type: application/json' -d '{
  "settings": { "index.knn": true },
  "mappings": { "properties": {
    "content":  { "type": "text" },
    "category": { "type": "keyword" },
    "vec": { "type": "knn_vector", "dimension": 3 }
  } }
}'
curl -s -X POST "$OS_HOST/$IDX/_doc/1" -H 'Content-Type: application/json' \
  -d '{"content":"向量检索入门","category":"tech","vec":[1,2,3]}'
curl -s -X POST "$OS_HOST/$IDX/_doc/2" -H 'Content-Type: application/json' \
  -d '{"content":"关系型数据库运维","category":"tech","vec":[4,5,6]}'
curl -s -X POST "$OS_HOST/$IDX/_doc/3" -H 'Content-Type: application/json' \
  -d '{"content":"咖啡拉花教程","category":"life","vec":[7,1,2]}'
curl -s -X DELETE "$OS_HOST/$IDX/_doc/3"      # 删除
curl -s -X DELETE "$OS_HOST/$IDX"              # 清理

避坑：OpenSearch 的 knn 查询体逐字参数名官方资料未核实，故此处不臆造查询 DSL；请按 https://docs.opensearch.org/3.6/search-plugins/knn/approximate-knn 构造 knn 查询后再做「写入一条 → knn 检索返回」的就绪验证。可以确认的行为是：ANN 索引的 filter 是检索后过滤（4.2 表），低命中率过滤会明显少结果。

5.4 旧教程会怎么写

避坑：ES 旧教程常把过滤写成 bool.filter / post_filter，并当成「pre-filter」。这是 post-filter：ANN 先取 TopK 再过滤，可能返回少于 k 条。正确写法是把 filter 放进 knn query 对象内部（5.1 第 4 步）。 避坑：OpenSearch 旧教程用 nmslib 引擎、或建索引时漏掉 index.knn: true 事后想补——前者已弃用（改 lucene / faiss），后者建后不可改，只能新建索引 + reindex。

6. 索引与检索进阶

6.1 索引参数调优（按子产品）

6.2 横向对照表：索引 / 量化 / 过滤 / 混合（第 6 章）

6.3 recall 与延迟取舍

num_candidates（ES）与候选 / 压缩档位（OpenSearch）是主要旋钮：候选越大召回越高、延迟与 CPU 越高。方法（经验）：用 flat / 精确检索跑 ground truth，再对同一批 query 算 recall@k，逐步加候选到达标。

6.4 标量过滤：pre-filter 还是 post-filter（重点）

避坑：「过滤结果变少」不要先怀疑数据没写进去，先看过滤子句放在哪一层。ES 一律用 knn query 的 filter；OpenSearch 需接受检索后过滤的语义，必要时改用引擎侧过滤能力或加大候选量（以官方文档为准）。

6.5 混合检索：ES retriever.rrf 参数与限制

retriever.rrf 用于把多个检索器（BM25 全文 + knn 稠密等）融合：

版本演进：9.1+ 支持多字段 query；9.2+ 子检索器支持 weight。限制：不支持 scroll、sort、rescore。

子检索器的逐字类型名官方资料未核实，故此处只给参数与限制、不给臆造的完整 JSON；retrievers 内具体写法以官方 RRF retriever 文档为准。

6.6 量化与压缩（重点）

ES 9.1+ 默认量化策略：Stack 9.1 起，float 向量 <384 维默认 int8_hnsw、≥384 维默认 bbq_hnsw；Serverless / 9.4+ 在许可允许时默认 bbq_disk。这意味着即使你没显式写 index_options.type，索引形态也已由维度决定。可用 element_type（float / bfloat16 / byte / bit）与 index_options.type（hnsw / int8_hnsw / int4_hnsw / bbq_hnsw / flat / int8_flat / int4_flat / bbq_flat / bbq_disk）显式覆盖。

避坑：改 index_options.type 不会重索引已有向量。已写入的 Lucene 段保持旧索引形态，只有新写入 / 新段才用新策略；要让存量向量生效必须 reindex。

OpenSearch：compression_level 1x～32x 配合 faiss PQ；data_type（binary / byte / float / half_float）与 mode（in_memory / on_disk）控制精度与内存。

6.7 容量估算（经验公式，非官方承诺）

向量原始体积 ≈ 4 × dim 字节/向量（float32）；dim=768、100 万条 ≈ 3.07 GB（未计副本与段开销）
含副本总量 ≈ 原始体积 × (1 + 副本数)
HNSW / 量化索引额外开销随 m、量化档位与段合并波动，须按集群实测
ES num_candidates 与 OpenSearch 候选量主要影响查询期 CPU / 堆内存，不影响存储

系数为经验区间，非官方承诺；用集群监控实测后做容量规划。

7. 生产部署与运维

7.1 高可用、备份与监控（按子产品）

• ES：向量索引随分片 / 副本复制；快照（snapshot）备份含向量段，恢复后无需单独重建索引；监控沿用集群指标，重点看查询延迟、num_candidates 相关 CPU、堆内存与段合并。
• OpenSearch：同样随分片 / 副本复制与快照备份；需额外监控 k-NN 插件的图 / 缓存内存、index.knn 是否生效、faiss IVF 模型是否已 Train。

7.2 升级、迁移与安全

• 升级：ES 跨 9.x 升级前核对默认量化策略变化（9.1+）；改 index_options.type 后要 reindex 存量。OpenSearch 升级时确认 nmslib 已弃用，迁移到 lucene / faiss；index.knn 开关只能在新建索引时决定。
• 容量与扩缩容：按 6.7 估算并预留副本与段合并空间；扩分片需重建索引（reindex），属计划内变更。
• 安全基线：认证、TLS、RBAC、网络暴露面沿用集群基线；向量字段同样受字段级 / 文档级安全控制（通用运维见根目录手册）。
• 日志：集群日志目录，k-NN 插件无独立日志文件。

⚠️ 危险：对生产索引执行 reindex / 删除重建会改变索引名与别名指向，务必先切别名、保留旧索引回滚能力。

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：ES 过滤后结果变少。原因：bool.filter 是 post-filter。怎么做：pre-filter 必须用 knn query 的 filter。
2. 现象：ES 改了 index_options.type 却没效果。原因：不会重索引已有向量。怎么做：reindex 存量数据。
3. 现象：ES 没写 index_options.type，索引形态却不是预期。原因：9.1+ 按维度默认量化（<384 int8_hnsw、≥384 bbq_hnsw）。怎么做：显式写 index_options.type 并核对维度阈值。
4. 现象：ES knn 报 k > num_candidates。原因：k 必须 ≤ num_candidates（≤10000，默认 1.5×k）。怎么做：调大 num_candidates 或减小 k。
5. 现象：ES RRF 查询加 sort / scroll 报错。原因：retriever.rrf 不支持 scroll / sort / rescore。怎么做：改走普通查询或调整融合结构。
6. 现象：ES 9.2 ES|QL 的 KNN() / FORK / FUSE 当成 GA 写进方案。原因：tech preview，GA 版本未核实。怎么做：标注「以官方文档为准」，勿写成稳定能力。
7. 现象：OpenSearch 建索引时漏 index.knn: true，事后想补。原因：建后不可改。怎么做：新建索引 + reindex。
8. 现象：OpenSearch 用了 nmslib。原因：引擎已弃用。怎么做：选 lucene / faiss。
9. 现象：OpenSearch 过滤后结果明显变少。原因：ANN filter 是检索后过滤。怎么做：加大候选量并接受语义差异，勿按 pre-filter 预期验收。
10. 现象：OpenSearch 动态映射建了 knn_vector 字段却不做 ANN。原因：knn.dynamic_mapping.enabled 默认关闭，只建字段不启用 ANN。怎么做：显式开启并核对索引设置。
11. 现象：把 ES 的 dense_vector 写法照搬到 OpenSearch（或反之）。原因：字段名、维度参数、索引开关、过滤语义都不通用。怎么做：按 4.2 对照表逐项区分。
12. 现象：reindex / 删索引重建后应用查不到数据。原因：别名未切换、索引名变化。怎么做：⚠️ 先切别名并保留旧索引回滚，这是可能导致线上事故的操作。

10. 速查表（横向对照）

11. 参考与延伸

官方链接清单

与同册其他产品的关系：已有 ES / OpenSearch → 本篇；已有 PG → pgvector.md；已有 Redis → Redis-Vector-Search.md；已有 ClickHouse → ClickHouse.md；已有国产关系库 → 国产数据库向量能力.md；需分布式专用向量库 → 01-专用向量数据库 分册。

进阶阅读：ES dense_vector 的 index_options 与量化档位、RRF retriever 限制；OpenSearch k-NN 插件的引擎差异、faiss IVF Train API、3.9 动态映射。

本篇「未核实 / 以官方为准」事项：

1. ES 9.2 ES|QL KNN() / FORK / FUSE 为 tech preview，GA 版本未核实，正文不得写成稳定能力。
2. OpenSearch Apache-2.0 官方 LICENSE 正文未直接核验，以官方仓库为准。
3. OpenSearch knn 查询 DSL 的逐字参数名未核实，故 5.3 / 6.5 未给臆造查询体，按官方文档构造。
4. ES RRF 子检索器的逐字类型名未核实；retrievers 内具体写法以官方文档为准。
5. ES 9.1 / 9.2 / 9.4+ 的具体发布日期未核实（官方资料仅给 9.5.6 日期）。
6. 两者官网 / 镜像仓库 / SDK / 控制台 URL、安装命令、镜像 tag、HTTP 端口均官方资料未提供，勿臆测。
7. 4.3 中相似度 / 距离方向的逐值口径、6.7 容量公式、各告警阈值均为经验性表述，非官方承诺，须实测。
8. ES 9.4+ / Serverless 默认 bbq_disk 的「许可允许」具体条件未核实，以官方许可文档为准。