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 を使用して推論を実行するサンプルコードも参照してください。