Amazon OpenSearch Service 的自訂套件 - Amazon OpenSearch Service

Amazon OpenSearch Service 的自訂套件

Amazon OpenSearch Service 可讓您上傳自訂字典檔案 (例如,停止字詞和同義字),以便與叢集搭配使用。這些類型檔案的通用術語是 packages (套件)。字典檔案會告訴 OpenSearch 忽略某些高頻詞,或將 frozen custard (軟香乳凍)、gelato (義式冰淇淋) 和 ice cream (冰淇淋) 等術語視為相同字詞,以改善您的搜尋結果。它們還可以提高字根還原的能力,例如在 Japanese (kuromoji) Analysis 分析外掛程式。

套件許可要求

沒有管理員存取權的使用者需要特定 AWS Identity and Access Management (IAM) 動作來管理套件:

  • es:CreatePackage - 在 OpenSearch Service 區域中建立套件

  • es:DeletePackage - 從 OpenSearch Service 區域中刪除套件

  • es:AssociatePackage - 將套件關聯到網域

  • es:DissociatePackage - 取消套件與網域的關聯

您也需要自訂套件所在的 Amazon S3 儲存貯體路徑或物件的許可。

授予 IAM 內的所有許可,而不是在網域存取政策中。如需詳細資訊,請參閱 Amazon OpenSearch Service 中的 Identity and Access Management

將套件上傳至 Amazon S3

您必須先將套件上傳至 Amazon S3 儲存貯體,才能將套件與網域產生關聯。如需指示說明,請參閱 Amazon Simple Storage Service 使用者指南中的上傳物件

如果您的套件包含敏感資訊,請在上傳時使用 S3 管理的金鑰指定伺服器端加密。OpenSearch Service 無法存取使用 AWS KMS 金鑰保護的 S3 上的檔案。

上傳檔案後,請記下其 S3 路徑。路徑格式為 s3://bucket-name/file-path/file-name

您可以使用下列同義字檔案進行測試。另存為 synonyms.txt

danish, croissant, pastry ice cream, gelato, frozen custard sneaker, tennis shoe, running shoe basketball shoe, hightop

某些字典 (例如 Hunspell 字典) 會使用多個檔案並要求在檔案系統上使用自己的字典。目前,OpenSearch Service 僅支援單一檔案字典。

匯入和關聯套件

主控台是將套件匯入 OpenSearch Service 並將套件與網域建立關聯的最簡單方法。當您從 Amazon S3 匯入套件時,OpenSearch Service 會儲存自己的套件副本,並搭配使用 AES-256 與 OpenSearch Service 管理的金鑰來自動加密該副本。

匯入套件並將其與網域 (主控台) 建立關聯

  1. 在 Amazon OpenSearch Service 主控台中,選擇 Packages (套件)。

  2. 選擇 Import package (匯入套件)。

  3. 為套件提供描述性名稱。

  4. 提供檔案的 S3 路徑,然後選擇 Submit (提交)。

  5. 返回 Packages (套件) 畫面。

  6. 當封裝狀態為 Available (可用) 時,請加以選取。然後選擇 Associate to a domain (關聯至網域)

  7. 選取網域,然後選擇 Associate (關聯)。

  8. 在導覽窗格中,選擇您的網域,然後移至 Packages (套件) 索引標籤。

  9. 當封裝狀態為 Available (可用) 時,請記下其 ID。使用 analyzers/id 作為對 OpenSearch 的請求中的檔案路徑。

或者,您也可以使用 AWS CLI、SDK 或組態 API 來匯入和關聯套件。如需詳細資訊,請參閱 AWS CLI 命令參考Amazon OpenSearch Service 的組態 API 參考

搭配使用自訂套件與 OpenSearch

將檔案與網域建立關聯後,您可以在建立分詞器和字符篩選條件時在 synonyms_pathstopwords_pathuser_dictionary 等參數中使用該檔案。確切的參數因物件而異。多個物件可支援 synonyms_pathstopwords_path,但 user_dictionary 專屬於 kuromoji 外掛程式。

對於 IK (中文) 分析外掛程式,您可以將自訂字典檔案做為自定套件上傳,並將其與一個網域相關聯,且外掛程式會自動將其掛載,不需要 user_dictionary 參數。如果您的檔案是同義詞檔案,請使用 synonyms_path 參數。

以下範例會將同義字檔案新增至新索引:

PUT my-index { "settings": { "index": { "analysis": { "analyzer": { "my_analyzer": { "type": "custom", "tokenizer": "standard", "filter": ["my_filter"] } }, "filter": { "my_filter": { "type": "synonym", "synonyms_path": "analyzers/F111111111", "updateable": true } } } } }, "mappings": { "properties": { "description": { "type": "text", "analyzer": "standard", "search_analyzer": "my_analyzer" } } } }

此請求建立使用標準分詞器和同義詞字符篩選條件索引的自訂分析器。

  • 分詞器會根據一組規則將字符分解為字符 (通常是字詞)。最簡單的例子是空格分詞器,每次遇到一個空白字符時,便會將前面的字元分解為字符。一個更複雜的例子是標準分詞器,它會使用一組基於語法的規則跨多種語言作業。

  • 字符篩選條件會新增、修改或刪除字符。例如,同義字字符篩選條件會在同義字清單中找到單字時加入字符。停止字符篩選條件會在停止字詞清單中找到字詞時移除標記。

此請求還會將一個文字欄位 (description) 新增至映射,並讓 OpenSearch 使用新分析器作為其搜尋分析器。你可以看到它仍然使用標準分析器作為其索引分析器。

最後,請注意字符篩選器中的 "updateable": true 行。此欄位僅適用於搜尋分析器,不適用於索引分析器,如果您稍後想要自動更新搜尋分析器,此欄位就非常重要。

為了測試,我們加入了一些文件索引:

POST _bulk { "index": { "_index": "my-index", "_id": "1" } } { "description": "ice cream" } { "index": { "_index": "my-index", "_id": "2" } } { "description": "croissant" } { "index": { "_index": "my-index", "_id": "3" } } { "description": "tennis shoe" } { "index": { "_index": "my-index", "_id": "4" } } { "description": "hightop" }

然後使用同義詞來搜尋它們:

GET my-index/_search { "query": { "match": { "description": "gelato" } } }

在這種情況下,OpenSearch 會傳回以下回應:

{ "hits": { "total": { "value": 1, "relation": "eq" }, "max_score": 0.99463606, "hits": [{ "_index": "my-index", "_type": "_doc", "_id": "1", "_score": 0.99463606, "_source": { "description": "ice cream" } }] } }
提示

字典檔案使用與其大小呈正比的 Java 堆積空間。例如,2 GiB 的字典檔案可能會在節點上使用 2 GiB 的堆積空間。如果您使用大型檔案,請確保節點有足夠的堆積空間可容納這些檔案。監控 JVMMemoryPressure 指標,並視需要擴展您的叢集。

更新自訂套件

將套件的新版本上傳到 Amazon S3 並不會自動更新 Amazon OpenSearch Service 上的套件。OpenSearch Service 會儲存自己的檔案副本,因此如果您將新版本上傳到 S3,則必須手動更新。

每個關聯網域也都會儲存自己的檔案副本。為了保持搜尋行為可預測,網域會繼續使用其目前的套件版本,直到您明確更新它們為止。

更新自訂套件 (主控台)

若要更新自訂套件,請在 Amazon S3 Control 中修改檔案,在 OpenSearch Service 中更新套件,然後套用更新。

  1. 在 OpenSearch Service 主控台中,選擇 Packages (套件)。

  2. 選擇套件和 Update (更新)。

  3. 提供檔案的 S3 路徑,然後選擇 Update package (更新套件)。

  4. 返回 Packages (套件) 畫面。

  5. 當套件狀態變為 Available (可用) 時,請加以選取。然後選擇一個或多個關聯網域,選擇 Apply update (套用更新) 並確認。等待關聯狀態變為 Active (作用中)。

  6. 接下來的步驟會有所不同,這取決於您如何設定索引:

    • 如果您的網域執行 OpenSearch 或 Elasticsearch 7.8 或更高版本,並且只使用搜尋分析器,且 updateable (可更新) 欄位設定為 true,您便無需採取進一步的動作。OpenSearch Service 會使用 _plugins/_refresh_search_analyzers API 自動更新您的索引。

    • 如果您的網域執行 Elasticsearch 7.7 或更早版本,則使用索引分析器,或者不使用 updateable 欄位,請參閱手動索引更新

雖然主控台是最簡單的方法,但是您也可以使用 AWS CLI、開發套件或組態 API 來更新 OpenSearch Service 套件。如需詳細資訊,請參閱 AWS CLI 命令參考Amazon OpenSearch Service 的組態 API 參考

自動化套件更新 (Python)

您可以使用開發套件來自動化更新程序,而不是在主控台中手動更新套件。以下範例 Python 指令碼會將新的套件檔案上傳到 Amazon S3,在 OpenSearch Service 中更新套件,並將新套件套用到指定網域。確認更新成功後,它會對 OpenSearch 進行範例呼叫,以證明已套用新的同義詞。

您必須提供 hostregionfile_namebucket_names3_keypackage_iddomain_namequery 的值。

from requests_aws4auth import AWS4Auth import boto3 import requests import time import json import sys host = '' # The OpenSearch domain endpoint with https:// and a trailing slash. For example, https://my-test-domain.us-east-1.es.amazonaws.com/ region = '' # For example, us-east-1 file_name = '' # The path to the file to upload bucket_name = '' # The name of the S3 bucket to upload to s3_key = '' # The name of the S3 key (file name) to upload to package_id = '' # The unique identifier of the OpenSearch package to update domain_name = '' # The domain to associate the package with query = '' # A test query to confirm the package has been successfully updated service = 'es' credentials = boto3.Session().get_credentials() awsauth = AWS4Auth(credentials.access_key, credentials.secret_key, region, service, session_token=credentials.token) # ****** Upload file to S3 ****** def upload_to_s3(file_name, bucket_name, s3_key): s3 = boto3.client('s3') try: s3.upload_file(file_name, bucket_name, s3_key) print('Upload successful') return True except FileNotFoundError: sys.exit('File not found. Make sure you specified the correct file path.') # ****** Update the package in OpenSearch Service ******* def update_package(package_id, bucket_name, s3_key): opensearch = boto3.client('opensearch') print(package_id, bucket_name, s3_key) response = opensearchservice.update_package( PackageID= package_id, PackageSource={ 'S3BucketName': bucket_name, 'S3Key': s3_key } ) print(response) # Associate the package to the domain def associate_package(package_id, domain_name): opensearch = boto3.client('opensearch') response = opensearch.associate_package(PackageID=package_id, DomainName=domain_name) print(response) print('Associating...') # Wait for the package to be updated def wait_for_update(domain_name, package_id): opensearch = boto3.client('opensearch') response = opensearch.list_packages_for_domain(DomainName=domain_name) package_details = response['DomainPackageDetailsList'] for package in package_details: if package['PackageID'] == package_id: status = package['DomainPackageStatus'] if status == 'ACTIVE': print('Association successful.') return elif status == 'ASSOCIATION_FAILED': sys.exit('Association failed. Please try again.') else: time.sleep(10) # Wait 10 seconds before rechecking the status wait_for_update(domain_name, package_id) # ****** Make sample search call to OpenSearch ****** def sample_search(query): path = '_search' params = {'q': query} url = host + path response = requests.get(url, params=params, auth=awsauth) print('Searching for ' + '"' + query + '"') print(response.text)
注意

如果您在使用 AWS CLI 執行指令碼時收到「找不到套件」錯誤,這可能意味著 Boto3 正在使用 ~/.aws/config 中指定的任何區域,這不是您的 S3 儲存貯體所在的區域。執行 aws configure 並指定正確的區域,或者明確地將區域新增至用戶端:

opensearchservice = boto3.client('opensearchservice', region_name='us-east-1')

手動索引更新

若要使用更新的套件,您必須手動更新索引,前提是您符合下列任何條件:

  • 您的網域執行 Elasticsearch 7.7 或更早版本。

  • 您使用自訂套件作為索引分析器。

  • 您使用自訂套件作為搜索分析器,但不包含 updateable (可更新) 欄位。

若要使用新套件檔案更新分析器,您有兩個選項:

  • 關閉並開啟您要更新的任何索引:

    POST my-index/_close POST my-index/_open
  • 對索引進行重新索引。首先,建立使用更新的同義字檔案的索引 (或全新檔案):

    PUT my-new-index { "settings": { "index": { "analysis": { "analyzer": { "synonym_analyzer": { "type": "custom", "tokenizer": "standard", "filter": ["synonym_filter"] } }, "filter": { "synonym_filter": { "type": "synonym", "synonyms_path": "analyzers/F222222222" } } } } }, "mappings": { "properties": { "description": { "type": "text", "analyzer": "synonym_analyzer" } } } }

    然後將舊索引重新索引到該新索引:

    POST _reindex { "source": { "index": "my-index" }, "dest": { "index": "my-new-index" } }

    如果您經常更新索引分析器,請使用索引別名來維持最新索引的一致路徑:

    POST _aliases { "actions": [ { "remove": { "index": "my-index", "alias": "latest-index" } }, { "add": { "index": "my-new-index", "alias": "latest-index" } } ] }

    如果您不需要舊索引,請將其刪除:

    DELETE my-index

解除關聯並移除套件

將套件與網域關聯代表當您建立新索引時,您無法再使用該檔案。任何已經使用該文件的索引都可以繼續使用它。

主控台是將套件與網域解除關聯並將其從 OpenSearch Service 中移除的最簡單方法。從 OpenSearch Service 中移除套件並不會將其從 Amazon S3 上的原始位置中移除。

將套件與網域解除關聯並將其從 OpenSearch Service (主控台) 中移除

  1. 前往 https://aws.amazon.com,然後選擇 Sign In to the Console (登入主控台)

  2. Analytics (分析) 下,選擇 Amazon OpenSearch Service

  3. 在導覽窗格中,選擇您的網域,然後選擇 Packages (套件) 標籤。

  4. 選擇套件,Actions (動作),然後選擇 Dissociate (解除關聯)。確認您的選擇。

  5. 等待套件從清單中消失。您可能需要重新整理瀏覽器。

  6. 如果您想要將套件與其他網域搭配使用,請在這裡停止。若要繼續移除套件,請選擇導覽窗格中的 Packages (套件)

  7. 選取套件並選擇 Delete (刪除)

或者,您也可以使用 AWS CLI、SDK 或設定 API 來解除關聯和移除套件。如需詳細資訊,請參閱 AWS CLI 命令參考Amazon OpenSearch Service 的組態 API 參考