AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 检索分析服务 Elasticsearch版 产品概述 AliES内核 FalconSeek向量索引使用指南

FalconSeek向量索引使用指南

更新时间：
产品详情
我的收藏

使用示例

基础示例

以下示例创建一个存储和检索向量数据的索引，索引名为 my_falcon_seek_index ，其中包含一个名为 product_vector 的向量字段，维度为 128，并使用HNSW 算法。

  1. 创建索引

    PUT /my_falcon_seek_index
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  },
  "mappings": {
    "properties": {
      "product_vector": {
        "type": "dense_vector",
        "dims": 128,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "HNSW",
          "m": 32,
          "ef_construction": 400
        }
      },
      "category": {
        "type": "keyword" 
      }
    }
  }
}

    核心参数：

    • dense_vector 字段类型，是用于存储稠密向量数据的专用字段类型。在 mappings 中定义此类型字段时，必须指定以下核心属性：

      • dims：向量的维度。

      • similarity：向量间的相似度计算函数。

      • index_options：向量索引的详细配置，包括算法类型和相关参数。

    • similarity 相似度函数，用于衡量两个向量之间的相似程度，选择合适的函数对召回效果至关重要。

      函数

      说明

      适用场景

      l2_norm

      欧氏距离。计算两个向量在多维空间中的直线距离。距离越小，越相似。

      通用场景，如图像识别、人脸识别。

      cosine

      余弦相似度。计算两个向量方向的夹角余弦值。值越接近 1，越相似。

      文本语义相似度分析，不受向量长度影响。

      dot_product

      内积。计算两个向量的点积。值越大，越相似。

      推荐系统等需要考虑向量模长的场景。

      max_inner_product

      与dot_product功能一样，但不要求向量归一化。

      推荐系统等需要考虑向量模长的场景。

  2. 写入数据：向索引中写入包含向量和元数据（如商品类别）的文档，product_vector 数组的长度必须与 dims 定义的维度（128）完全一致。

    POST /my_falcon_seek_index/_doc/1
{
  "product_vector": [0.12, -0.05, 0.08, 0.24, -0.17, 0.31, 0.02, -0.19, 0.11, 0.28,
    -0.03, 0.15, 0.22, -0.11, 0.09, 0.33, -0.07, 0.14, 0.26, -0.21,
    0.18, 0.29, -0.13, 0.06, 0.35, -0.08, 0.16, 0.23, -0.15, 0.12, 
    0.27, -0.22, 0.19, 0.32, -0.14, 0.07, 0.25, -0.18, 0.13, 0.30,
    -0.09, 0.17, 0.24, -0.16, 0.10, 0.34, -0.10, 0.20, 0.31, -0.23,
    0.15, 0.28, -0.12, 0.11, 0.26, -0.19, 0.14, 0.29, -0.17, 0.08,
    0.22, -0.20, 0.16, 0.27, -0.15, 0.09, 0.25, -0.21, 0.18, 0.30,
    -0.13, 0.07, 0.24, -0.22, 0.19, 0.32, -0.16, 0.10, 0.26, -0.18,
    0.12, 0.28, -0.14, 0.06, 0.23, -0.19, 0.15, 0.29, -0.11, 0.05,
    0.21, -0.17, 0.13, 0.27, -0.10, 0.04, 0.20, -0.15, 0.11, 0.25,
    -0.09, 0.03, 0.19, -0.13, 0.10, 0.24, -0.08, 0.02, 0.18, -0.12,
    0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.22, 0.05, -0.06,
    0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.22],
  "category": "clothes"
}
POST /my_falcon_seek_index/_doc/2
{"product_vector":[0.12, -0.05, 0.08, 0.24, -0.17, 0.31, 0.02, -0.19, 0.11, 0.28,
    -0.03, 0.15, 0.22, -0.11, 0.09, 0.33, -0.07, 0.14, 0.26, -0.21,
    0.18, 0.29, -0.13, 0.06, 0.35, -0.08, 0.16, 0.23, -0.15, 0.12, 
    0.27, -0.22, 0.19, 0.32, -0.14, 0.07, 0.25, -0.18, 0.13, 0.30,
    -0.09, 0.17, 0.24, -0.16, 0.10, 0.34, -0.10, 0.20, 0.31, -0.23,
    0.15, 0.28, -0.12, 0.11, 0.26, -0.19, 0.14, 0.29, -0.17, 0.08,
    0.22, -0.20, 0.16, 0.27, -0.15, 0.09, 0.25, -0.21, 0.18, 0.30,
    -0.13, 0.07, 0.24, -0.22, 0.19, 0.32, -0.16, 0.10, 0.26, -0.18,
    0.12, 0.28, -0.14, 0.06, 0.23, -0.19, 0.15, 0.29, -0.11, 0.05,
    0.21, -0.17, 0.13, 0.27, -0.10, 0.04, 0.20, -0.15, 0.11, 0.25,
    -0.09, 0.03, 0.19, -0.13, 0.10, 0.24, -0.08, 0.02, 0.18, -0.12,
    0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.22, 0.05, -0.06,
    0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.22],"category": "clothes"}

  3. 向量检索（k-NN）： 根据给定的查询向量，查找最相似的 5个文档。

    GET /my_falcon_seek_index/_search
{
  "knn": {
    "field": "product_vector",
    "query_vector": [0.12, -0.05, 0.01, 0.24, -0.17, 0.31, 0.02, -0.19, 0.11, 0.28,
    -0.03, 0.15, 0.22, -0.11, 0.09, 0.23, -0.07, 0.14, 0.26, -0.21,
    0.18, 0.29, -0.13, 0.06, 0.35, -0.18, 0.16, 0.23, -0.15, 0.12, 
    0.27, -0.22, 0.19, 0.32, -0.14, 0.87, 0.25, -0.18, 0.13, 0.30,
    -0.09, 0.17, 0.24, -0.16, 0.10, 0.64, -0.10, 0.20, 0.31, -0.23,
    0.15, 0.28, -0.12, 0.11, 0.26, -0.19, 0.14, 0.29, -0.17, 0.08,
    0.22, -0.20, 0.16, 0.27, -0.15, 0.09, 0.25, -0.21, 0.18, 0.30,
    -0.13, 0.07, 0.24, -0.22, 0.19, 0.52, -0.16, 0.10, 0.26, -0.18,
    0.12, 0.28, -0.14, 0.06, 0.23, -0.19, 0.14, 0.29, -0.11, 0.05,
    0.21, -0.17, 0.13, 0.27, -0.10, 0.04, 0.20, -0.15, 0.11, 0.25,
    -0.09, 0.03, 0.19, -0.13, 0.10, 0.24, -0.08, 0.02, 0.18, -0.12,
    0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.22, 0.05, -0.06,
    0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.12],
    "k": 5,
    "num_candidates": 100
  }
}

    核心参数：

    knn 查询语法，是执行 k-最近邻（k-Nearest Neighbors）搜索的专用查询体。

    • field：要查询的 dense_vector 字段名。

    • query_vector：用于查询的向量，其维度必须与字段定义一致。

    • k：需要返回的最相似结果数量。

    • num_candidates：在每个分片上，算法内部搜索的候选集大小。该值大于 k，通常是 k 的数倍。值越大，召回率越高，但查询延迟也相应增加。

  4. 过滤检索：在执行向量检索的同时，对结果进行过滤，以满足更复杂的业务需求。以下示例将在 category 为 "shoes" 的文档中，查找最相似的 5 个文档。

    GET /my_falcon_seek_index/_search
{
  "knn": {
    "field": "product_vector",
    "query_vector": [
      0.12, -0.05, 0.01, 0.24, -0.17, 0.31, 0.02, -0.19, 0.11, 0.28,
      -0.03, 0.15, 0.22, -0.11, 0.09, 0.23, -0.07, 0.14, 0.26, -0.21,
      0.18, 0.29, -0.13, 0.06, 0.35, -0.18, 0.16, 0.23, -0.15, 0.12,
      0.27, -0.22, 0.19, 0.32, -0.14, 0.87, 0.25, -0.18, 0.13, 0.30,
      -0.09, 0.17, 0.24, -0.16, 0.10, 0.64, -0.10, 0.20, 0.31, -0.23,
      0.15, 0.28, -0.12, 0.11, 0.26, -0.19, 0.14, 0.29, -0.17, 0.08,
      0.22, -0.20, 0.16, 0.27, -0.15, 0.09, 0.25, -0.21, 0.18, 0.30,
      -0.13, 0.07, 0.24, -0.22, 0.19, 0.52, -0.16, 0.10, 0.26, -0.18,
      0.12, 0.28, -0.14, 0.06, 0.23, -0.19, 0.14, 0.29, -0.11, 0.05,
      0.21, -0.17, 0.13, 0.27, -0.10, 0.04, 0.20, -0.15, 0.11, 0.25,
      -0.09, 0.03, 0.19, -0.13, 0.10, 0.24, -0.08, 0.02, 0.18, -0.12,
      0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.22, 0.05, -0.06,
      0.09, 0.23, -0.07, 0.01, 0.17, -0.11, 0.08, 0.12
    ],
    "k": 5,
    "num_candidates": 100,
    "filter": {
      "term": {
        "category": "shoes"
      }
    }
  }
}

扩展功能：tags_filter过滤检索

tags_filter 是一种专为 HNSW 和 QGraph 算法优化的前置过滤机制。与标准的 bool filter 相比，它在图遍历的早期阶段就排除不匹配的节点，因此性能更高。

  • 适用场景：当过滤字段取值有限（如类目、品牌 ID），且对查询性能要求极致时。

  • 如何启用：

    1. 在 mappings 的 index_options 中，使用 tags 参数声明要用于过滤的 keyword 类型字段。

      PUT /my_vector_index_with_tags
{
  "mappings": {
    "properties": {
      "product_vector": {
        "type": "dense_vector",
        "dims": 128,
        "index_options": {
          "type": "havenask_native",
          "knn_type": "HNSW",
          "tags": ["category"] // 声明 category 字段用于 tags_filter
        }
      },
      "category": {
        "type": "keyword" // 必须是 keyword 类型
      }
    }
  }
}

    2. 在查询的 knn 体中使用 tags_filter 参数，并采用 "field_name = value" 语法。支持 | (OR) 和 & (AND) 逻辑。

      GET /my_vector_index_with_tags/_search
{
  "knn": {
    "field": "product_vector",
    "query_vector": [...],
    "k": 5,
    "tags_filter": "category = shoes | category = socks"
  }
}

算法选择与性能指南

选择合适的 knn_type 算法对于实现性能、成本和精度的最佳平衡至关重要。

算法对比与决策建议

算法

召回率

查询速度

内存占用

适用场景与决策建议

核心限制

HNSW

高

快

中

通用首选。

适用于绝大多数场景，在召回率、性能和资源消耗之间取得了最佳平衡。数据规模在 10 万到 1000 万时表现优异。

无特殊限制。

RabitQGraph

高

最快

最低

极致性能与成本敏感场景。

适用于对查询延迟有毫秒级响应要求，或内存成本极其敏感的超大规模（千万级以上）数据集。

仅支持 l2_norm 相似度；向量维度必须是 64 的正整数倍。

QGraph

高

快

低

大规模数据且存储成本敏感场景。

通过向量量化技术显著降低内存和存储占用，适用于 500 万以上规模的数据集。

无特殊限制。

QC

中

中

低

大规模数据且内存受限场景。当构建时间不敏感，但运行时内存资源非常紧张时可以考虑。适用于 100 万以上规模的数据集。

构建时间较长。

Linear

最高 (100%)

慢

低

小数据集或要求绝对精确场景。

适用于数据总量小于 brute_force_threshold（默认 1000）或 linear_build_threshold 的场景，系统会自动切换。查询时间随数据量线性增长。

仅适用于小数据集。

场景化选型路径

  • 刚开始或不确定时：直接选择 HNSW。

  • 数据量增长，性能下降：

    • 如果内存充足，追求更高 QPS：从 HNSW 迁移到 RabitQGraph (需满足其限制)。

    • 如果内存/存储成本过高：从 HNSW 迁移到 QGraph，并配置 quantizer。

  • 超大规模数据集（千万级以上）：

    • 对延迟要求极高：直接选用 RabitQGraph。

    • 对成本敏感，延迟要求稍低：选用 QGraph。

索引管理 (Mappings)

在创建索引时，所有向量相关的配置都在 mappings 的 index_options 块内完成。

PUT /<your_index_name>
{
  "mappings": {
    "properties": {
      "<your_vector_field>": {
        "type": "dense_vector",
        "dims": 768,
        "similarity": "l2_norm",
        "index_options": {
          // --- 通用参数 ---
          "type": "havenask_native",
          "knn_type": "HNSW",
          // --- 算法构建参数 ---
          "m": 32,
          "ef_construction": 400,
          // --- 高级参数 ---
          "thread_count": 8
        }
      }
    }
  }
}

通用参数

参数

描述

类型

是否必需

默认值

type

指定使用 FalconSeek 的向量索引引擎。必须设置为 "havenask_native"。

String

是

无

knn_type

指定使用的向量索引算法。可选值为 "HNSW", "RabitQGraph", "QGraph", "QC", "Linear"。

String

否

"HNSW"

算法构建参数

以下参数在索引构建时生效，决定了索引的结构和质量。

HNSW / QGraph 共有参数

参数

描述

类型

默认值

取值建议与影响

m

图中每个节点的最大邻居数。

Integer

16

影响：直接影响召回率和内存占用。
建议：16 (低内存)、32 (平衡)、64-128 (高召回率)。值越大，召回率越高，但内存占用和构建时间也越长。取值范围：4-128。

ef_construction

构建图时搜索候选集的宽度。

Integer

200

影响：决定索引构建的质量和时间。
建议：200 (快速构建)、400-500 (平衡)、800+ (高质量构建)。值越大，索引质量越高（最终召回率也越高），但构建时间越长。取值范围：10-2000。

QGraph 专用参数

参数

描述

类型

默认值

取值建议与影响

quantizer

向量量化方式，用于压缩向量以减少内存和存储占用。

String

无

影响：显著降低资源占用，但可能带来轻微精度损失。
建议："int8" (推荐，8倍压缩)、"int4" (更高压缩比)、"fp16" (高精度，2倍压缩)、"2bit" (极致压缩)。

高级参数

参数

描述

类型

默认值

取值建议与影响

thread_count

索引构建时使用的并行线程数。

Integer

1

影响：加快构建速度。
建议：设置为 0 可自动使用机器的所有 CPU 核数，或根据资源情况指定具体数值（1-32）。

tags

声明用于 tags_filter 高性能过滤的字段列表。

Array

[]

影响：启用高性能前置过滤。
建议：将取值基数小、过滤频繁的 keyword 字段加入列表，如 ["category", "brand_id"]。

linear_build_threshold

当索引的文档总数低于此阈值时，自动切换为 Linear（暴力）搜索，以优化小数据集场景的资源消耗和查询效率。

Integer

0

影响：避免为小数据集构建复杂索引结构。
建议：对于文档数可能很少的索引，可设置为 1000 或 5000。

index_params

底层引擎的参数配置接口，用于高级调优。

Object

{}

影响：可以精细控制构建和查询的每一个细节。
重要：index_params 内的参数会覆盖顶层同名参数（如 m, ef_construction）。这是为高级用户提供的接口，普通用户推荐使用顶层参数。

index_params 提供了对底层 proxima.* 和 param.* 参数的直接访问能力。例如，顶层的 m 参数对应底层的 proxima.hnsw.builder.max_neighbor_count。仅当您需要调整顶层参数未暴露的细节时，才需要使用此配置。

json

"index_options": {  "knn_type": "HNSW",  "m": 32, // 会被下面的 index_params 覆盖  "index_params": {    "proxima.hnsw.builder.max_neighbor_count": 48 // 最终生效的是 48  }}

knn查询体

参数

描述

类型

是否必需

field

要执行 k-NN 搜索的 dense_vector 字段名。

String

是

query_vector

用于查询的向量。

Array

是

k

返回最相似结果的数量。

Integer

是

num_candidates

每个分片上的搜索候选集大小。值越大，召回率越高，查询越慢。

Integer

否 (推荐设置)

tags_filter

（可选）用于 HNSW 和 QGraph 的高性能前置过滤。

String

否

search_params

（可选）在查询时动态调整部分搜索参数，用于临时调优。

Object

否

参数说明

HNSW

HNSW (Hierarchical Navigable Small Worlds) 算法的参数使用 proxima.hnsw. 命名空间，可通过 index_params 设置。

HNSW Builder

参数名

类型

默认值

说明

proxima.hnsw.builder.max_neighbor_count

uint32

100

图的邻居数，值越大图越精确，但计算和存储开销越大，一般不超过特征维度，最大65535个

proxima.hnsw.builder.efconstruction

uint32

500

用于控制图的构建精度，值越大构建的图越精确但构建更耗时

proxima.hnsw.builder.thread_count

uint32

0

构建时开启线程数量，设置为0时为CPU核数

proxima.hnsw.builder.memory_quota

uint64

0

限制最大构建内存，暂不支持磁盘构建，当超过此值时会构建失败

proxima.hnsw.builder.scaling_factor

uint32

50

每层图之间节点比例，一般无须修改，取值范围 [5,1000]

proxima.hnsw.builder.neighbor_prune_ratio

float

0.5

用于控制邻居表开始裁边邻居数，一般无须修改

proxima.hnsw.builder.upper_neighbor_ratio

float

0.5

图的上层邻居数相对0层图邻居比例，一般无须修改

proxima.hnsw.builder.enable_adsampling

bool

false

默认不开启，目前只支持fp32数据集下的欧式距离计算，256维以下不建议开启

proxima.hnsw.builder.slack_pruning_factor

float

1.0

默认为1.0，建议在 [1.1, 1.2] 之间，gist960、sift128建议 1.1

HNSW Searcher

参数名

类型

默认值

说明

proxima.hnsw.searcher.ef

uint32

500

用于检索时考察精度，值越大扫描doc数越多，召回率越高

proxima.hnsw.searcher.max_scan_ratio

float

0.1

用在检索时控制最多扫描文档的比例，如ef值提前收敛则不会扫描到此比例

proxima.hnsw.searcher.neighbors_in_memory_enable

bool

false

开启时将邻居表保存在内存，提升性能但消耗较多内存

proxima.hnsw.searcher.check_crc_enable

bool

false

是否对索引进行CRC校验，开启时加载时间会延长

proxima.hnsw.searcher.visit_bloomfilter_enable

bool

false

使用bloomfilter作为graph节点访问去重容器，内存优化但性能稍差

proxima.hnsw.searcher.visit_bloomfilter_negative_prob

float

0.001

bloomfilter的准确度，越小越精确但内存占用越大

proxima.hnsw.searcher.brute_force_threshold

int

1000

当总doc数量小于此值时，走线性检索

HNSW配置示例

// 基础 HNSW 配置
PUT /hnsw_basic
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 768,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "HNSW"
        }
      }
    }
  }
}

// 高性能 HNSW 配置
PUT /hnsw_performance
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 1024,
        "index": true,
        "similarity": "dot_product",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "HNSW",
          "m": 48,
          "ef_construction": 500,
          "thread_count": 8,
          "linear_build_threshold": 1000,
          "is_embedding_saved": true,
          "embedding_load_strategy": "ANN_INDEX_FILE",
          "index_load_strategy": "MEM"
        }
      }
    }
  }
}

RabitQGraph

RabitQGraph Builder

参数名

类型

默认值

说明

param.rabitQGraph.builder.neighbor_cnt

uint32

128

每个节点的邻居数量，影响图的连通性和搜索精度

param.rabitQGraph.builder.ef_construction

uint32

512

构建时的 EF 参数，控制构建过程中的候选节点数量

param.rabitQGraph.builder.prune_ratio

float

0.5

邻居剪枝比例，用于优化图结构

param.rabitQGraph.builder.cluster_count

uint32

64

聚类中心数量，用于向量量化

param.rabitQGraph.builder.quantized_bit_count

uint32

1

量化的比特数，只能设置为 1, 4, 5, 8, 9

param.rabitQGraph.builder.slack_prune_factor

float

1.0

松弛剪枝因子，用于控制剪枝策略

param.rabitQGraph.builder.repair_connectivity

bool

true

是否修复图连通性

param.rabitQGraph.builder.thread_count

uint32

0

构建时使用的线程数，设置为0时为CPU核数

param.rabitQGraph.builder.ckpt_count

uint32

0

检查点数量，用于增量构建

param.rabitQGraph.builder.ckpt_threshold

uint32

2000000

检查点阈值

RabitQGraph Searcher

参数名

类型

默认值

说明

param.rabitQGraph.searcher.ef

uint32

250

搜索时的 EF 参数，影响搜索精度和性能

param.rabitQGraph.searcher.max_scan_ratio

double

0.05

最大扫描比例，限制搜索的节点百分比

param.rabitQGraph.searcher.check_crc_enable

bool

false

是否启用 CRC 校验

param.rabitQGraph.searcher.thread_count

uint32

1

搜索时使用的线程数

param.rabitQGraph.searcher.thread_safe_filter

bool

false

是否启用线程安全过滤

RabitQGraph配置示例

// 高性能配置
{
  "index_params": {
    "param.rabitQGraph.builder.neighbor_cnt": 256,
    "param.rabitQGraph.builder.ef_construction": 512,
    "param.rabitQGraph.builder.quantized_bit_count": 8,
    "param.rabitQGraph.builder.cluster_count": 128,
    "param.rabitQGraph.builder.thread_count": 8,
    "param.rabitQGraph.searcher.ef": 300,
    "param.rabitQGraph.searcher.max_scan_ratio": 0.1
  }
}

// 内存优化配置
{
  "index_params": {
    "param.rabitQGraph.builder.neighbor_cnt": 64,
    "param.rabitQGraph.builder.ef_construction": 200,
    "param.rabitQGraph.builder.quantized_bit_count": 1,
    "param.rabitQGraph.builder.cluster_count": 32,
    "param.rabitQGraph.searcher.ef": 150,
    "param.rabitQGraph.searcher.max_scan_ratio": 0.03
  }
}

// 平衡配置
{
  "index_params": {
    "param.rabitQGraph.builder.neighbor_cnt": 128,
    "param.rabitQGraph.builder.ef_construction": 400,
    "param.rabitQGraph.builder.quantized_bit_count": 4,
    "param.rabitQGraph.builder.cluster_count": 64,
    "param.rabitQGraph.searcher.ef": 250
  }
}

Linear

Linear 算法使用线性暴力搜索，参数相对简单，使用 proxima.linear. 命名空间。

Linear Builder/Searcher

参数名

类型

默认值

说明

proxima.linear.builder.column_major_order

string

false

构建时特征用行排(false)或列排(true)

proxima.linear.searcher.read_block_size

uint32

1048576

search阶段一次性读取到内存的大小，推荐值1M

Linear配置示例

// 基础配置
{
  "index_params": {
    "proxima.linear.builder.column_major_order": "false",
    "proxima.linear.searcher.read_block_size": 1048576
  }
}

// 大内存配置
{
  "index_params": {
    "proxima.linear.builder.column_major_order": "true",
    "proxima.linear.searcher.read_block_size": 2097152
  }
}

QC

QC (Quantization Clustering) 算法使用量化聚类索引，参数使用 proxima.qc. 命名空间。

QC Builder

参数名

类型

默认值

说明

proxima.qc.builder.train_sample_count

uint32

0

指定训练数据量，如果为0则使用全部数据

proxima.qc.builder.thread_count

uint32

0

构建时开启线程数量，设置为0时为CPU核数

proxima.qc.builder.centroid_count

string

-

聚类中心点参数，支持层次聚类，层之间用"*"分隔

proxima.qc.builder.cluster_class

string

OptKmeansCluster

指定聚类方法

proxima.qc.builder.cluster_auto_tuning

bool

false

指定是否开启中心点数目自适应

proxima.qc.builder.optimizer_class

string

HcBuilder

针对中心点部分的优化器，用于提升分类时的精度

proxima.qc.builder.optimizer_params

IndexParams

-

optimize方法对应的构建和检索参数

proxima.qc.builder.converter_class

string

-

如果Measure是InnerProduct，会自动进行Mips转换操作

proxima.qc.builder.converter_params

IndexParams

-

converter_class 初始化参数

proxima.qc.builder.quantizer_class

string

-

配置量化器，可选 Int8QuantizerConverter, Int4QuantizerConverter 等

proxima.qc.builder.quantizer_params

IndexParams

-

量化器相关参数

proxima.qc.builder.quantize_by_centroid

bool

false

使用quantizer_class时，是否按中心点进行量化

proxima.qc.builder.store_original_features

bool

false

是否保留原始特征

QC Searcher

参数名

类型

默认值

说明

proxima.qc.searcher.scan_ratio

float

0.01

用于计算max_scan_num数量，总doc数量 * scan_ratio

proxima.qc.searcher.optimizer_params

IndexParams

-

指定Build时optimizer对应的在线检索参数

proxima.qc.searcher.brute_force_threshold

int

1000

如果总doc数少于此值，则走线性检索

QC配置示例

// 基础配置
{
  "index_params": {
    "proxima.qc.builder.thread_count": 4,
    "proxima.qc.builder.centroid_count": "1000",
    "proxima.qc.builder.cluster_class": "OptKmeansCluster",
    "proxima.qc.searcher.scan_ratio": 0.02
  }
}

// 层次聚类配置
{
  "index_params": {
    "proxima.qc.builder.thread_count": 8,
    "proxima.qc.builder.centroid_count": "100*100",
    "proxima.qc.builder.optimizer_class": "HnswBuilder",
    "proxima.qc.builder.quantizer_class": "Int8QuantizerConverter",
    "proxima.qc.searcher.scan_ratio": 0.01
  }
}

// 高精度配置
{
  "index_params": {
    "proxima.qc.builder.thread_count": 12,
    "proxima.qc.builder.centroid_count": "2000",
    "proxima.qc.builder.train_sample_count": 100000,
    "proxima.qc.builder.store_original_features": true,
    "proxima.qc.searcher.scan_ratio": 0.05
  }
}

QGraph

QGraph (Quantized Graph) 算法是量化图索引，继承了HNSW的大部分参数，并增加了量化相关参数。

QGraph Builder

QGraph继承了所有 HNSW Builder 参数，并添加：

参数名

类型

默认值

说明

proxima.qgraph.builder.quantizer_class

string

-

配置量化器，可选 Int8QuantizerConverter, Int4QuantizerConverter, HalfFloatConverter, DoubleBitConverter

proxima.qgraph.builder.quantizer_params

IndexParams

-

配置量化器相关参数

所有 proxima.hnsw.builder.* 参数同样适用于 QGraph。

QGraph Searcher

QGraph 继承了所有 HNSW Searcher 参数。

QGraph配置示例

// Int8 量化配置
{
  "index_params": {
    "proxima.hnsw.builder.max_neighbor_count": 32,
    "proxima.hnsw.builder.efconstruction": 400,
    "proxima.hnsw.builder.thread_count": 4,
    "proxima.qgraph.builder.quantizer_class": "Int8QuantizerConverter",
    "proxima.qgraph.builder.quantizer_params": {},
    "proxima.hnsw.searcher.ef": 300
  }
}

// Int4 量化配置（更省内存）
{
  "index_params": {
    "proxima.hnsw.builder.max_neighbor_count": 48,
    "proxima.hnsw.builder.efconstruction": 500,
    "proxima.hnsw.builder.thread_count": 6,
    "proxima.qgraph.builder.quantizer_class": "Int4QuantizerConverter",
    "proxima.qgraph.builder.quantizer_params": {},
    "proxima.hnsw.searcher.ef": 400,
    "proxima.hnsw.searcher.max_scan_ratio": 0.1
  }
}

// HalfFloat 量化配置（高精度）
{
  "index_params": {
    "proxima.hnsw.builder.max_neighbor_count": 64,
    "proxima.hnsw.builder.efconstruction": 600,
    "proxima.hnsw.builder.thread_count": 8,
    "proxima.qgraph.builder.quantizer_class": "HalfFloatConverter",
    "proxima.qgraph.builder.quantizer_params": {},
    "proxima.hnsw.searcher.ef": 500
  }
}

search_params 动态参数调整

在不重建索引的情况下，临时调整某些搜索参数，以在不同场景下平衡召回率和查询延迟。

例如，对于普通在线查询，使用默认或较低的 ef 值以保证低延迟；对于离线分析或高精度要求的任务，通过 search_params 临时调高 ef 值以获取更高的召回率。

HNSW

{
  "search_params": {
    "proxima.hnsw.searcher.ef": "400",
    "proxima.hnsw.searcher.max_scan_ratio": "0.15"
  }
}

QGraph

{
  "search_params": {
    "proxima.hnsw.searcher.ef": "400",
    "proxima.hnsw.searcher.max_scan_ratio": "0.15"
  }
}

QC

{
  "search_params": {
    "proxima.qc.searcher.scan_ratio": "0.02"
  }
}

RabitQGraph

{
  "search_params": {
    "param.rabitQGraph.searcher.ef": "300",
    "param.rabitQGraph.searcher.max_scan_ratio": "0.08"
  }
}

search_params配置示例

// HNSW 动态调整精度和性能
GET vector_index/_search
{
  "knn": {
    "field": "vector",
    "query_vector": [0.1, 0.2, 0.3],
    "k": 10,
    "num_candidates": 100,
    "search_params": {
      "proxima.hnsw.searcher.ef": "500",
      "proxima.hnsw.searcher.max_scan_ratio": "0.2"
    }
  }
}

// QC 动态调整扫描比例
GET vector_index/_search
{
  "knn": {
    "field": "vector",
    "query_vector": [0.1, 0.2, 0.3],
    "k": 10,
    "num_candidates": 100,
    "search_params": {
      "proxima.qc.searcher.scan_ratio": "0.05"
    }
  }
}

// RabitQGraph 动态调整搜索精度
GET vector_index/_search
{
  "knn": {
    "field": "vector",
    "query_vector": [0.1, 0.2, 0.3],
    "k": 10,
    "num_candidates": 100,
    "search_params": {
      "param.rabitQGraph.searcher.ef": "400",
      "param.rabitQGraph.searcher.max_scan_ratio": "0.1"
    }
  }
}

linear_build_threshold

类型为integer，属于非必须参数，默认值为0。当文档数量小于此阈值时，使用线性搜索而不构建复杂索引

// 禁用线性阈值
{
  "linear_build_threshold": 0
}

// 小数据集使用线性搜索
{
  "linear_build_threshold": 1000
}

// 较大阈值，适用于测试环境
{
  "linear_build_threshold": 5000
}

附录：完整示例

HNSW

// 基础 HNSW 配置
PUT /hnsw_basic
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 768,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "HNSW"
        }
      }
    }
  }
}

// 高性能 HNSW 配置
PUT /hnsw_performance
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 1024,
        "index": true,
        "similarity": "dot_product",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "HNSW",
          "m": 48,
          "ef_construction": 500,
          "thread_count": 8,
          "linear_build_threshold": 1000,
          "is_embedding_saved": true,
          "embedding_load_strategy": "ANN_INDEX_FILE",
          "index_load_strategy": "MEM"
        }
      }
    }
  }
}

Linear

// 基础 Linear 配置
PUT /linear_basic
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 384,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "Linear"
        }
      }
    }
  }
}

QC

// 基础 QC 配置
PUT /qc_basic
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 768,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "QC"
        }
      }
    }
  }
}

// 自定义 QC 配置
PUT /qc_custom
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 1024,
        "index": true,
        "similarity": "dot_product",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "QC",
          "thread_count": 8,
          "linear_build_threshold": 5000,
          "index_params": "{\"proxima.qc.builder.thread_count\": 8, \"proxima.qc.builder.centroid_count\": \"2000\"}"
        }
      }
    }
  }
}

QGraph

// 基础 QGraph 配置
PUT /qgraph_basic
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 768,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "QGraph",
          "quantizer": "int8"
        }
      }
    }
  }
}

// 高精度 QGraph 配置
PUT /qgraph_high_precision
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 1536,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "QGraph",
          "m": 40,
          "ef_construction": 600,
          "thread_count": 8,
          "quantizer": "fp16",
          "is_embedding_saved": true,
          "index_load_strategy": "MEM"
        }
      }
    }
  }
}

// 内存优化 QGraph 配置
PUT /qgraph_memory_optimized
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 1024,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "QGraph",
          "m": 24,
          "ef_construction": 300,
          "thread_count": 6,
          "quantizer": "int4",
          "is_embedding_saved": false,
          "index_load_strategy": "BUFFER"
        }
      }
    }
  }
}

RabitQGraph

// 基础 RabitQGraph 配置（仅支持 l2_norm 相似度）
PUT /rabitqgraph_basic
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 64,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "RabitQGraph"
        }
      }
    }
  }
}

// 高性能 RabitQGraph 配置 - 使用 Map 格式 index_params
PUT /rabitqgraph_performance
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 128,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "RabitQGraph",
          "thread_count": 8,
          "index_params": {
            "param.rabitQGraph.builder.neighbor_cnt": 256,
            "param.rabitQGraph.builder.ef_construction": 512,
            "param.rabitQGraph.builder.quantized_bit_count": 4,
            "param.rabitQGraph.builder.cluster_count": 128,
            "param.rabitQGraph.searcher.ef": 300
          }
        }
      }
    }
  }
}

// 内存优化 RabitQGraph 配置
PUT /rabitqgraph_memory_optimized
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 192,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "RabitQGraph",
          "thread_count": 4,
          "linear_build_threshold": 1000,
          "index_params": {
            "param.rabitQGraph.builder.neighbor_cnt": 64,
            "param.rabitQGraph.builder.ef_construction": 200,
            "param.rabitQGraph.builder.quantized_bit_count": 1,
            "param.rabitQGraph.builder.cluster_count": 32,
            "param.rabitQGraph.searcher.ef": 150,
            "param.rabitQGraph.searcher.max_scan_ratio": 0.05
          }
        }
      }
    }
  }
}

// RabitQGraph 带标签过滤配置
PUT /rabitqgraph_with_tags
{
  "mappings": {
    "properties": {
      "vector": {
        "type": "dense_vector",
        "dims": 256,
        "index": true,
        "similarity": "l2_norm",
        "index_options": {
          "type": "havenask_native",
          "knn_type": "RabitQGraph",
          "tags": ["category", "region"],
          "index_params": {
            "param.rabitQGraph.builder.neighbor_cnt": 128,
            "param.rabitQGraph.builder.ef_construction": 400,
            "param.rabitQGraph.builder.quantized_bit_count": 8,
            "param.rabitQGraph.searcher.ef": 250
          }
        }
      },
      "category": {
        "type": "keyword"
      },
      "region": {
        "type": "keyword"
      }
    }
  }
}
上一篇：使用 FalconSeek 云原生内核加速 Elasticsearch 查询下一篇：产品计费