Packages personnalisés pour Amazon OpenSearch Service - Amazon OpenSearch Service
Exigences en matière d'autorisations pour les packagesChargement des packages dans Amazon S3Importation et association de packagesUtilisation de packages avec OpenSearchMise à jour des packagesMises à jour manuelles des index pour les dictionnairesDissociation et suppression de packages

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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 :

  • es:CreatePackage- créer un package dans une région OpenSearch de service

  • es:DeletePackage- supprimer un package d'une région OpenSearch de service

  • es:AssociatePackage – permet d'associer un package à un domaine

  • es:DissociatePackage – permet de dissocier un package d'un domaine

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.

  1. Dans la console Amazon OpenSearch Service, choisissez Packages.

  2. Choisissez Import package (Importer un package).

  3. Donnez un nom descriptif au dictionnaire personnalisé.

  4. Indiquez le chemin d'accès S3 au fichier, puis choisissez Submit (Envoyer).

  5. Revenez à l'écran Packages.

  6. Lorsque le statut du package est Available (Disponible), sélectionnez-le. Les plugins optionnels seront automatiquement disponibles.

  7. Choisissez Associer à un domaine.

  8. Sélectionnez un domaine, puis choisissez Associate (Associer).

  9. Dans le panneau de navigation, choisissez votre domaine, puis accédez à l'onglet Packages.

  10. Si le package est un dictionnaire personnalisé, notez l'ID lorsque le package devient disponible. À utiliser analyzers/id comme chemin de fichier dans les demandes adressées à OpenSearch.

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 ».

  • Les tokenizers séparent les flux de caractères en tokens (des mots en règle générale) en fonction d'un ensemble de règles. L'exemple le plus simple est le tokenizer whitespace, qui sépare les caractères précédents en token chaque fois qu'il rencontre un caractère espace. Autre exemple plus complexe, le tokenizer standard, qui utilise un ensemble de règles basées sur la grammaire pour parcourir plusieurs langues.

  • Les filtres de token ajoutent, modifient ou suppriment des tokens. Par exemple, le filtre de token « synonym » ajoute des tokens lorsqu'il trouve un mot figurant dans la liste des synonymes. Le filtre de token « stop » supprime les tokens lorsqu'il trouve un mot dans la liste des mots vides.

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

Les fichiers de dictionnaire utilisent l'espace de tas Java proportionnel à leur taille. Par exemple, un fichier de dictionnaire de 2 Go peut consommer 2 Go d'espace de tas sur un nœud. Si vous utilisez des fichiers volumineux, assurez-vous que vos nœuds disposent d'un espace suffisant pour les accueillir. Surveillez la métrique JVMMemoryPressure et mettez votre cluster à l'échelle si nécessaire.

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.

  1. Dans la console OpenSearch de service, choisissez Packages.

  2. Choisissez un package et sélectionnez Update (Mettre à jour).

  3. Indiquez le chemin d'accès S3 au fichier, puis choisissez Update package (Mettre le package à jour).

  4. Revenez à l'écran Packages.

  5. Lorsque le statut du package passe à Available (Disponible), sélectionnez-le. Choisissez ensuite un ou plusieurs domaines associés, sélectionnez Apply update (Appliquer la mise à jour) et confirmez. Attendez que le statut de l'association passe à Actif.

  6. Les étapes suivantes varient en fonction de la façon dont vous avez configuré vos index :

    • Si votre domaine exécute OpenSearch Elasticsearch 7.8 ou version ultérieure et qu'il utilise uniquement des analyseurs de recherche dont le champ modifiable est défini sur true, aucune autre action n'est nécessaire. OpenSearch Le service met automatiquement à jour vos index à l'aide de l'API _plugins/_refresh_search_analyzers.

    • Si votre domaine exécute Elasticsearch 7.7 ou une version antérieure, utilise des analyseurs d'index ou n'utilise pas le updateable champ, consultez. Mises à jour manuelles des index pour les dictionnaires

Bien que la console soit la méthode la plus simple, vous pouvez également utiliser les AWS CLI SDK ou l'API de configuration pour mettre à jour les packages OpenSearch de service. Pour plus d'informations, consultez le AWS CLI Command Reference et le Amazon OpenSearch Service API Reference.

Au lieu de mettre à jour manuellement un package dans la console, vous pouvez utiliser les kits SDK pour automatiser le processus de mise à jour. L'exemple de script Python suivant télécharge un nouveau fichier de package sur Amazon S3, met à jour le package dans OpenSearch Service et applique le nouveau package au domaine spécifié. Après avoir confirmé la réussite de la mise à jour, il lance un exemple d'appel pour OpenSearch démontrer que les nouveaux synonymes ont été appliqués.

Vous devez fournir des valeurs pour host, region, file_name, bucket_name, s3_key, package_id, domain_name et query.

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

Si vous recevez une erreur « package introuvable » lorsque vous exécutez le script à l'aide de AWS CLI, cela signifie probablement que Boto3 utilise la région spécifiée dans ~/.aws/config, qui n'est pas la région dans laquelle se trouve votre compartiment S3. Vous pouvez exécuter aws configure et spécifier la région qui convient, ou bien ajouter explicitement la région dans le client : 

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 :

  • Votre domaine exécute Elasticsearch 7.7. ou une version antérieure.

  • Vous utilisez des packages personnalisés comme analyseurs d'index.

  • Vous utilisez des packages personnalisés comme analyseurs de recherche, mais n'incluez pas le champ actualisable.

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

  • Fermez et ouvrez les index que vous souhaitez mettre à jour :

    POST my-index/_close
POST my-index/_open

  • Réindexez les index. Créez d'abord un index qui utilise le fichier de synonymes mis à jour (ou un tout nouveau fichier). Notez que seul l'UTF-8 est pris en charge.

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

    Réindexez ensuite l'ancien index par rapport à ce nouvel index :

    POST _reindex
{
  "source": {
    "index": "my-index"
  },
  "dest": {
    "index": "my-new-index"
  }
}

    Si vous mettez fréquemment à jour des analyseurs d'index, utilisez des alias d'index pour que le chemin d'accès à l'index le plus récent reste cohérent :

    POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "my-index",
        "alias": "latest-index"
      }
    },
    {
      "add": {
        "index": "my-new-index",
        "alias": "latest-index"
      }
    }
  ]
}

    Si vous n'avez pas besoin de l'ancien index, supprimez-le :

    DELETE my-index

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.

  1. Accédez à https://aws.amazon.com, puis choisissez Se connecter à la console.

  2. Sous Analytics, sélectionnez Amazon OpenSearch Service.

  3. Dans le panneau de navigation, choisissez votre domaine, puis l'onglet Packages.

  4. Sélectionnez un package, Actions, puis choisissez Dissociate (Dissocier). Confirmez votre choix.

  5. Attendez que le package disparaisse de la liste. Vous devrez peut-être actualiser votre navigateur.

  6. Si vous souhaitez utiliser le package avec d'autres domaines, arrêtez le processus ici. Pour continuer à supprimer le package (s'il s'agit d'un dictionnaire personnalisé), choisissez Packages dans le volet de navigation.

  7. Sélectionnez le package et choisissez Delete (Supprimer).

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.