Importação e gerenciamento de pacotes no Amazon Service OpenSearch

O Amazon OpenSearch Service permite carregar arquivos de dicionário personalizados, por exemplo, palavras irrelevantes e sinônimos, e associar plug-ins ao seu domínio. Esses plug-ins podem ser pré-empacotados, personalizados ou de terceiros, o que oferece flexibilidade para ampliar a funcionalidade do seu 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 Identity and Access Management no Amazon OpenSearch Service.

Carregar pacotes para o Amazon S3

Esta seção aborda como carregar pacotes de dicionários personalizados, já que pacotes de plug-ins pré-empacotados já estão 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 sigilosas, especifique a criptografia do lado do servidor com chaves gerenciadas pelo S3 ao carregá-lo. OpenSearch O serviço não pode acessar arquivos no S3 protegidos por uma AWS KMS chave do.

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 Serviço 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 Serviço. 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 pelo serviço. OpenSearch

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.

Usando pacotes com OpenSearch

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

Uso de dicionários customizados

Depois de associar um arquivo a um domínio, você pode usá-lo em parâmetros como synonyms_pathstopwords_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 uso do novo analisador como seu analisador de pesquisas. OpenSearch 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, OpenSearch retorna a seguinte 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"
      }
    }]
  }
}

Usando plug-ins pré-empacotados

OpenSearch O serviço permite associar OpenSearch plug-ins opcionais pré-instalados para usar com seu domínio. Um pacote de plug-in pré-empacotado é compatível com uma OpenSearch versão específica e só pode ser associado 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 Serviço.

Associar e dissociar um plug-in requer uma implantação azul/verde. Para obter mais informações, consulte Mudanças que geralmente causam blue/green implantações.

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 de OpenSearch. Para obter uma lista de todos os plug-ins compatíveis, consulte Plugins 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 com tipo TXT-DICTIONARY e fornecer seus pacotes IDs 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 pacotes de plug-ins pré-empacotados já são atualizados para você. O upload de uma nova versão de um dicionário do Amazon S3 não atualiza automaticamente o pacote no Amazon OpenSearch Service. OpenSearch O serviço 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')

Atualização manual de índices com um novo dicionário

As atualizações manuais do índice se aplicam somente a dicionários personalizados, não a 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

Dissociar 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 Serviço não o remove de sua localização original no Amazon S3.

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