予測リクエストの詳細

predict メソッドは、リクエスト内のデータに関する予測を実行します。

このページでは、予測リクエスト本文およびレスポンス本文の形式と、HTTP リクエストの URL 形式について説明します。予測リクエストの送信方法を示すコードサンプルについては、TensorFlow によるオンライン予測のリクエストのガイドと、scikit-learn および XGBoost によるオンライン予測の取得のチュートリアルをご覧ください。

リクエスト本文

TensorFlow

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

{
  "instances": [
    <value>|<simple/nested list&gt|<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 は、XGBoost の入力インスタンスのスパース表現をサポートしていません。

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

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

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

レスポンス本文

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

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

{
  "predictions": [
    {
      object
    }
  ]
}

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

{
  "error": string
}

predictions[] オブジェクトには予測のリストが含まれます。それぞれの予測が、リクエストの 1 つのインスタンスに対応します。

エラーの場合、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"}
    

HTTP URL 形式

予測リクエストの送信方法を示すコードサンプルについては、TensorFlow によるオンライン予測のリクエストのガイドと、scikit-learn および XGBoost によるオンライン予測の取得のチュートリアルをご覧ください。このページの残りの部分では、詳細な説明が必要な方のために、AI Platform で実装される HTTP URL 形式について説明します。

AI Platform は、HTTP POST メソッドにカスタム predict 動詞を実装しています。URL は、Google API HTTP アノテーション構文で説明されています。

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

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

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

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

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

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model:predict

パスの最後にある :predict セグメントは、AI Platform が Google API HTTP ドキュメントで定義されているカスタム動詞を使用することを表しています。上記の例の場合、カスタム動詞は predict です。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...