API: ライブデプロイメントのクエリ

Modeling Objectivesアプリケーションでは、ライブデプロイメントを作成し、HTTPエンドポイントを介してモデルをホストできます。ライブデプロイメントのクエリタブからホストされたモデルをテストし、モデル上の関数を使用して本番環境でモデルを利用するか、ライブデプロイメントAPIを直接使用できます。

ホストされたモデルに直接クエリを実行するには、以下のエンドポイントオプションから選択してください。

• マルチI/Oエンドポイント: 複雑なホストモデルと入力タイプに対応した、より柔軟なエンドポイント。
• シングルI/Oエンドポイント: より単純なホストモデル用に設計された簡略化されたエンドポイント。

マルチI/Oエンドポイント

マルチI/Oエンドポイントは、1つ以上の入力と1つ以上の出力をサポートする柔軟なエンドポイントです。

• URL: <ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<LIVE_DEPLOYMENT_RID>/v2
  • <ENVIRONMENT_URL>: 詳細については、以下のセクションを参照してください。
• HTTPメソッド: POST
• 認証タイプ: Bearer token
• 必須HTTPヘッダー:
  • Content-Type: "application/json"でなければなりません。
  • Authorization: "Bearer <BEARER_TOKEN>"でなければなりません。ここで、<BEARER_TOKEN>は認証トークンです。
• リクエストボディ: モデルに送信する情報を含むJSONオブジェクト。これの期待される形状は、デプロイされたモデルのAPIに依存します。
• レスポンス: 成功したレスポンスは、ステータスコード200と、モデルが返す推論レスポンスを表すJSONオブジェクトを返します。このオブジェクトの形状は、現在デプロイされているモデルのAPIを反映しています。

例: マルチI/Oエンドポイントでライブデプロイメントをクエリする

以下の例では、単一の入力と出力を持つシンプルなAPIのモデルを使用します。

この例のホストされたモデルは、inference_dataという名前の単一の入力を期待しており、これはtext行を含むデータセットです。この場合、期待されるリクエスト形式は次のようになります。

Copied!
1
2
3
4
5
6
{
  "inference_data": [{
    // ここにテキストを入力してください
    "text": "<Text goes here>"
  }]
}

モデルは、output_data という名前のデータセットを返し、それには prediction 行が含まれています。これは次のようなレスポンスになります。

Copied!
1
2
3
4
5
{
  "output_data": [{
    "prediction": "<モデル予測はここに>"
  }]
}

例: curl

Copied!
1
2
3
4
5
6
7
# curlコマンドでHTTPリクエストを送信します。
# --http2オプションはHTTP/2を利用することを指定します。
# -Hオプションでリクエストヘッダーを設定します。ここでは"Content-Type: application/json"と"Authorization: <BEARER_TOKEN>"を設定しています。
# -dオプションでリクエストボディを指定します。ここではinference_dataというキーに対してテキストデータをJSON形式で送信しています。
# --request POSTオプションでPOSTメソッドを使うことを指定します。
# 最後にリクエスト先のURLを指定します。ここでは<ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<LIVE_DEPLOYMENT_RID>を指定しています。
curl --http2 -H "Content-Type: application/json" -H "Authorization: <BEARER_TOKEN>" -d '{ "inference_data": [ { "text": "Hello, how are you?" } ] }' --request POST <ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<LIVE_DEPLOYMENT_RID>

例：Python

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import requests

# APIのエンドポイントURL
url = '<ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<LIVE_DEPLOYMENT_RID>/v2'

# 推論リクエストのデータ
inference_request = { 'inference_data': [ { 'text': 'Hello, how are you?' } ] }

# APIにPOSTリクエストを送信
response = requests.post(url, json = inference_request, headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer <BEARER_TOKEN>' })

# レスポンスが成功した場合、結果を表示
if response.ok:
    modelResult = response.json()
    print(modelResult)
else:
    # エラーが発生した場合、エラーメッセージを表示
    print("An error occurred")

例: JavaScript (Node.js 18 を使用)

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
  // リクエストを作成
  const inferenceRequest = {
    "inference_data": [{
      "text": "Hello, how are you?"
    }]
  };

  // リクエストを送信
  // ここでは、fetchメソッドを使用してHTTPリクエストを送信しています。
  // "<ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<RID>/v2"は、リクエストを送信するURLです。
  // method: "POST"は、HTTPメソッドを指定します。ここではPOSTを使用しています。
  // "Content-Type": "application/json"は、送信するコンテンツのタイプを指定します。ここではJSON形式のデータを送信します。
  // Authorization: "Bearer <BEARER_TOKEN>"は、APIにアクセスするための認証情報を指定します。
  // body: JSON.stringify(inferenceRequest)は、送信するデータを指定します。ここでは、inferenceRequestオブジェクトをJSON形式の文字列に変換して送信します。
  const response = await fetch(
    "<ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<RID>/v2",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization:
          "Bearer <BEARER_TOKEN>",
      },
      body: JSON.stringify(inferenceRequest),
    }
  );

  // レスポンスが成功（200 OK）でない場合、エラーをスローします。
  // response.okは、レスポンスのステータスが成功（200 OK）かどうかを返します。
  // エラーメッセージは、レスポンスのステータスコードとステータステキスト（理由句）を含みます。
  if (!response.ok) {
    throw Error(`${response.status}: ${response.statusText}`);
  }

  // レスポンスをJSON形式で解析します。
  const result = await response.json();

  // 結果をコンソールに表示します。
  console.log(result);

例：マルチ I/O モデル

マルチ I/O モデルは、複数の入力を受け取り、複数の出力を返すことができます。以下の画像は、複数の入力と出力を持つモデルの例を示しています：

マルチ I/O をクエリするには、前の例で示したのと同じリクエスト形式を使用し、inference_request には各入力の名前付きフィールドを含めます：

Copied!
1
2
3
4
5
6
{ 
  // "table_1" というキーに対応する値は、"Text for table one"というテキストを持つオブジェクトの配列です。
  "table_1": [{ "text": "Text for table one" }],
  // "table_2" というキーに対応する値は、"Text for table two"というテキストを持つオブジェクトの配列です。
  "table_2": [{ "text": "Text for table two" }]
}

モデルは、各出力に対応する名前付きフィールドを含むオブジェクトも返します：

Copied!
1
2
3
4
{
  "table_1_out": [{ "text": "Result for table one" }], // "table_1_out"は"テーブル1の結果"を意味します
  "table_2_out": [{ "text": "Result for table two" }], // "table_2_out"は"テーブル2の結果"を意味します
}

シングル I/O エンドポイント

• URL: <ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<LIVE_DEPLOYMENT_RID>
• <ENVIRONMENT_URL>: 詳細については、以下のセクションを参照してください。
• HTTPメソッド: POST
• 認証タイプ: Bearer トークン
• 必要な HTTP ヘッダー:
  • Content-Type: "application/json" でなければなりません。
  • Authorization: "Bearer <BEARER_TOKEN>" でなければなりません。<BEARER_TOKEN> は、ユーザーの認証トークンです。
• リクエストボディ: 以下のフィールドを持つ JSON オブジェクト:
  • requestData: モデルに送信される情報を含む配列。これの期待される形状は、デプロイされたモデルの API に依存します。
  • requestParams: モデルに送信されるリクエストパラメーターを含むオブジェクト。これは foundry_ml でパッケージ化されたモデルにのみ使用され、期待される形状もデプロイされたモデルの API に依存します。
• レスポンス: 成功したレスポンスは、ステータスコード 200 と、以下のフィールドを含む JSON オブジェクトを返します:
  • modelUuid: モデルを識別する文字列。
  • responseData: オブジェクトの配列で、各オブジェクトがモデルの推論レスポンスを表します。これらのオブジェクトの形状は、デプロイされたモデルの API に依存します。

例: シングル I/O エンドポイントでライブデプロイメントをクエリする

以下の例では、単一の入力と出力を持つシンプルな API のモデルを使用します。

この例のホストされたモデルは、inference_data という名前の単一の入力を期待しており、これは text 行を含むデータセットです。この場合、期待されるリクエスト形式は以下のようになります:

Copied!
1
2
3
4
5
6
7
{
  // "requestData"はリクエストの詳細を含む配列です。各リクエストは"text"というキーでテキスト情報を保持します。
  "requestData": [{ "text": "<ここにテキストが入ります>" }],
  
  // "requestParams"はリクエストのパラメータを格納するオブジェクトです。この場合、パラメータは空です。
  "requestParams": {},
}

モデルは、prediction 行を含む output_data という名前のデータセットで応答します。これは以下の応答に変換されます:

Copied!
1
2
3
4
5
6
{
  "modelUuid": "000-000-000", // モデルの一意の識別子
  "responseData": [{ // 応答データ
    "prediction": "<Model prediction here>" // モデルの予測結果
  }]
}

例: curl

Copied!
1
curl --http2 -H "Content-Type: application/json" -H "Authorization: <BEARER_TOKEN>" -d '{"requestData":[ { "text": "Hello, how are you?" } ], "requestParams":{}}' --request POST <ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<RID>

例: Python

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import requests

# 推論のためのURLを設定します
url = '<ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<RID>'

# 推論のリクエストデータを作成します
inference_request = {
    'requestData': [{ 'text': 'Hello, how are you?' }],  # 推論に使用するデータ
    'requestParams': {},  # 追加のリクエストパラメータ（必要に応じて）
}

# POSTリクエストを送信し、レスポンスを取得します
response = requests.post(url, json = inference_request, headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer <BEARER_TOKEN>' })

# レスポンスが正常であれば、モデルの結果を表示します
if response.ok:
    modelResult = response.json()['responseData']
    print(modelResult)
# レスポンスが異常であれば、エラーメッセージを表示します
else:
    print("An error occurred")

例: JavaScript (Node.js 18 を使用)

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// リクエストの作成
const inferenceRequest = {
  requestData: [{ text: "Hello, how are you?" }], // リクエストデータとしてテキストを入力します
  requestParams: {}, // リクエストのパラメーター
};

// リクエストの送信
const response = await fetch(
  "<ENVIRONMENT_URL>/foundry-ml-live/api/inference/transform/ri.foundry-ml-live.<RID>", // 予測の変換を行うためのAPIエンドポイント
  {
    method: "POST", // POSTメソッドを使用
    headers: {
      "Content-Type": "application/json", // コンテンツタイプは JSON
      Authorization:
        "Bearer <BEARER_TOKEN>", // Bearerトークンで認証
    },
    body: JSON.stringify(inferenceRequest), // リクエストデータをJSONに変換
  }
);

// レスポンスがOKでない場合はエラーをスロー
if (!response.ok) {
  throw Error(`${response.status}: ${response.statusText}`);
}

// レスポンスをJSONとして取得
const result = await response.json();

// レスポンスデータをコンソールに表示
console.log(result.responseData);

環境 URL

上記の例で、<ENVIRONMENT_URL> プレースホルダーはユーザーの環境の URL を表しています。環境の URL を取得するには、デプロイメントサンドボックスの クエリ タブから curl リクエストをコピーし、URL を抽出してください。

エラー処理

最も一般的な HTTP エラーコードは以下のとおりです。

• 400: 通常、モデル推論中に発生した例外によって引き起こされます。
• 422: 正しくフォーマットされていないリクエストによって引き起こされます。リクエスト内の JSON が有効であり、モデル API に準拠していることを確認してください。
• 429: リクエストが多すぎることによって引き起こされます。バックオフを伴って再試行してください。レート制限は、ユーザーの環境に依存します。
• 500: 内部サーバーエラーまたはデプロイメントエラーによって引き起こされます。これは、デプロイメントが不健全であり、自動的に再起動を試みる場合に発生することがあります。手動での対応が必要な場合があります。
• 503: サービスが利用できません。バックオフを伴って再試行してください。手動での対応が必要な場合があります。