Importación y administración de paquetes en Amazon OpenSearch Service

Amazon OpenSearch Service le permite cargar archivos de diccionario personalizados, como listas de palabras vacías (stop words) y sinónimos y asociar complementos con su dominio. Estos complementos pueden ser preempaquetados, personalizados o de terceros, lo que le brinda flexibilidad para ampliar la funcionalidad de su dominio. El término genérico para referirse a todos estos tipos de archivos es paquetes.

Permisos necesarios

Los usuarios sin acceso de administrador requieren ciertas acciones de AWS Identity and Access Management (IAM) para administrar paquetes:

También necesita permisos en la ruta del bucket de Amazon S3 u objeto donde reside el paquete personalizado.

Otorgue todos los permisos en IAM, no en la política de acceso al dominio. Para más información, consulte Identity and Access Management en Amazon OpenSearch Service.

Carga de paquetes en Amazon S3

Esta sección explica cómo cargar paquetes de diccionarios personalizados, dado que los paquetes de complementos prediseñados ya están instalados. Antes de poder asociar un diccionario personalizado a un dominio, debe cargarlo en un bucket de Amazon S3. Para ver las instrucciones, consulte Carga de objetos en la Guía del usuario de Amazon Simple Storage Service. No es necesario cargar los complementos admitidos.

Si el diccionario contiene información confidencial, especifique el cifrado del servidor mediante claves administradas por S3 al cargarlo. El Servicio OpenSearch no puede acceder a archivos en S3 protegidos con una clave AWS KMS.

Después de cargar el archivo, tome nota de su ruta de S3. El formato de la ruta es s3://amzn-s3-demo-bucket/file-path/file-name.

Puede utilizar el siguiente archivo de sinónimos para fines de prueba. Guárdelo como synonyms.txt.

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

Algunos diccionarios, como los diccionarios Hunspell, utilizan varios archivos y requieren sus propios directorios en el sistema de archivos. En este momento, OpenSearch Service solo admite diccionarios de un solo archivo.

Importación y asociación de paquetes

La consola es la forma más sencilla de importar un diccionario personalizado a OpenSearch Service. Al importar un diccionario desde Amazon S3, OpenSearch Service almacena su propia copia del paquete y cifra automáticamente esa copia mediante AES-256 con claves administradas por OpenSearch Service.

Los complementos opcionales ya vienen preinstalados en OpenSearch Service, por lo que no es necesario que los cargue usted mismo, pero sí debe asociar un complemento a un dominio. Los complementos disponibles aparecen en la pantalla Paquetes de la consola.

Uso de paquetes con OpenSearch

Esta sección explica cómo usar ambos tipos de paquetes: diccionarios personalizados y complementos prediseñados.

Uso de diccionarios personalizados

Después de asociar un archivo a un dominio, puede usarlo en parámetros como synonyms_path, stopwords_path y user_dictionary al crear generadores de tokens y filtros de token. El parámetro exacto varía según el objeto. Varios objetos admiten synonyms_path y stopwords_path, pero user_dictionary es exclusivo del complemento kuromoji.

Para el complemento IK (chino) Analysis, puede cargar un archivo de diccionario personalizado en forma de paquete personalizado y asociarlo a un dominio, y el complemento lo recogerá automáticamente sin necesidad de parámetro user_dictionary. Si se trata de un archivo de sinónimos, utilice el parámetro synonyms_path.

El siguiente ejemplo agrega un archivo de sinónimos a un nuevo í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 solicitud crea un analizador personalizado para el índice que utiliza el generador de tokens estándar y un filtro de token de sinónimos.

Esta solicitud también agrega un campo de texto (description) al mapeo e indica a OpenSearch que utilice el nuevo analizador como analizador de búsqueda. Puede ver que todavía utiliza el analizador estándar como analizador de índices.

Por último, tenga en cuenta la línea "updateable": true en el filtro de token. Este campo solo se aplica a los analizadores de búsqueda, no a los analizadores de índice, y es crítico si luego desea actualizar el analizador de búsqueda de forma automática.

Con fines de prueba, agregue algunos documentos al í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" }

A continuación, use un sinónimo para buscarlos:

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

En este caso, OpenSearch devuelve la siguiente respuesta:

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

Uso de complementos preempaquetados

El servicio OpenSearch le permite asociar complementos de OpenSearch opcionales y preinstalados para usarlos con su dominio. Un paquete de complementos preempaquetados es compatible con una versión específica de OpenSearch y solo se puede asociar a los dominios con esa versión. La lista de paquetes disponibles para su dominio incluye todos los complementos compatibles con la versión de su dominio. Después de asociar un complemento a un dominio, comienza un proceso de instalación en el dominio. Luego, puede hacer referencia al complemento y usarlo cuando realice solicitudes a OpenSearch Service.

Asociar y disociar un complemento requiere una implementación azul/verde. Para más información, consulte Cambios que suelen causar implementaciones azul/verde.

Los complementos opcionales incluyen analizadores de idioma y resultados de búsqueda personalizados. Por ejemplo, el complemento Amazon Personalize Search Ranking utiliza machine learning para personalizar los resultados de búsqueda para sus clientes. Para obtener más información sobre este complemento, consulte Personalización de los resultados de búsqueda desde OpenSearch. Para ver una lista de todos los complementos admitidos, consulte Complementos según la versión de motor en Amazon OpenSearch Service.

Complemento Sudachi

En el caso del complemento Sudachi, al volver a asociar un archivo de diccionario, no se refleja inmediatamente en el dominio. El diccionario se actualiza cuando se ejecuta la siguiente implementación azul/verde en el dominio como parte de un cambio de configuración u otra actualización. Como alternativa, puede crear un nuevo paquete con los datos actualizados, crear un nuevo índice con un nuevo paquete, volver a indexar el índice existente en el nuevo índice y, a continuación, eliminar el índice anterior. Si prefiere utilizar el enfoque de reindexación, utilice un alias de índice para que no se interrumpa el tráfico.

Además, el complemento Sudachi solo admite diccionarios binarios de Sudachi, que puede cargar con la operación de API CreatePackage. Para obtener información sobre el diccionario del sistema prediseñado y el proceso de compilación de diccionarios de usuario, consulte Documentación de Sudachi.

En el siguiente ejemplo, se muestra cómo utilizar los diccionarios de sistema y de usuario con el tokenizador de Sudachi. Debe cargar estos diccionarios como paquetes personalizados con el tipo TXT-DICTIONARY y proporcionar sus ID de paquete en la configuración adicional.

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

Actualización de paquetes

En esta sección solo se explica cómo actualizar un paquete de diccionarios personalizados, ya que los paquetes de complementos preempaquetados ya están actualizados. Al cargar una nueva versión de un diccionario en Amazon S3, no se actualiza automáticamente el paquete en Amazon OpenSearch Service. OpenSearch Service almacena su propia copia del archivo, por lo que si carga una nueva versión en S3, debe actualizarla de forma manual.

Cada uno de los dominios asociados también almacena su propia copia del archivo. Para mantener el comportamiento de búsqueda predecible, los dominios siguen utilizando la versión actual del paquete hasta que los actualice explícitamente. Para actualizar un paquete personalizado, modifique el archivo en Amazon S3 Control, actualice el paquete en OpenSearch Service y, a continuación, aplique la actualización.

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

Actualización manual de los índices con un nuevo diccionario

Las actualizaciones manuales de índices solo se aplican a los diccionarios personalizados, no a los complementos preempaquetados. Para utilizar un diccionario actualizado, debe actualizar de forma manual los índices, si cumple alguna de las siguientes condiciones:

Para actualizar los analizadores con los nuevos archivos de paquete, dispone de dos opciones:

Disociación y eliminación de paquetes

Si disocia un paquete de un dominio, ya sea un diccionario personalizado o un complemento preempaquetado, ya no podrá usar ese paquete cuando cree nuevos índices. Una vez disociado un paquete, los índices existentes que utilizaban el paquete ya no pueden usarlo. Debe eliminar el paquete de cualquier índice antes de poder disociarlo; de lo contrario, la disociación fallará.

La consola es la forma más sencilla de disociar un paquete de un dominio y eliminarlo de OpenSearch Service. La eliminación de un paquete de OpenSearch Service no lo elimina de la ubicación original en Amazon S3.

Si lo prefiere, puede usar la AWS CLI, los SDK o la API de configuración para disociar y eliminar paquetes. Para más información, consulte AWS CLI Command Reference y Amazon OpenSearch Service API Reference.