KServe 互換 RESTful API#

はじめに

gRPC APIs API に加えて、OpenVINO™ モデルサーバーは KServe REST API のドキュメントにある RESTful API もサポートします。REST API は、クライアント側の Python 依存関係の数を減らし、アプリケーション・コードを簡素化することを目的とする場合に推奨します。

このドキュメントでは、次の API について説明します:

サーバーライブ API#

説明

サーバーの稼働状況に関する情報を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v2/health/live

応答形式

サーバーの稼働状況に関する情報は、応答ステータスコードで提供されます。サーバーが稼働している場合、ステータスコードは 200 です。それ以外は 4xx です。応答の本文にはコンテンツがありません。

使用例

$ curl -i http://localhost:5000/v2/health/live 

HTTP/1.1 200 OK 
Content-Type: application/json 
Date: Tue, 09 Aug 2022 09:20:24 GMT 
Content-Length: 2

HTTP サーバーライブのエンドポイント上の KServe API を使用してサーバーの稼働状態を取得するサンプルコードも参照してください。

サーバーレディー API#

説明

サーバーの準備状況に関する情報を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v2/health/ready

応答形式

サーバーの準備状況に関する情報は、応答ステータスコードで提供されます。サーバーの準備ができている場合、ステータスコードは 200 です。それ以外は 4xx です。応答の本文にはコンテンツがありません。

使用例

$ curl -i http://localhost:5000/v2/health/ready 

HTTP/1.1 200 OK 
Content-Type: application/json 
Date: Tue, 09 Aug 2022 09:22:14 GMT 
Content-Length: 2

HTTP サーバーレディーのエンドポイントで KServe API を使用してサーバーの準備を整えるサンプルコードも参照してください。

サーバーメタデータ API#

説明

サーバーの情報を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v2

応答形式

成功した場合:

{ 
  "name" : $string, 
  "version" : $string, 
  "extensions" : [ $string,...] 
}

失敗した場合:

{ 
  "error": $string 
}

使用例

$ curl http://localhost:5000/v2 
{"name":"OpenVINO Model Server","version":"2022.2.0.fd742507"}

応答内容の詳細については、KServe API ドキュメントを参照してください。

HTTP サーバーメタデータのエンドポイントで KServe API を使用してサーバーのメタデータを取得するサンプルコードも参照してください。

モデルレディー API#

説明

モデルの準備状況に関する情報を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v2/models/${MODEL_NAME}
[/versions/${MODEL_VERSION}]/ready

応答形式

モデルの準備状況に関する情報は、応答ステータスコードで提供されます。モデルが推論の準備ができている場合、ステータスコードは 200 です。それ以外は 4xx です。応答の本文にはコンテンツがありません。

使用例

$ curl -i http://localhost:5000/v2/models/resnet/ready 

HTTP/1.1 200 OK 
Content-Type: application/json 
Date: Tue, 09 Aug 2022 09:25:31 GMT 
Content-Length: 2

HTTP モデルレディーのエンドポイントで KServe API を使用してモデルの準備を整えるサンプルコードも参照してください。

モデルメタデータ API#

説明

特定のモデルの情報を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v2/models/${MODEL_NAME}
[/versions/${MODEL_VERSION}]

注: ${MODEL_VERSION} のインクルードはオプションです。省略した場合、最新バージョンのモデルメタデータが返されます。

応答形式

成功した場合:

{ 
  "name" : $string, 
  "versions" : [ $string, ... ] #optional, 
  "platform" : $string,
  "inputs" : [ $metadata_tensor, ... ], 
  "outputs" : [ $metadata_tensor, ... ] 
}

説明:

$metadata_tensor = 
{ 
  "name" : $string, 
  "datatype" : $string, 
  "shape" : [ $number, ... ] 
}

失敗した場合:

{ 
  "error": $string 
}

使用例

$ curl http://localhost:8000/v2/models/resnet 
{"name":"resnet","versions":["1"],"platform":"OpenVINO","inputs":
[{"name":"0","datatype":"FP32","shape":[1,224,224,3]}],"outputs":
[{"name":"1463","datatype":"FP32","shape":[1,1000]}]}

応答内容の詳細については、KServe API ドキュメントを参照してください。

HTTP モデルメタデータのエンドポイントで KServe API を使用してモデルメタデータを取得をするサンプルコードも参照してください。

推論 API#

説明

読み込まれたモデルまたは DAG を使用して推論を実行するエンドポイントです。

URL

POST http://${REST_URL}:${REST_PORT}/v2/models/${MODEL_NAME}
[/versions/${MODEL_VERSION}]/infer

要求本体の形式

{ 
  "id" : $string #optional, 
  "parameters" : $parameters #optional, 
  "inputs" : [ $request_input, ... ], 
  "outputs" : [ $request_output, ... ] #optional 
}

説明:

$request_input = 
{ 
  "name" : $string, 
  "shape" : [ $number, ... ], 
  "datatype" : $string, 
  "parameters" : $parameters #optional, 
  "data" : $tensor_data 
} 

$request_output = 
{ 
  "name" : $string, 
  "parameters" : $parameters #optional, 
}

注: tensor_data の要素は多次元表現、または平坦化された 1 次元表現として表現できます。推論実行前に tensor データがフラット化され、tensor_data 内の要素数のみが検証されます。

数値のほかに、バイナリーデータ拡張子を使用してエンコードされた画像を渡すことができます:

JPEG / PNG でエンコードされた画像 - この場合、バイナリーエンコードされたデータは OpenCV を使用して OVMS によってロードされ、推論のため OpenVINO に適したデータ形式に変換されます。データタイプが BYTES で、モデルまたはパイプラインの形状次元が 4 (demultiplexing の場合は 5) である場合、入力はエンコードされたイメージとして扱われます。すべてのバッチの BYTES 入力の前に、そのサイズを含む 4 バイト (リトル・エンディアン) を付ける必要があります。

Content-Type: application/octet-stream 
Inference-Header-Content-Length: <xx> 
Content-Length: <xx+9472> 
{ "model_name" : "my_model"
, "inputs" : [ 
  { 
    "name" : "model_input", 
    "shape" : [ 1 ], 
    "datatype" : "BYTES" 
  } 
] 
} 
<0x00250000 (9472 as four bytes little endian)><9472 bytes of data for model_input tensor>

生データ - OVMS によって前処理されないことを意味します。バイナリーデータ拡張機能を使用して生データを送信するには、BYTES 以外のデータタイプを使用します。

Content-Type: application/octet-stream 
Inference-Header-Content-Length: <xx> 
Content-Length: <xx+(3 x 1080000)> 
{ 
"model_name" : "my_model", 
"inputs" : [ 
  { 
    "name" : "model_input", 
    "shape" : [ 3, 300, 300, 3 ], 
    "datatype" : "FP32" 
  }, 

] 
} 
<3240000 bytes of the whole data batch for model_input tensor>

*バイナリー拡張内で文字列を送信するには、各バッチをそのサイズを含む 4 バイト (リトル・エンディアン) で先行させる必要があります。

詳細については、OpenVINO モデルサーバーでバイナリーデータがどのように処理されるかを確認してください。

応答形式

成功した場合:

{ 
  "model_name" : $string, 
  "model_version" : $string #optional, 
  "id" : $string, 
  "parameters" : $parameters #optional, 
  "outputs" : [ $response_output, ... ] 
}

説明:

$response_output = 
{ 
  "name" : $string, 
  "shape" : [ $number, ... ], 
  "datatype" : $string, 
  "parameters" : $parameters #optional, 
  "data" : $tensor_data 
}

失敗した場合:

{ 
  "error": <error message string> 
}

応答の出力は、バイナリーデータ拡張機能を使用してバイナリー形式で送信できます。出力を強制的にバイナリー形式で送信するには、要求 JSON で “binary_data” : true パラメーターを使用する必要があります。次に例を示します:

{ 
  "model_name" : "mymodel", 
  "inputs" : [...], 
  "outputs" : [ 
    { 
      "name" : "output0", 
      "parameters" : { 
        "binary_data" : true 
      } 
    } 
  ] 
}

出力データタイプが FP32 で、形状が [ 2, 2 ] であると仮定すると、この要求に対する応答は次のようになります:

HTTP/1.1 200 OK 
Content-Type: application/octet-stream 
Inference-Header-Content-Length: <yy> 
Content-Length: <yy+16> 
{ 
  "outputs" : [ 
    { 
      "name" : "output0", 
      "shape" : [ 2, 2 ], 
      "datatype" : "FP32", 
      "parameters" : { 
        "binary_data_size" : 16 
      } 
    } 
  ] 
} 
<16 bytes of data for output0 tensor>

要求と応答の内容の詳細については、KServe API ドキュメントを参照してください。

注: REST 経由で推論を実行する効率的な方法は、バイナリーデータ拡張機能を使用して、JSON オブジェクトの外部にバイナリー形式でデータを送信することです。

注: 要求 URI の最後に //.. を使用すると、パスが切り詰められ、予想とは異なる応答が返される可能性があります。

HTTP 推論エンドポイントで KServe API を使用して推論を実行するサンプルコードも参照してください。