Pacchetti personalizzati per il servizio OpenSearch di Amazon - Amazon OpenSearch Service

Pacchetti personalizzati per il servizio OpenSearch di Amazon

Il servizio OpenSearch di Amazon consente di caricare file dizionario personalizzati (ad esempio stop word e sinonimi) da utilizzare con il cluster. Il termine generico per questi tipi di file è pacchetti. I file del dizionario migliorano i risultati della ricerca dicendo a OpenSearch di ignorare determinate parole ad alta frequenza o di trattare termini come "crema congelata", "gelato" e "ice cream" come equivalenti. Possono anche migliorare lo stemming, ad esempio nel plug-in di analisi del giapponese (kuromoji).

Requisiti di autorizzazioni per i pacchetti

Gli utenti senza accesso da amministratore richiedono determinate operazioni AWS Identity and Access Management (IAM) per gestire i pacchetti:

  • es:CreatePackage: creazione di un pacchetto in una regione di OpenSearch Service

  • es:DeletePackage: eliminazione di un pacchetto da una regione di OpenSearch Service

  • es:AssociatePackage: associazione di un pacchetto a un dominio

  • es:DissociatePackage: dissociazione di un pacchetto da un dominio

Sono necessarie anche le autorizzazioni per il percorso del bucket Amazon S3 o l'oggetto in cui si trova il pacchetto personalizzato.

Concedere tutte le autorizzazioni all'interno di IAM, non nella policy di accesso al dominio. Per ulteriori informazioni, consultare Gestione di accessi e identità nel servizio OpenSearch di Amazon.

Caricamento di pacchetti in Amazon S3

Per associare un pacchetto al dominio, occorre prima caricarlo in un bucket Amazon S3. Per le istruzioni, consulta Caricamento di oggetti nella Guida per l'utente di Amazon Simple Storage Service.

Se il pacchetto contiene informazioni sensibili, specifica la crittografia lato server con chiavi gestite da S3 al momento del caricamento. OpenSearch Service non è in grado di accedere ai file in S3 protetti tramite una chiave AWS KMS.

Dopo aver caricato il file, prendi nota del suo percorso S3. Il formato del percorso è s3://bucket-name/file-path/file-name.

Puoi utilizzare il file di sinonimi seguente per scopi di test. Salvalo come synonyms.txt.

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

Alcuni dizionari, ad esempio i dizionari Hunspell, utilizzano più file e richiedono proprie directory nel file system. Al momento, OpenSearch Service supporta solo dizionari a file singolo.

Importazione e associazione di pacchetti

La console è il modo più semplice per importare un pacchetto in OpenSearch Service e associarlo a un dominio. Quando si importa un pacchetto da Amazon S3, OpenSearch Service memorizza la propria copia del pacchetto e ne esegue automaticamente la crittografia utilizzando AES-256 con chiavi gestite da OpenSearch Service.

Per importare e associare un pacchetto a un dominio (console)

  1. Nella console del servizio OpenSearch di Amazon, scegli Pacchetti.

  2. Scegli Importa pacchetto.

  3. Assegna al pacchetto un nome descrittivo.

  4. Fornisci il percorso S3 del file e quindi scegli Invia.

  5. Torna alla schermata Pacchetti.

  6. Quando lo stato del pacchetto è Disponibile, selezionalo. Quindi scegli Associate to a domain (Associare a un dominio).

  7. Seleziona un dominio, quindi scegli Associate (Associa).

  8. Nel riquadro di navigazione, scegli il dominio e accedi alla scheda Pacchetti.

  9. Quando lo stato del pacchetto è Disponibile, prendi nota del relativo ID. Utilizzare analyzers/id come percorso del file nelle richieste a OpenSearch.

In alternativa, utilizza la AWS CLI, gli SDK o l'API di configurazione per importare e associare pacchetti. Per ulteriori informazioni, consultare Riferimento ai comandi AWS CLI e Riferimento dell'API di configurazione per il servizio OpenSearch di Amazon.

Utilizzo di pacchetti personalizzati con OpenSearch

Dopo aver associato un file a un dominio, puoi utilizzarlo nei parametri, ad esempio synonyms_path, stopwords_path e user_dictionary, quando crei tokenizer e filtri token. Il parametro esatto varia in base all'oggetto. Diversi oggetti supportano synonyms_path e stopwords_path, ma user_dictionary è esclusivo per il plugin kuromoji.

Per il plug-in IK (Chinese) Analysis, è possibile caricare un file di dizionario personalizzato come pacchetto personalizzato e associarlo a un dominio e il plug-in lo raccoglie automaticamente senza richiedere un parametro user_dictionary. Se il file è un file di sinonimi, usa il parametro synonyms_path.

Nel seguente esempio viene aggiunto un file di sinonimi a un nuovo indice:

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

Questa richiesta crea un analizzatore personalizzato per l'indice che utilizza il tokenizer standard e un filtro token sinonimo.

  • I tokenizer scompongono i flussi di caratteri in token (generlamente parole) in base a una serie di regole. L'esempio più semplice è il tokenizer whitespace, che scompone i caratteri precedenti in un token ogni volta che incontra un carattere whitespace. Un esempio più complesso è il tokenizer standard, che utilizza un insieme di regole grammaticali per gestire numerose lingue.

  • I filtri token aggiungono, modificano o eliminano token. Ad esempio, un filtro token sinonimo aggiunge token quando trova una parola nell'elenco dei sinonimi. Il filtro token di arresto rimuove i token quando trova una parola nell'elenco di stop word.

Questa richiesta aggiunge anche un campo di testo (description) alla mappatura e indica a OpenSearch di utilizzare il nuovo analizzatore come analizzatore di ricerca. Si può vedere che come analizzatore di indice è utilizzato ancora l'analizzatore standard.

Infine, prendere nota della riga "updateable": true nel filtro token. Questo campo si applica solo agli analizzatori di ricerca non agli analizzatori di indice, ed è critico se in seguito si desidera aggiornare l'analizzatore di ricerca automaticamente.

A scopo di test, aggiungi alcuni documenti all'indice:

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

Cercali, quindi, utilizzando un sinonimo:

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

In questo caso, OpenSearch restituisce la seguente risposta:

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

I file del dizionario utilizzano spazio heap Java proporzionale alle loro dimensioni. Ad esempio, un file dizionario di 2 GiB potrebbe consumare su un nodo 2 GiB di spazio heap. Se utilizzi file di notevoli dimensioni, accertati che lo spazio heap dei nodi sia sufficiente a contenerli. Monitora il parametro JVMMemoryPressure e dimensiona il cluster in base alla necessità.

Aggiornamento di pacchetti personalizzati (console)

Il caricamento di una nuova versione di un pacchetto in Amazon S3 non aggiorna automaticamente il pacchetto sul servizio OpenSearch di Amazon. OpenSearch Service memorizza la propria copia del file, quindi se si carica una nuova versione su S3, sarà necessario aggiornarla manualmente.

Ciascuno dei domini associati archivia anche la propria copia del file. Per mantenere un comportamento di ricerca prevedibile, i domini continueranno a utilizzare la versione corrente del pacchetto fino a quando non vengono aggiornati esplicitamente. Per aggiornare un pacchetto personalizzato, modifica il file in Amazon S3 Control, aggiorna il pacchetto nel servizio OpenSearch e applica l'aggiornamento.

  1. Nella console del servizio OpenSearch, scegli Pacchetti.

  2. Scegli un pacchetto, quindi seleziona Aggiorna.

  3. Fornisci il percorso S3 del file e scegli Aggiorna pacchetto.

  4. Torna alla schermata Pacchetti.

  5. Quando lo stato del pacchetto è Disponibile, selezionarlo. Scegliere uno o più domini associati, selezionare Applica aggiornamento e confermare. Attendere che lo stato dell'associazione cambi in Attivo.

  6. I passaggi successivi variano a seconda di come sono stati configurati gli indici:

    • Se i domini eseguono OpenSearch o Elasticsearch 7.8 o versioni successive e utilizzano solo analizzatori di ricerca con il campo aggiornabile impostato su true, non è necessario eseguire altre operazioni. OpenSearch Service aggiorna automaticamente gli indici utilizzando l'API _plugins/_refresh_search_analyzers.

    • Se il dominio esegue Elasticsearch 7.7 o versioni precedenti, utilizza gli analizzatori di indice o non utilizza il campo updateable, consultare Aggiornamenti manuali degli indici.

Nonostante la console rappresenti il metodo più semplice, per aggiornare i pacchetti di OpenSearch Service è possibile utilizzare anche la AWS CLI, gli SDK o l'API di configurazione. Per ulteriori informazioni, consulta Riferimento ai comandi AWS CLI e Riferimento dell'API di configurazione per il servizio OpenSearch di Amazon.

Aggiornamento di pacchetti personalizzati (SDK AWS)

Invece di aggiornare manualmente un pacchetto nella console, puoi utilizzare gli SDK per automatizzare il processo di aggiornamento. Lo script Python di esempio seguente carica un nuovo file di pacchetto in Amazon S3, aggiorna il pacchetto in OpenSearch Service e applica il nuovo pacchetto al dominio specificato. Dopo aver confermato che l'aggiornamento ha avuto esito positivo, effettua una chiamata di esempio a OpenSearch dimostrando che i nuovi sinonimi sono stati applicati.

È necessario fornire valori per host, region, file_name, bucket_name, s3_key, package_id, domain_name e 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)
Nota

Se quando si esegue lo script dalla AWS CLI viene visualizzato un errore "package not found" (pacchetto non trovato), è probabile che Boto3 stia usando una qualsiasi regione specificata in ~/.aws/config, che non è la regione in cui si trova il bucket S3. Esegui aws configure e specifica la regione corretta oppure aggiungi esplicitamente la regione al client:

client = boto3.client('opensearch', region_name='us-east-1')

Aggiornamenti manuali degli indici

Per utilizzare un pacchetto aggiornato, occorre aggiornare manualmente gli indici se si verifica una delle seguenti condizioni:

  • Il dominio esegue Elasticsearch 7.7 o versioni precedenti.

  • I pacchetti personalizzati vengono utilizzati come analizzatori di indice.

  • I pacchetti personalizzati vengono utilizzati come analizzatori di ricerca, ma non includono il campo aggiornabile.

Per aggiornare gli analizzatori con i file del nuovo pacchetto, sono disponibili due opzioni:

  • Chiudi e apri gli indici da aggiornare:

    POST my-index/_close POST my-index/_open
  • Reindicizzare gli indici. Innanzitutto, crea un indice che utilizza il file dei sinonimi aggiornato (o un file completamente nuovo):

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

    Reindicizza, quindi, il vecchio indice nel nuovo indice:

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

    Se gli analizzatori di indice vengono aggiornati con una certa frequenza, utilizzare gli alias di indice per mantenere un percorso coerente per l'indice più recente:

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

    Se il vecchio indice non è necessario, eliminarlo.

    DELETE my-index

Dissociazione e rimozione di pacchetti

Dissociare un pacchetto da un dominio significa che non è più possibile utilizzare quel file quando si creano nuovi indici. Tutti gli indici che già utilizzano il file possono continuare a utilizzarlo.

La console costituisce il metodo più semplice per dissociare un pacchetto da un dominio e rimuoverlo dal servizio OpenSearch. La rimozione di un pacchetto da OpenSearch Service non lo rimuove dalla posizione originale in Amazon S3.

Come dissociare un pacchetto da un dominio e rimuoverlo da OpenSearch Service (console)

  1. Accedi all'indirizzo https://aws.amazon.com e scegli Accedi alla console.

  2. In Analisi, scegli Servizio OpenSearch di Amazon.

  3. Nel riquadro di navigazione, scegli il dominio e seleziona la scheda Pacchetti.

  4. Scegliere un pacchetto, selezionare Operazioni, quindi scegliere Dissocia. Conferma la scelta.

  5. Attendi che il pacchetto scompaia dall'elenco. Potrebbe essere necessario aggiornare il browser.

  6. Per utilizzare il pacchetto con altri domini, interrompi l’operazione a questo punto. Per continuare a rimuovere il pacchetto, scegli Pacchetti nel riquadro di navigazione.

  7. Seleziona il pacchetto e scegli Elimina.

In alternativa, utilizza la AWS CLI, gli SDK o l'API di configurazione per dissociare e rimuovere pacchetti. Per ulteriori informazioni, consultare Riferimento ai comandi AWS CLI e Riferimento dell'API di configurazione per il servizio OpenSearch di Amazon.