Amazon API Gateway マッピングテンプレートと Amazon SageMaker を使用して機械学習を搭載した REST API の作成

Amazon SageMaker を使用して、組織は機械学習モデルを構築、トレーニング、およびデプロイできます。コンシューマー向けの組織は、パーソナライズされた製品の推奨事項を作成したり、顧客の好みに基づいてアプリケーションの動作を自動で調整したりすることにより、顧客体験を豊かにすることができます。そのようなアプリケーションを構築する場合、コンシューマーデバイスで実行されているクライアントソフトウェアでランタイム推論エンドポイントを使用可能にする方法は、アーキテクチャ上の重要な考慮事項の 1 つです。通常、エンドポイントは、クライアントソフトウェアに一連の完全なアプリケーション機能を提供する REST など、ウェブ上で使いやすい従来のアプローチに基づいて、より広範囲な API の一部として提供されます。

Amazon API Gateway は、開発者があらゆる規模の API を簡単に作成、公開、保守、監視、保護できるようにするフルマネージド型サービスです。API Gateway を使用して、Amazon SageMaker エンドポイントの外部に面した単一のエントリポイントを提示できます。これには、次の利点があります。

クライアント向けの REST API と、基となる Amazon SageMaker ランタイム推論 API の間を変換することにより、基本実装仕様からクライアントを隔離
クライアントリクエストの認証と承認をサポート
調整、評価制限、およびクォータ管理を使用してクライアントリクエストを管理
AWS WAF が提供するファイアウォール機能を使用
キャッシングとリクエストの検証により、コスト削減と運用の最適化を実現
モデルの変更を安全に導入するためのカナリアデプロイメントを簡単に作成

この記事では、マッピングテンプレートと呼ばれる API Gateway 機能を使用して、REST API の一部として Amazon SageMaker 推論エンドポイントを処理する方法をお見せします。この機能により、REST API を Amazon SageMaker ランタイムエンドポイントに直接統合できるため、エンドポイントを呼び出すための中間コンピューティングリソース (AWS Lambda または Amazon ECS コンテナなど) の使用を回避できます。その結果、よりシンプルで、高速で、安価で実行できるソリューションを実現します。

この直接統合アプローチは、ピーク需要の時期にトラフィック量が多いコンシューマーアプリケーションにとって特に有用です。Amazon SageMaker は、推論エンドポイントの自動化スケーリングをサポートし、API Gateway は需要に合わせて自動的にスケーリングを行い、常に着信リクエストを処理するために十分な容量を確保して、使用した分に対してのみ料金をお支払いいただきます。

注意: この記事では Amazon SageMaker との直接統合に焦点を当てていますが、マッピングテンプレートを中間コンピューティングレイヤー (AWS Lambda などに基づく) と組み合わせて使用することもできます。この場合、ゲートウェイ自体でペイロードを再形成することにより、コンピューティングレイヤーの負荷を減らすために使用できます。

コンソールベースのチュートリアルを使用して、Amazon SageMaker モデルエンドポイントのデプロイを始め、このエンドポイントと Amazon API Gateway 統合の作成を手順通りに実行するアプローチをお見せします。

ソリューションの概要

この記事では、説明のために、TV アプリが映画リストの評価予測をリクエストするユースケースを採用しています。アプリが映画のページを表示するときは、常に、評価予測がより高い映画がページ上でより目立つように表示する必要があります。この例では、すべてのユーザーと映画を数値 ID で識別でき、評価は 1〜5 の範囲で予測されます。評価が高いほど、ユーザーが特定の映画を気に入る可能性が高くなります。

アーキテクチャ

次の図は、ソリューションのアーキテクチャ、主要なコンポーネント、および相互作用をまとめたものです。エンドユーザーは、REST スタイルのリクエストを API Gateway エンドポイントに送信するクライアントアプリケーションと (ウェブブラウザまたはモバイルデバイスを使用して) 対話します。API Gateway はこれを Amazon SageMaker エンドポイントの必須リクエスト形式にマッピングし、エンドポイントを呼び出して、モデルから推論を取得します。その後、API Gateway は Amazon SageMaker エンドポイントから応答を受信し、クライアントに返される応答にマッピングします。

リクエストとレスポンスの形式

このソリューションには、単一のリソース (予測評価) と GET メソッドをサポートする REST API が組み込まれています。リクエストの形式は次のとおりです。

GET /<api-path>/predicted-ratings/{user_id}?items=id1,id2,…,idn&

ここで、パスパラメータ user_id は評価を必要とするユーザーを表し、クエリ文字列パラメータ items にはコンマ区切りの項目識別子一覧が含まれます。

リクエストが正常に処理されると、返される HTTP 応答の応答コードは 200 になり、本文は次のように指定された項目の予測評価一覧を含む JSON オブジェクトになります。

{
  "ratings": [
    rating_1,
    rating_2,
    …,
    rating_n
  ]
}

たとえば、次のリクエストを入力できます。

% curl "https://<api-path>/predicted-ratings/321?items=101,131,162&"

これは、以下のような応答で返されます。

{
  "ratings": [
    3.527499437332153,   
    3.951640844345093,   
    3.658416271209717    
  ]
}

Amazon SageMaker モデルの入力および出力形式

評価予測ソリューションは、Amazon SageMaker に不随しているサンプルモデル、つまり、object2vec_movie_recommendation.ipynb に基づいています。このモデル推論エンドポイントは POST メソッドをサポートし、次のようにリクエスト本文に JSON ペイロードが含まれることを想定しています。

{
  "instances": [
    {"in0": [863], "in1": [882]},
    {"in0": [278], "in1": [311]},
    {"in0": [705], "in1": [578]},
    …
  ]
}

in0 はユーザー ID を表し、in1 は映画 ID を表します。

モデル推論は次の出力を返します。

{
  "predictions": [
    {"scores": [3.047305107116699]},
    {"scores": [3.58427882194519]},
    {"scores": [4.356469631195068]},
    …
  ]
}

マッピングテンプレートを使用して、REST API で受信した GET リクエスト形式を Amazon SageMaker モデルエンドポイントで予測される POST 入力形式にマッピングします。逆に、モデル出力形式は REST API の必須応答形式にマッピングできます。

Amazon API Gateway メソッドの統合

API Gateway を使用して REST API を作成する場合、各 API メソッドに対して次の設定モデルを定義する必要があります。

メソッドリクエスト – REST リクエスト形式のデータモデルを定義し、受信した REST リクエストで実行される検証および承認チェックを指定します。
統合リクエスト – REST リクエストと関連パラメータが、どのようにバックエンドサービスエンドポイント (この例では Amazon SageMaker 推論エンドポイント) で予測される形式にマッピングされるかを詳しく説明します。
統合応答 – バックエンドサービスから受信した応答 (エラーを含む) がどのように API Gateway によって予測される応答形式にマッピングされるかを詳しく説明します。
メソッド応答 – REST API によって予測されるデータモデルと応答形式を定義します。

次の図は、処理フローを示しており、リクエストと応答の例が各段階でどのように変換されるかを示しています。

マッピングテンプレート

統合リクエストおよび応答設定の一部として、ソリューションは Apache Velocity Template Language (VTL) を使用してマッピングテンプレートを定義します。VTL は、もともとウェブ開発用に設計されたテンプレート言語ですが、データ形式変換ツールとして使用して、ある JSON 形式から別の JSON 形式に変換することもできます。マッピングテンプレートを使用すると、VTL テンプレートを使用して REST リクエスト形式からモデル入力形式に変換し、モデル出力を REST 応答形式に変換できます。

チュートリアルの手順

このチュートリアルには、次の主要な手順があります。

Amazon SageMaker モデルを構築してデプロイする
AWS CLI を使用して Amazon SageMaker モデルのエンドポイントをテストする
REST API の IAM 実行ロールを作成する
REST API の API Gateway エンドポイントを構築する
リクエスト統合用のマッピングテンプレートを作成する
応答統合用のマッピングテンプレートを作成する
API Gateway エンドポイントをデプロイしてテストする

前提条件

このチュートリアルを実行するには、次の前提条件を満たす必要があります。

AWS アカウントへのアクセス – IAM ロール、Amazon SageMaker、Amazon S3、および API Gateway を使用するには、十分な IAM アクセス許可が必要です。
AWS CLI – 最新バージョンをインストールします。
Curl ユーティリティ – バージョン 7.52 以降を使用します。

手順 1: Amazon SageMaker モデルを構築してデプロイする

この手順では、モデルデータを保存するための S3 バケットが必要です。既存のバケットを使用するか、新しいバケットを作成できます。後で必要になるため、バケットの名前を記録します。

Amazon SageMaker ノートブックインスタンスを使用してモデルを作成します。次の手順を完了してください。

AWS マネジメントコンソールを使用して AWS アカウントにログインします。
Amazon SageMaker ダッシュボードの [ノートブックインスタンス] で、[ノートブックインスタンスを作成] を選択します。
ノートブックインスタンスの設定で、ノートブックの名前を指定します。

この例では、インスタンスタイプを最も費用対効果の高いオプションである ml.t2.medium に設定できます。実際には、データセットのサイズとデータ変換の性質に基づいてインスタンスタイプを選択します。

[アクセス許可と暗号化] で、IAM ロールを [新しいロールを作成] に設定します。
指定する S3 バケットが選択されていることを確認し、バケットの名前を指定して、[ロールを作成] を選択します。
残りの設定はデフォルト値のままにします。
[ノートブックインスタンスを作成] を選択します。

インスタンスの作成には数分かかります。ステータスが [Pending] から [InService] に変わると、ノートブックインスタンスを使用する準備が整います。

[アクション] で、[JupyterLab を開く] を選択します。

Jupyter ノートブック用の新しいブラウザタブが開きます。

左側のナビゲーションバーから、Amazon SageMaker サンプルノートブックのアイコンを選択します (アイコンにカーソルを合わせてラベルを表示します)。
サンプルノートブックのリストから、以下に示すように object2vec_movie_recommendation.ipynb を選択します。

開いたサンプルノートブックは読み取り専用なので、書き込み可能なコピーを作成する必要があります。

ペインの右上にある [コピーを作成] を選択します。
カーネルを選択するように求められたら、conda_python3 を使用します。

これで、ノートブックでモデルを構築してトレーニングする準備が整いました。このノートブックは、2 つのモデル推論エンドポイント (評価予測用と推奨用) を作成します。必要なのは最初のものだけなので、ノートブックのすべてのセルを実行する必要はありません。

セルを実行する前に、次の手順を完了してください。

ノートブックで、[モデルのトレーニングと推論] セクションまでスクロールダウンします (ノートブックの半分を少し下回ります)。最初のセル (データとモデルをホストし、データを S3 にアップロードする S3 バケットを定義するといったラベル付き) で、バケット名を前に特定した S3 バケットの選択に設定します。
[推奨タスク] セクションの直前 (ノートブックの約 4 分の 3) に到達するまで、ノートブックを使用してすべてのセルを上から順番に実行します。

これを行うには、一度に 1 つのセルを実行するか、[推奨タスク] セクションで最初のセルを選択し、[実行] で [選択したすべてのセルを実行] を選びます (以下を参照)。

モデルのトレーニングとデプロイには約 10 分かかります。完了したら、次の手順に進みます。

Amazon SageMaker コンソールの [推論] で [エンドポイント] を選択します。
ランタイムエンドポイントを表示できることを確認します。
後で必要になるため、エンドポイント名と ARN を記録します。

手順 2: AWS CLI を使用して Amazon SageMaker モデルのエンドポイントをテストする

次のように AWS CLI を使用して推論エンドポイントをテストできます。

aws sagemaker-runtime invoke-endpoint \
  --endpoint-name <endpoint-name> \
  --body '{"instances": [{"in0":[863],"in1":[882]}]}' \
  --content-type application/json \
  --accept application/json \
  results

注意: 上記の内容は、bash 互換シェルを使用していることを前提としています。標準 Windows コマンドラインをご使用の場合は、本文パラメータの外側の一重引用符を二重引用符に置き換え、JSON 内の二重引用符文字をエスケープします。

エンドポイントが正常に機能している場合、次のような出力を含む、結果というファイルが表示されます。

{"predictions":[{"scores":[2.433111906051636]}]}

Amazon SageMaker エンドポイントが動作するようになったので、その前に REST API を構築できます。

手順 3: REST API の実行ロールを作成する

REST API を構築する前に、Amazon SageMaker エンドポイントを呼び出すために必要なアクセス許可を API に付与する実行ロールを作成する必要があります。次の手順を完了してください。

IAM コンソールの [ロール] で、[ロールを作成] を選択します。
[信頼できるエンティティの種類を選択] で、[AWS サービス] を選択します。
サービス API Gateway を選択します。
[確認] が表示されるまで [次へ] を選択します。

API Gateway がログを CloudWatch にプッシュできるようにするポリシーが含まれていることがわかります。

ロールに名前を付けます (例: APIGatewayAccessToSageMaker)。
[ロールを作成] をクリックします。

ロールが Amazon SageMaker エンドポイントを呼び出せるように、アクセス許可を追加する必要があります。

ロールフィルターを使用して、作成したロールを見つけます。
作成したロールを選択して、[ロールの概要] 画面を表示します。
[インラインポリシーを追加] を選択します。
[ポリシーを作成] 画面で、サービス [SageMaker] とアクション [InvokeEndpoint] を選択します。
[リソース] で [特定] を選択し、Amazon SageMaker エンドポイントの ARN を入力します。
[ポリシーを確認] をクリックします。
ポリシーに名前を付けます (例: SageMakerEndpointInvokeAccess)。
[ポリシーを作成] を選択します。
[ロールの概要] ページで、後で必要になるため、ロールの ARN を記録します。

手順 4: API Gateway エンドポイントを構築する

このセクションでは、REST API を構築します。

API の作成

次の手順を完了してください。

API Gateway コンソールで、API を作成を選択します。
[REST] を選択します。
新しい API を選択します。
API に名前を付けます (例: RatingsPredictor)。
エンドポイントタイプには、[リージョン] を選択します。
[API を作成] を選択します。

注意: 実稼働システムでは、最適化されたエッジオプションを活用するかどうかを検討する必要があります。

リソースの作成

[リソースエディタ] で、[アクション] メニューから [CreateResource] を選択します。
[リソース名] に predicted-ratings と入力します。
[リソースパス] フィールドにも予測評価が含まれていることを確認します。
[リソースを作成] を選択します。

ナビゲーションツリーに予測評価リソースが表示されます。

作成した予測評価リソースを選択します。
[アクション] メニューから [リソースを作成] を選択します。
リソースパスに {user_id} と入力します。
リソース名に user_id と入力します。
[リソースを作成] を選択します。

リソースナビゲーションツリーは、次のスクリーンショットのように、/predicted-ratings/{user_id} が表示されます。

GET メソッドの作成

次の手順では、リソースパス /predicted-ratings/{user_id} で GET メソッドを作成し、Amazon SageMaker エンドポイントと統合します。次の手順を完了してください。

[アクション] メニューで、[{user_id}] を選択します。
[メソッドを作成] を選択します。
{user_id} リソースの下に表示されるドロップダウンから [GET] を選択し、チェックマークをクリックして確認します。

右側のペインに [セットアップ] 画面が表示されます。次のスクリーンショットを参照してください。

[リクエスト統合タイプ] で、[AWS サービス] を選択します。
[AWS リージョン] で、[リージョン] を入力します。
[AWS サービス] で、[SageMaker ランタイム] を選択します。
[AWS サブドメイン] を空白のままにします。
[HTTP メソッド] で、[POST] を選択します。
[アクションタイプ] で、[パス上書きを使用] を選択します。
[パス上書き] で、エンドポイント /<sagemaker-endpoint-name>/invocations の形式を使用して Amazon SageMaker エンドポイントパスを入力します。
[実行ロール] には、以前に作成したロールの ARN を入力します。
[コンテンツ処理] で、[パススルー] を選択します。
[デフォルトのタイムアウトを使用] を選択します。
[保存] を選択します。

REST API で GET エンドポイントを作成し、POST エンドポイントにマップしました。次の手順では、マッピングテンプレートを使用して、(パスとクエリ文字列からの) GET リクエストで渡されたパラメータを Amazon SageMaker エンドポイントで予測される POST リクエストの適切な場所にマッピングします。

手順 5: リクエスト統合用のマッピングテンプレートを作成する

右側のペインに [メソッド実行] 画面が表示されます。次のスクリーンショットを参照してください。

これには、REST API から Amazon SageMaker ランタイムへのリクエストフローと、応答のフローバック方法を示す図が含まれています。

VTL マッピングテンプレートの作成

この次の手順では、VTL マッピングテンプレートを作成して、REST API で受信した GET リクエストを Amazon SageMaker ランタイムで予測される POST リクエストに変換します。次の手順を完了してください。

[統合リクエスト] を選択します。
マッピングテンプレートを展開します。
[リクエスト本文のパススルー: なし] を選択します。

マッピングテンプレートを指定した後は警告が表示されなくなるため、警告を無視しても問題ありません。

[マッピングテンプレートを追加] を選択します。
[コンテンツタイプ] で [アプリケーション/json] を指定し、チェックボックスをクリックして確認します。

下にスクロールすると、複数行のテキスト入力フィールドが表示されます。VTL テンプレートを追加する場所です。

次のコードを入力します。

{
  "instances": [
#set( $user_id = $input.params("user_id") )
#set( $items = $input.params("items") )
#foreach( $item in $items.split(",") )
    {"in0": [$user_id], "in1": [$item]}#if( $foreach.hasNext ),#end
    $esc.newline
#end
  ]
}

[保存] を選択します。

テンプレートは、POST リクエストの本文に含まれる内容を定義します。最初の 2 行は、指定された通りリクエスト本文にコピーされます。3 行目では、#set ディレクティブを使用して user_id パスパラメータを抽出し、変数 $user_id に格納します。4 行目では、クエリ文字列パラメータ items を抽出し、変数 $items に配置します。これは、コンマ区切りの項目リストを含む単一の文字列として保存されます。

5〜8 行は、すべての項目をループし、各項目に必要な JSON を生成します。テンプレートは、文字列 split() メソッドを使用して $items に保持されている文字列を配列に変換し、#foreach ディレクティブを使用して反復処理します。JSON オブジェクトの間にコンマ区切りが挿入され、最後の入力後にはコンマを使用しません。

マッピングのテスト

これで、API Gateway の組み込みテストハーネスを使用してこのマッピングをテストできます。次の手順を完了してください。

[メソッド実行] を選択します。
[テスト] をクリックします。
パスパラメータ {user_id} に 321 を入力します。
クエリ文字列パラメータに items=101,131,162& を入力します。
[テスト] をクリックします。

すべてが正常に機能している場合は、以下のような JSON オブジェクトを含む応答本文とともに、応答コード 200 が表示されます。

{
  "predictions": [
    {"scores": [3.527499437332153]},
    {"scores": [3.951640844345093]},
    {"scores": [3.658416271209717]}
  ]
}

ログをスクロールして、イベントのシーケンスを確認することもできます。次のような内容が表示されます。

<timestamp>: 変換後のエンドポイントリクエスト本文: {
  "instances": [
    {"in0": [321], "in1": [101]},
    {"in0": [321], "in1": [131]},
    {"in0": [321], "in1": [162]}
  ]
}
<timestamp> : https://runtime.sagemaker.eu-west-1.amazonaws.com/endpoints/recs/invocations にリクエストを送信する
<timestamp> : 応答を受信しました。状態: 200、統合レイテンシー: 232 ms

これは、REST リクエストがモデルの必須入力形式に正常に変換されたこと、およびモデルランタイムが正常に実行されたことを示します。ただし、返される応答本文は、REST API に規定された形式のままです。デフォルトでは、API Gateway は応答統合をセットアップして、応答を変更せずに渡します。次の手順では、2 番目のマッピングテンプレートを追加して、モデルの応答を必須 REST API 形式に変換します。

手順 6: 応答統合用のマッピングテンプレートを作成する

応答のマッピングテンプレートを追加するには、次の手順を実行します。

[メソッド実行] 画面で、[統合応答] を選択します。

メソッド応答 200 で、HTTP ステータスの正規表現が単一の文字に設定された単一のエントリが表示されます。これは、200 応答コードを返し、応答を変更せずに渡すデフォルトの応答ルールです。

このルールを展開します。
[マッピングテンプレート] で、[アプリケーション/json] を選択します。

次のマッピングテンプレートを入力します。

{
  "ratings": [
#set( $predictions = $input.path("$.predictions") )
#foreach( $item in $predictions )
    $item.scores[0]#if( $foreach.hasNext ),#end
    $esc.newline
#end
  ]
}

このテンプレートは、モデルによって返された予測のリストを反復処理し、REST API の必須形式に準拠した出力を生成します。

[保存] を選択します。

前に使用したのと同じ手順通りに再度テストできます。今回は、出力が必須応答形式で表示されます。

手順 7: API のデプロイとテスト

これで、REST API をデプロイする準備が整いました。次の手順を完了してください。

[メソッド実行] 画面の [アクション] で、[API をデプロイ] を選択します。
デプロイステージで、[新しいステージ] を選択します。
ステージに [test] などの名前を付けます。
このステージとデプロイメントに必要な説明を入力します。
デプロイを選択します。

右側のペインに、デプロイされた API の [URL を呼び出す] エンドポイントを含む [ステージエディタ] が表示されます。[curl] を使用して、デプロイされたエンドポイントをテストできます。

コマンドラインで、次を入力します。
```
curl "<invoke-url>/predicted-ratings/321?items=101,131,162&"
```
<invoke-url> をエンドポイントの URL に置き換えます。

以下のような出力が表示されます。

{
  "ratings": [
    3.527499437332153,   
    3.951640844345093,   
    3.658416271209717    
  ]
}

これで、Amazon SageMaker ランタイムに統合されたデプロイ済みで動作中の REST API が作成されました。

追加の考慮事項

この記事では、API Gateway マッピングテンプレートを使用して、REST API とモデルランタイムの必須形式間でリクエストと応答を変換する方法に焦点を当てました。API Gateway には、承認、リクエストの検証、キャッシュ、応答エラーコードのマッピング、および調整の実装に使用できる多数の追加機能があります。全体的なアーキテクチャを設計するときは、これらの機能において最適な使用方法を検討してください。

この記事では、中間コンピューティングリソースを必要とせずに、リクエストと応答を直接マッピングできる例を使用しました。これは、リクエスト本文を別のソースからの追加データで強化する必要がある場合など、すべての状況に適用できるとは限りません。そのような場合でも、VTL ベースのマッピングテンプレートを使用してリクエストの前処理と後処理の応答を行うことができます。これにより、中間コンピューティングレイヤーの負荷が軽減されます。

クリーンアップ

セットアップの実験が終了したら、API Gateway、S3、および Amazon SageMaker で使用したさまざまなリソースをクリーンアップします。引き続き料金が発生しないように、Amazon SageMaker エンドポイントを削除してください。

後でさらに実験を行うためにモデルと API Gateway のセットアップを保持したい場合は、必要に応じてエンドポイントを再作成できます。別のエンドポイント名を使用している場合は、API Gateway リクエストの統合を必ず更新してください。

まとめ

この記事では、API Gateway を使用して、Amazon SageMaker 推論用のパブリック RESTful エンドポイントを作成する方法を示しました。具体的には、マッピングテンプレートと VTL を使用して、パブリックな REST エンドポイントと内部推論エンドポイントで予測される形式に一致するようにリクエストと応答を変換する方法を示しました。

マッピングテンプレートは、API Gateway と Amazon SageMaker の間で中間コンピューティングリソースを使用しないようにする場合に役立ちます。その結果、アプリケーションのレイテンシーと運用の複雑さが軽減されます。API Gateway マッピングテンプレートは、中間コンピューティングを避けられない状況にも役立ちます。マッピングテンプレートを使用して前処理と後処理を実行し、コンピューティングレイヤーの負荷を減らすことができます。

このアプローチは、コンシューマー向けアプリケーションで一般的に見られるように、低レイテンシーの推論による大量のピーク需要を特徴とするユースケースにとって特に役立ちます。

著者について

Mike Rizzo は、英国に拠点を置く AWS EMEA 商業チームのシニアソリューションアーキテクトです。彼はケント大学でコンピュータサイエンスの博士号を、ロンドンビジネススクールで MBA を取得しました。

Amazon Web Services ブログ