Elasticsearch：使用向量檢索外掛程式（aliyun-knn）

前提條件

• 安裝向量檢索外掛程式（英文名稱為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：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"
               }
           }
         }
       }
     }
  }