Portable Prediction Server running modes¶
サーバーでサポートされているモデルモードには、単一モデル(SM)と複数モデル(MM)の2つがあります。 /opt/ml/model
ディレクトリ内のDockerコンテナに単一のモデルパッケージのみがマウントされている場合は、SMモードを使用します。 これ以外の場合はすべてMMモードを使用します。 互換性のある予測にもかかわらず、SMモードはディスク上でモデルパッケージを識別する必要のない簡略化されたHTTP APIを作成し、起動時にモデルをメモリーにプリロードします。
Dockerコンテナのファイルシステムディレクトリは、次のレイアウトと一致する必要があります。
SMモードの場合:
/opt/ml/model/
└── model_5fae9a023ba73530157ebdae.mlpkg
MMモードの場合:
/opt/ml/model/
├── fraud
| └── model_5fae9a023ba73530157ebdae.mlpkg
└── revenue
├── config.yml
└── revenue-estimate.mlpkg
HTTP API(単一モデル)¶
単一モデルモードで実行している場合、Dockerイメージは3つのHTTPエンドポイントを公開します。
POST /predictions
は、所定のデータセットをスコアリングします。GET /info
は、ロードされたモデルに関する情報を返します。GET /ping
は、技術スタックが起動していることを確認します。
備考
予測ルートは、スコアリングデータセットとしてカンマ区切りのCSVおよびJSONレコードのみをサポートします。 最大ペイロードサイズは、50MBです。
curl -X POST http://<ip>:8080/predictions \
-H "Content-Type: text/csv" \
--data-binary @path/to/scoring.csv
{
"data": [
{
"predictionValues": [
{"value": 0.250833758, "label": "yes"},
{"value": 0.749166242, "label": "no"},
],
"predictionThreshold": 0.5,
"prediction": 0.0,
"rowId": 0
}
]
}
CSVが望ましい出力である場合は、Accept: text/csv
HTTPヘッダーを使用してリクエストします。
curl -X POST http://<ip>:8080/predictions \
-H "Accept: text/csv" \
-H "Content-Type: text/csv" \
--data-binary @path/to/scoring.csv
<target>_yes_PREDICTION,<target>_no_PREDICTION,<target>_PREDICTION,THRESHOLD,POSITIVE_CLASS
0.250833758,0.749166242,0,0.5,yes
HTTP API(複数モデル)¶
複数モデルモードでは、Dockerイメージは以下のエンドポイントを公開します。
POST /deployments/:id/predictions
は、所定のデータセットをスコアリングします。GET /deployments/:id/info
は、ロードされたモデルに関する情報を返します。POST /deployments/:id
は、モデルパッケージをコンテナーにアップロードします。DELETE /deployments/:id
は、コンテナからモデルパッケージを削除します。GET /deployments
は、コンテナ内のモデルパッケージのリストを返します。GET /ping
は、技術スタックが起動していることを確認します。
:id
(上記の/deployments
ルートに含まれる)はディスク上のモデルパッケージの一意の識別子を指します。 IDはモデルパッケージを含むディレクトリ名です。 したがって、次の/opt/ml/model
レイアウトの場合は次のようになります。
/opt/ml/model/
├── fraud
| └── model_5fae9a023ba73530157ebdae.mlpkg
└── revenue
├── config.yml
└── revenue-estimate.mlpkg
fraud
およびrevenue
を:id
のルートの/deployments
セットの代わりに使用することを検討してください。
備考
予測ルートは、スコアリングデータセットとしてカンマ区切りのCSVおよびJSONレコードのみをサポートします。 最大ペイロードサイズは、50MBです。
curl -X POST http://<ip>:8080/deployments/revenue/predictions \
-H "Content-Type: text/csv" \
--data-binary @path/to/scoring.csv
{
"data": [
{
"predictionValues": [
{"value": 0.250833758, "label": "yes"},
{"value": 0.749166242, "label": "no"},
],
"predictionThreshold": 0.5,
"prediction": 0.0,
"rowId": 0
}
]
}
モニタリング¶
備考
続行する前に、PPSコンテナの監視を設定してください。 詳細については、環境変数と例のセクションを参照してください。 監視エージェントを使用するには、エージェントスプーラーも設定する必要があります。
データドリフトや精度などの予測統計を監視できます。その場合は、DataRobotのデプロイインベントリに外部デプロイを作成する必要があります。
モデルパッケージを特定のデプロイに接続するには、予測統計をホストするデプロイのデプロイIDを指定します。
単一モデル(SM)モードの場合、デプロイIDはMLOPS_DEPLOYMENT_ID
環境変数で提供する必要があります。 複数モデル(MM)モードでは、特別なconfig.yml
を準備して目的のdeployment_id
値を持つモデルパッケージの横にドロップする必要があります。
deployment_id: 5fc92906ad764dde6c3264fa
精度を追跡する場合は、デプロイ用に設定してから、実行中のモデルに追加の設定を提供します。
SMモードの場合、次の環境変数を設定します。
MLOPS_ASSOCIATION_ID_COLUMN=transaction_country
(必須)MLOPS_ASSOCIATION_ID_ALLOW_MISSING_VALUES=false
(オプション、デフォルト=false
)
MMモードの場合、config.yml
で次のプロパティを設定します。
association_id_settings:
column_name: transaction_country
allow_missing_values: false
HTTPSサポート¶
本機能の提供について
以前にダウンロードしたPPSイメージを実行している場合、これらのパラメーターは、PPSイメージが手動で更新するまで使用できません。
- マネージドAIプラットフォーム:2021年8月から
- Self-Managed AI Platform: starting v7.2
デフォルトでは、PPSは8080
ポート上のセキュアでないリスナー(クリアテキストHTTP over TCP)を介して予測を提供します。
また、8443
ポート上のセキュアなリスナー(HTTP over TLS/SSL、または単にHTTPS)を介して予測を提供することもできます。 セキュアなリスナーを有効にした場合、セキュアでないリスナーは使用できなくなります。
備考
PPSは同時に両方のポートで利用できるように設定できます。8080
のHTTPまたは8443
のHTTPSです。
設定は、以下の通り環境変数を使用して実行できます。
-
PREDICTION_API_TLS_ENABLED
:ポート8443
でHTTPSリスナーを有効にし、ポート8080
でHTTPSリスナーを無効にするマスターフラグ。- デフォルト:false(HTTPS無効)
-
有効な値(大文字と小文字は区別されません):
パラメーター値 解釈 true, t, yes, y, 1 true false、f、no、n、0 false
備考
TLSを有効にするには、フラグの値を
true
として解釈する必要があります。 この設定を有効にしていない場合、その他のすべてのPREDICTION_API_TLS_*
環境変数(渡された場合)は無視されます。 -
PREDICTION_API_TLS_CERTIFICATE
:TLS/SSL証明書のPEM形式のコンテンツ。- 必須:
PREDICTION_API_TLS_ENABLED
がtrue
の場合はYes、それ以外の場合はNo。 - 以下も参照してください。:NGINX SSL証明書ドキュメント
- 必須:
-
PREDICTION_API_TLS_CERTIFICATE_KEY
:TLS/SSL証明書キーの秘密証明書キーのPEM形式のコンテンツ。- 必須:
PREDICTION_API_TLS_ENABLED
がtrue
の場合はYes、それ以外の場合はNo。 - 以下も参照してください。:NGINX SSL証明書キードキュメント
- 必須:
-
PREDICTION_API_TLS_CERTIFICATE_KEY_PASSWORD
:PREDICTION_API_TLS_CERTIFICATE_KEY
に渡された秘密証明書キーのパスフレーズ。- 必須:パスフレーズで証明書キーを作成した場合のみ必須です。
-
PREDICTION_API_TLS_PROTOCOLS
:使用する暗号化プロトコルの実装。- デフォルト:
TLSv1.2 TLSv1.3
| * 有効な値:SSLv2
|SSLv3
|TLSv1
|TLSv1.1
|TLSv1.2
|TLSv1.3
、またはこれらの値のスペースで区切られた組み合わせ。 |
注意
2021年8月時点で、
TLSv1.2
およびTLSv1.3
を除くすべての実装は使用非推奨および/またはセキュアではないとみなされます。 DataRobotは、これらの実装のみを使用することを強く推奨します。 新しいインストールは、最新のセキュアなTLSバージョンであるため、TLSv1.3
のみ使用することを検討できます。 - デフォルト:
-
PREDICTION_API_TLS_CIPHERS
:使用する暗号スイートのリスト。- デフォルト:必須TLSv1.3暗号および推奨TLSv1.2暗号
- 必須:なし。
- 有効な値:暗号スイートについては、OpenSSL構文を参照してください。
注意
TLSサポートは高度な機能です。 暗号スイートリストは、最新の推奨および現在のベストプラクティスに準じて慎重に選択されています。 DataRobotはそれをオーバーライドすることを推奨しません。
環境変数¶
特徴量 | 説明 | デフォルト |
---|---|---|
PREDICTION_API_WORKERS |
起動するワーカーの数を設定します。 このオプションは、予測APIが同時に処理できるHTTPリクエストの数を制御します。 通常、これはコンテナで使用可能なCPUコアの数に設定します。 | 1 |
PREDICTION_API_MODEL_REPOSITORY_PATH |
DataRobotでモデルパッケージを検索するディレクトリへのパスを設定します。 PREDICTION_API_MODEL_REPOSITORY_PATH がルートに単一モデルパッケージを含むディレクトリを指している場合、PPSでは単一モード実行モードが想定されます。 それ以外の場合、複数モデルモードが想定されています。 |
/opt/ml/model/ |
PREDICTION_API_PRELOAD_MODELS_ENABLED |
すべてのワーカーは、開始時にすべてのマウントされたモデルをプロアクティブにプリロードする必要があります。 これは、サーバーが起動し、キャッシュがまだ「コールド」である後の最初のリクエストのキャッシュミスの問題を排除するのに役立つはずです。キャッシュミスを完全に排除するには、PREDICTION_API_SCORING_MODEL_CACHE_MAXSIZE も参照してください。 |
|
PREDICTION_API_SCORING_MODEL_CACHE_MAXSIZE |
リクエストごとにオンデマンドでロードされないようにするために、各ワーカーのRAMキャッシュに保持するスコアリングモデルの最大数。 実務上、デフォルト設定は低くなっています。 PPSを実行しているサーバーに十分なRAMがある場合は、これを事前にマウントされたモデルの総数よりも大きい値に設定して、キャッシュを完全に活用し、キャッシュミスを回避する必要があります。 各ワーカーのキャッシュは独立しているため、各モデルは各ワーカーのキャッシュにコピーされます。 キャッシュミスを回避するために、マルチモデルモードでPREDICTION_API_PRELOAD_MODELS_ENABLED を有効にすることも検討してください。 |
4 |
PREDICTION_API_DEPLOYED_MODEL_RESOLVER_CACHE_TTL_SEC |
デフォルトでは、パッケージがHTTP経由で再アップロードされた場合、PPSは定期的にmplkg からデプロイ情報を読み取ろうとします。 PPSの開始後にmplkg を更新する予定がない場合は、これを0 に設定して、デプロイ情報キャッシュの無効化を無効にすることを検討してください。 これは、一部のリクエストのレイテンシーを減らすのに役立ちます。 |
60 |
PREDICTION_API_MONITORING_ENABLED |
データ監視をオフロードするかどうかを設定します。 Trueの場合、予測APIは監視エージェントに監視データをオフロードします。 | false |
PREDICTION_API_MONITORING_SETTINGS |
予測APIから監視エージェントに監視データをオフロードする方法を制御します。 セミコロンで区切られたキー=値ペアでスプーラー構成設定のリストを指定します。 ファイルシステムスプーラーの例: PREDICTION_API_MONITORING_SETTINGS="spooler_type=filesystem;directory=/tmp;max_files=50;file_max_size=102400000" SQSスプーラーの例: PORTABLE_PREDICTION_API_MONITORING_SETTINGS="spooler_type=sqs;sqs_queue_url=<SQS_URL>" PPSの単一モデルモードの場合、 MLOPS_DEPLOYMENT_ID およびMLOPS_MODEL_ID 特徴量は必須です。複数モデルモードには必須ではありません。 |
None |
MONITORING_AGENT |
監視エージェントを予測APIと一緒に実行するかどうかを設定します。 監視エージェントを使用するには、エージェントスプーラーを設定する必要があります。 | false |
MONITORING_AGENT_DATAROBOT_APP_URL |
URIをDataRobotインストールに設定します(例:https://app.datarobot.com/)。 | None |
MONITORING_AGENT_DATAROBOT_APP_TOKEN |
DataRobot APIで使用するユーザートークンを設定します。 | None |
PREDICTION_API_TLS_ENABLED |
TLSリスナーマスターフラグを設定します。 TLSリスナーが動作するには、アクティブ化する必要があります。 | false |
PREDICTION_API_TLS_CERTIFICATE |
証明書のインラインコンテンツをPEM形式で追加します。 | None |
PREDICTION_API_TLS_CERTIFICATE_KEY |
証明書キーのインラインコンテンツをPEM形式で追加します。 | None |
PREDICTION_API_TLS_CERTIFICATE_KEY_PASSWORD |
証明書キーファイルにプレーンテキストパスフレーズを追加します。 | None |
PREDICTION_API_TLS_PROTOCOLS |
TLS/SSLプロトコルをオーバーライドします。 | TLSv1.2 TLSv1.3 |
PREDICTION_API_TLS_CIPHERS |
デフォルト暗号スイートをオーバーライドします。 | 必須TLSv1.3、推奨TLSv1.2 |
PREDICTION_API_RPC_DUAL_COMPUTE_ENABLED |
Requires that the PPS run Python2 and Python3 interpreters. Then, the PPS automatically determines the version requirement based on which Python version the model was trained on. When this setting is enabled, PYTHON3_SERVICES is redundant and ignored. Note that this requires additional RAM to run both versions of the interpreter. |
True |
PYTHON3_SERVICES |
Only enable this setting when the PREDICTION_API_RPC_DUAL_COMPUTE_ENABLED setting is disabled and each model was trained on Python3. You can save approximately 400MB of RAM by excluding the Python2 interpreter service from the container. |
None |
重要
As of June 2022, the PPS runs in "dual-compute mode" by default, running both Python2 and Python3 interpreter services and automatically routing prediction requests to the appropriate interpreter. As a result of this change, setting PYTHON3_SERVICES
to true
is no longer necessary to support Python3 models; however, this configuration requires an extra 400MB of RAM. If you want to reduce the RAM footprint (and all models are either Python2 or Python3), you can disable dual-compute mode (PREDICTION_API_RPC_DUAL_COMPUTE_ENABLED='false'
). Next, if all models are trained on Python3, enable Python3 services (PYTHON3_SERVICES='true''
). If all models are trained on Python2, there is no need to configure an additional environment variable, as the default interpreter is still Python2.
リクエストパラメーター¶
ヘッダー¶
PPSは承認をサポートしていないため、 Datarobot-key
とAuthorization
は必要ありません。
キー | タイプ | 説明 | 例 |
---|---|---|---|
Content-Type |
文字列 | 必須。 リクエストフォーマットを定義します。 |
|
Content-Encoding |
文字列 | オプションです。 現在、デフォルトのデータ拡張子を持つgzip -エンコーディングのみをサポートしています。 |
gzip |
Accept |
文字列 | オプションです。 応答スキーマの形状を制御します。 現在、JSON(デフォルト)とCSVがサポートされています。 例を参照してください。 |
|
引数のクエリ¶
The predictions
routes (POST /predictions
(single-model mode) and POST /deployments/:id/predictions
) have the same query arguments and HTTP headers as their standard route counterparts, with a few exceptions. As with regular Dedicated Predictions API, the exact list of supported arguments depends on the deployed model. 以下は、すべてのデプロイでサポートされている一般的なクエリ引数のリストです。
キー | タイプ | 説明 | 例 |
---|---|---|---|
passthroughColumns |
文字列のリスト | オプションです。 予想応答で公開(またはコピー)するスコアリングデータセットの列を制御します。 リクエストには、1つ以上の列が含まれる場合、および列が含まれない場合があります。 (パスできる列名の数に制限はありません。) 列名はUTF-8バイトとして渡し、パーセントエンコードする必要があります(この要件に関するHTTP標準を参照してください)。 列の正確な名前を値として使用してください。 |
/v1.0/deployments/<deploymentId>/predictions?passthroughColumns=colA&passthroughColumns=colB |
passthroughColumnsSet |
文字列 | オプションです。 予想応答で公開(またはコピー)するスコアリングデータセットの列を制御します。 使用できる唯一のオプションはall です。このオプションが渡された場合、スコアリングデータベースのすべての列が返却されます。 |
/v1.0/deployments/deploymentId/predictions?passthroughColumnsSet=all |
decimalsNumber |
integer | オプションです。 予測結果のフロートのプレシジョンを設定します。 小数点以下の桁数を設定します。 小数点の後に数字がない場合、ゼロを追加するのではなく、浮動小数点のプレシジョンは decimalsNumber 未満になります。 |
?decimalsNumber=15 |
以下の点に注意してください。
passthroughColumns
およびpassthroughColumnsSet
パラメーターの両方を同じリクエストで渡すことはできません。passthroughColumns
クエリーパラメーターで渡すことのできる列名の数に制限はありませんが、HTTPリクエストラインの制限があります(現在の制限は8192バイト)。
予測の説明パラメーター¶
次のクエリーパラメーターを使用して、予測の説明の予測リクエストをパラメーター化することができます。
備考
予測の説明をトリガーするには、Nが0
より大きいmaxExplanations=N
を送信する必要があります。
キー | タイプ | 説明 | 例 |
---|---|---|---|
maxExplanations |
int OR string | オプションです。 サーバーによって返される説明の数を制限します。 以前はmaxCodes と呼ばれていました(使用非推奨)。 SHAPの説明については、特別な定数all のみも受け入れられます。 |
|
thresholdLow |
浮動小数 | オプションです。 予測の説明の下限しきい値。 予測の説明を計算するには、予測は、この値以下(またはthresholdHighの値以上)である必要があります。 | ?thresholdLow=0.678 |
thresholdHigh |
浮動小数 | オプションです。 予測の説明の上限しきい値。 予測の説明を計算するには、予測は、この値以上(またはthresholdLowの値以下)である必要があります。 | ?thresholdHigh=0.345 |
excludeAdjustedPredictions |
bool | オプションです。 モデル構築中にエクスポージャーが使用された場合、エクスポージャー調整された予測を予測応答に含めるか予測応答から除外します。 デフォルト値はtrue です(エクスポージャー調整済み予測を除外します)。 |
?excludeAdjustedPredictions=true |
explanationNumTopClasses |
int | オプションです。 多クラスモデルのみ。 説明される各行の上位予測クラスの数。 多クラスの説明のみ。 デフォルトは1です。 explanationClassNames と相互排他的。 |
?explanationNumTopClasses=5 |
explanationClassNames |
文字列タイプのリスト | オプションです。 多クラスモデルのみ。 各行について説明されるクラス名のリスト。 多クラスの説明のみ。 クラス名はUTF-8バイトとして渡し、パーセントエンコードする必要があります(この要件に関するHTTP標準を参照してください)。 This parameter is mutually exclusive with explanationNumTopClasses . デフォルトでは、explanationNumTopClasses=1 が想定されます。 |
?explanationClassNames=classA&explanationClassNames=classB |
時系列パラメーター¶
次のクエリーパラメーターを使用して、時系列予測リクエストをパラメーター化することができます。
キー | タイプ | 説明 | 例 |
---|---|---|---|
forecastPoint |
ISO-8601文字列 | ISO 8601形式のDateTime文字列(タイムゾーンなし)。予測ポイントを表します。 predictionsStartDate およびpredictionsEndDate がパスされる場合、このパラメーターは使用できません。 |
?predictionsStartDate=2013-12-20T01:30:00Z |
relaxKnownInAdvanceFeaturesCheck |
bool | true またはfalse 。 true の場合、予測時に予測ウィンドウで事前に既知の特徴量の欠損値を使用できます。 デフォルト値false はです。 事前に既知の値がない場合、予測品質に負の影響が生じることがあります。 |
?relaxKnownInAdvanceFeaturesCheck=true |
predictionsStartDate |
ISO-8601文字列 | データセット内での一括予測の生成開始時間。 このパラメーターは、predictionsEndDate と一緒に定義する必要があります。 predictionsStartDate およびpredictionsEndDate がパスされる場合、forecastPoint パラメーターは使用できません。 |
?predictionsStartDate=2013-12-20T01:30:00Z&predictionsEndDate=2013-12-20T01:40:00Z |
predictionsEndDate |
ISO-8601文字列 | データセット内での一括予測の生成停止時間。 このパラメーターは、predictionsStartDate と一緒に定義する必要があります。 predictionsStartDate およびpredictionsEndDate がパスされる場合、forecastPoint パラメーターは使用できません。 |
上記を参照。 |
外部設定¶
Dockerイメージを使用して構成オプションを読み取り、上記の表に示されている設定オプションを設定することもできます(/opt/ml/config
から)。 ファイルには、<key>=<value>
ペアが含まれている必要があります。各キー名は対応する環境変数です。
例¶
-
2つのワーカーで実行:
docker run \ -v /path/to/mlpkgdir:/opt/ml/model \ -e PREDICTION_API_WORKERS=2 \ -e PREDICTION_API_SCORING_MODEL_CACHE_MAXSIZE=32 \ -e PREDICTION_API_PRELOAD_MODELS_ENABLED='true' \ -e PREDICTION_API_DEPLOYED_MODEL_RESOLVER_CACHE_TTL_SEC=0 \ datarobot/datarobot-portable-prediction-api:<version>
-
外部監視を設定して実行:
docker run \ -v /path/to/mlpkgdir:/opt/ml/model \ -e PREDICTION_API_MONITORING_ENABLED='true' \ -e PREDICTION_API_MONITORING_SETTINGS='<settings>' \ datarobot/datarobot-portable-prediction-api:<version>
-
内部監視を構成して実行:
docker run \ -v /path/to/mlpkgdir:/opt/ml/model \ -e PREDICTION_API_MONITORING_ENABLED='true' \ -e PREDICTION_API_MONITORING_SETTINGS='<settings>' \ -e MONITORING_AGENT='true' \ -e MONITORING_AGENT_DATAROBOT_APP_URL='https://app.datarobot.com/' \ -e MONITORING_AGENT_DATAROBOT_APP_TOKEN='<token>' \ datarobot/datarobot-portable-prediction-api:<version>
-
デフォルトプロトコルと暗号を使用してHTTPSサポートで実行:
docker run \ -v /path/to/mlpkgdir:/opt/ml/model \ -p 8443:8443 \ -e PREDICTION_API_TLS_ENABLED='true' \ -e PREDICTION_API_TLS_CERTIFICATE="$(cat /path/to/cert.pem)" \ -e PREDICTION_API_TLS_CERTIFICATE_KEY="$(cat /path/to/key.pem)" \ datarobot/datarobot-portable-prediction-api:<version>
-
Run with Python3 interpreter only to minimize RAM footprint:
docker run \ -v /path/to/my_python3_model.mlpkg:/opt/ml/model \ -e PREDICTION_API_RPC_DUAL_COMPUTE_ENABLED='false' \ -e PYTHON3_SERVICES='true' \ datarobot/datarobot-portable-prediction-api:<version>
-
Run with Python2 interpreter only to minimize RAM footprint:
docker run \ -v /path/to/my_python2_model.mlpkg:/opt/ml/model \ -e PREDICTION_API_RPC_DUAL_COMPUTE_ENABLED='false' \ datarobot/datarobot-portable-prediction-api:<version>