RESTful API

gRPC APIに加えて、 TensorFlow ModelServerはRESTful APIもサポートしています。このページでは、これらのAPIエンドポイントとエンドツーエンドの使用例について説明します。

リクエストとレスポンスはJSONオブジェクトです。このオブジェクトの構成は、要求のタイプまたは動詞によって異なります。詳細については、以下のAPI固有のセクションを参照してください。

エラーが発生した場合、すべてのAPIは、 errorをキー、エラーメッセージを値として、レスポンス本文でJSONオブジェクトを返します。

 {
  "error": <error message string>
}
 

モデルステータスAPI

このAPIは、 ModelService.GetModelStatus gRPC APIにModelService.GetModelStatus従っています。 ModelServerのモデルのステータスを返します。

URL

 GET http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]
 

/versions/${VERSION}または/labels/${LABEL}を含めることはオプションです。省略された場合、すべてのバージョンのステータスが応答で返されます。

応答フォーマット

成功した場合、 GetModelStatusResponse protobufのJSON表現を返します。

モデルメタデータAPI

このAPIはPredictionService.GetModelMetadata gRPC APIに密接に従っています。 ModelServer内のモデルのメタデータを返します。

URL

 GET http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]/metadata
 

/versions/${VERSION}または/labels/${LABEL}を含めることはオプションです。省略した場合、最新バージョンのモデルメタデータが応答で返されます。

応答フォーマット

成功した場合、 GetModelMetadataResponse protobufのJSON表現を返します。

分類および回帰API

このAPIは、 PredictionService gRPC APIのClassifyメソッドとRegressメソッドに厳密に従います。

URL

 POST http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]:(classify|regress)
 

/versions/${VERSION}または/labels/${LABEL}を含めることはオプションです。省略した場合、最新バージョンが使用されます。

リクエストフォーマット

classify APIとregress APIのリクエスト本文は、次の形式のJSONオブジェクトである必要があります。

 {
  // Optional: serving signature to use.
  // If unspecifed default serving signature is used.
  "signature_name": <string>,

  // Optional: Common context shared by all examples.
  // Features that appear here MUST NOT appear in examples (below).
  "context": {
    "<feature_name3>": <value>|<list>
    "<feature_name4>": <value>|<list>
  },

  // List of Example objects
  "examples": [
    {
      // Example 1
      "<feature_name1>": <value>|<list>,
      "<feature_name2>": <value>|<list>,
      ...
    },
    {
      // Example 2
      "<feature_name1>": <value>|<list>,
      "<feature_name2>": <value>|<list>,
      ...
    }
    ...
  ]
}
 

<value>はJSON番号（整数または10進数）または文字列で、 <list>はそのような値のリストです。バイナリ（バイトのストリーム）値を表す方法の詳細については、以下のバイナリ値のエンコードのセクションを参照してください。この形式は、gRPCのClassificationRequestおよびRegressionRequestプロトに似ています。どちらのバージョンも、 Exampleオブジェクトのリストを受け入れます。

応答フォーマット

classifyリクエストは、次の形式でフォーマットされたJSONオブジェクトをレスポンス本文で返します。

 {
  "result": [
    // List of class label/score pairs for first Example (in request)
    [ [<label1>, <score1>], [<label2>, <score2>], ... ],

    // List of class label/score pairs for next Example (in request)
    [ [<label1>, <score1>], [<label2>, <score2>], ... ],
    ...
  ]
}
 

<label>は文字列です（モデルにスコアに関連付けられたラベルがない場合は、空の文字列""でもかまいません）。 <score>は10進数（浮動小数点）です。

regressリクエストは、次のような形式のJSONオブジェクトをレスポンス本文で返します。

 {
  // One regression value for each example in the request in the same order.
  "result": [ <value1>, <value2>, <value3>, ...]
}
 

<value>は10進数です。

gRPC APIのユーザーは、このフォーマットがClassificationResponseおよびRegressionResponseプロトと類似していることに気付くでしょう。

予測API

このAPIは、 PredictionService.Predict gRPC APIに密接に従っています。

URL

 POST http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]:predict
 

/versions/${VERSION}または/labels/${LABEL}を含めることはオプションです。省略した場合、最新バージョンが使用されます。

リクエストフォーマット

predict APIのリクエスト本文は、次の形式のJSONオブジェクトである必要があります。

 {
  // (Optional) Serving signature to use.
  // If unspecifed default serving signature is used.
  "signature_name": <string>,

  // Input Tensors in row ("instances") or columnar ("inputs") format.
  // A request can have either of them but NOT both.
  "instances": <value>|<(nested)list>|<list-of-objects>
  "inputs": <value>|<(nested)list>|<object>
}
 

入力テンソルを行形式で指定します。

この形式は、gRPC APIおよびCMLE予測APIの PredictRequestプロトに似ています 。名前付き入力テンソルがすべて同じ0番目の次元を持っている場合は、この形式を使用します。そうでない場合は、以下で説明する列形式を使用します。

行形式では、入力はJSONリクエストのインスタンスキーにキー付けされます。

名前付き入力が1つしかない場合は、 インスタンスキーの値を入力の値に指定します。

 {
  // List of 3 scalar tensors.
  "instances": [ "foo", "bar", "baz" ]
}

{
  // List of 2 tensors each of [1, 2] shape
  "instances": [ [[1, 2]], [[3, 4]] ]
}
 

リストを手動でフラット化する必要がないため、テンソルはネストされた表記で自然に表現されます。

複数の名前付き入力の場合、各項目は、名前付き入力ごとに1つずつ、入力名/テンソル値のペアを含むオブジェクトであることが期待されます。例として、以下は2つのインスタンスを持つリクエストで、それぞれに3つの名前付き入力テンソルのセットがあります。

 {
 "instances": [
   {
     "tag": "foo",
     "signal": [1, 2, 3, 4, 5],
     "sensor": [[1, 2], [3, 4]]
   },
   {
     "tag": "bar",
     "signal": [3, 4, 1, 2, 5]],
     "sensor": [[4, 5], [6, 8]]
   }
 ]
}
 

注、各名前の入力（「タグ」、「信号」、「センサー」）が暗黙的に（ インスタンスリスト内の2つのオブジェクトがあるように、上記の例では2つ ）と同じ0番目の寸法を有するものとします。 0番目の次元が異なる名前付き入力がある場合は、以下で説明する列形式を使用します。

入力テンソルを列形式で指定します。

個々の名前付き入力が同じ0番目の次元を持たない場合、またはよりコンパクトな表現が必要な場合は、この形式を使用して入力テンソルを指定します。この形式は、gRPC Predictリクエストのinputsフィールドに似ています。

列形式では、入力はJSONリクエストの入力キーにキー設定されます。

入力キーの値は、単一の入力テンソルまたは入力名のテンソルへのマップ（自然なネストされた形式でリスト）のいずれかです。各入力は任意の形状を持つことができ、上記の行フォーマットで必要とされる同じ/ 0番目の次元（別名バッチサイズ）を共有する必要はありません。

前の例の列表現は次のとおりです。

 {
 "inputs": {
   "tag": ["foo", "bar"],
   "signal": [[1, 2, 3, 4, 5], [3, 4, 1, 2, 5]],
   "sensor": [[[1, 2], [3, 4]], [[4, 5], [6, 8]]]
 }
}
 

入力はJSONオブジェクトであり、 インスタンスのようなリストではありません（行表現で使用されます ）。また、名前付き入力はすべて、前述の行形式で行われる個々の行に展開するのではなく、一緒に指定されます。これにより、表現がコンパクトになります（ただし、可読性が低下する可能性があります）。

応答フォーマット

predictリクエストは、レスポンス本文でJSONオブジェクトを返します。

行形式のリクエストには、次のような形式の応答があります。

 {
  "predictions": <value>|<(nested)list>|<list-of-objects>
}
 

モデルの出力に名前付きテンソルが1つだけ含まれている場合は、名前とpredictionsキーマップをスカラーまたはリスト値のリストに省略します。モデルが複数の名前付きテンソルを出力する場合は、上記の行形式のリクエストと同様に、代わりにオブジェクトのリストを出力します。

列形式のリクエストには、次のような形式の応答があります。

 {
  "outputs": <value>|<(nested)list>|<object>
}
 

モデルの出力に名前付きテンソルが1つだけ含まれている場合は、名前を省略して、キーマップをスカラーまたはリスト値のリストにoutputsます。モデルが複数の名前付きテンソルを出力する場合、代わりにオブジェクトを出力します。このオブジェクトの各キーは、名前付きの出力テンソルに対応しています。形式は、上記の列形式の要求に似ています。

バイナリ値の出力

TensorFlowは非バイナリ文字列とバイナリ文字列を区別しません。すべてDT_STRINGタイプです。名前のサフィックスとして_bytesを持つ名前付きテンソルは、バイナリ値を持つと見なされます。このような値は、以下のバイナリ値のエンコードのセクションで説明するように、異なる方法でエンコードされます。

JSONマッピング

RESTful APIはJSONの正規エンコーディングをサポートしているため、システム間でデータを簡単に共有できます。サポートされているタイプの場合、エンコードはタイプごとに以下の表で説明されています。以下にリストされていないタイプは、サポートされていないことを意味します。

バイナリ値のエンコード

JSONはUTF-8エンコーディングを使用します。 （画像バイトのように）バイナリである必要がある入力特徴またはテンソル値がある場合は 、データをBase64でエンコードし、次のようにb64をキーとして持つJSONオブジェクトにカプセル化する必要があります。

 { "b64": <base64 encoded string> }
 

このオブジェクトを入力特徴またはテンソルの値として指定できます。同じ形式が出力応答のエンコードにも使用されます。

image （バイナリデータ）とcaption機能を含む分類要求を以下に示します。

 {
  "signature_name": "classify_objects",
  "examples": [
    {
      "image": { "b64": "aW1hZ2UgYnl0ZXM=" },
      "caption": "seaside"
    },
    {
      "image": { "b64": "YXdlc29tZSBpbWFnZSBieXRlcw==" },
      "caption": "mountains"
    }
  ]
}
 

JSON準拠

多くの特徴またはテンソル値は浮動小数点数です。有限値（3.14、1.0など）とは別に、これらはNaNおよび非有限（ Infinityおよび-Infinity ）値を持つことができます。残念ながら、JSON仕様（ RFC 7159 ）はこれらの値を認識しません （JavaScript仕様は認識します）。

このページで説明するREST APIを使用すると、要求/応答JSONオブジェクトにそのような値を設定できます。これは、次のようなリクエストが有効であることを意味します。

 {
  "example": [
    {
      "sensor_readings": [ 1.0, -3.14, Nan, Infinity ]
    }
  ]
}
 

（厳密な）標準に準拠したJSONパーサーは、これを解析エラーで拒否します（ NaNトークンとInfinityトークンが実際の数値と混在しているため）。コードでリクエスト/レスポンスを正しく処理するには、これらのトークンをサポートするJSONパーサーを使用します。

NaN 、 Infinity 、 -Infinityトークンは、 proto3 、Python JSONモジュールおよびJavaScript言語で認識されます。

例

おもちゃのhalf_plus_threeモデルを使用して、REST APIの動作を確認できます。

REST APIエンドポイントを使用してModelServerを起動する

gitリポジトリからhalf_plus_threeモデルをダウンロードします 。

 $ mkdir -p /tmp/tfserving
$ cd /tmp/tfserving
$ git clone --depth=1 https://github.com/tensorflow/serving
 

Dockerを使用してModelServerを実行します。システムにネイティブにModelServerをインストールする場合は、 セットアップ手順に従って代わりにインストールし、 --rest_api_portオプションを使用してModelServerを起動してREST APIエンドポイントをエクスポートします（Dockerを使用する場合は不要）。

 $ cd /tmp/tfserving
$ docker pull tensorflow/serving:latest
$ docker run --rm -p 8501:8501 \
    --mount type=bind,source=$(pwd),target=$(pwd) \
    -e MODEL_BASE_PATH=$(pwd)/serving/tensorflow_serving/servables/tensorflow/testdata \
    -e MODEL_NAME=saved_model_half_plus_three -t tensorflow/serving:latest
...
.... Exporting HTTP/REST API at:localhost:8501 ...
 

ModelServerに対してREST API呼び出しを行う

別の端末で、 curlツールを使用してREST API呼び出しを行います。

次のようにモデルのステータスを取得します。

 $ curl http://localhost:8501/v1/models/saved_model_half_plus_three
{
 "model_version_status": [
  {
   "version": "123",
   "state": "AVAILABLE",
   "status": {
    "error_code": "OK",
    "error_message": ""
   }
  }
 ]
}
 

predict呼び出しは次のようになります。

 $ curl -d '{"instances": [1.0,2.0,5.0]}' -X POST http://localhost:8501/v1/models/saved_model_half_plus_three:predict
{
    "predictions": [3.5, 4.0, 5.5]
}
 

また、 regressコールは次のようになります。

 $ curl -d '{"signature_name": "tensorflow/serving/regress", "examples": [{"x": 1.0}, {"x": 2.0}]}' \
  -X POST http://localhost:8501/v1/models/saved_model_half_plus_three:regress
{
    "results": [3.5, 4.0]
}
 

regressはデフォルト以外のシグニチャー名で使用可能であり、明示的に指定する必要があることに注意してください。リクエストURLまたは本文が正しくない場合、HTTPエラーステータスが返されます。

 $ curl -i -d '{"instances": [1.0,5.0]}' -X POST http://localhost:8501/v1/models/half:predict
HTTP/1.1 404 Not Found
Content-Type: application/json
Date: Wed, 06 Jun 2018 23:20:12 GMT
Content-Length: 65

{ "error": "Servable not found for request: Latest(half)" }
$