OSQ Disk 搜索

OSQ Disk 搜索 #

Easysearch 3.0 内置 OSQ Disk,通过量化向量和磁盘簇检索生成候选,再按配置使用保留的原精度向量重排。无需安装 k-NN 插件。

对外使用兼容 API 名称 index_options.type: "bbq_disk",不接受 osq_disk 别名。 OSQ Disk 与 OSQ HNSW 是不同的索引类型;Disk 不使用 HNSW 的 m 和 ef_construction 参数。 省略 index_options 时仍使用普通 HNSW,不会自动选择 Disk;普通 HNSW 检索字段仍需显式 dims 和 index: true。

创建索引与写入 #

集群所有节点应先升级到支持 OSQ Disk 的 Easysearch 3.0 版本,再创建 Disk 字段。

PUT /disk-vectors
{
  "mappings": {
    "properties": {
      "category": { "type": "keyword" },
      "vector": {
        "type": "dense_vector",
        "dims": 4,
        "element_type": "float",
        "similarity": "l2_norm",
        "index_options": {
          "type": "bbq_disk",
          "cluster_size": 384,
          "rescore_vector": { "oversample": 3 }
        }
      }
    }
  }
}
PUT /disk-vectors/_doc/1?refresh=true
{
  "category": "guide",
  "vector": [1.0, 2.0, 3.0, 4.0]
}

向量必须为单值数组,分量为有限数,长度与字段维度一致。bfloat16 字段按所声明的精度保留原向量;需要保留输入数组的原始 JSON 精度时,应在建索引时显式关闭向量的自动 source 排除。

映射参数 #

参数默认值约束与含义
dims可由首个有效向量确定1–4096;生产环境建议显式指定
element_typefloat支持 float、bfloat16;不支持 byte、bit
indextrue显式 bbq_disk 不接受 false
similaritycosine也支持 dot_product、l2_norm、max_inner_product,输入须满足对应相似度的约束
index_options.bits1当前仅支持 1-bit 索引量化
index_options.cluster_size38464–65536的整数,控制构建时的目标簇大小
index_options.flat_index_threshold-1-1 使用 3 × cluster_size;0 禁用小段平面检索;正整数指定阈值
index_options.default_visit_percentage0有限数,范围0–100;0 为自动确定访问目标
index_options.rescore_vector.oversample30 关闭原精度重排;非零范围为[1,10]
index_options.on_disk_rescorefalse原向量读取策略;两种取值均保留原向量,实际IO方式取决于平台与文件布局
index_options.preconditionfalse当前不支持 true
index_options.auto_calibratefalse当前不支持 true

维度、元素类型和相似度不能原地修改。Disk 与普通 HNSW、OSQ HNSW 之间不能通过更新同一字段的 mapping 转换;应创建目标索引并 Reindex。 更新允许调整的构建参数只影响后续生成的段,不会立即重写已有段。

查询与过滤 #

顶层 knn 用于协调全局 top-k:

POST /disk-vectors/_search
{
  "size": 10,
  "_source": false,
  "knn": {
    "field": "vector",
    "query_vector": [1.0, 2.0, 3.0, 4.0],
    "k": 10,
    "num_candidates": 100,
    "filter": { "term": { "category": "guide" } },
    "rescore_vector": { "oversample": 3 }
  }
}

也可以使用 DSL query.knn 与其它查询组合:

POST /disk-vectors/_search
{
  "size": 10,
  "query": {
    "knn": {
      "field": "vector",
      "query_vector": [1.0, 2.0, 3.0, 4.0],
      "k": 10,
      "num_candidates": 100,
      "filter": { "term": { "category": "guide" } }
    }
  }
}

k 必须为正整数,num_candidates 不小于 k 且不超过10000。建议显式设置两者,避免不同入口的默认值影响结果数量。 查询级 rescore_vector.oversample 覆盖 mapping 配置,接受 0 或不小于1的有限数;重排候选池受候选上限约束。 开启重排时会按需要扩大有效候选预算,以容纳重排池。

可在 knn 内指定 visit_percentage 覆盖字段的 default_visit_percentage,范围为0–100。 0 表示自动确定访问目标;正值控制每段的访问目标比例。它是近似检索的访问目标,不保证只读取某个固定比例的文档;过滤、候选补足等条件可能增加访问工作。

将希望参与候选选择的条件放在 knn.filter 中。post_filter 在候选选择后执行,可能使最终结果少于 k。 访问目标、候选数量和重排倍率都可能影响召回率和查询成本,应按业务数据选择。

两种查询入口也可用lookup替代显式 query_vector,引用已refresh的向量。以下是knn对象内的参数片段:

{
  "query_vector_builder": {
    "lookup": { "index": "disk-vectors", "id": "1", "path": "vector" }
  }
}

query_vector 与 query_vector_builder 必须且只能提供一个。lookup不是realtime GET;未刷新或不可搜索的文档不能当作有效查询向量。 similarity 阈值含义与字段相似度相关:cosine/dot_product为最小相似度,L2为最大距离,max_inner_product为最小内积。 完整度量与分数转换见 原生HNSW得分计算,量化候选分数与raw重排分数需分别理解。

Nested 与向量读取 #

Disk 支持 nested 向量检索和 inner_hits。外层结果按父文档去重;inner_hits 返回相应的子文档。 同时需要父、子响应恢复向量时,应在外层和 inner_hits 中都显式请求 _source: {"exclude_vectors": false}。

Nested 完整示例 #

下面创建4维 L2 nested 字段,与本页普通字段示例使用相同维度:

PUT /osq-disk-nested
{
  "mappings": {
    "properties": {
      "tenant": { "type": "keyword" },
      "children": {
        "type": "nested",
        "properties": {
          "tag": { "type": "keyword" },
          "vector": {
            "type": "dense_vector",
            "dims": 4,
            "similarity": "l2_norm",
            "index_options": { "type": "bbq_disk" }
          }
        }
      }
    }
  }
}
PUT /osq-disk-nested/_doc/article-1?refresh=true
{
  "tenant": "allowed",
  "children": [
    { "tag": "keep", "vector": [0.25, 0.0, 0.0, 0.0] },
    { "tag": "keep", "vector": [2.0, 0.0, 0.0, 0.0] },
    { "tag": "drop", "vector": [0.0, 0.0, 0.0, 0.0] },
    { "tag": "keep" }
  ]
}

顶层入口使用 knn.inner_hits:

POST /osq-disk-nested/_search
{
  "size": 2,
  "_source": { "exclude_vectors": false },
  "knn": {
    "field": "children.vector",
    "query_vector": [0.0, 0.0, 0.0, 0.0],
    "k": 2,
    "num_candidates": 10,
    "visit_percentage": 100,
    "rescore_vector": { "oversample": 3 },
    "filter": [
      { "term": { "tenant": "allowed" } },
      { "term": { "children.tag": "keep" } }
    ],
    "inner_hits": {
      "name": "selected",
      "size": 2,
      "sort": [{ "_score": "desc" }],
      "_source": { "exclude_vectors": false }
    }
  }
}

DSL 入口使用外层 nested.inner_hits,不放在 query.knn 中:

POST /osq-disk-nested/_search
{
  "size": 2,
  "_source": { "exclude_vectors": false },
  "query": {
    "nested": {
      "path": "children",
      "score_mode": "max",
      "query": {
        "knn": {
          "field": "children.vector",
          "query_vector": [0.0, 0.0, 0.0, 0.0],
          "k": 2,
          "num_candidates": 10,
          "visit_percentage": 100,
          "rescore_vector": { "oversample": 3 },
          "filter": [
            { "term": { "tenant": "allowed" } },
            { "term": { "children.tag": "keep" } }
          ]
        }
      },
      "inner_hits": {
        "name": "selected",
        "size": 2,
        "sort": [{ "_score": "desc" }],
        "_source": { "exclude_vectors": false }
      }
    }
  }
}

两个请求都只返回父文档 article-1,父分数约为 0.9411765;子命中总数为2,_nested.offset 为0、1,分数约为 0.9411765、0.2。 父文档按符合根/子过滤条件的最佳子向量得分排序;没有向量的子文档不参与向量命中。 inner_hits.from/size 控制子分页,offset始终指原数组位置。例如 from: 1, size: 1 仅返回offset=1,总数仍为2。 本例使用全访问目标及raw重排方便说明分数,不代表生产场景固定使用100%访问;关闭重排后不能要求相同的raw分数。 inner_hits在匹配的子文档范围评分,不另起一次独立ANN召回。

取回向量 #

新建 OSQ 索引默认自动从物理 _source 排除向量,保留的原精度向量仍用于重排、字段读取及 source 恢复。 搜索需要返回向量时,可写为:

POST /disk-vectors/_search
{
  "_source": { "exclude_vectors": false },
  "knn": {
    "field": "vector",
    "query_vector": [1.0, 2.0, 3.0, 4.0],
    "k": 10,
    "num_candidates": 100
  }
}

GET 可使用 GET /disk-vectors/_doc/1?_source_exclude_vectors=false。 也支持 fields、docvalue_fields 和向量脚本读取;恢复值遵循保留的 float/bfloat16 精度,不是从 1-bit 码反量化得到。 需要在物理 _source 中保留输入数组时,在建索引 settings 中设置 index.mapping.exclude_source_vectors: false;该设置不能动态修改。

cosine向量可能经历归一化及取回时的模长恢复,float恢复值也可能有舍入差异,不保证输入JSON或数值逐位不变。 自动排除关闭时,mapping中永久排除的向量不能依靠请求选项补回;显式禁用 _source 也不能靠该选项重建完整文档。 更多source过滤及字段读取说明见 OSQ HNSW 的向量存储与取回。

持久化与恢复 #

Disk向量和nested关系使用正常索引持久化及同产品快照流程。flush后可close/open,快照恢复后仍需核对实际向量查询、inner_hits分数/offset和向量内容。 对只读索引执行forceMerge后,如需通过 _segments 检查搜索使用的段,应先refresh;commit段数与当前搜索reader的段数可能暂时不同。 不要仅凭健康状态或快照成功响应判定恢复内容正确。

迁移与适用边界 #

  • 历史索引不会因升级程序自动变成 Disk。转换索引类型时,预先创建目标 mapping,再使用 Reindex。
  • 只有支持相应能力的节点才能承载、查询 Disk 字段;不要将此类索引分配到旧版本节点。
  • API 参数兼容不代表能够与 Elasticsearch 互读 segment 或跨产品恢复快照。迁移时复制文档并由目标索引重新构建。
  • OSQ 为有损量化,不保证固定召回率,也不保证与其它引擎返回相同的 ANN 集合或逐位相同的近似分数。
  • 索引还保存原向量、校正信息及其它必要数据,不能将1-bit码解释为整个索引缩小32倍。

原生 HNSW、OSQ HNSW 与 Disk 的接口选择见向量搜索。