前提條件

• 安裝向量檢索插件（英文名稱為aliyun-knn）。插件的默認安裝情況與阿里云Elasticsearch的實例版本和內核版本相關，具體說明如下。

  Elasticsearch版本	內核版本	插件安裝情況說明
  6.7.0	1.2.0以下	需要在插件配置頁面手動安裝向量檢索插件，安裝方法請參見安裝或卸載系統默認插件。 不支持使用script檢索和索引預熱等功能配置。如有需求，建議使用有AliES內核版本的實例，詳細信息請參見內核版本發布記錄。 創建向量索引時僅支持默認的SquaredEuclidean，不支持通過distance_method參數指定具體的距離度量函數。
  6.8	無
  7.4	無
  7.7	無
  6.7.0	1.2.0及以上	向量檢索插件默認集成在apack插件中（默認已安裝），安裝或卸載向量檢索插件都需對apack插件進行操作。詳細信息請參見使用apack插件的物理復制功能。 支持使用script檢索、索引預熱、擴展函數等擴展功能，但需要將內核版本升級至1.3.0及以上，具體操作請參見升級版本。 如果創建向量索引時遇到解析mapping報錯，請升級內核版本至1.3.0及以上后再重試。
  7.10.0	1.4.0及以上	向量檢索插件默認集成在apack插件中（默認已安裝），安裝或卸載向量檢索插件都需對apack插件進行操作。詳細信息請參見使用apack插件的物理復制功能。 內核小版本大于等于1.4.0時，apack插件版本已為最新版本，無需更新。使用時，可通過GET _cat/plugins?v命令獲取插件版本。
  其他版本	無	不支持向量檢索功能。

  說明

  內核版本不等同于apack插件版本，使用時可通過GET _cat/plugins?v命令獲取apack插件版本。

• 完成索引規劃。

  算法	適用場景	是否全內存	其他
  hnsw	單機數據量小。 對延遲要求高。 對召回率要求高。	是	hnsw是基于“鄰居的鄰居可能是鄰居”的核心思想，它在距離衡量算法上有一定的限制，需要滿足三角形不等式，即三角形的兩邊之和大于第三邊。例如，對于內積向量空間，由于不滿足三角形不等式，需要轉化為歐式空間或球面空間，才能使用hnsw檢索方法。 建議寫入結束后，在業務低峰期定期forceMerge，有助于降低查詢延遲。
  linear	暴力檢索。 召回率100%。 延遲與數據量成正比。 效果對照。	是	無 。

• 完成集群規劃。

  規劃項	說明
  數據節點規格（必須）	16核64 GB及以上。 說明 使用aliyun-knn插件構建索引時，需要消耗大量的計算資源。由于小規格集群極易達到瓶頸，嚴重時會影響集群穩定性，因此建議您使用16核64 GB及以上規格的集群。
  節點類型	集群中需要有獨立的專有主節點。
  集群堆外內存	大于集群總向量數據*2。 示例： 索引中只有一個960維float字段，索引總文檔數是400，float類型數據占4字節內存，此索引向量數據內存占用=960*400*4=1.5MB，內存空間中堆外內存>1.5*2=3MB。 說明 如果存在forcemerge操作，考慮到新老數據會出現同時占用內存的情況，請在上面公式的基礎上再乘以2。 64GB及以上內存規格，堆外大小≈總內存-32G。
  寫入限流	向量索引的構建屬于CPU密集型任務，建議業務控制寫入流量不要太高。以16核64 GB的數據節點為例，建議單節點寫入峰值控制在5000tps以內。 同時，由于在向量索引的查詢過程中，會把索引文件全部加載到系統內存，因此建議在業務查詢期間，不要同時進行大批量的寫入，避免因節點內存緊張導致分片重啟的情況。

  說明

  以上均為預估，以業務實際的應用情況為準，建議提前進行壓測，并提供充足的內存空間。

使用限制

• 開啟共享彈性存儲功能的6.7版本實例不支持向量檢索插件。

• 在安裝向量檢索插件前，需要確保阿里云Elasticsearch實例的數據節點規格為16核64 GB及以上。如果不滿足，請先將數據節點規格升級至16核64 GB及以上，詳細信息請參見升配集群。

• 使用向量檢索插件的場景中，部分AliES內核的增強功能將不能使用。以物理復制功能為例，如果您使用了物理復制功能，使用向量檢索插件前，需要先關閉該功能，具體操作請參見使用apack插件的物理復制功能。

• 阿里云Elasticsearch向量檢索插件不支持通過OSS快照、DataWorks等方式進行數據遷移，建議使用Logstash方式。

創建向量索引

1. 登錄目標阿里云Elasticsearch實例的Kibana控制臺，根據頁面提示進入Kibana主頁。
   登錄Kibana控制臺的具體操作，請參見登錄Kibana控制臺。

   說明 本文以阿里云Elasticsearch 6.7.0版本為例，其他版本操作可能略有差別，請以實際界面為準。
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" 
           }
         }
       }
     }
   }

   說明

   • 在向量索引結構的基礎上，支持添加Elasticsearch支持的其他字段類型。

   • 如果創建向量索引時遇到解析mapping報錯："type": "mapper_parsing_exception", "reason": "Mapping definition for [feature] has unsupported parameters: [distance_method : SquaredEuclidean]，請及時升級內核版本至最新后重試。

   類型	參數	默認值	含義
   setting	index.codec	proxima	是否需要底層構建proxima knn索引，可選值如下： proxima（推薦）：底層構建proxima knn索引，支持向量檢索。 null：創建索引的時候，底層不構建proxima knn索引，只構建正排索引。此時，proxima_vector類型字段僅支持script檢索，不支持hnsw或linear檢索。 說明 當數據量較大，且對查詢延遲要求不高的場景，可以把該項配置去掉或設置為null，此時可使用script檢索方式進行knn向量查詢。支持script檢索方式的版本：實例版本為6.7.0且apack插件版本≥1.2.1或實例版本為7.10.0且apack插件版本≥1.4.0。
   	index.vector.algorithm	hnsw	指定向量檢索算法，可選值如下： hnsw：hnsw算法。 linear：linear算法。
   	index.vector.general.builder.offline_mode	false	指定knn索引構建是否使用離線優化模式，可選值如下： false: 不使用離線優化模式。 true: 使用離線優化模式，寫入構建的segment碎片將會大幅度減少，提升整體寫入吞吐能力。 說明 開啟離線優化模式需要保證：實例版本為6.7.0且apack插件版本≥1.2.1或實例版本為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]。 說明 實例版本為6.7.0且apack插件版本≥1.2.1或實例版本為7.10.0且apack插件版本≥1.4.0，向量數據類型支持以上三種類型。否則，向量數據類型僅支持float類型。
   	distance_method	SquaredEuclidean（未開方）	距離度量函數，可選值如下： SquaredEuclidean：歐氏距離（未開方）。 InnerProduct：內積。 Cosine：余弦相似度。 Hamming：漢明距離（僅支持binary類型）。 說明 實例版本為6.7.0且apack插件版本≥1.2.1或實例版本為7.10.0且apack插件版本≥1.4.0時，支持以上四種距離度量函數。其他版本（6.8，7.4和7.7）實例創建向量時僅支持使用默認的SquaredEuclidean，不支持通過distance_method參數指定其他距離度量函數。 距離度量函數詳細說明請參見距離度量函數。 因Hamming函數實現比較特殊，索引使用hnsw或linear時，不支持標準的knn查詢方式，僅支持script方式，且查詢語句兼容script_score。在不同的場景下，您需要根據具體業務測試查詢語句的可用性。

   說明

   • 您可以通過GET /_cat/plugins?v命令獲取apack插件版本，如果apack插件版本不滿足要求，可提交工單，由阿里云工程師幫您升級。

   • knn向量檢索還提供高級查詢參數，詳細信息請參見高階參數。

4. 執行如下命令，添加文檔。

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

   說明

   除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向量檢索僅支持在script_score方式下使用。例如使用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檢索不支持X-Pack提供的函數，僅支持以下函數：

  函數	說明
  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檢索功能，需要確保：實例版本為6.7.0且apack插件版本≥1.2.1版本或實例版本為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

  說明

  • 使用索引預熱功能，需要確保：實例版本為6.7.0且apack插件版本≥1.2.1或實例版本為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插件查詢時報錯class_cast_exception: class org.apache.lucene.index.SoftDeletesDirectoryReaderWrapper$SoftDeletesFilterCodecReader cannot be cast to class org.apache.lucene.index.SegmentReader (org.apache.lucene.index.SoftDeletesDirectoryReaderWrapper$SoftDeletesFilterCodecReader and org.apache.lucene.index.SegmentReader are in unnamed module of loader 'app')，如何處理？

  A：關閉索引的物理復制功能，具體操作請參見使用apack插件的物理復制功能。

• Q：使用aliyun-knn插件進行向量檢索，速度過慢或出現內存熔斷，怎么辦？

  A：aliyun-knn插件進行向量檢索時，使用的是全內存型向量，非常消耗內存。當索引數據量較大時，由于需要將數據加載到內存，因此會出現速度慢或內存熔斷的情況。建議索引數據量是機器內存的一半，在數據量無法變更的情況下，如果內存太小，建議您升配集群。

• Q：關于aliyun-knn插件是否有提供最佳實踐文檔供參考？

  A：您可以參見阿里云開發者社區提供的aliyun-knn插件業務場景和aliyun-knn最佳實踐。

• Q：如果當下阿里云Elasticsearch集群的向量檢索能力不滿足業務需求，怎么辦？

  A：推薦您使用阿里巴巴自主研發的大規模分布式搜索引擎OpenSearch-向量檢索版，詳細信息請參見向量檢索版介紹。

• Q：knn場景使用must_not exists無法過濾出feature字段為空的文檔，如何編寫語句過濾出feature字段為空的數據？

  A：knn數據存儲比較特殊，可能會存在個別DSL查詢不兼容的情況，您可以使用以下腳本進行過濾。

  GET jx-similar-product-v1/_search
  {
     "query": {
       "bool": {
         "must": {
           "script": {
             "script": {
               "source": "doc['feature'].empty",
               "lang": "painless"
               }
           }
         }
       }
     }
  }