Method: projects.predict

Performs online prediction on the data in the request.

AI Platform Prediction は、HTTP POST メソッドにカスタム predict 動詞を実装しています。predict メソッドは、リクエストのデータに対して予測を行います。

URL は、Google API HTTP アノテーション構文で説明されています。

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

name パラメータは必須です。モデルの名前は必須で、バージョンは任意となります。バージョンなしでモデルを指定すると、そのモデルのデフォルト バージョンが使用されます。

モデルとバージョンの両方を指定する例:

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name/versions/your-version-name:predict

モデルのみを指定する例。そのモデルのデフォルト バージョンが使用されます。

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:predict

このページでは、予測リクエストの本文とレスポンスの本文の形式について説明します。予測リクエストの送信方法を示すサンプルコードについては、オンライン予測のリクエストのガイドをご覧ください。

リクエスト本文の詳細

TensorFlow

リクエストの本文には、次の構造をしたデータが含まれています(JSON 表現)。

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

instances[] オブジェクトは必須であり、予測の取得対象となるインスタンスのリストをこれに含める必要があります。

インスタンスのリストに含まれる各要素の構造は、モデルの入力定義によって決まります。インスタンスには、名前付き入力を(オブジェクトとして)含めることも、ラベルなし値のみを含めることもできます。

すべてのデータに名前付き入力が含まれるわけではありません。インスタンスは、単純な JSON 値(ブール値、数値、文字列)の場合もあれば、単純な値のリスト、または複雑なネスト構造のリストの場合もあります。

以下にリクエスト本文の例を示します。

各行が文字列値としてエンコードされた CSV データ:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

書式なしテキスト:

{"instances": ["the quick brown fox", "la bruja le dio"]}

単語のリスト(文字列のベクトル)としてエンコードされた文:

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

浮動小数点スカラー値:

{"instances": [0.0, 1.1, 2.2]}

整数のベクトル:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

テンソル(この場合、2 次元のテンソル):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

画像は、さまざまな方法で表現できます。次のエンコード スキームでは、最初の 2 つの次元は画像の行と列を表し、3 つ目の次元に各ピクセルの R、G、B 値のリスト(ベクトル)が含まれます。

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

データのエンコード

JSON 文字列は UTF-8 としてエンコードする必要があります。バイナリデータを送信するには、データを Base64 エンコードし、バイナリとしてマークする必要があります。JSON 文字列をバイナリとしてマークするには、b64 という名前の単一の属性の JSON オブジェクトに置き換えます。

{"b64": "..."} 

次の例は、Base64 エンコードを必要とする 2 つのシリアル化された tf.Examples インスタンスを示しています(例示のための架空データ)。

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

次の例は、Base64 エンコーディングを必要とする、JPEG 画像の 2 つのバイト文字列を示しています(例示のための架空のデータ)。

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

複数の入力テンソル

一部のモデルでは、基盤となる TensorFlow グラフで複数の入力テンソルが受け入れられます。この場合、JSON の名前と値のペアの名前を使用して入力テンソルを識別します。

入力テンソルの別名 "tag"(文字列)と "image"(Base64 でエンコードされた文字列)を持つグラフの場合:

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

入力テンソルの別名 "tag"(文字列)と "image"(8 ビット整数の 3 次元配列)を持つグラフの場合:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

リクエストの本文には、次の構造をしたデータが含まれています(JSON 表現)。

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] オブジェクトは必須であり、予測の取得対象となるインスタンスのリストをこれに含める必要があります。次の例では、各入力インスタンスは浮動小数点数のリストです。

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

入力インスタンスの次元は、モデルが想定している次元と一致している必要があります。たとえば、モデルに 3 つの特徴が必要な場合、各入力インスタンスの長さは 3 である必要があります。

XGBoost

リクエストの本文には、次の構造をしたデータが含まれています(JSON 表現)。

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] オブジェクトは必須であり、予測の取得対象となるインスタンスのリストをこれに含める必要があります。次の例では、各入力インスタンスは浮動小数点数のリストです。

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

入力インスタンスの次元は、モデルが想定している次元と一致している必要があります。たとえば、モデルに 3 つの特徴が必要な場合、各入力インスタンスの長さは 3 である必要があります。

AI Platform Prediction は、XGBoost の入力インスタンスのスパース表現をサポートしていません。

オンライン予測サービスは、ゼロと NaN を区別して解釈します。特徴の値がゼロの場合は、対応する入力で 0.0 を使用します。特徴の値が不足している場合は、対応する入力で NaN を使用します。

次の例は、単一入力インスタンスを含む予測リクエストを表しています。ここで最初の特徴の値は 0.0、2 番目の特徴の値は 1.1、3 番目の特徴の値はありません。

{"instances": [[0.0, 1.1, NaN]]}

カスタム予測ルーチン

リクエストの本文には、次の構造をしたデータが含まれています(JSON 表現)。

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ],
  "<other-key>": <value>|<simple/nested list>|<object>,
  ...
}

instances[] オブジェクトは必須であり、予測の取得対象となるインスタンスのリストをこれに含める必要があります。

他の有効な JSON Key-Value ペアを指定することもできます。AI Platform Prediction は JSON を解析し、これらのフィールドを **kwargs 辞書のエントリとして Predictor クラスpredict メソッドに渡します。

インスタンスのリストを構造化する方法

インスタンスのリストに含まれる各要素の構造は、Predictor クラスpredict メソッドによって決定されます。インスタンスには、名前付き入力を(オブジェクトとして)含めることも、ラベルなし値のみを含めることもできます。

すべてのデータに名前付き入力が含まれるわけではありません。インスタンスは、単純な JSON 値(ブール値、数値、文字列)の場合もあれば、単純な値のリスト、または複雑なネスト構造のリストの場合もあります。

以下にリクエスト本文の例を示します。

各行が文字列値としてエンコードされた CSV データ:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

書式なしテキスト:

{"instances": ["the quick brown fox", "la bruja le dio"]}

単語のリスト(文字列のベクトル)としてエンコードされた文:

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

浮動小数点スカラー値:

{"instances": [0.0, 1.1, 2.2]}

整数のベクトル:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

テンソル(この場合、2 次元のテンソル):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

画像は、さまざまな方法で表現できます。次のエンコード スキームでは、最初の 2 つの次元は画像の行と列を表し、3 つ目の次元に各ピクセルの R、G、B 値のリスト(ベクトル)が含まれます。

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

複数の入力テンソル

一部のモデルでは、基盤となる TensorFlow グラフで複数の入力テンソルが受け入れられます。この場合、JSON の名前と値のペアの名前を使用して入力テンソルを識別します。

入力テンソルの別名 "tag"(文字列)と "image"(8 ビット整数の 3 次元配列)を持つグラフの場合:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

レスポンス本文の詳細

レスポンスはリクエストと非常によく似ています。

呼び出しが成功した場合、レスポンスの本文には、リクエストの本文内のインスタンスごとに、同じ順序で 1 つの予測エントリが含まれます。

{
  "predictions": [
    {
      object
    }
  ]
}

いずれかのインスタンスの予測に失敗した場合、レスポンスの本文には予測が含まれません。代わりに、単一のエラーエントリが含まれます。

{
  "error": string
}

predictions[] オブジェクトには、リクエストのインスタンスごとに 1 つの予測からなるリストが含まれます。カスタム予測ルーチン(ベータ版)の場合、predictions には Predictor クラスpredict メソッドから返された値が格納され、JSON としてシリアル化されます。

エラーの場合、error 文字列には問題を説明するメッセージが含まれます。インスタンスの処理中にエラーが発生した場合は、予測リストではなくエラーが返されます。

インスタンスごとに 1 つの予測があっても、予測の形式はインスタンスの形式に直接関係しません。予測には、モデルに定義された出力コレクションで指定されている形式が適用されます。予測のコレクションは JSON リストで返されます。リストの各メンバーは、単純な値、リスト、多様な複雑度の JSON オブジェクトのいずれかです。モデルに複数の出力テンソルがある場合、各予測は各出力の名前と値のペアを含む JSON オブジェクトになります。名前はグラフの出力エイリアスを識別します。

レスポンス本文の例

TensorFlow

次の例は、いくつかの可能なレスポンスを示しています。

  • 3 つの入力インスタンスの単純な予測セット。各予測は整数値です。

    {"predictions": [5, 4, 3]}
    
  • より複雑な予測セット。予測のそれぞれに、出力テンソルに対応する labelscores という 2 つの名前付き値が含まれます。label の値は予測カテゴリ("car" または "beach")であり、scores には可能性のあるカテゴリでそのインスタンスで発生する可能性のあることのリストが含まれます。

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 入力インスタンスの処理中にエラーが発生した場合のレスポンス:

    {"error": "Divide by zero"}
    

scikit-learn

次の例は、いくつかの可能なレスポンスを示しています。

  • 3 つの入力インスタンスの単純な予測セット。各予測は整数値です。

    {"predictions": [5, 4, 3]}
    
  • 入力インスタンスの処理中にエラーが発生した場合のレスポンス:

    {"error": "Divide by zero"}
    

XGBoost

次の例は、いくつかの可能なレスポンスを示しています。

  • 3 つの入力インスタンスの単純な予測セット。各予測は整数値です。

    {"predictions": [5, 4, 3]}
    
  • 入力インスタンスの処理中にエラーが発生した場合のレスポンス:

    {"error": "Divide by zero"}
    

カスタム予測ルーチン

次の例は、いくつかの可能なレスポンスを示しています。

  • 3 つの入力インスタンスの単純な予測セット。各予測は整数値です。

    {"predictions": [5, 4, 3]}
    
  • より複雑な予測セット。予測のそれぞれに、出力テンソルに対応する labelscores という 2 つの名前付き値が含まれます。label の値は予測カテゴリ("car" または "beach")であり、scores には可能性のあるカテゴリでそのインスタンスで発生する可能性のあることのリストが含まれます。

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 入力インスタンスの処理中にエラーが発生した場合のレスポンス:

    {"error": "Divide by zero"}
    

API 仕様

次のセクションでは、predict メソッドの仕様を AI Platform Training and Prediction API のディスカバリ ドキュメントの定義に従って説明します。メソッドの詳細については、このドキュメントの前のセクションをご覧ください。

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:predict

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The prediction request body. Refer to the request body details section for more information on how to structure your request.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.