予測リクエストの詳細

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

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

リクエストの本文

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

{
  "instances": {[
    object
  ]}
}

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

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

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

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

各行が文字列値としてエンコードされた 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 エンコーディングを必要とする 2 つの JPEG イメージバイト文字列を示しています(単に例示を目的とした偽のデータ)。

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

名前付き参照

データに名前付き参照が含まれている場合は、名前付き参照をキーとした各インスタンスを JSON オブジェクトとしてフォーマットします。

前処理する JSON 入力データ:

{
  "instances": [
    {
      "a": 1.0,
      "b": true,
      "c": "x"
    },
    {
      "a": -2.0,
      "b": false,
      "c": "y"
    }
  ]
}

複数の入力テンソル

一部のモデルでは、基盤となる 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],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

レスポンスの本文

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

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

{
  "predictions": [
    {
      object
    }
  ]
}

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

{
  "error": string
}

predictions[] オブジェクトには、リクエストのインスタンスごとに 1 つずつ、予測のリストが含まれます。

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

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

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

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

{"predictions": [5, 4, 3]}

より複雑な予測セット。それぞれに出力テンソルに対応する 2 つの名前付き値が含まれ、それぞれ labelscores と呼ばれます。label の値は予測カテゴリ("car" または "beach")であり、scores には可能なカテゴリ全体のそのインスタンスの可能性のリストが含まれます。

{
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ]
}

入力インスタンスの処理中にエラーが発生した場合のレスポンス:

{"error": "Divide by zero"}

HTTP URL 形式

予測リクエストの送信方法を示すコードサンプルについては、オンライン予測のリクエストのガイドをご覧ください。このページの残りの部分では、詳細な説明が必要な方のために、Cloud ML Engine によって実装された HTTP URL 形式について説明します。

Cloud ML Engine は、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 セグメントは、Cloud ML Engine が Google API HTTP ドキュメントで定義されている「カスタム動詞」を使用していることを示します。この場合、カスタム動詞は predict です。

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

Cloud Machine Learning Engine(Cloud ML Engine)