Amazon OpenSearch Service 的自訂套件

Amazon OpenSearch Service 可讓您上傳自訂字典檔案，例如停止單字和同義詞，也提供數個預先封裝的選用外掛程式，您可以與網域建立關聯。這兩種檔案類型的一般術語都是套件。

字典檔案會告訴 OpenSearch 忽略某些高頻詞，或將 frozen custard (軟香乳凍)、gelato (義式冰淇淋) 和 ice cream (冰淇淋) 等術語視為相同字詞，以改善您的搜尋結果。它們還可以提高字根還原的能力，例如在 Japanese (kuromoji) Analysis 分析外掛程式。

選用的外掛程式可以為您的網域提供新增的功能。例如，您可以使用 Amazon Personalize 外掛程式來為您提供個人化的搜尋結果。選用外掛程式使用 ZIP-PLUGIN套件類型。如需選用外掛程式的詳細資訊，請參閱依 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://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 受管金鑰自動加密該複本。

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

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

搭配 OpenSearch 使用套件

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

使用自訂字典

將檔案與網域建立關聯後，您可以在建立分詞器和字符篩選條件時在 synonyms_path、stopwords_path 和 user_dictionary 等參數中使用該檔案。確切的參數因物件而異。多個物件可支援 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 參考。