View a markdown version of this page

Pipelines d'inférence ML dans Amazon OpenSearch Sans serveur - Amazon OpenSearch Service

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.

Pipelines d'inférence ML dans Amazon OpenSearch Sans serveur

Le ml_inference processeur sur Amazon OpenSearch Serverless est un processeur polyvalent qui appelle un modèle d'apprentissage automatique configuré et associe les entrées et les sorties du modèle à des champs de document ou de requête. Vous contrôlez le mappage à l'aide du input_map et output_map paramètres, qui spécifient les champs de document ou de requête qui fournissent l'entrée du modèle et les champs qui reçoivent la sortie du modèle.

Contrairement aux processeurs d'apprentissage automatique spécialement conçus tels que text_embedding, text_image_embedding, et sparse_encoding, qui prennent chacun en charge un seul type de modèle, le ml_inference le processeur fonctionne avec n'importe quel modèle configuré. Il peut également être exécuté à la fois dans les pipelines d'ingestion et dans les pipelines de recherche. Vous pouvez donc appliquer l'inférence de modèle lors de l'indexation, avant l'exécution d'une requête ou après le renvoi des résultats. Utilisez le ml_inference processeur lorsque vous avez besoin d'un modèle ou d'un mappage d'entrées et de sorties que les processeurs spécialement conçus ne fournissent pas. Pour une documentation conceptuelle complète, voir Processeur d'inférence ML sur le OpenSearch Documentation site web.

Vous pouvez utiliser le ml_inference processeur pour prendre en charge des flux de travail tels que les suivants :

  • Recherche sémantique

  • Retrieval-augmented génération (RAG)

  • Recherche multimodale

  • Récapitulatif des résultats

  • Enrichissement des requêtes

Conditions préalables

Avant d'utiliser le ml_inference processeur, effectuez les opérations suivantes :

  • Créez une collection de recherches vectorielles. OpenSearch Serverless prend en charge les ml_inference processeur sur les collections de recherche vectorielle (type VECTORSEARCH) dans un NextGen groupe de collecte. OpenSearch Serverless accepte uniquement les modèles dotés d'un function_name de remote. Pour créer le groupe de collections, voir Création d'un groupe de collection. Pour créer la collection, voir Utilisation de collections de recherche vectorielle. Activez les répliques de secours à la fois sur le groupe de collection et sur la collection.

    Les suivants AWS CLI l'exemple crée un NextGen groupe de collections et une collection de recherche vectorielle qu'il contient. Remplacer my-collection-group et my-collection avec vos propres noms.

    aws opensearchserverless create-collection-group \ --name my-collection-group \ --generation NEXTGEN \ --standby-replicas ENABLED \ --capacity-limits maxIndexingCapacityInOCU=8,maxSearchCapacityInOCU=8 aws opensearchserverless create-collection \ --name my-collection \ --type VECTORSEARCH \ --collection-group-name my-collection-group \ --standby-replicas ENABLED
  • Configurez et déployez un modèle distant. Le processeur appelle un modèle distant configuré et déployé, que vous référencez par son ID de modèle. Pour un exemple de configuration d'un modèle d'intégration Amazon Titan, voir Exemple : configurer un modèle d'intégration Amazon Titan. Pour plus d’informations, consultez Configurer le Machine Learning sur Amazon OpenSearch Serverless.

  • Signez vos demandes. Signez chaque demande adressée au point de terminaison de collecte avec AWS Signature version 4 utilisant le nom du service aoss. Pour plus d’informations, consultez Signature des demandes HTTP avec d'autres clients.

Exemple : configurer un modèle d'intégration Amazon Titan

Les exemples de cette rubrique utilisent un modèle Amazon Titan Text Embeddings V2 dans Amazon Bedrock. Les étapes suivantes permettent de créer le connecteur et le modèle de votre collection.

  1. Créez un rôle IAM qui OpenSearch Serverless suppose d'appeler Amazon Bedrock. La politique de confiance du rôle doit permettre ml.opensearchservice.amazonaws.com principal de service, et la politique d'autorisations du rôle doit autoriser bedrock:InvokeModel sur le modèle. Le principal qui crée le connecteur doit également iam:PassRole sur ce rôle.

  2. Créez le connecteur. Remplacer region avec le Région AWS du modèle Amazon Bedrock, account-id avec votre AWS identifiant de compte, et bedrock-role avec le nom du rôle de l'étape précédente.

    POST /_plugins/_ml/connectors/_create { "name": "Amazon Bedrock Titan Text Embeddings V2", "description": "Connector for amazon.titan-embed-text-v2:0", "version": 1, "protocol": "aws_sigv4", "parameters": { "region": "region", "service_name": "bedrock", "model": "amazon.titan-embed-text-v2:0" }, "credential": { "roleArn": "arn:aws:iam::account-id:role/bedrock-role" }, "actions": [ { "action_type": "predict", "method": "POST", "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke", "headers": { "content-type": "application/json", "x-amz-content-sha256": "required" }, "request_body": "{ \"inputText\": \"${parameters.inputText}\" }", "post_process_function": "connector.post_process.bedrock.embedding" } ] }

    La réponse contient l'ID du connecteur. Le post_process_function le réglage renvoie l'intégration à $.inference_results[0].output[0].data, qui est le chemin utilisé dans les exemples de cette rubrique.

  3. Enregistrez le modèle à l'aide du connecteur. Remplacer my-connector-id avec l'ID du connecteur de l'étape précédente.

    POST /_plugins/_ml/models/_register { "name": "titan-embed-text-v2", "function_name": "remote", "description": "Amazon Titan Text Embeddings V2", "connector_id": "my-connector-id" }

    La réponse contient l'ID du modèle.

  4. Déployez le modèle. Remplacer my-model-id avec l'identifiant du modèle de l'étape précédente.

    POST /_plugins/_ml/models/my-model-id/_deploy
  5. Testez le modèle à l'aide de l'API de prédiction, comme indiqué dans Adaptez le processeur à votre modèle.

Ces étapes nécessitent les autorisations suivantes sur le model type de ressource : aoss:CreateMLResource pour créer le connecteur et enregistrer le modèle, aoss:UpdateMLResource pour le déployer, et aoss:ExecuteMLResource pour appeler l'API de prédiction. Pour un exemple de politique d'accès aux données qui accorde ces autorisations, voir Configuration des autorisations pour le Machine Learning.

Adaptez le processeur à votre modèle

Le ml_inference le processeur ne connaît pas la forme de votre modèle. Tu le racontes avec input_map et output_map. Si celles-ci ne correspondent pas à l'API de prédiction du modèle, le processeur échoue ou écrit la mauvaise valeur. Testez d'abord le modèle avec l'API de prédiction, puis copiez les noms des paramètres et le chemin de sortie dans votre pipeline.

Le tableau suivant indique l'origine de chaque partie du mappage.

Mappage Ce qu'il doit correspondre
Entrez input_map Un nom de paramètre dans la demande de prédiction, qui est un ${parameters.name} espace réservé dans le connecteur request_body.
Valeur en input_map Le champ de document, ou champ de requête, qui fournit la valeur.
Entrez output_map Nom du champ qui reçoit la sortie du modèle.
Valeur en output_map Un chemin JSON vers la réponse de prédiction, par exemple $.inference_results[0].output[0].data.

L'exemple suivant appelle l'API de prédiction pour un modèle d'intégration de texte. Le inputText le paramètre est le même nom que celui que l'exemple de pipeline d'ingestion utilise comme clé dans input_map. Remplacer my-model-id avec l'ID de votre modèle déployé.

POST /_plugins/_ml/models/my-model-id/_predict { "parameters": { "inputText": "Example document text" } }

Le modèle renvoie une réponse semblable à la suivante. Le data le tableau est raccourci pour des raisons de lisibilité.

{ "inference_results": [ { "output": [ { "name": "sentence_embedding", "data_type": "FLOAT32", "shape": [1024], "data": [0.0123, -0.0456, 0.0789] } ], "status_code": 200 } ] }

L'intégration se trouve dans le data tableau de la première sortie. Le chemin JSON $.inference_results[0].output[0].data le sélectionne. Il s'agit du chemin que l'exemple de pipeline d'ingestion utilise dans output_map.

Note

Cette forme de réponse s'applique lorsque le connecteur d'intégration Amazon Titan définit post_process_function pour connector.post_process.bedrock.embedding. Sans fonction de post-traitement, le vecteur est à $.inference_results[0].output[0].dataAsMap.embedding au lieu de cela. Pour la configuration des connecteurs, voir Configurer le Machine Learning sur Amazon OpenSearch Serverless.

Important

Les paramètres de demande et la forme de la réponse dépendent du modèle et de son connecteur. Lorsque vous utilisez un autre modèle, ne réutilisez pas les chemins des exemples de cette rubrique. Exécutez l'API de prédiction pour votre modèle et lisez les chemins à partir de sa réponse.

Par exemple, un grand modèle de langage qui renvoie sa réponse brute a une forme différente. Le texte est imbriqué dans dataAsMap objet, et le paramètre que vous envoyez est nommé d'après l'espace réservé au connecteur au lieu de inputText.

POST /_plugins/_ml/models/my-llm-model-id/_predict { "parameters": { "messages": "[{\"role\":\"user\",\"content\":[{\"text\":\"Summarize: Example text\"}]}]" } }
{ "inference_results": [ { "output": [ { "name": "response", "dataAsMap": { "output": { "message": { "role": "assistant", "content": [ { "text": "A short summary of the example text." } ] } }, "stopReason": "end_turn" } } ], "status_code": 200 } ] }

Pour cette réponse, le chemin JSON est $.inference_results[0].output[0].dataAsMap.output.message.content[0].text. La structure exacte sous dataAsMap est la réponse de votre fournisseur de modèles, elle diffère donc selon les fournisseurs et les modèles.

Pour changer de modèle de processeur, procédez comme suit :

  1. Trouvez les noms des paramètres dans request_body du connecteur du modèle. Chaque ${parameters.name} l'espace réservé est un nom que vous pouvez utiliser comme clé dans input_map.

  2. Appelez l'API de prédiction avec une valeur d'échantillon pour chaque paramètre.

  3. Lisez la réponse de prédiction et écrivez le chemin JSON vers la valeur que vous souhaitez conserver.

  4. Mettre à jour model_id, input_map, et output_map dans le pipeline.

  5. Exécutez le _simulate API sur un exemple de document pour confirmer que le champ de sortie possède la valeur que vous attendez.

Note

L'API de prédiction nécessite aoss:ExecuteMLResource autorisation sur la ressource modèle. Pour plus d’informations, consultez Configurer le Machine Learning sur Amazon OpenSearch Serverless.

Utilisation de ml_inference dans un pipeline d'ingestion

Dans un pipeline d'ingestion, le ml_inference le processeur exécute l'inférence de modèle lors de l'indexation. Une utilisation courante consiste à générer des intégrations vectorielles à partir d'un champ de texte afin que vous puissiez effectuer une recherche sémantique sur vos données. Le input_map mappe un champ de document à l'entrée du modèle, et le output_map écrit la sortie du modèle dans un nouveau champ.

L'exemple suivant crée un pipeline qui envoie le text champ dans le modèle et écrit l'intégration renvoyée dans un embedding champ. Remplacer my-pipeline avec le nom de votre pipeline et my-model-id avec l'ID de votre modèle déployé.

PUT _ingest/pipeline/my-pipeline { "description": "Generates embeddings with a configured model", "processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "input_map": [ { "inputText": "text" } ], "output_map": [ { "embedding": "$.inference_results[0].output[0].data" } ] } } ] }

La demande renvoie la réponse suivante :

{ "acknowledged": true }

Le output_map le chemin est enraciné dans inference_results parce que full_response_path est réglé sur true. Ce paramètre évalue le chemin de sortie par rapport à la réponse complète du modèle. Pour plus d'informations, voir Processeur d'inférence ML sur le OpenSearch Documentation site web.

Avant d'appliquer le pipeline au trafic réel, vous pouvez le simuler par rapport à des exemples de documents à l'aide du _simulate point final. Pour exécuter automatiquement l'inférence de modèle sur chaque document indexé dans un index, définissez le index.default_pipeline réglage lors de la création de l'index. Vous pouvez également spécifier le pipeline sur une demande d'indexation individuelle avec le pipeline paramètre de requête. Pour plus d'informations sur la création, la simulation et l'application de pipelines d'ingestion, voir Pipelines d'ingestion sur Amazon OpenSearch Sans serveur.

L'exemple suivant indexe un document et exécute le pipeline. Remplacer my-index avec le nom de votre index et my-pipeline avec le nom de votre pipeline.

POST my-index/_doc?pipeline=my-pipeline { "text": "Example document text" }

La réponse confirme que le document a été indexé :

{ "_index": "my-index", "_id": "93VTg6EBtHTIBjFym5yW", "_version": 1, "result": "created", "_shards": { "total": 0, "successful": 0, "failed": 0 }, "_seq_no": 0, "_primary_term": 0 }
Note

L'index cible doit être configuré pour la recherche vectorielle. Activer index.knn et mappez le champ de sortie (par exemple, embedding) en tant que knn_vector champ dont la dimension correspond à votre modèle.

Dans un pipeline de recherche, le ml_inference le processeur exécute l'inférence de modèle dans le cadre d'une requête. Un processeur de requêtes de recherche transforme ou réécrit la requête avant son exécution. Un processeur de réponses de recherche enrichit les résultats avant que vous ne les receviez. Pour exécuter un pipeline de recherche, envoyez la demande avec search_pipeline paramètre de requête. Remplacer my-index avec le nom de votre index et my-pipeline avec le nom de votre pipeline.

POST my-index/_search?search_pipeline=my-pipeline

Pour créer ou mettre à jour un pipeline de recherche, envoyez le corps du pipeline au _search/pipeline point de terminaison, comme le montrent les exemples des sections suivantes.

Note

L'effet d'un pipeline de recherche nouvellement créé peut prendre quelques minutes, même après le retour de la demande de création "acknowledged": true. D'ici là, les requêtes de recherche qui font référence au pipeline échouent avec un Pipeline my-pipeline is not defined erreur. Réessayez la demande après une courte attente.

Processeur de demandes de recherche

Vous utilisez un processeur de requêtes de recherche pour réécrire une requête entrante avant OpenSearch Serverless l'exécute. L'exemple suivant utilise le texte d'un match requête, génère un vecteur à partir de celle-ci avec un modèle configuré et réécrit la demande dans une requête K-nN avec le query_template paramètre. OpenSearch Serverless remplace le ${query_vec} espace réservé dans le modèle avec la sortie du modèle qui output_map capture. Remplacer my-model-id avec l'ID de votre modèle déployé.

PUT /_search/pipeline/my-pipeline { "request_processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "query_template": "{\"size\":2,\"_source\":[\"text\"],\"query\":{\"knn\":{\"embedding\":{\"vector\":${query_vec},\"k\":2}}}}", "input_map": [ { "inputText": "query.match.text.query" } ], "output_map": [ { "query_vec": "$.inference_results[0].output[0].data" } ], "ignore_missing": true } } ] }

Set full_response_path pour true afin que le output_map Le chemin JSON est résolu par rapport à la réponse complète du modèle. Cela vous permet d'utiliser le même chemin de sortie que celui que vous avez lu dans la réponse de l'API de prédiction.

Set ignore_missing pour true lorsque le champ source est peut-être absent. Une requête qui ne contient pas le champ mappé, tel qu'un match_all requête, puis passe inchangée au lieu d'échouer. Le processeur réécrit toujours les requêtes qui contiennent le champ.

Processeur de réponse à la recherche

Un processeur de réponse de recherche s'exécute après le retour d'une requête, afin que vous puissiez enrichir ou résumer chaque résultat. L'exemple suivant envoie le text champ de chaque accès vers un modèle configuré et écrit la sortie du modèle dans un text_vec champ. Set one_to_one pour true de sorte que le processeur exécute le modèle une fois pour chaque résultat de recherche. La valeur par défaut est false, qui envoie tous les accès au modèle en une seule requête, et les modèles qui n'attendent qu'une seule valeur d'entrée rejettent cette demande. Remplacer my-model-id avec l'ID de votre modèle déployé.

PUT /_search/pipeline/my-pipeline { "response_processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "input_map": [ { "inputText": "text" } ], "output_map": [ { "text_vec": "$.inference_results[0].output[0].data" } ], "one_to_one": true } } ] }

Pour résumer les résultats à l'aide d'un grand modèle de langage, ajoutez model_config objet contenant l'invite du modèle et définit one_to_one pour true afin que le processeur récapitule chaque résultat de recherche séparément. L'invite peut référencer l'entrée mappée via un paramètre de modèle tel que ${parameters.context}. Le output_map Dans cet exemple, path correspond à un modèle qui renvoie sa réponse brute. Pour plus d’informations, consultez Adaptez le processeur à votre modèle. Remplacer my-model-id avec l'ID de votre modèle déployé.

PUT /_search/pipeline/my-pipeline { "response_processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "input_map": [ { "context": "text" } ], "output_map": [ { "summary": "$.inference_results[0].output[0].dataAsMap.output.message.content[0].text" } ], "model_config": { "messages": "[{\"role\":\"user\",\"content\":[{\"text\":\"Summarize the following text: ${parameters.context}\"}]}]" }, "one_to_one": true } } ] }

Tarification

Le ml_inference le processeur s'exécute sur le calcul qui traite les demandes de votre collection. Dans un pipeline d'ingestion, son traitement est pris en compte pour l'indexation OpenSearch Unités de calcul (OCU) pour votre collection. Dans un pipeline de recherche, son traitement est pris en compte dans les OCU de recherche, au même titre que les autres activités d'indexation et de recherche. Les pipelines dotés d'un plus grand nombre de processeurs ou de processeurs gourmands en ressources de calcul consomment plus de capacité que les pipelines simples. Pour plus d'informations sur la manière dont la capacité évolue et est facturée, voir Gestion des limites de capacité pour Amazon OpenSearch Sans serveur et Amazon OpenSearch Tarification des services.

Le processeur invoque également le modèle distant que vous avez configuré et le fournisseur du modèle facture l'inférence de modèle séparément.

Autorisations requises

Gestion des pipelines de recherche et d'ingestion contenant un ml_inference le processeur correspond à ce qui suit OpenSearch Autorisations relatives à la politique d'accès aux données sans serveur. Les autorisations s'appliquent à collection type de ressource.

  • aoss:CreateCollectionItems — Créez ou mettez à jour un pipeline.

  • aoss:DescribeCollectionItems — Obtenez, répertoriez et simulez des pipelines.

  • aoss:DeleteCollectionItems — Supprimez un pipeline.

Le processeur appelle également le modèle que vous avez configuré. Pour les autorisations de politique d'accès aux données dont un principal a besoin pour créer et exécuter des modèles, voir Configurer le Machine Learning sur Amazon OpenSearch Serverless.

Important

Le principal qui envoie une demande via le pipeline a besoin du aoss:ExecuteMLResource autorisation sur le modèle. Cela s'applique à l'indexation de documents, à l'exécution _simulate, et en recherchant. Sans cette autorisation, ces demandes échouent avec un Forbidden erreur qui ne nomme pas l'autorisation manquante.

L'exemple de politique d'accès aux données suivant accorde une autorisation principale pour gérer les pipelines d'une collection et exécuter les modèles de cette collection. Remplacer collection-name avec le nom de votre collection, account-id avec votre AWS identifiant de compte, et role-name avec le nom du rôle IAM qui gère et utilise les pipelines.

[ { "Description": "Manage pipelines and run models", "Rules": [ { "ResourceType": "collection", "Resource": ["collection/collection-name"], "Permission": [ "aoss:CreateCollectionItems", "aoss:DescribeCollectionItems", "aoss:DeleteCollectionItems" ] }, { "ResourceType": "model", "Resource": ["model/collection-name/*"], "Permission": [ "aoss:ExecuteMLResource" ] } ], "Principal": [ "arn:aws:iam::account-id:role/role-name" ] } ]

Pour la cartographie complète de OpenSearch Opérations d'API pour OpenSearch Autorisations sans serveur, voir Opérations et plug-ins pris en charge dans Amazon OpenSearch Serverless.

Résolution des problèmes

Si une demande utilisant un ml_inference le pipeline tombe en panne avec un Forbidden erreur, vérifiez les causes courantes suivantes :

  • Le principal appelant n'a pas aoss:ExecuteMLResource sur le modèle. Ajoutez un model règle de la politique d'accès aux données, comme indiqué dans Autorisations requises.

  • La politique d'accès aux données n'accorde pas au principal les autorisations d'index ou de collecte pour l'opération, telle que la rédaction de documents, la recherche ou la création de pipelines.

  • La demande est signée avec le nom du service es au lieu de aoss.

  • La politique réseau de la collection n'autorise pas l'accès depuis la source de la demande.

Si une demande de recherche échoue avec un Pipeline my-pipeline is not defined erreur juste après avoir créé le pipeline, attendez quelques minutes et réessayez. Pour plus d’informations, consultez Utilisation de ml_inference dans un pipeline de recherche.

Pour plus d’informations

Pour plus d'informations sur le ml_inference processeur, consultez les rubriques suivantes :