前置條件

1. 成功注冊(cè)阿里云賬號(hào)并通過(guò)實(shí)名認(rèn)證。

2. 開通阿里云賬號(hào)并登錄控制臺(tái)時(shí)，會(huì)提示先創(chuàng)建access key才能繼續(xù)使用。

   1. 創(chuàng)建及使用應(yīng)用依賴access key參數(shù)，主賬號(hào)下access key參數(shù)不能為空。

   2. 在為主賬號(hào)創(chuàng)建access key參數(shù)后，還可以再創(chuàng)建RAM子賬號(hào)access key通過(guò)RAM子賬號(hào)進(jìn)行訪問(wèn)，RAM子賬號(hào)賦予對(duì)應(yīng)訪問(wèn)權(quán)限，請(qǐng)參考授權(quán)訪問(wèn)鑒權(quán)規(guī)則。（ps：子賬號(hào)需要賦予AliyunSearchEngineFullAccess、AliyunSearchEngineReadOnlyAccess訪問(wèn)向量檢索版實(shí)例的權(quán)限）。

3.需要用戶擁有VPC環(huán)境，詳情可點(diǎn)擊此處進(jìn)行查看。

購(gòu)買實(shí)例

1. 進(jìn)入OpenSearch控制臺(tái)，在左上角切換到OpenSearch-向量檢索版：

2. 進(jìn)入向量檢索版控制臺(tái)后，在實(shí)例管理界面，點(diǎn)擊創(chuàng)建實(shí)例：

3. 商品版本選擇向量檢索版，選擇地區(qū)，配置“查詢節(jié)點(diǎn)個(gè)數(shù)”、“查詢節(jié)點(diǎn)規(guī)格”、“數(shù)據(jù)節(jié)點(diǎn)數(shù)量”、“數(shù)據(jù)節(jié)點(diǎn)規(guī)格”、“單數(shù)據(jù)節(jié)點(diǎn)總存儲(chǔ)空間”，設(shè)置“專有網(wǎng)絡(luò)”和“虛擬交換機(jī)”，最后按提示要求設(shè)置用戶名和用戶密碼（用于查詢時(shí)校驗(yàn)權(quán)限，非阿里云賬號(hào)密碼），點(diǎn)擊“立即購(gòu)買”：

4. 在確認(rèn)訂單界面，查看服務(wù)協(xié)議，確認(rèn)無(wú)誤后，點(diǎn)擊立即開通：

5. 購(gòu)買成功后，點(diǎn)擊管理控制臺(tái)，即可在實(shí)例管理界面查看已購(gòu)買的向量檢索版實(shí)例：

6. 新購(gòu)的實(shí)例會(huì)設(shè)置一個(gè)默認(rèn)實(shí)例名稱，可在操作欄下點(diǎn)擊管理按鈕，進(jìn)入詳情頁(yè)進(jìn)行修改：

點(diǎn)擊修改圖標(biāo)，按提示框要求修改實(shí)例名稱最后點(diǎn)擊確認(rèn)：

配置集群

新購(gòu)買的實(shí)例，在其詳情頁(yè)中，實(shí)例狀態(tài)為“待配置”，并且會(huì)自動(dòng)部署一個(gè)與購(gòu)買的查詢節(jié)點(diǎn)和數(shù)據(jù)節(jié)點(diǎn)的個(gè)數(shù)及規(guī)格一致的空集群，之后需要為該集群配置數(shù)據(jù)源--->配置索引--->索引重建，之后才可正常搜索。

1. 配置數(shù)據(jù)源（目前支持的數(shù)據(jù)源有MaxCompute數(shù)據(jù)源和API推送數(shù)據(jù)源），這里以MaxCompute數(shù)據(jù)源為例：點(diǎn)擊“添加數(shù)據(jù)源”，數(shù)據(jù)源類型選擇“MaxCompute”，設(shè)置project、accesskeyID、accesskeyId、accesskeySecret、Table、分組鍵partition，可按需選擇是否開啟“MaxCompute數(shù)據(jù)源”：

校驗(yàn)成功之后，點(diǎn)擊“確定”，完成數(shù)據(jù)源的添加：

2. 數(shù)據(jù)源配置成功后，需點(diǎn)擊下一步配置索引結(jié)構(gòu)：

2.1. 添加索引表：

2.2. 配置索引表，模板選擇通用模板：

• 索引表：可自定義

• 數(shù)據(jù)源：選擇 1 中配置的數(shù)據(jù)源

• 數(shù)據(jù)分片：根據(jù)用戶購(gòu)買的數(shù)據(jù)節(jié)點(diǎn)個(gè)數(shù)進(jìn)行配置

2.3. 設(shè)置字段，至少需要定義2個(gè)字段主鍵字段和向量字段（向量字段需要設(shè)置為多值float類型）：

如果需要帶有類目的向量，可以在主鍵和向量字段中間加一個(gè)類目字段，類型要求單值或多值的整數(shù)類型：

屬性和字段內(nèi)容壓縮：

• 屬性字段可以選擇是否壓縮，默認(rèn)為不壓縮，選擇file_compressor表示開啟壓縮

• 字段內(nèi)容可以選擇是否壓縮，默認(rèn)為不壓縮，默認(rèn)多值和STRING類型選擇uniq，單值數(shù)值類型是equal

3. 設(shè)置索引，主鍵字段索引類型設(shè)置為PRIMARYKEY64，向量索引類型選擇CUSTOMIZED：

索引字段設(shè)置壓縮：

• 索引字段可以選擇是否壓縮，默認(rèn)為不壓縮，選擇file_compressor表示開啟壓縮

3.1. 為向量字段添加包含字段：

3.2. 高級(jí)配置，向量索引需要單獨(dú)配置參數(shù)，可以參考如下配置，詳情可參考向量索引：

更多參數(shù)：

其中build_index_params的配置如下：

{
  "proxima.qc.builder.quantizer_class": "Int8QuantizerConverter",
  "proxima.qc.builder.quantize_by_centroid": true,
  "proxima.qc.builder.optimizer_class": "BruteForceBuilder",
  "proxima.qc.builder.thread_count": 10,
  "proxima.qc.builder.optimizer_params": {
    "proxima.linear.builder.column_major_order": true
  },
  "proxima.qc.builder.store_original_features": false,
  "proxima.qc.builder.train_sample_count": 3000000,
  "proxima.qc.builder.train_sample_ratio": 0.5
}

search_index_params的配置如下：

{
  "proxima.qc.searcher.scan_ratio": 0.01
}

4. 配置完成后，點(diǎn)擊保存版本，并在彈框后填寫備注（可選），點(diǎn)擊發(fā)布：

等待索引發(fā)布完成后，可點(diǎn)擊“下一步”進(jìn)行索引重建：

5. 索引重建，選擇索引重建需要配置的參數(shù)項(xiàng)，點(diǎn)擊“下一步”：

• API推送數(shù)據(jù)源：

• MaxCompute數(shù)據(jù)源：

6. 可在運(yùn)維中心>歷史變更>數(shù)據(jù)源變更查看索引重建進(jìn)度，進(jìn)度完成后即可進(jìn)行查詢測(cè)試：

7. 頁(yè)面查詢測(cè)試：

語(yǔ)法說(shuō)明

• 通用查詢：

HA3語(yǔ)法：

query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6...'
注：index_name為向量索引名，后面是要查詢的向量

SQL語(yǔ)法：

query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731"]]
注：index_name為向量索引名，kvpair中的dynamic_params是要查詢的向量

• 指定topN查詢：

HA3語(yǔ)法：

query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10'
注：index_name為向量索引名，后面是要查詢的向量，n指定向量檢索返回的top結(jié)果數(shù)。

SQL語(yǔ)法：

query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10"]]
注：index_name為向量索引名，kvpair中的dynamic_params是要查詢的向量，n指定向量檢索返回的top結(jié)果數(shù)。

• 設(shè)定最低分閾值：

HA3語(yǔ)法：

query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10&sf=0.8'
注：index_name為向量索引名，后面是要查詢的向量，sf指定要過(guò)濾分?jǐn)?shù)的閾值。

SQL語(yǔ)法：

query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10&sf=0.8"]]
注：index_name為向量索引名，kvpair中的dynamic_params是要查詢的向量，sf指定要過(guò)濾分?jǐn)?shù)的閾值。

• 設(shè)置召回參數(shù)：

HA3語(yǔ)法：

query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10&sf=0.8&search_params={"proxima.qc.searcher.scan_ratio":0.001,"proxima.general.searcher.scan_count":10000}'
注：search_params指定向量召回參數(shù)，為json格式。proxima.qc.searcher.scan_ratio含有同上，proxima.general.searcher.scan_count意義同min_scan_doc_cnt
注：n,sf,search_params出現(xiàn)的順序不能變

SQL語(yǔ)法：

query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10&sf=0.8&search_params={"proxima.qc.searcher.scan_ratio":0.001,"proxima.general.searcher.scan_count":10000}"]]

注：index_name為向量索引名，kvpair中的dynamic_params是要查詢的向量，search_params指定向量召回參數(shù)，為json格式。proxima.qc.searcher.scan_ratio含有同上，proxima.general.searcher.scan_count意義同min_scan_doc_cnt
注：n,sf,search_params出現(xiàn)的順序不能變

query=select proxima_score('vector_index_name') as score, cate_id from table_name where MATCHINDEX('vector_index_name', ?) &&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;trace:INFO;formatType:json;dynamic_params:[["168#0.01747940666973591,-0.03125246614217758,-0.03254068270325661..."]]

SDK中使用向量檢索

添加依賴：

pip install alibabacloud-ha3engine

搜索 demo：

from alibabacloud_ha3engine import models, client
from alibabacloud_tea_util import models as util_models
from Tea.exceptions import TeaException, RetryError

def search():
    Config = models.Config(
        endpoint="",
        instance_id="",
        protocol="http",
        access_user_name="",
        access_pass_word=""
    )

    # 如用戶請(qǐng)求時(shí)間較長(zhǎng). 可通過(guò)此配置增加請(qǐng)求等待時(shí)間. 單位 ms
    # 此參數(shù)可在 search_with_options 方法中使用
    runtime = util_models.RuntimeOptions(
        connect_timeout=5000,
        read_timeout=10000,
        autoretry=False,
        ignore_ssl=False,
        max_idle_conns=50
    )
    # 初始化 Ha3Engine Client
    ha3EngineClient = client.Client(Config)
    optionsHeaders = {}
    try:
        # 示例3: 直接使用 ha - sql  查詢串進(jìn)行搜索.
        # =====================================================
        sql_str = '''query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10"]]'''
        sqlsearchQuery = models.SearchQuery(sql=sql_str)
        sqlSearchRequestModel = models.SearchRequestModel(optionsHeaders, sqlsearchQuery)
        sqlstrSearchResponseModel = ha3EngineClient.search(sqlSearchRequestModel)
        print(sqlstrSearchResponseModel)

    except TeaException as e:
        print(f"send request with TeaException : {e}")
    except RetryError as e:
        print(f"send request with Connection Exception  : {e}")


if(__name__  == "__main__"):
    search()

注意事項(xiàng)

• 如果對(duì)向量檢索耗時(shí)有較嚴(yán)格的要求，建議向量索引lock內(nèi)存