Packages personnalisés pour Amazon OpenSearch Service

Amazon OpenSearch Service vous permet de télécharger des fichiers de dictionnaire personnalisés, tels que des mots vides et des synonymes, et fournit également plusieurs plug-ins optionnels préemballés que vous pouvez associer à votre domaine. Le terme générique désignant ces deux types de fichiers est « packages ».

Les fichiers de dictionnaire améliorent les résultats de recherche en vous demandant OpenSearch d'ignorer certains mots fréquents ou de traiter des termes tels que « crème glacée », « gelato » et « crème glacée » comme des équivalents. Ils peuvent également améliorer la recherche de radical, comme dans le plugin d'analyse japonais (kuromoji).

Les plugins optionnels peuvent apporter des fonctionnalités supplémentaires à votre domaine. Par exemple, vous pouvez utiliser le plugin Amazon Personalize pour obtenir des résultats de recherche personnalisés. Les plugins facultatifs utilisent le type de ZIP-PLUGIN package. Pour plus d'informations sur les plug-ins facultatifs, consultezPlug-ins par version de moteur dans Amazon OpenSearch Service.

Exigences en matière d'autorisations pour les packages

Les utilisateurs sans accès administrateur ont besoin de certaines actions AWS Identity and Access Management (IAM) pour gérer les packages :

Vous devez également disposer d'autorisations sur le chemin du compartiment Amazon S3 ou l'objet où réside le package personnalisé.

Accordez toutes les autorisations dans IAM, et non dans la stratégie d'accès au domaine. Pour en savoir plus, consultez Identity and Access Management dans Amazon OpenSearch Service.

Chargement des packages dans Amazon S3

Cette section explique comment télécharger des packages de dictionnaires personnalisés, étant donné que les packages de plugins facultatifs sont déjà préinstallés. Avant de pouvoir associer un dictionnaire personnalisé à votre domaine, vous devez le télécharger dans un compartiment Amazon S3. Pour en savoir plus, consultez Chargement d'objets dans le Guide de l'utilisateur Amazon Simple Storage Service. Les plugins pris en charge n'ont pas besoin d'être téléchargés.

Si votre dictionnaire contient des informations sensibles, spécifiez le chiffrement côté serveur avec des clés gérées par S3 lorsque vous le chargez. OpenSearch Le service ne peut pas accéder aux fichiers sur S3 que vous protégez à l'aide d'une AWS KMS clé.

Après avoir chargé le fichier, notez son chemin d'accès S3. Le format du chemin d'accès est s3://bucket-name/file-path/file-name.

Vous pouvez utiliser le fichier de synonymes suivant à des fins de test. Enregistrez-le sous synonyms.txt.

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

Certains dictionnaires, notamment les dictionnaires Hunspell, utilisent plusieurs fichiers et nécessitent leurs propres répertoires sur le système de fichiers. À l'heure actuelle, le OpenSearch Service ne prend en charge que les dictionnaires à fichier unique.

Importation et association de packages

La console est le moyen le plus simple d'importer un dictionnaire personnalisé dans OpenSearch Service. Lorsque vous importez un dictionnaire depuis Amazon S3, OpenSearch Service stocke sa propre copie du package et chiffre automatiquement cette copie à l'aide du protocole AES-256 avec OpenSearch des clés gérées par le service.

Les plugins optionnels sont déjà préinstallés dans OpenSearch Service. Vous n'avez donc pas besoin de les télécharger vous-même, mais vous devez associer un plugin à un domaine. Les plug-ins disponibles sont répertoriés sur l'écran Packages de la console.

Vous pouvez également utiliser les AWS CLI SDK ou l'API de configuration pour importer et associer des packages. Pour plus d'informations, consultez le AWS CLI Command Reference et le Amazon OpenSearch Service API Reference.

Utilisation de packages avec OpenSearch

Cette section explique comment utiliser les deux types de packages : les dictionnaires personnalisés et les plugins optionnels.

Utilisation de dictionnaires personnalisés

Après avoir associé un fichier à un domaine, vous pouvez l'utiliser dans des paramètres tels que synonyms_path, stopwords_path et user_dictionary lors de la création de tokenizers et de filtres de token. Le paramètre exact varie selon l'objet. Plusieurs objets prennent en charge synonyms_path et stopwords_path, mais user_dictionary est exclusif au plugin kuromoji.

Pour le plugin IK (Chinese) Analysis, vous pouvez charger un fichier de dictionnaire personnalisé en tant que package personnalisé et l'associer à un domaine, et le plugin le récupère automatiquement sans avoir besoin d'un paramètre user_dictionary. Si votre fichier est un fichier de synonymes, utilisez le paramètre synonyms_path.

L'exemple suivant ajoute un fichier de synonymes à un nouvel index :

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

Cette demande crée un analyseur personnalisé pour l'index qui utilise le tokenizer standard et un filtre de token « synonym ».

Cette demande ajoute également un champ de texte (description) au mappage et indique OpenSearch d'utiliser le nouvel analyseur comme analyseur de recherche. Vous pouvez constater qu'elle utilise toujours l'analyseur standard comme analyseur d'index.

Enfin, notez la ligne "updateable": true dans le filtre de jeton. Ce champ s'applique uniquement aux analyseurs de recherche, et non aux analyseurs d'index, et il est essentiel si vous souhaitez par la suite mettre automatiquement à jour l'analyseur de recherche.

À des fins de test, ajoutez des documents à l'index :

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

Recherchez-les ensuite en utilisant un synonyme :

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

Dans ce cas, OpenSearch renvoie la réponse suivante :

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

Utilisation de plugins optionnels

OpenSearch Le service vous permet d'associer des OpenSearch plugins optionnels préinstallés à utiliser avec votre domaine. Un package de plug-in optionnel est compatible avec une OpenSearch version spécifique et ne peut être associé qu'à des domaines dotés de cette version. La liste des packages disponibles pour votre domaine inclut tous les plugins compatibles avec la version de votre domaine. Une fois que vous avez associé un plug-in à un domaine, le processus d'installation sur le domaine commence. Ensuite, vous pouvez référencer et utiliser le plugin lorsque vous faites des demandes au OpenSearch Service.

L'association et la dissociation d'un plugin nécessitent un déploiement bleu/vert. Pour plus d’informations, consultez Modifications entraînant généralement des déploiements bleu/vert.

Les plugins optionnels incluent des analyseurs de langue et des résultats de recherche personnalisés. Par exemple, le plugin Amazon Personalize Search Ranking utilise l'apprentissage automatique pour personnaliser les résultats de recherche pour vos clients. Pour plus d'informations sur ce plugin, consultez la section Personnalisation des résultats de recherche à partir de OpenSearch. Pour obtenir la liste de tous les plug-ins pris en charge, consultezPlug-ins par version de moteur dans Amazon OpenSearch Service.

Plug-in Sudachi

Pour le plugin Sudachi, lorsque vous réassociez un fichier de dictionnaire, cela ne se répercute pas immédiatement sur le domaine. Le dictionnaire est actualisé lorsque le prochain déploiement bleu/vert s'exécute sur le domaine dans le cadre d'une modification de configuration ou d'une autre mise à jour. Vous pouvez également créer un nouveau package avec les données mises à jour, créer un nouvel index à l'aide de ce nouveau package, réindexer l'index existant dans le nouvel index, puis supprimer l'ancien index. Si vous préférez utiliser l'approche de réindexation, utilisez un alias d'index afin de ne pas perturber votre trafic.

De plus, le plugin Sudachi ne prend en charge que les dictionnaires Sudachi binaires, que vous pouvez télécharger à l'aide de l'CreatePackageAPI. Pour plus d'informations sur le dictionnaire système prédéfini et le processus de compilation des dictionnaires utilisateur, consultez la documentation de Sudachi.

L'exemple suivant montre comment utiliser les dictionnaires système et utilisateur avec le tokenizer Sudachi. Vous devez télécharger ces dictionnaires sous forme de packages personnalisés avec leur type TXT-DICTIONARY et fournir leurs identifiants de package dans les paramètres supplémentaires.

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

Mise à jour des packages

Cette section explique uniquement comment mettre à jour un package de dictionnaire personnalisé, car les packages de plugins facultatifs sont déjà mis à jour pour vous. Le téléchargement d'une nouvelle version d'un dictionnaire sur Amazon S3 ne met pas automatiquement à jour le package sur Amazon OpenSearch Service. OpenSearch Le service stocke sa propre copie du fichier. Par conséquent, si vous téléchargez une nouvelle version sur S3, vous devez la mettre à jour manuellement.

Chacun de vos domaines associés stocke également sa propre copie du fichier. Pour que le comportement de recherche reste prévisible, les domaines continuent à utiliser leur version actuelle du package jusqu'à ce que vous le mettiez explicitement à jour. Pour mettre à jour un package personnalisé, modifiez le fichier dans Amazon S3 Control, mettez à jour le package dans OpenSearch Service, puis appliquez la mise à jour.

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

Mises à jour manuelles des index pour les dictionnaires

Les mises à jour manuelles de l'index ne s'appliquent qu'aux dictionnaires personnalisés, et non aux plug-ins facultatifs. Pour utiliser un dictionnaire mis à jour, vous devez mettre à jour manuellement vos index si vous remplissez l'une des conditions suivantes :

Pour mettre à jour les analyseurs avec les nouveaux fichiers de package, deux options s'offrent à vous :

Dissociation et suppression de packages

Dissocier un package, qu'il s'agisse d'un dictionnaire personnalisé ou d'un plugin optionnel, d'un domaine signifie que vous ne pouvez plus utiliser ce package lorsque vous créez de nouveaux index. Une fois qu'un package est dissocié, les index existants qui l'utilisaient ne peuvent plus l'utiliser. Vous devez supprimer le package de tout index avant de pouvoir le dissocier, sinon la dissociation échoue.

La console est le moyen le plus simple de dissocier un package d'un domaine et de le supprimer du OpenSearch Service. La suppression d'un package du OpenSearch service ne le supprime pas de son emplacement d'origine sur Amazon S3.

Vous pouvez également utiliser les AWS CLI SDK ou l'API de configuration pour dissocier et supprimer les packages. Pour plus d'informations, consultez le AWS CLI Command Reference et le Amazon OpenSearch Service API Reference.