OpenVINO モデルサーバー C API#

はじめに

このドキュメントでは、OpenVINO モデルサーバーを C/C++ アプリケーションにリンクできるようにする OpenVINO モデルサーバー (OVMS) C API について説明します。このドキュメントの最後に記載されている例外を除き、OpenVINO モデルサーバーのすべての機能は共有ライブラリーに含まれています。

OpenVINO モデルサーバー 2023.1 リリースでは、C-API はプレビュー状態ではなくなり、正式に公開されました。このバージョンには大きな変更はほとんど含まれていません。次の関数名が変更されました - *Get* が名前から削除されました:

  • OVMS_StatusGetCode

  • OVMS_StatusGetDetails

  • OVMS_InferenceResponseGetOutputCount

  • OVMS_InferenceResponseGetOutput

  • OVMS_InferenceResponseGetParameterCount

  • OVMS_InferenceResponseGetParameter

  • OVMS_ServableMetadataGetInputCount

  • OVMS_ServableMetadataGetOutputCount

  • OVMS_ServableMetadataGetInput

  • OVMS_ServableMetadataGetOutput

  • OVMS_ServableMetadataGetInfo

API の説明#

サーバー機能は、OpenVINO モデルサーバーのソースから構築された共有ライブラリーにカプセル化されています。OpenVINO モデルサーバーを組み込むには、このライブラリーをアプリケーションにリンクし、ヘッダーファイルで定義された C API を使用します。

アプリケーションで提供されるモデルを開始するメソッドを呼び出すと、OpenVINO モデルサーバーが別のスレッドとして起動されます。その後、C API と gRPC/HTTP エンドポイントを使用してアプリから直接推論をスケジュールできます。

API は SemVer 2.0 に従ってバージョン管理されています。OVMS_ApiVersion を呼び出すと、major バージョン番号と minor バージョン番号を取得できます。

  • major - 新しい下位互換性のない変更が API 自体に導入されたときに増分されます (API 呼び出しの削除、名前の変更、パラメーターの変更など)。

  • minor - API が変更されると増分されますが、下位互換性があります (新しい API 呼び出しが追加されたなど)。

パッチのバージョン番号はありません。API 自体に関係のない基礎的な機能の変更は、OpenVINO モデルサーバーのバージョンを通じて追跡されます。OpenVINO モデルサーバーと OpenVINO のバージョンは、ログまたは ServerMetadata 要求 (KServe API 経由) を介して追跡できます。

サーバーの構成と開始#

OpenVINO モデルサーバーを起動するには、サーバーの構成を記述する OVMS_ServerSettings および OVMS_ModelsSettings を設定するとともに、OVMS_ServerNew を使用して OVMS_Server オブジェクトを作成する必要があります。OVMS_ServerStartFromConfigurationFile を使用してサーバーを起動したら、OVMS_Inference を使用して推論をスケジュールできます。サーバーを停止するには、OVMS_ServerDelete を呼び出す必要があります。サーバーが稼働している間は、インプロセス推論の両方をスケジュールすることも、gRPC API を介してリモートマシンから推論をスケジュールすることもできます。オプションで、HTTP サービスを有効にすることもできます。OVMS_ServerMetadata を使用してメタデータを照会することもできます。C/C++ アプリケーションで OpenVINO モデルサーバーを使用する方法の例は、こちらをご覧ください。

エラー処理#

OpenVINO モデルサーバー C API 関数のほとんどは、成功/失敗を示す OVMS_Status オブジェクト・ポインターを返します。成功した場合は nullptr (NULL) が返ります。失敗すると OVMS_Status オブジェクトを返すことで示されます。ステータスコードは OVMS_StatusCode 関数を使用して抽出でき、エラーの詳細は OVMS_StatusDetails 関数を使用して取得できます。

OVMS_Status の所有権は関数の呼び出し元に渡されます。OVMS_StatusDelete を使用してオブジェクトを削除する必要があります。

推論#

C API を使用して推論を実行するには、以下で説明する手順に従う必要があります。

推論要求の準備#

OVMS_InferenceRequestNew を使用して推論要求を作成し、使用するサービス可能名とオプションでバージョンを指定します。次に、OVMS_InferenceRequestAddInput で入力テンソルを指定し、OVMS_InferenceRequestSetData を使用してテンソルデータを設定します。

推論の起動#

OVMS_Inference 同期呼び出しを使用して、OpenVINO モデルサーバーで推論を実行します。推論の実行中は、OVMS_InferenceRequest およびバインドされたメモリーバッファーを変更してはなりません。

推論応答処理#

推論が成功すると、OVMS_InferenceRequest オブジェクトを受け取ります。応答を処理した後、OVMS_InferenceResponseDelete を呼び出して応答メモリーを解放する必要があります。

応答を処理するには、まず推論エラーをチェックする必要があります。エラーが発生しなかった場合、OVMS_InferenceResponseOutputCount と OVMS_InferenceResponseParameterCount を使用して応答出力とパラメーターを反復する必要があります。次に、OVMS_InferenceResponseOutput と OVMS_InferenceResponseParameter を使用して、各出力とパラメーターの詳細を抽出する必要があります。C/C++ アプリケーションで OpenVINO モデルサーバーを使用する方法の例は、こちらをご覧ください。サンプルアプリでは推論要求をスケジュールするスレッドは 1 つしかありませんが、異なるスレッドを使用して複数の推論を同時に実行できます。

注: 推論の実行が終了した後、OVMS_InferenceRequestInputRemoveData を使用して同じ OVMS_InferenceRequest を再利用し、OVMS_InferenceRequestSetData で異なるテンソルデータを設定できます。

サーバーの稼働状況と準備状況#

OpenVINO モデルサーバーが稼働中で、要求に応答するかどうかを確認するには、OVMS_ServerLive を使用します。ライブステータスはモデルの準備が整っていることを保証するものではないことに注意してください。`OVMS_ServerReady’ 呼び出しで準備状況を確認し、正しく構成されたすべてのモデルのロードを含む初期構成が完了したかどうかを確認します。

サーバーの準備状況#

サービス可能状態が推論およびメタデータ要求の準備ができているかどうかを確認するには、名前とオプションでバージョンを指定して OVMS_GetServableState を呼び出します。

提供可能なメタデータ#

OVMS_GetServableMetadata 呼び出しを実行して、サービス可能な入力、出力に関する情報を取得します。要求が成功すると、OVMS_ServableMetadata オブジェクトを受け取ります。すべての入力/出力に関する情報を取得するには、まず OVMS_ServableMetadataInputCount/OVMS_ServableMetadataOutputCount を使用して入力/出力の数を確認し、次に OVMS_ServableMetadataInput 呼び出しと OVMS_ServableMetadataOuput 呼び出しを使用して各入力/出力の詳細を抽出する必要があります。必要なデータを取得した後、OVMS_ServableMetadataDelete を使用して応答オブジェクトを解放する必要があります。

サーバーメタデータ#

サーバーのメタデータを確認するには、OVMS_ServerMetadata 呼び出しを使用します。これにより、OVMS_Metadata タイプの新しいオブジェクトが作成されます。このオブジェクトは、後に OVMS_StringFree で解放する必要があります。これには、OpenVINO のバージョンとモデルサーバーのバージョンに関する情報が含まれます。OVMS_ServerMetadata を文字列 JSON にシリアル化するには、OVMS_SerializeMetadataToString 関数を使用できます。これにより、後で解放する必要がある文字テーブルも OVMS_StringFree で割り当てられます。

制限事項#

  • 単一モデルモードでのサーバーの起動はサポートされていません。設定ファイルを使用する必要があります。

  • C API を介した jpeg/png エンコード入力形式の直接サポートはありません。

  • C API を通じて公開されるメトリックのエンドポイントはありません。

  • C API を介してスケジュールされた推論では、ovms_requests_success、ovms_requests_fail および ovms_request_time_us メトリックはカウントされません。

  • gRPC エンドポイントをオフにすることはできません。REST API エンドポイントはオプションです。

  • 非同期推論用の API はありません。

  • ステートフル・モデルはサポートされていません。

  • mediapipe グラフはサポートされていません。