Importar e gerenciar pacotes no Amazon OpenSearch Service

O Amazon OpenSearch Service permite carregar arquivos de dicionários personalizados, como palavras irrelevantes e sinônimos, e também associar plug-ins ao seu domínio. Esses plug-ins podem ser pré-empacotados, personalizados ou de terceiros, o que dá a você flexibilidade para estender a funcionalidade do domínio. O termo genérico para todos esses tipos de arquivos é pacotes.

Permissões obrigatórias

Os usuários sem acesso de administrador exigem determinadas ações do AWS Identity and Access Management (IAM) para gerenciar pacotes:

Você também precisa de permissões no caminho do bucket do Amazon S3 ou no objeto em que o pacote personalizado reside.

Conceda todas as permissões no IAM, e não na política de acesso ao domínio. Para obter mais informações, consulte Gerenciamento de identidade e acesso no Amazon OpenSearch Service.

Carregar pacotes para o Amazon S3

Esta seção aborda como carregar pacotes de dicionários personalizados, já que os pacotes de plug-ins pré-empacotados já estão pré-instalados. Antes de associar um dicionário customizado ao seu domínio, você deverá carregá-lo em um bucket do Amazon S3. Para obter mais informações, consulte Carregar objetos no Manual do usuário do Amazon Simple Storage Service. Plug-ins compatíveis não precisam ser carregados.

Se o dicionário contiver informações confidenciais, especifique a criptografia do lado do servidor com chaves gerenciadas pelo S3 ao carregá-lo. O OpenSearch Service não pode acessar arquivos no S3 que foram protegidos com uma chave do AWS KMS.

Depois de carregar o arquivo, anote o caminho do S3. O formato do caminho é s3://amzn-s3-demo-bucket/file-path/file-name.

Você pode usar o seguinte arquivo de sinônimos para fazer testes. Salve-o como synonyms.txt.

danish, croissant, pastry
ice cream, gelato, frozen custard
sneaker, tennis shoe, running shoe
basketball shoe, hightop

Certos dicionários, como dicionários Hunspell, usam vários arquivos e exigem seus próprios diretórios no sistema de arquivos. No momento, o OpenSearch Service oferece suporte somente a dicionários de arquivo único.

Importação e associação de pacotes

O console é a maneira mais simples de importar um dicionário personalizado para o OpenSearch Service. Quando você importa um dicionário do Amazon S3, o OpenSearch Service armazena sua própria cópia do pacote e a criptografa automaticamente usando AES-256 com chaves gerenciadas de serviço do OpenSearch.

Os plug-ins opcionais já estão pré-instalados no OpenSearch Service, então você não precisa carregá-los, mas é necessário associar um plug-in a um domínio. Os plug-ins disponíveis estão listados na tela Pacotes, no console.

Uso de pacotes com o OpenSearch

Esta seção aborda como usar os dois tipos de pacotes: dicionários personalizados e plug-ins opcionais.

Uso de dicionários customizados

Depois de associar um arquivo a um domínio, será possível usá-lo em parâmetros como synonyms_path, stopwords_path e user_dictionary ao criar tokenizadores e filtros de token. O parâmetro exato varia de acordo com o objeto. Vários objetos oferecem suporte a synonyms_path e stopwords_path, mas user_dictionary é exclusivo para o plug-in kuromoji.

Para o plug-in de análise IK (chinês), você pode carregar um arquivo de dicionário personalizado como um pacote personalizado e associá-lo a um domínio, e o plug-in o seleciona automaticamente sem exigir um parâmetro user_dictionary. Se seu arquivo for um arquivo de sinônimos, use o parâmetro synonyms_path.

O seguinte exemplo adiciona um arquivo de sinônimo a um novo índice:

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"
      }
    }
  }
}

Esta solicitação cria um analisador personalizado para o índice que utiliza o tokenizer padrão e um filtro de token de sinônimo.

Essa solicitação também adiciona um campo de texto (description) ao mapeamento e orienta o OpenSearch a usar o novo analisador como seu analisador de pesquisas. Você pode ver que ele ainda usa o analisador padrão como seu analisador de índices.

Finalmente, observe a linha "updateable": true no filtro de token. Este campo aplica-se somente a analisadores de pesquisas, e não a analisadores de índices, e será crítico se você desejar atualizar o analisador de pesquisas automaticamente.

Para fazer testes, adicione alguns documentos ao índice:

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" }

Depois, pesquise-os usando um sinônimo:

GET my-index/_search
{
  "query": {
    "match": {
      "description": "gelato"
    }
  }
}

Nesse caso, o OpenSearch retorna esta resposta:

{
  "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"
      }
    }]
  }
}

Usar plug-ins pré-empacotados

O OpenSearch Service permite associar plug-ins OpenSearch opcionais pré-instalados para usar com seu domínio. Um pacote de plug-in pré-empacotado é compatível com uma versão específica do OpenSearch e pode ser associado apenas a domínios com essa versão. A lista de pacotes disponíveis para seu domínio inclui todos os plug-ins compatíveis com a versão do seu domínio. Depois de associar um plug-in a um domínio, um processo de instalação no domínio é iniciado. Em seguida, você pode consultar e usar o plug-in ao fazer solicitações ao OpenSearch Service.

Associar e dissociar um plug-in requer uma implantação azul/verde. Para obter mais informações, consulte Alterações que normalmente causam implantações azuis/verdes.

Plug-ins opcionais incluem analisadores de idioma e resultados de pesquisa personalizados. Por exemplo, o plug-in Amazon Personalize Search Ranking usa machine learning para personalizar os resultados da pesquisa para seus clientes. Para obter mais informações sobre esse plug-in, consulte Personalizar resultados de pesquisa do OpenSearch. Para obter uma lista de todos os plug-ins compatíveis, consulte Plug-ins por versão do mecanismo no Amazon OpenSearch Service.

Plug-in Sudachi

Quando você reassocia um arquivo de dicionário do plug-in Sudachi, ele não reflete imediatamente no domínio. O dicionário é atualizado quando a próxima implantação azul/verde é executada no domínio como parte de uma alteração de configuração ou outra atualização. Como alternativa, você pode criar um novo pacote com os dados atualizados, criar um novo índice usando esse novo pacote, reindexar o índice existente ao novo e, em seguida, excluir o índice antigo. Se preferir usar a abordagem de reindexação, use um alias de índice para que não haja interrupções no tráfego.

Além disso, o plug-in Sudachi é compatível apenas com dicionários Sudachi binários, que você pode carregar com a operação da API CreatePackage. Para obter informações sobre o dicionário do sistema pré-construído e o processo para compilar dicionários do usuário, consulte a documentação do Sudachi.

O exemplo a seguir demonstra como usar os dicionários do sistema e do usuário com o tokenizador do Sudachi. Você deve carregar esses dicionários como pacotes personalizados de tipo TXT-DICTIONARY e fornecer seus IDs de pacote nas configurações adicionais.

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"
          }
        }
      }
    }
  }
}

Atualização de pacotes

Esta seção aborda apenas como atualizar um pacote de dicionário personalizado, porque os pacotes de plug-ins pré-empacotados já foram atualizados para você. O carregamento de uma nova versão de um dicionário do Amazon S3 não atualiza automaticamente o pacote no Amazon OpenSearch Service. O OpenSearch Service armazena sua própria cópia do arquivo. Portanto, se você carregar uma nova versão no S3, precisará atualizá-la manualmente.

Cada um dos seus domínios associados armazena sua própria cópia do arquivo também. Para manter o comportamento de pesquisa previsível, os domínios continuarão a usar a versão atual do pacote até que você os atualize explicitamente. Para atualizar um pacote personalizado, modifique o arquivo no Amazon S3 Control, atualize o pacote no OpenSearch Service e, em seguida, aplique a atualização.

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')

Atualizar manualmente os índices com um novo dicionário

As atualizações manuais de índice se aplicam somente aos dicionários personalizados, não aos plug-ins pré-empacotados. Para usar um dicionário atualizado, será necessário atualizar manualmente seus índices se você atender a qualquer uma das seguintes condições:

Para atualizar os analisadores com os novos arquivos de pacote, você tem duas opções:

Dissociação e remoção de pacotes

Desassociar um pacote, seja um dicionário personalizado ou um plug-in pré-empacotado, de um domínio significa que você não poderá mais usar esse pacote ao criar novos índices. Depois que um pacote é dissociado, os índices existentes que estavam usando o pacote não podem mais usá-lo. Você deve remover o pacote de qualquer índice antes de poder dissociá-lo, caso contrário, a dissociação falhará.

O console é a maneira mais simples de dissociar um pacote de um domínio e removê-lo do OpenSearch Service. A remoção de um pacote do OpenSearch Service não o remove de sua localização original no Amazon S3.

Como alternativa, use a AWS CLI, os SDKs ou a API de configuração para dissociar e remover pacotes. Para mais informações, leia Referência de comandos da AWS CLI e Referências de API do Amazon OpenSearch Service.