View a markdown version of this page

Amazon OpenSearch Serverless の ML 推論パイプライン - Amazon OpenSearch Service

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon OpenSearch Serverless の ML 推論パイプライン

Amazon OpenSearch Serverless のml_inferenceプロセッサは、設定された機械学習モデルを呼び出し、モデルの入出力をドキュメントフィールドまたはクエリフィールドにマッピングする汎用プロセッサです。マッピングは、 input_map および output_mapパラメータで制御します。これにより、モデル入力を提供するドキュメントまたはクエリフィールドと、モデル出力を受信するフィールドが指定されます。

sparse_encodingそれぞれが 1 つのモデルタイプをサポートする text_embedding、text_image_embedding、 などの専用機械学習プロセッサとは異なり、ml_inferenceプロセッサは任意の設定済みモデルで動作します。また、取り込みパイプラインと検索パイプラインの両方で実行できるため、インデックス作成中、クエリ実行前、または結果が返された後にモデル推論を適用できます。専用ml_inferenceプロセッサが提供していないモデルまたは入出力マッピングが必要な場合は、プロセッサを使用します。完全な概念ドキュメントについては、OpenSearch ドキュメントウェブサイトの「ML 推論プロセッサ」を参照してください。

ml_inference プロセッサを使用して、次のようなワークフローをサポートできます。

  • セマンティック検索

  • 取得拡張生成 (RAG)

  • マルチモーダル検索

  • 結果の概要

  • クエリエンリッチメント

前提条件

ml_inference プロセッサを使用する前に、次の手順を実行します。

  • ベクトル検索コレクションを作成します。OpenSearch Serverless は、NextGen コレクショングループのベクトル検索コレクション (タイプ VECTORSEARCH) でml_inferenceプロセッサをサポートします。OpenSearch Serverless は、 が function_nameのモデルのみを受け入れますremote。コレクショングループを作成するには、「」を参照してくださいコレクショングループを作成する。コレクションを作成するには、「」を参照してくださいベクトル検索コレクションの使用。コレクショングループとコレクションの両方でスタンバイレプリカを有効にします。

    次の AWS CLI 例では、NextGen コレクショングループとその中にベクトル検索コレクションを作成します。my-collection-group と my-collection を独自の名前に置き換えます。

    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
  • リモートモデルを設定してデプロイします。プロセッサは、設定およびデプロイされたリモートモデルを呼び出し、モデル ID で参照します。Amazon Titan 埋め込みモデルをセットアップする例については、「」を参照してください例: Amazon Titan 埋め込みモデルを設定する。詳細については、「Amazon OpenSearch Serverless で機械学習を設定する」を参照してください。

  • リクエストに署名します。サービス名 を使用して、 AWS 署名バージョン 4 でコレクションエンドポイントへのすべてのリクエストに署名しますaoss。詳細については、「他のクライアントを使用した HTTP リクエストの署名」を参照してください。

例: Amazon Titan 埋め込みモデルを設定する

このトピックの例では、Amazon Bedrock で Amazon Titan Text Embeddings V2 モデルを使用します。次の手順では、 コレクションにコネクタとモデルを作成します。

  1. OpenSearch Serverless が Amazon Bedrock を呼び出すために引き受ける IAM ロールを作成します。ロールの信頼ポリシーはml.opensearchservice.amazonaws.comサービスプリンシパルを許可し、ロールのアクセス許可ポリシーはモデルbedrock:InvokeModelで を許可する必要があります。コネクタを作成するプリンシパルもこのロールiam:PassRoleに必要です。

  2. コネクタを作成します。region AWS リージョン を Amazon Bedrock モデルの に、account-id をアカウント AWS ID に、bedrock-role を前のステップのロールの名前に置き換えます。

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

    レスポンスにはコネクタ ID が含まれます。post_process_function この設定は$.inference_results[0].output[0].data、このトピックの例が使用するパスである に埋め込みを返します。

  3. コネクタにモデルを登録します。my-connector-id を前のステップのコネクタ ID に置き換えます。

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

    レスポンスにはモデル ID が含まれます。

  4. モデルをデプロイします。my-model-id を前のステップのモデル ID に置き換えます。

    POST /_plugins/_ml/models/my-model-id/_deploy
  5. に示すように、予測 API を使用してモデルをテストしますプロセッサをモデルに一致させる。

これらのステップでは、modelリソースタイプに対して次のアクセス許可が必要です。コネクタを作成してモデルを登録aoss:CreateMLResourceし、aoss:UpdateMLResourceデプロイaoss:ExecuteMLResourceし、予測 API を呼び出します。これらのアクセス許可を付与するデータアクセスポリシーの例については、「」を参照してください機械学習のアクセス許可を設定する。

プロセッサをモデルに一致させる

ml_inference プロセッサはモデルの形状を認識しません。と input_map で指示しますoutput_map。これらがモデルの予測 API と一致しない場合、プロセッサは失敗するか、間違った値を書き込みます。最初に予測 API を使用してモデルをテストし、パラメータ名と出力パスをパイプラインにコピーします。

次の表は、マッピングの各部分がどこから来たかを示しています。

マッピング 一致する必要があるもの
のキー input_map コネクタ の${parameters.name}プレースホルダーである予測リクエストのパラメータ名request_body。
の値 input_map 値を指定するドキュメントフィールド、またはクエリフィールド。
のキー output_map モデル出力を受け取るフィールドの名前。
の値 output_map 予測レスポンスへの JSON パス。例: $.inference_results[0].output[0].data。

次の例では、テキスト埋め込みモデルの予測 API を呼び出します。inputText パラメータは、取り込みパイプラインの例が のキーとして使用するのと同じ名前ですinput_map。my-model-id をデプロイされたモデルの ID に置き換えます。

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

モデルは次のようなレスポンスを返します。data 配列は読みやすいように短縮されています。

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

埋め込みは、最初の出力のdata配列にあります。JSON パスがそれ$.inference_results[0].output[0].dataを選択します。これは、取り込みパイプラインの例が で使用するパスですoutput_map。

注記

このレスポンスシェイプは、Amazon Titan 埋め込みコネクタが post_process_functionを に設定する場合に適用されますconnector.post_process.bedrock.embedding。後処理関数がない場合、ベクトルは $.inference_results[0].output[0].dataAsMap.embedding になります。コネクタのセットアップについては、「」を参照してくださいAmazon OpenSearch Serverless で機械学習を設定する。

重要

リクエストパラメータとレスポンスシェイプは、モデルとそのコネクタによって異なります。別のモデルを使用する場合は、このトピックの例のパスを再利用しないでください。モデルの予測 API を実行し、レスポンスからパスを読み取ります。

たとえば、raw レスポンスを返す大規模な言語モデルは、異なる形状です。テキストは dataAsMap オブジェクト内にネストされ、送信するパラメータは ではなくコネクタプレースホルダーにちなんで命名されます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 } ] }

このレスポンスの JSON パスは です$.inference_results[0].output[0].dataAsMap.output.message.content[0].text。の正確な構造dataAsMapはモデルプロバイダーの応答であるため、プロバイダーとモデルによって異なります。

プロセッサを別のモデルに切り替えるには、次の手順を実行します。

  1. モデルのコネクタrequest_bodyの でパラメータ名を見つけます。各${parameters.name}プレースホルダーは、 のキーとして使用できる名前ですinput_map。

  2. 各パラメータのサンプル値を使用して予測 API を呼び出します。

  3. 予測レスポンスを読み、保持する値に JSON パスを書き込みます。

  4. パイプラインoutput_mapの model_id、input_map、および を更新します。

  5. サンプルドキュメントで _simulate API を実行して、出力フィールドに期待どおりの値があることを確認します。

注記

予測 API には、モデルリソースに対する アクセスaoss:ExecuteMLResource許可が必要です。詳細については、「Amazon OpenSearch Serverless で機械学習を設定する」を参照してください。

取り込みパイプラインでの ml_inference の使用

取り込みパイプラインでは、ml_inferenceプロセッサはインデックス作成中にモデル推論を実行します。一般的な用途は、データに対してセマンティック検索を実行できるように、テキストフィールドからベクトル埋め込みを生成することです。はドキュメントフィールドをモデル入力にinput_mapマッピングし、 はモデル出力を新しいフィールドにoutput_map書き込みます。

次の例では、 textフィールドをモデルに送信し、返された埋め込みを embeddingフィールドに書き込むパイプラインを作成します。my-pipeline をパイプラインの名前に置き換え、my-model-id をデプロイされたモデルの ID に置き換えます。

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

リクエストは次のレスポンスを返します。

{ "acknowledged": true }

が に設定されているinference_resultsため、output_mapパスfull_response_pathは にルートされますtrue。この設定では、完全なモデルレスポンスに対して出力パスを評価します。詳細については、OpenSearch Documentation ウェブサイトの「ML 推論プロセッサ」を参照してください。

パイプラインをライブトラフィックに適用する前に、_simulateエンドポイントを使用してサンプルドキュメントに対してパイプラインをシミュレートできます。インデックスにインデックス付けされているすべてのドキュメントでモデル推論を自動的に実行するには、インデックスの作成時に index.default_pipelineを設定します。または、pipelineクエリパラメータを使用して個々のインデックス作成リクエストでパイプラインを指定します。取り込みパイプラインの作成、シミュレーション、適用の詳細については、「」を参照してくださいAmazon OpenSearch Serverless でパイプラインを取り込む。

次の例では、ドキュメントのインデックスを作成し、パイプラインを実行します。my-index をインデックスの名前に、my-pipeline をパイプラインの名前に置き換えます。

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

レスポンスは、ドキュメントにインデックスが作成されたことを確認します。

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

ターゲットインデックスはベクトル検索用に設定する必要があります。出力フィールド ( などembedding) を有効にindex.knnして、モデルに一致するディメンションを持つknn_vectorフィールドとしてマッピングします。

検索パイプラインでは、ml_inferenceプロセッサはクエリの一部としてモデル推論を実行します。検索リクエストプロセッサは、実行前にクエリを変換または書き換えます。検索レスポンスプロセッサは、結果を受け取る前に結果を強化します。検索パイプラインを実行するには、search_pipelineクエリパラメータを使用してリクエストを送信します。my-index をインデックスの名前に、my-pipeline をパイプラインの名前に置き換えます。

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

検索パイプラインを作成または更新するには、以下のセクションの例に示すように、パイプライン本文を_search/pipelineエンドポイントに送信します。

注記

新しく作成された検索パイプラインは、作成リクエストが を返した後でも、有効になるまでに数分かかることがあります"acknowledged": true。それまでは、パイプラインを参照する検索リクエストはPipeline my-pipeline is not definedエラーで失敗します。しばらく待ってからリクエストを再試行します。

検索リクエストプロセッサ

OpenSearch Serverless がクエリを実行する前に、検索リクエストプロセッサを使用して受信クエリを書き換えます。次の の例では、matchクエリのテキストを取得し、設定済みのモデルを使用してそこからベクトルを生成し、 query_templateパラメータを使用してリクエストを k-NN クエリに書き換えます。OpenSearch Serverless は、テンプレートの${query_vec}プレースホルダーをoutput_mapキャプチャするモデル出力に置き換えます。my-model-id をデプロイされたモデルの ID に置き換えます。

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

JSON output_map パスが完全なモデルレスポンスに対して解決trueされるように full_response_pathに設定します。これにより、予測 API レスポンスから読み取ったのと同じ出力パスを使用できます。

ソースフィールドが欠落している可能性があるtrue場合は、 ignore_missing に設定します。クエリなどのマッピングされたフィールドが含まれていないmatch_allクエリは、失敗するのではなく変更されずに渡されます。プロセッサは、 フィールドを含むクエリを書き換えます。

検索レスポンスプロセッサ

検索レスポンスプロセッサはクエリが返された後に実行されるため、各ヒットを強化または要約できます。次の の例では、各ヒットの textフィールドを設定済みモデルに送信し、モデル出力を text_vecフィールドに書き込みます。を one_to_oneに設定すると、プロセッサは検索ヒットごとにモデルを 1 回実行trueします。デフォルトは でfalse、1 つのリクエストですべてのヒットをモデルに送信し、1 つの入力値を想定するモデルはそのリクエストを拒否します。my-model-id をデプロイされたモデルの ID に置き換えます。

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

大規模な言語モデルで結果を要約するには、モデルプロンプトを含むmodel_configオブジェクトを追加し、プロセッサが各検索ヒットを個別に要約trueするように one_to_oneを に設定します。プロンプトは、 などのテンプレートパラメータを使用してマッピングされた入力を参照できます${parameters.context}。この例のoutput_mapパスは、raw レスポンスを返すモデルと一致します。詳細については、「プロセッサをモデルに一致させる」を参照してください。my-model-id をデプロイされたモデルの ID に置き換えます。

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

料金

ml_inference プロセッサは、コレクションのリクエストを処理するコンピューティングで実行されます。取り込みパイプラインでは、その処理はコレクションのインデックス作成 OpenSearch Compute Units (OCUs) にカウントされます。検索パイプラインでは、他のインデックス作成や検索アクティビティと同様に、その処理は検索 OCUs にカウントされます。より多くのプロセッサを持つパイプライン、またはコンピューティング集約型プロセッサを持つパイプラインは、単純なパイプラインよりも多くの容量を消費します。容量のスケーリングと請求方法の詳細については、Amazon OpenSearch Serverless でのキャパシティ制限の管理「」および「Amazon OpenSearch Service の料金」を参照してください。

また、プロセッサは設定したリモートモデルを呼び出し、モデルプロバイダーはモデル推論を個別に請求します。

必要なアクセス許可

ml_inference プロセッサを含む検索パイプラインと取り込みパイプラインの管理は、次の OpenSearch Serverless データアクセスポリシーのアクセス許可にマッピングされます。アクセス許可はリソースcollectionタイプに適用されます。

  • aoss:CreateCollectionItems – パイプラインを作成または更新します。

  • aoss:DescribeCollectionItems – パイプラインを取得、一覧表示、シミュレートします。

  • aoss:DeleteCollectionItems – パイプラインを削除します。

プロセッサは、設定したモデルも呼び出します。プリンシパルがモデルを作成および実行するために必要なデータアクセスポリシーのアクセス許可については、「」を参照してくださいAmazon OpenSearch Serverless で機械学習を設定する。

重要

パイプラインを介してリクエストを送信するプリンシパルには、モデルに対する aoss:ExecuteMLResource アクセス許可が必要です。これは、ドキュメントのインデックス作成、 の実行_simulate、検索に適用されます。このアクセス許可がないと、これらのリクエストは失敗し、見つからないアクセス許可に名前を付けないForbiddenエラーが発生します。

次のデータアクセスポリシーの例では、プリンシパルに、コレクション内のパイプラインを管理し、そのコレクション内のモデルを実行するアクセス許可を付与します。collection-name をコレクションの名前に、account-id を AWS アカウント ID に、role-name をパイプラインを管理および使用する IAM ロールの名前に置き換えます。

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

OpenSearch API オペレーションと OpenSearch Serverless アクセス許可の完全なマッピングについては、「」を参照してくださいAmazon OpenSearch Serverless でサポートされているオペレーションとプラグイン。

トラブルシューティング

ml_inference パイプラインを使用するリクエストがForbiddenエラーで失敗した場合、次の一般的な原因を確認してください。

  • 呼び出し元のプリンシパルにモデルaoss:ExecuteMLResourceに がありません。に示すように、データアクセスポリシーにmodelルールを追加します必要なアクセス許可。

  • データアクセスポリシーは、ドキュメントの記述、検索、パイプラインの作成など、オペレーションのインデックスまたはコレクションのアクセス許可をプリンシパルに付与しません。

  • リクエストは、 esではなくサービス名で署名されますaoss。

  • コレクションのネットワークポリシーは、リクエストのソースからのアクセスを許可しません。

パイプラインの作成直後に検索リクエストがPipeline my-pipeline is not definedエラーで失敗した場合は、数分待ってから再試行してください。詳細については、「検索パイプラインでの ml_inference の使用」を参照してください。

詳細情報

ml_inference プロセッサの詳細については、以下を参照してください。