亚马逊 OpenSearch 服务的自定义套餐 - 亚马逊 OpenSearch 服务
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

亚马逊 OpenSearch 服务的自定义套餐

Amazon Ser OpenSearch vice 允许您上传自定义词典文件,例如停用词和同义词,还提供多个预打包的可选插件,您可以将这些插件与您的域名相关联。这两种类型的文件的通用术语是软件包

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

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

程序包权限要求

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

  • es:CreatePackage-在 OpenSearch 服务区域创建软件包

  • es:DeletePackage-从 OpenSearch 服务区域删除包裹

  • es:AssociatePackage-将软件包与域关联

  • es:DissociatePackage-将程序包与域取消关联

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

授予 IAM 中的所有权限,而不是域访问策略中的权限。有关更多信息,请参阅亚马逊 OpenSearch 服务中的身份和访问管理

将程序包上传到 Amazon S3

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

如果您的字典包含敏感信息,请在上传时使用 S3 托管密钥指定服务器端加密。 OpenSearch 服务无法访问您使用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 字典)使用多个文件,并且在文件系统上需要自己的目录。目前,S OpenSearch ervice 仅支持单文件字典。

导入和关联程序包

控制台是将自定义词典导入 S OpenSearch ervice 的最简单方法。当您从 Amazon S3 导入字典时, OpenSearch 服务会存储自己的包副本,并使用 OpenSearch 服务托管密钥使用 AES-256 自动加密该副本。

可选插件已预先安装在 S OpenSearch ervice 中,因此您无需自己上传,但需要将插件与域关联起来。控制台的 “软件包” 屏幕上列出了可用的插件。

  1. 在亚马逊 OpenSearch 服务控制台中,选择套餐

  2. 选择 Import package(导入软件包)

  3. 为自定义词典指定一个描述性名称。

  4. 提供文件的 S3 路径,然后选择 Submit(提交)

  5. 返回到 Packages (程序包) 屏幕。

  6. 当程序包状态为 Available (可用) 时,选择它。可选插件将自动可

  7. 选择 “与域关联”。

  8. 选择一个域,然后选择 Associate(关联)

  9. 在导航窗格中,选择您的域,然后选择 Packages (程序包) 选项卡。

  10. 如果包是自定义词典,请记下软件包变为可用时的 ID。在对的请求中analyzers/id用作文件路径 OpenSearch

或者,使用 Amazon CLI、开发工具包或配置 API 导入和关联程序包。有关更多信息,请参阅Amazon CLI命令参考亚马逊 OpenSearch 服务 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 指标,并根据需要扩展集群。

使用可选插件

OpenSearch 服务允许您将预安装的可选 OpenSearch 插件关联到您的域名中。可选的插件包与特定 OpenSearch 版本兼容,并且只能与具有该版本的域名相关联。适用于您的域名的可用软件包列表包括与您的域名版本兼容的所有受支持插件。将插件与域关联后,该域上的安装过程就开始了。然后,当你向 S OpenSearch ervice 发出请求时,你可以引用和使用该插件。

关联和解除关联插件需要蓝/绿部署。有关更多信息,请参阅通常会导发蓝/绿部署的更改

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

可选插件包括语言分析器和自定义搜索结果。例如,Amazon Personalize 搜索排名插件使用机器学习为您的客户对搜索结果进行个性化设置。有关此插件的更多信息,请参阅对搜索结果进行个性化设置。 OpenSearch有关所有支持的插件的列表,请参阅亚马逊 OpenSearch 服务中按引擎版本划分的插件

更新软件包

本节仅介绍如何更新自定义词典包,因为可选的插件包已经为您更新了。将新版本的字典上传到 Amazon S3 不会自动更新亚马逊 OpenSearch 服务上的压缩包。 OpenSearch 服务会存储自己的文件副本,因此,如果您将新版本上传到 S3,则必须手动对其进行更新。

您的每个关联域也存储自己的文件副本。为了保持搜索行为的可预测性,域将继续使用其当前的软件包版本,直到您明确更新它们。要更新自定义软件包,请在中修改文件Amazon S3 Control,在 S OpenSearch ervice 中更新软件包,然后应用更新。

  1. 在 OpenSearch 服务控制台中,选择软件包

  2. 选择一个软件包,然后选择 Update(更新)

  3. 提供文件的 S3 路径,然后选择更新软件包

  4. 返回到 Packages (程序包) 屏幕。

  5. 当程序包状态为 Available (可用) 时,将其选中。然后选择一个或多个关联域,应用更新,并确认。等待关联状态更改为处于活动状态

  6. 下面的步骤因您配置索引的方式而异:

    • 如果您的域名运行 OpenSearch 或 Elasticsearch 7.8 或更高版本,并且仅使用可更新字段设置为 true 的搜索分析器,则无需采取任何进一步的行动。 OpenSearch 服务使用 _plugins/_refresh_search_ analyzers API 自动更新您的索引。

    • 如果您的域运行 Elasticsearch 7.7 或更早版本,使用索引分析器,或者不使用 updateable 字段,请参阅 手动更新词典索引

尽管控制台是最简单的方法,但您也可以使用Amazon CLI、软件开发工具包或配置 API 来更新 OpenSearch 服务包。有关更多信息,请参阅Amazon CLI命令参考亚马逊 OpenSearch 服务 API 参考

您可以使用 SDK 自动执行更新过程,而不是在控制台中手动更新软件包。以下示例 Python 脚本将新的包文件上传到 Amazon S3,更新 OpenSearch 服务中的软件包,并将新包应用于指定的域。确认更新成功后,它会进行示例调用,以 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() 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)
注意

如果您在运行使用 Amazon CLI 的脚本时收到“未找到包”错误,这可能意味着 Boto3 正在使用 ~/.aws/config 中指定的任何区域,而不是您的 S3 存储桶所在的区域。或者运行 aws configure 并指定正确的区域,或者将区域显式添加到客户端:

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

手动更新词典索引

手动索引更新仅适用于自定义词典,不适用于可选插件。要使用更新的词典,如果您满足以下任一条件,则必须手动更新索引:

  • 您的域名运行弹性搜索 7.7 或更早版本。

  • 您可以使用自定义软件包作为索引分析器。

  • 您可以使用自定义软件包作为搜索分析器,但不包括可更新字段中返回的子位置类型。

要使用新的程序包文件更新分析器,您有两种选择:

  • 关闭并打开要更新的任何索引:

    POST my-index/_close POST my-index/_open
  • 重建索引。首先,使用更新的同义词文件(或全新的文件)创建一个索引。请注意,仅支持 UTF-8。

    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 服务中移除包裹并不会将其从 Amazon S3 上的原始位置移除。

  1. 转至 https://aws.amazon.com,然后选择 Sign In to the Console (登录控制台)

  2. 在 “分析” 下,选择 “亚马逊 OpenSearch 服务”。

  3. 在导航窗格中,选择您的域,然后选择 Packages (程序包) 选项卡。

  4. 选择程序包、Actions (操作),然后选择 Dissociate (取消关联)。确认您的选择。

  5. 等待程序包从列表中消失。您可能需要刷新浏览器。

  6. 如果要将程序包与其他域一起使用,请在此处停止。要继续删除软件包(如果是自定义词典),请在导航窗格中选择 Packages。

  7. 选择程序包,然后选择 Delete (删除)

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