Amazon OpenSearch Service 的定制包裹

Amazon OpenSearch Service 可让您上传自定义字典文件（例如，停用词和同义词），还提供了多个预打包的可选插件，您可以将它们与域关联。这些类型文件的通用术语都是程序包。

字典文件通过告诉 OpenSearch 忽略某些高频字词或将诸如“软冻蛋奶”、”冰淇淋”和“冰激凌”等词语视为等效，从而改善搜索结果。它们也可以改进词干提取，如在日语 (kuromoji) 分析插件中。

可选插件可以为您的域提供更多功能。例如，您可以使用 Amazon Personalize 插件为您提供个性化的搜索结果。可选插件使用 ZIP-PLUGIN 程序包类型。有关可选插件的更多信息，请参阅 Amazon OpenSearch 服务中按引擎版本划分的插件。

程序包权限要求

没有管理员权限的用户需要某些 Amazon Identity and Access Management (IAM) 操作来管理软件包：

您还需要对自定义软件包所在的 Amazon S3 存储桶路径或对象的权限。

授予 IAM 中的所有权限，而不是域访问策略中的权限。有关更多信息，请参阅 Amazon OpenSearch Service 中的 Identity and Access Management。

将程序包上传到 Amazon S3

因为已预安装了可选的插件包，所以本节介绍如何上传自定义字典程序包。在您将自定义字典与域关联之前，您必须将其上传到 Amazon S3 存储桶。有关说明，请参阅 Amazon Simple Storage Service 用户指南中的上传对象。受支持的插件无需上传。

如果字典包含敏感信息，请在上传时指定使用 S3 托管密钥的服务器端加密。OpenSearch Service 无法访问您使用 Amazon 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 中已预安装了可选插件，因此您无需上传插件，但需要将其与域关联起来。控制台中的程序包屏幕上列出了可用的插件。

或者，使用 Amazon CLI、开发工具包或配置 API 导入和关联程序包。有关更多信息，请参阅Amazon 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 搜索排名插件使用机器学习，为您的客户进行搜索结果的个性化设置。有关此插件的更多信息，请参阅个性化 OpenSearch 的搜索结果。有关受支持插件的完整列表，请参阅 Amazon OpenSearch 服务中按引擎版本划分的插件。

Sudachi 插件

对于 Sudachi 插件，当您重新关联字典文件时，它不会立即反映在域上。当作为配置更改或其他更新的一部分在域上运行下一个蓝绿部署时，字典会刷新。您也可以使用更新后的数据创建新的程序包，使用此新程序包创建新索引，利用现有索引重新创建新索引，然后删除旧索引。如果您更喜欢使用重新编制索引的方法，请使用索引别名，这样您的流量就不会受到干扰。

此外，Sudachi 插件仅支持二进制 Sudachi 字典，您可以使用 CreatePackage API 操作上传这些字典。有关预先构建的系统字典和编译用户字典流程的信息，请参阅 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 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 上的原始位置移除。

或者，使用 Amazon CLI、开发工具包或配置 API 取消程序包关联并删除程序包。有关更多信息，请参阅Amazon CLI 命令参考和 Amazon OpenSearch Service API 参考。