TensorFlow サービングと互換性のある RESTful API#

はじめに

gRPC API に加えて、OpenVINO™ モデルサーバーは TensorFlow Serving 互換 REST API のドキュメントにある RESTful API もサポートします。要求の行形式と列形式の両方がこれらの API に実装されています。REST API は、クライアント側の Python 依存関係の数を減らし、アプリケーション・コードを簡素化することを目的とする場合に推奨します。

注: 数値データタイプのみがサポートされます。

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

モデルステータス API
モデルメタデータ API
予測 API
リロード API の構成
ステータス API の構成

注: Predict、GetModelMetadata、および GetModelStatus 関数呼び出しの実装は利用可能です。これらは最も一般的な関数呼び出しであり、ほとんどの使用シナリオに対応する必要があります。

モデルステータス API#

説明

提供されているモデルのステータス情報を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v1/models/${MODEL_NAME}/versions/${MODEL_VERSION}

注: /versions/${MODEL_VERSION} のインクルードはオプションです。省略した場合は、すべてのバージョンのステータスが返されます。

応答形式

成功すると、次の形式の JSON が返されます:

{ 
  "model_version_status":[ 
    { 
      "version": <model version>|<string>, 
      "state": <model state>|<string>, 
      "status":
        { "error_code": <error code>|<string>, 
        "error_message": <error message>|<string> 
      } 
    } 
  ] 
}

使用例

$ curl http://localhost:8001/v1/models/person-detection/versions/1

{ 
  'model_version_status':[ 
    { 
      'version': '1', 
      'state': 'AVAILABLE', 
      'status': { 
        'error_code': 'OK', 
        'error_message': '’ 
      } 
    } 
  ] 
}

モデルのステータス取得 API の使用法をご覧ください。

モデルメタデータ API#

説明

モデルサーバー内のモデルのメタデータを取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v1/models/${MODEL_NAME}/versions/${MODEL_VERSION}/metadata

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

応答形式

成功すると、GetModelMetadataResponse の JSON 表現が返されます。

使用例

$ curl http://localhost:8001/v1/models/person-detection/versions/1/metadata 
{ 
  "modelSpec": { 
    "name": "person-detection", 
    "version": "1" 
  }, 
  "metadata": { 
    "signature_def": { 
      "@type": "type.googleapis.com/tensorflow.serving.SignatureDefMap", 
      "signatureDef": { 
        "serving_default": { 
          "inputs": { 
            "data": { 
              "name": "data_2:0", 
              "dtype": "DT_FLOAT", 
              "tensorShape": { 
                "dim": [ 
                  { 
                    "size": "1" 
                  }, 
                  { 
                    "size": "3" 
                  }, 
                  { 
                    "size": "400" 
                  }, 
                  { 
                    "size": "600" 
                  } 
                ] 
              } 
            } 
          }, 
          "outputs": { 
            "detection_out": { 
              "name": "detection_out_2:0", 
              "dtype": "DT_FLOAT", 
              "tensorShape": { 
                "dim": [ 
                  { 
                    "size": "1" 
                  }, 
                  { 
                    "size": "1" 
                  }, { 
                    "size": "200" 
                  }, { 
                    "size": "7" 
                  } 
                ] 
              } 
            }  
          }, 
          "methodName": "tensorflow/serving/predict" 
        } 
      } 
    } 
  } 
}

モデルのメタデータ取得 API の使用法をご覧ください。

予測 API#

説明

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

URL

POST http://${REST_URL}:${REST_PORT}/v1/models/${MODEL_NAME}/versions/${MODEL_VERSION}:predict

要求ヘッダー

{ 
  // (オプション) 使用するサービング署名 
  // 指定されていない場合はデフォルトのサービング署名が使用されます。
  "signature_name": <string>,
 
  // 行形式 ("インスタンス") または列形式 ("入力") でテンソルを入力します。 
  // リクエストにはいずれか一方を含めることができますが、両方を含めることはできません。 
   "instances": <value>|<(nested)list>|<list-of-objects> 
  "inputs": <value>|<(nested)list>|<object> 
}

詳細については、行形式で入力テンソルを指定する方法と列形式で入力テンソルを指定する方法を参照してください。

応答

行形式の要求には、次のような形式の応答が含まれます:

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

列形式の要求には、次のような形式の応答が含まれます:

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

数値のほかに、JPEG / PNG でエンコードされた画像をバイナリー入力として渡すことができます。以下のように b64 キーで渡され、Base64 でエンコードされている必要があります:

{ 
  "instances": [ 
    { 
      "image": { "b64": "aW1hZ2UgYnl0ZXM=" }, 
    }, 
    { 
      "image": { "b64": "YXdlc29tZSBpbWFnZSBieXRlcw==" }, 
    } 
  ] 
}

サーバー側では、バイナリーエンコードされたデータが OpenCV を使用してロードされ、推論のため OpenVINO に適したデータ形式に変換されます。

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

予測 API API の使用法については、こちらをご覧ください。

リロード API の構成#

説明

RESTful API 経由で要求を送信して構成の再読み込みをトリガーし、応答としてモデルと DAG のステータスを取得します。このエンドポイントを無効な自動構成リロードで使用すると、構成の変更が特定の時間内に適用されるようにしたり、リロード操作のステータスに関する確認を取得することができます。通常、このオプションは、OVMS がパラメーター --file_system_poll_wait_seconds 0 で起動される場合に使用されます。リロード操作では、新しい構成は OVMS サーバーに渡されません。構成ファイルの変更は、OVMS 管理者によって適用される必要があります。REST API 呼び出しは、すでに存在する構成ファイルの適用を開始するだけです。

URL

POST http://${REST_URL}:${REST_PORT}/v1/config/reload

Flow

要求を受けてからの流れ:

設定ファイルが変更された場合は、設定をリロードします。
モデルのバージョン・ディレクトリーが変更された場合、または新しいバージョンが追加された場合は、このモデルをリロードします。
DAG の一部のモデルが変更された場合、または新しいバージョンが追加された場合は、このパイプラインをリロードします。
リロード操作にエラーがない場合、応答にはすべてのモデルと DAG のステータスが含まれます。それ以外の場合は、エラーメッセージが返されます。

要求

リロードをトリガーするには、空の本文を含む HTTP POST 要求を URL に送信する必要があります。curl コマンドの例:

curl --request POST http://${REST_URL}:${REST_PORT}/v1/config/reload

応答

構成のリロードが成功した場合、応答には、リロード完了後のすべてのモデルと DAG の getModelStatus 応答の集計と操作ステータスを含む JSON が含まれます。

{ 
  "<model name>": 
    { 
      "model_version_status": [ 
        { 
          "version": <model version>|<string>, 
          "state": <model state>|<string>, 
          "status": 
            { 
              "error_code": <error code>|<string>, 
              "error_message": <error message>|<string> 
            } 
    }, 
    ... 
    ] 
  }, 
  ...
}

実行中にエラーが発生した場合:

{ 
  "error": <error message>|<string> 
}

操作が成功した場合の HTTP 応答のステータスコードは次のとおりです。

201 - config (設定ファイルまたはモデルのバージョン) がリロードされたとき
200 - リロードが必要なかった場合、すでに適用されていた場合、または OVMS が単一モデルのモードで開始された場合

操作が失敗すると、別のステータスコードが返されます。エラー時に返される可能性のあるメッセージ:

構成ファイルの変更時刻の取得に失敗しました (ファイルが存在しないか、アクセスできません):

{ 
  "error": "Config file not found or cannot open." 
}

構成ファイルが変更され、構成の再ロードが失敗しました (ファイルの内容が有効な JSON ではなく、モデルまたは DAG 構成のいずれかが正しくありません):

{ 
  "error": "Reloading config file failed. Check server logs for more info." 
}

構成ファイルは変更されず、モデルバージョンのリロードは失敗しました (モデル・ディレクトリーは削除されました):

{ 
  "error": "Reloading models versions failed. Check server logs for more info."
}

いずれかのモデルのステータスの取得に失敗しました:

{ 
  "error": "Retrieving all model statuses failed. Check server logs for more info."
}

モデルステータス応答の JSON への変換に失敗しました:

{ 
  "error": "Serializing model statuses to JSON failed. Check server logs for more info."
}

モデルの 1 つがリロードに失敗した場合でも、他のモデルは正常に動作している可能性があります。ロードされたモデルの状態を確認するには、ステータス API の構成を使用します。上記のエラーの正確な原因を検出するには、サーバーログの分析が必要になる場合があります。

ステータス API の構成#

説明

RESTful API 経由で要求を送信し、すべてのモデルと DAGs の getModelStatus 応答の集計を含む応答を取得します。

URL

GET http://${REST_URL}:${REST_PORT}/v1/config

リクエスト この API をトリガーするには、指定された URL で HTTP GET リクエストを送信する必要があります。curl コマンドの例:

curl --request GET http://${REST_URL}:${REST_PORT}/v1/config

応答成功した場合、応答には、すべてのモデルおよび DAG の getModelStatus 応答の集計と操作ステータスを含む JSON が含まれます。

{ 
  "<model name>": 
    { 
      "model_version_status": [ 
        { 
          "version": <model version>|<string>, 
          "state": <model state>|<string>, 
          "status": 
            { 
              "error_code": <error code>|<string>, 
              "error_message": <error message>|<string> 
            } 
    }, 
    ...
    ] 
  }, 
  ...
}

実行中にエラーが発生した場合:

{ 
  "error": <error message>|<string> 
}

操作が成功した場合、HTTP 応答のステータスコードは 200 ですが、それ以外の場合は別のコードが返されます。エラー時に返される可能性のあるメッセージ:

いずれかのモデルのステータスの取得に失敗しました:

{ 
  "error": "Retrieving all model statuses failed. Check server logs for more info."
}

モデルステータス応答の JSON への変換に失敗しました:

{ 
  "error": "Serializing model statuses to json failed. Check server logs for more info."
}