使用向量检索插件（aliyun-knn）

索引规划

集群规划

创建向量索引

1. 登录对应阿里云Elasticsearch实例的Kibana控制台。
   具体操作，请参见登录Kibana控制台。
2. 在左侧导航栏，单击Dev Tools（开发工具）。
3. 在Console中执行如下命令，创建向量索引结构。

   PUT test
   {
     "settings": {
       "index.codec": "proxima",
       "index.vector.algorithm": "hnsw"
     },
     "mappings": {
       "_doc": {
         "properties": {
           "feature": {
             "type": "proxima_vector", 
             "dim": 2, 
             "vector_type": "float", 
             "distance_method": "SquaredEuclidean" 
           }
         }
       }
     }
   }

   类型	参数	默认值	含义
   setting	index.codec	proxima	是否需要底层构建proxima knn索引，可选值如下： proxima（推荐）：底层构建proxima knn索引，支持向量检索。 null：创建索引的时候，底层不构建proxima knn索引，只构建正排索引。 此时，proxima_vector类型字段仅支持script检索，不支持hnsw或linear检索。 说明 当数据量较大，且对查询延迟要求不高的场景，可以把该项配置去掉或设置为null，可使用script检索（阿里云Elasticsearch版本为6.7.0且apack插件版本大于等于1.2.1或阿里云Elasticsearch版本为7.10.0且apack插件版本大于等于1.4.0才支持）方式进行knn向量查询。
   	index.vector.algorithm	hnsw	指定向量检索算法，可选值如下： hnsw：hnsw算法。 linear：linear算法。
   	index.vector.general.builder.offline_mode	false	指定knn索引构建是否使用离线优化模式，可选值如下： false: 不使用离线优化模式。 true: 使用离线优化模式，写入构建的segment碎片将会大幅度减少，提升整体写入吞吐能力。 说明 开启离线优化模式需要保证阿里云Elasticsearch版本为6.7.0且apack插件版本大于等于1.2.1或阿里云Elasticsearch版本为7.10.0且apack插件版本大于等于1.4.0；开启离线模式构建的索引，不支持使用script检索数据。 当一次性批量导入全量数据时，建议开启离线优化模式。
   mapping	type	proxima_vector	向量字段类型。例如：将feature字段指定为 proxima_vector，说明feature为向量字段。
   	dim	2	向量维度，必填，仅支持1~2048维。
   	vector_type	float	向量数据类型，可选值如下： float：浮点型。 short：短整型。 binary：二进制类型。 其中binary类型为二进制类型，向量数据需要用无符号的32位十进制（uint32）数组表示，且dim必须为32的整数倍。 例如：业务数据为64位二进制1000100100100101111000001001111101000011010010011010011010000100，那么写入vector为 [-1994006369, 1128900228]。 注意 阿里云Elasticsearch版本为6.7.0且apack插件版本大于等于1.2.1或阿里云Elasticsearch版本为7.10.0且apack插件版本大于等于1.4.0，向量数据类型支持以上三种类型。否则，向量数据类型仅支持float类型。
   	distance_method	SquaredEuclidean（未开方）	距离度量函数，可选值如下： SquaredEuclidean：欧氏距离（未开方）。 InnerProduct：内积距离。 Cosine：余弦距离。 Hamming：汉明距离（仅支持binary类型）。 注意 阿里云Elasticsearch版本为6.7.0且apack插件版本大于等于1.2.1或阿里云Elasticsearch版本为7.10.0且apack插件版本大于等于1.4.0，距离度量函数支持以上四种函数。否则，距离度量函数只支持SquaredEuclidean 欧氏距离（未开方）。 距离度量函数详细说明请参见距离度量函数。

   注意

   • 可通过GET /_cat/plugins?v命令获取apack插件版本，如果apack插件版本不满足要求，可提交工单，由阿里工程师帮您升级。
   • knn向量检索还提供高级查询参数，可参考高阶参数。
4. 执行如下命令，添加文档。

   POST test/_doc
   {
     "feature": [1.0, 2.0], 
     "id": 1
   }

   注意 除binary类型外，其他类型数组长度必须与dim保持一致，而binary类型的向量数据需要转换成无符号的32位十进制（uint32）数组表示，且dim必须为32的整数倍。

向量查询

• 标准检索

  执行如下命令，对文档进行标准检索。

  GET test/_search
  {
    "query": {
      "hnsw": {  
        "feature": {
          "vector": [1.5, 2.5], 
          "size": 10 
        }
      }
    }
  }

  常用参数说明：

  参数	说明
  hnsw	向量查询算法，与创建索引时指定的algorithm一致。
  vector	查询的向量数据，数组长度必须与创建索引时，mapping指定的dim保持一致。
  size	指定召回的文档数。 说明 向量检索中的size参数与Elasticsearch自带的size参数存在区别，前者控制向量检索插件knn召回的文档数，后者控制整个查询的召回文档数。使用时，系统会先通过向量检索中的size参数召回topN的文档，然后再由Elasticsearch自带的size参数召回整个查询的文档，最终返回结果。 建议将向量检索中的size参数值和Elasticsearch自带的size参数值（默认值为10）保持一致。

  说明 knn向量检索还提供高级查询参数，可参考高阶参数。
• script检索

  script向量检索方式兼容elastic DSL查询。例如使用script_score对查询返回的每个文档进行打分，该分数等于1/(1+l2Squared(params.queryVector, doc['feature'])) 。示例命令如下：

  GET test/_search
  {
    "query": {
      "match_all": {}
    },
    "rescore": {
      "query": {
        "rescore_query": {
          "function_score": {
            "functions": [{
              "script_score": {
                "script": {
                    "source": "1/(1+l2Squared(params.queryVector, doc['feature'])) ", 
                    "params": {
                      "queryVector": [2.0, 2.0]
                    }
                }
              }
            }]
          }
        }
      }
    }
  }

  knn向量script检索兼容官方函数，并拓展了如下函数：

  函数	说明
  l2Squared(float[] queryVector, DocValues docValues)	欧式算法函数。
  hamming(float[] queryVector, DocValues docValues)	汉明距离函数。
  cosineSimilarity(float[] queryVector, DocValues docValues) cosine(float[] queryVector, DocValues docValues)	余弦相似度函数。 说明 阿里云Elasticsearch 6.7版本请使用cosineSimilarity(float[] queryVector, DocValues docValues)函数，7.10版本请使用cosine(float[] queryVector, DocValues docValues)函数。

  说明

  • 使用script检索功能，需要确保阿里云Elasticsearch版本为6.7.0且apack插件版本大于等于1.2.1版本或阿里云Elasticsearch版本为7.10.0版本且apack插件版本大于等于1.4.0版本。可通过GET /_cat/plugins?v命令获取apack插件版本，如果apack插件版本不满足要求，可提交工单，由阿里工程师帮您升级。
  • 函数参数：
    • float[] queryVector：用于表示查询向量，可传入形参和实参。
    • DocValues docValues：用于指定文档向量。
  • script向量检索不支持处于离线模式（index.vector.builder.offlineMode = true）下构建的索引。
• 索引预热（降低延迟）

  knn索引由于需要进行全内存检索，所以在索引冷加载时会出现查询延迟较高的情况。因此knn插件提供了索引预热功能，可以在knn索引提供检索服务之前，提前对knn索引进行预热，加载到本地内存，从而大大降低冷启动时的查询延迟。

  • 所有向量索引实现预热。

    POST _vector/warmup

  • 特定向量索引实现预热能力。

    POST _vector/{indexName}/warmup

  注意

  • 阿里云Elasticsearch版本为6.7.0且apack插件版本大于等于1.2.1或阿里云Elasticsearch版本为7.10.0且apack插件版本大于等于1.4.0，才支持索引预热功能。可通过GET _cat/plugins?v命令获取apack插件版本，如果apack插件版本不满足要求，可提交工单，由阿里工程师帮您升级。
  • 如果集群中向量索引比较多且数据量比较大，业务只需要对特定索引实现向量检索，建议只对特定向量使用预热能力，提升内存检索能力。

向量打分

向量检索拥有统一的打分公式，而打分机制主要依赖距离度量函数。不同的距离函数直接性的影响检索排序。

打分公式：

分数= 1/(向量距离函数+1)

距离度量函数

熔断参数

高阶参数

查询示例如下：

GET test/_search
{
  "query": {
    "hnsw": {
      "feature": {
        "vector": [1.5, 2.5],
        "size": 10,
        "ef": 100       
      }
    }
  }
}

常见问题

• Q：如何评估查询的召回率？

  A：可以同时创建两个索引，一个为hnsw算法，一个为linear算法，其他配置相同。客户端向两个索引同时推送相同的向量数据，刷新后，用同样的查询向量对比linear索引和hnsw索引召回的文档ID，交集的文档ID个数/召回总数，即为待测向量的召回率。

  说明 交集的文档ID个数是指两个索引召回的文档ID的交集。

• Q：集群写入期间报错“circuitBreakingException”，如何处理？

  A：这个错误表明此时系统的堆外内存使用率超过了indices.breaker.vector.native.indexing.limit指定的比例（默认为70%），触发了写入的熔断操作，一般等待后台的索引构建任务完成后会自动释放。建议客户端写入时添加错误重试机制。

• Q：为什么写入任务已经停止了，CPU依然在工作？

  A：向量索引的构建发生在refresh或flush期间，虽然写入流量已经停止，但后台的向量索引构建任务可能仍然在继续。等待最后一轮refresh结束后，计算资源就会被释放。

• Q：关于aliyun-knn插件是否有提供最佳实践文档供参考？

  A：阿里云开发者社区提供了aliyun-knn插件业务场景和aliyun-knn最佳实践，希望在向量检索方面能够帮助到您。