Amazon OpenSearch 服務的定制包

Amazon Ser OpenSearch vice 可讓您上傳自訂字典檔案 (例如停用字和同義字)，並提供數個預先封裝的選用外掛程式，讓您與網域建立關聯。這兩種類型的文件的通用術語是包。

字典文件通過告訴忽略某些高頻單詞或 OpenSearch 將諸如「冰淇淋」，「意式冰淇淋」和「冰淇淋」等詞語對待，從而改善您的搜索結果。它們還可以提高字根還原的能力，例如在 Japanese (kuromoji) Analysis 分析外掛程式。

可選插件可以為您的域提供附加功能。例如，您可以使用 Amazon Personalize 外掛程式為您提供個人化的搜尋結果。可選插件使用ZIP-PLUGIN包類型。如需選用外掛程式的詳細資訊，請參閱Amazon OpenSearch Service 中依引擎版本的外掛程式。

套件許可要求

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

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

授予 IAM 內的所有許可，而不是在網域存取政策中。如需詳細資訊，請參閱 Amazon OpenSearch Service 中的身分和存取管理。

將套件上傳至 Amazon S3

本節介紹了如何上傳自定義字典包，因為可選插件包已經預先安裝。您必須先將自訂字典上傳到 Amazon S3 儲存貯體，才能將自訂字典與網域建立關聯。如需指示說明，請參閱 Amazon Simple Storage Service 使用者指南中的上傳物件。支持的插件不需要上傳。

如果您的字典包含敏感資訊，請在上傳時使用 S3 管理的金鑰指定伺服器端加密。 OpenSearch 服務無法存取您使用 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 服務僅支援單一檔案字典。

匯入和關聯套件

控制台是將自定義字典導入 OpenSearch 服務的最簡單方法。當您從 Amazon S3 匯入字典時， OpenSearch 服務會存放自己的套件副本，並使用 AES-256 與 OpenSearch 服務受管金鑰自動加密該副本。

可選插件已經預先安裝在 OpenSearch 服務中，因此您不需要自己上傳它們，但您確實需要將插件與域關聯。可用的外掛程式會列在主控台的「套件」畫面上。

或者，使用 AWS CLI、SDK 或設定 API 匯入和關聯套件。如需詳細資訊，請參閱AWS CLI 命令參考和 Amazon OpenSearch 服務 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 服務可讓您將預先安裝的選用 OpenSearch 外掛程式與網域建立關聯。選用的外掛程式套件與特定 OpenSearch 版本相容，而且只能與該版本的網域相關聯。您網域的可用套件清單包括所有支援與您的網域版本相容的外掛程式。將外掛程式與網域建立關聯後，網域上的安裝程序便會開始。然後，您可以在向 OpenSearch 服務發出請求時引用並使用該插件。

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

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

酢橘插件

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

此外，Sudachi 插件僅支持二進制 Sudachi 字典，您可以通過 CreatePackageAPI 操作上傳該字典。有關預構建的系統字典和用於編譯用戶字典的過程的信息，請參閱 Sudachi 文檔。

下面的示例演示瞭如何將系統和用戶字典與 Sudachi 標記生成器一起使用。您必須將這些字典上傳為具有類型的自訂套件，TXT-DICTIONARY並在其他設定中提供其套件 ID。

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 服務上的套件。 OpenSearch 服務會儲存自己的檔案副本，因此如果您將新版本上傳到 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 從 OpenSearch 服務移除套件並不會將其從 Amazon S3 上的原始位置移除。

或者，使用 AWS CLI、SDK 或設定 API 來分離和移除套件。如需詳細資訊，請參閱AWS CLI 命令參考和 Amazon OpenSearch 服務 API 參考。