在 Amazon OpenSearch Service 中匯入和管理套件

Amazon OpenSearch Service 可讓您上傳自訂字典檔案，例如停止單字和同義詞，並將外掛程式與您的網域建立關聯。這些外掛程式可以是預先封裝、自訂或第三方，可讓您彈性擴展網域的功能。所有這些類型檔案的一般術語都是套件。

所需的許可

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

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

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

將套件上傳至 Amazon S3

本節說明如何上傳自訂字典套件，因為已安裝預先封裝的外掛程式套件。您必須先將其上傳至 Amazon S3 儲存貯體，才能將自訂字典與您的網域建立關聯。如需指示說明，請參閱 Amazon Simple Storage Service 使用者指南中的上傳物件。不需要上傳支援的外掛程式。

如果您的字典包含敏感資訊，請在上傳時以 S3-managed金鑰指定伺服器端加密。OpenSearch Service 無法存取您使用 AWS KMS 金鑰保護的 S3 中的檔案。

上傳檔案後，請記下其 S3 路徑。路徑格式為 s3://amzn-s3-demo-bucket/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 受管金鑰自動加密該複本。

選用外掛程式已預先安裝在 OpenSearch Service 中，因此您不需要自行上傳，但您需要將外掛程式與網域建立關聯。可用的外掛程式會列在 主控台的套件畫面上。

搭配 OpenSearch 使用套件

本節說明如何使用兩種類型的套件：自訂字典和預先封裝的外掛程式。

使用自訂字典

將檔案與網域建立關聯後，您可以在建立權杖化程式和權杖篩選條件user_dictionary時synonyms_path，將其用於參數，例如 stopwords_path、 和 。確切的參數因物件而異。多個物件可支援 synonyms_path 和 stopwords_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"
      }
    }]
  }
}

使用預先封裝的外掛程式

OpenSearch Service 可讓您將預先安裝的選用 OpenSearch 外掛程式與網域建立關聯。預先封裝的外掛程式套件與特定 OpenSearch 版本相容，而且只能與該版本的網域建立關聯。您網域的可用套件清單包含與您的網域版本相容的所有支援外掛程式。將外掛程式與網域建立關聯後，網域上的安裝程序就會開始。然後，您可以在向 OpenSearch Service 提出請求時參考和使用外掛程式。

關聯和取消關聯外掛程式需要藍/綠部署。如需詳細資訊，請參閱通常會導致藍/綠部署的變更。

選用的外掛程式包括語言分析器和自訂搜尋結果。例如，Amazon Personalize Search Ranking 外掛程式使用機器學習來為您的客戶個人化搜尋結果。如需此外掛程式的詳細資訊，請參閱從 OpenSearch 個人化搜尋結果。如需所有支援的外掛程式清單，請參閱 依 Amazon OpenSearch Service 中引擎版本區分的外掛程式。

Sudachi 外掛程式

對於 Sudachi 外掛程式，當您重新關聯字典檔案時，它不會立即反映在網域上。當下一個藍/綠部署在網域上執行時，字典會重新整理，作為組態變更或其他更新的一部分。或者，您可以使用更新的資料建立新的套件、使用此新套件建立新的索引、將現有索引重新索引為新索引，然後刪除舊索引。如果您偏好使用重新索引方法，請使用索引別名，以免流量中斷。

此外，Sudachi 外掛程式僅支援二進位 Sudachi 字典，您可以使用 CreatePackage API 操作來上傳。如需有關預先建置的系統字典和編譯使用者字典程序的資訊，請參閱 Sudachi 文件。

下列範例示範如何使用系統和使用者字典搭配 Sudachi 權杖化工具。您必須將這些字典上傳為具有 類型的自訂套件，TXT-DICTIONARY並在其他設定中提供其套件 IDs。

PUT sudachi_sample
{
  "settings": {
    "index": {
      "analysis": {
        "tokenizer": {
          "sudachi_tokenizer": {
            "type": "sudachi_tokenizer",
            "additional_settings": "{\"systemDict\": \"<system-dictionary-package-id>\",\"userDict\": [\"<user-dictionary-package-id>\"]}"
        }
        },
        "analyzer": {
          "sudachi_analyzer": {
            "filter": ["my_searchfilter"],
            "tokenizer": "sudachi_tokenizer",
            "type": "custom"
          }
        },
        "filter":{
          "my_searchfilter": {
            "type": "sudachi_split",
            "mode": "search"
          }
        }
      }
    }
  }
}

更新套件

本節僅涵蓋如何更新自訂字典套件，因為預先封裝的外掛程式套件已為您更新。將新版本的字典上傳至 Amazon S3 並不會自動更新 Amazon OpenSearch Service 上的套件。OpenSearch Service 會儲存自己的檔案副本，因此如果您將新版本上傳到 S3，則必須手動更新。

每個關聯網域也都會儲存其自己的檔案副本。為了保持搜尋行為可預測，網域會繼續使用其目前的套件版本，直到您明確更新它們為止。若要更新自訂套件，請在 中修改 檔案 Amazon S3 Control、在 OpenSearch Service 中更新套件，然後套用更新。

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()
client = boto3.client('opensearch')
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key,
                   region, service, session_token=credentials.token)


def upload_to_s3(file_name, bucket_name, s3_key):
    """Uploads file to S3"""
    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.')


def update_package(package_id, bucket_name, s3_key):
    """Updates the package in OpenSearch Service"""
    print(package_id, bucket_name, s3_key)
    response = client.update_package(
        PackageID=package_id,
        PackageSource={
            'S3BucketName': bucket_name,
            'S3Key': s3_key
        }
    )
    print(response)


def associate_package(package_id, domain_name):
    """Associates the package to the domain"""
    response = client.associate_package(
        PackageID=package_id, DomainName=domain_name)
    print(response)
    print('Associating...')


def wait_for_update(domain_name, package_id):
    """Waits for the package to be updated"""
    response = client.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)


def sample_search(query):
    """Makes a sample search call to OpenSearch"""
    path = '_search'
    params = {'q': query}
    url = host + path
    response = requests.get(url, params=params, auth=awsauth)
    print('Searching for ' + '"' + query + '"')
    print(response.text)

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

使用新的字典手動更新索引

手動索引更新僅適用於自訂字典，不適用於預先封裝的外掛程式。若要使用更新的字典，如果您符合下列任何條件，則必須手動更新索引：

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

解除關聯並移除套件

從網域取消套件的關聯，無論是自訂字典或預先封裝的外掛程式，都表示您無法在建立新索引時再使用該套件。取消套件的關聯後，使用套件的現有索引就無法再使用它。您必須從任何索引移除套件，才能將其取消關聯，否則取消關聯會失敗。

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

或者，使用 、 AWS CLI SDKs或組態 API 來取消關聯和移除套件。如需詳細資訊，請參閱 AWS CLI 命令參考和 Amazon OpenSearch Service API 參考。