向量字段与 KNN-检索分析服务 Elasticsearch版(ES)-阿里云帮助中心

以下说明 DiskBBQ 的字段配置和 KNN 查询参数。普通索引和 Collection 共用 bbq_disk 字段配置；该类型的向量字段在 Collection 中按 Slice 范围检索时采用 Sliced DiskBBQ，无需新增一套 Mapping 参数。首次调用可直接使用普通索引完整示例。

操作	普通索引	Collection
增加向量字段	`PUT /{index}/_mapping`	`PUT /{collection}/_mapping`
查询近邻	`POST /{index}/_search`	`POST /{collection}/_search?_slice={slice}`，或按向量簇模式自动选择范围。

文档和查询向量的维度必须与 dims 一致。以下 Mapping 示例以 Collection 为目标；目标为普通索引时，使用实际索引名。查询时通过 knn.field 引用这里配置的向量字段。

字段配置与查询参数

配置 Mapping

快速入门已经在创建 Collection 时配置了 DiskBBQ。对于尚未创建向量字段的其他 Collection，可以使用 Mapping API 增加字段：

PUT /{collection}/_mapping
{
  "properties": {
    "embedding": {
      "type": "dense_vector",
      "dims": 4,
      "index": true,
      "similarity": "cosine",
      "index_options": {
        "type": "bbq_disk"
      }
    }
  }
}

显式指定 "type": "bbq_disk" 时，服务端会补全以下 index_options 默认值。这些默认值与向量维度无关：

{
  "index_options": {
    "type": "bbq_disk",
    "cluster_size": 384,
    "flat_index_threshold": -1,
    "default_visit_percentage": 0.0,
    "rescore_vector": { "oversample": 3.0 },
    "bits": 1
  }
}

default_visit_percentage 是 Mapping 级默认值；未设置查询级 visit_percentage 时使用该值，查询级参数优先级更高。rescore_vector.oversample 可在查询中覆盖。cluster_size、flat_index_threshold 和 bits 由服务端维护，无需调整。

向量维度和相似度应与生成向量所使用的模型保持一致。存量向量字段如果需要切换索引类型，建议创建目标 Collection、配置新 Mapping，再使用 Reindex 迁移并重新评测。

执行 KNN 查询

以下请求在指定 Slice 中使用 visit_percentage 调整 DiskBBQ 的访问范围：

POST /knowledge-chunks/_search?_slice=tenant-a
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.80, 0.12, 0.05, 0.03],
    "k": 10,
    "visit_percentage": 10.0
  },
  "_source": ["document_id", "title", "content"]
}

参数	说明
`k`	全局选取的近邻数量；实际返回条数还受请求顶层 `size`（默认 `10`）限制。
`visit_percentage`	每个分片访问的向量比例，取值范围 0～100。值越大通常越有利于召回，也会增加计算和读取开销。查询显式设置的值覆盖 Mapping 默认值；最终生效值大于 `0` 时，`num_candidates` 不再决定访问比例。
`num_candidates`	最终生效的 `visit_percentage` 为 `0` 时，用于推导候选访问范围；查询显式设置的值优先于 Mapping 默认值，包括显式设置为 `0`。
`filter`	增加结构化过滤，减少不相关候选。
`rescore_vector`	使用原始向量对量化检索得到的候选重打分，可覆盖 Mapping 中的 `oversample` 默认值。

使用向量簇召回时，还需配置候选 Slice 的范围，见向量簇召回参考。

按需读取向量值

常规检索保持默认不返回向量，只通过 _source 选择业务需要的字段，如上例中的标题和内容。KNN 检索和重打分在服务端完成，无需把向量返回给应用。

仅在核对向量或确需导出向量值时，才显式取回所需字段。例如，读取一条文档的 embedding：

GET /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a&_source_exclude_vectors=false

使用 _source_exclude_vectors=false 显式取回向量；该参数会同时返回 _source 中的业务字段和向量。返回向量会增加数据读取、重建和网络传输开销，应仅在核对或导出向量时使用。

返回值取决于向量字段的存储精度。示例默认使用 float（float32）；写入的十进制值转换为 float32，以及 cosine 相似度下的归一化和还原，都可能产生浮点舍入。若字段使用 element_type: bfloat16，存储精度更低，误差比 float32 明显。DiskBBQ 取回向量时使用保留的向量值，不是从量化编码反推原值。需要保留模型原始输出用于逐位校验或精度评估时，应另行保存原始向量。

普通索引完整示例

完成创建和连接 Agent 引擎版实例后，在 Kibana Dev Tools 中依次执行以下请求。示例使用普通索引 vector-demo 和手工构造的四维向量，只用于验证配置与查询链路。创建索引和写入、读取数据需要账号具备对应权限。

创建向量索引

PUT /vector-demo
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 2
  },
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "embedding": {
        "type": "dense_vector",
        "dims": 4,
        "similarity": "cosine",
        "index": true,
        "index_options": { "type": "bbq_disk" }
      }
    }
  }
}

使用一个尚不存在的索引名。真实业务中，向量维度和相似度应与模型输出一致；节点和副本配置见无状态架构与资源规划。

写入数据并确认查询可见

POST /vector-demo/_bulk
{"index":{"_id":"1"}}
{"title":"知识库搜索","embedding":[0.80,0.12,0.05,0.03]}
{"index":{"_id":"2"}}
{"title":"商品搜索","embedding":[0.10,0.75,0.10,0.05]}

普通索引的常规写入同样不应传 refresh，也不要在应用代码中调用 _refresh。确认 Bulk 响应中的 errors=false，然后等待约 5 秒，让后台自动刷新使数据可搜索；若结果尚未包含新文档，再等一个自动刷新周期后重试。按 ID 确认写入及同步等待的适用条件见 Refresh 与查询可见性。

查询相近向量

POST /vector-demo/_search
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.80, 0.12, 0.05, 0.03],
    "k": 2,
    "visit_percentage": 10.0
  },
  "_source": ["title"]
}

检查 timed_out=false、_shards.failed=0，并确认 hits.hits 中包含标题为“知识库搜索”和“商品搜索”的两条文档。该示例只验证请求链路，召回率和性能应使用真实业务向量、查询集及并发负载评估。

两层能力的收益、适用场景和取舍见DiskBBQ 与 Sliced DiskBBQ 向量检索。