デプロイしたモデルによる予測の説明¶
エンドポイント: /deployments/<deploymentId>/predictions?maxExplanations=<number>
予測の説明では、指定されたモデルで特定の予測が作成される理由を識別します。 予測の説明を計算するには、裸の予測の計算に使用したのと同じエンドポイントを使用します。 maxExplanations
URIパラメーターが正の整数値に設定されています。
予測の説明は次のいずれかになります。
-
XEMP-based(デフォルト)。 XEMPベースの説明を使用するには、まず特徴量のインパクトを計算し、次に予測に対する効果特徴量の数量的インジケータ(qualitativeStrength)を提供するために、予測の説明を初期化します。 説明は、特徴量のインパクトスコアによってランク付けされた上位50の特徴量について計算されます(特徴量のインパクトがゼロの特徴量は含まれません)。
-
モデルを構築する前に、SHAP値をサポートするモデルのみを含める高度なオプションが有効になっている場合は、SHAPベース。 特徴量のインパクトを計算する必要はありません。qualitativeStrengthインジケーターはSHAPでは使用できません。
XEMPベースとSHAPベースの説明は相互に排他的であり、モデルはXEMPベースとSHAPベースの両方の説明を提供することはできません。 特定の計算情報については、予測の説明の完全なドキュメントを参照してください。
以下の点に注意してください。
- SHAPベースの説明は、時系列またはカスタムモデルでは使用できません。
- XEMPまたはSHAPの説明は、画像には使用できません(つまり、画像の説明はありません)。
XEMPベースの説明のパフォーマンスに関する注意事項
XEMPベースの説明は、通常の予測に比べて100倍遅くなることがあります。 低レイテンシーが重要となるユースケースではXEMPベースの説明を使用しないでください。 SHAPベースの説明は、はるかに高速ですが、若干のレイテンシーが発生することもあります。
多クラスのサポート
多クラスプロジェクト、XEMPベースのモデル、SHAPベースのモデルでは、予測の説明を生成できません。 説明の操作に関する注意事項については、こちらを参照してください。
リクエストメソッド: POST
リクエストURL:デプロイ済みURL、例:https://your-company.orm.datarobot.com/predApi/v1.0
リクエストパラメーター¶
ヘッダー¶
キー | 説明 | 例 |
---|---|---|
Datarobot-key | 予測サーバーの追加認証要素として使用される、組織ごとのシークレット。 /api/v2/predictionServers エンドポイントにアクセスして、datarobot-key をプラグマティックに取得します。 エンドポイントは、予測サーバーのURLと対応するdatarobot-key を返します。 マネージドAIプラットフォームユーザーに必須です。文字列タイプ モデルがデプロイされたら、予測 > 予測APIで、DataRobot UIのコードスニペットを参照してください。 |
DR-key-12345abcdb-xyz6789 |
Authorization | 必須。文字列 次の3つの方法がサポートされます。
|
|
Content-Type | オプション。文字列型 |
|
Content-Encoding | オプション。文字列型 現在、デフォルトのデータ拡張を含むgzipエンコーディングだけがサポートされています。 |
gzip |
Datarobot-key:このヘッダーはマネージドAIプラットフォームでのみ必須です。 これは、他の検証済みDataRobotユーザーからユーザーのデータを保護するための対策です。 キーはDataRobot APIに対する次のリクエストで取得することもできます。
`GET
クエリ引数(説明固有)¶
備考
予測の説明をトリガーするには、リクエストはNが0
より大きいmaxExplanations=N
を送信する必要があります。
キー | タイプ | 説明 | 例 |
---|---|---|---|
maxExplanations | 整数または文字列 | (オプション)サーバーによって返される説明の数を制限します。 以前はmaxCodes と呼ばれていました(使用非推奨)。 SHAPの説明については、特別な定数all のみも受け入れられます。 |
|
thresholdLow | 浮動小数 | (オプション)予測の説明を要求するための下限しきい値。 予測の説明を計算するには、予測は、この値以下(またはthresholdHighの値以上)である必要があります。 | ?thresholdLow=0.678 |
thresholdHigh | 浮動小数 | (オプション)予測の説明を要求するための上限しきい値。 予測の説明を計算するには、予測は、この値以上(またはthresholdLowの値以下)である必要があります。 | ?thresholdHigh=0.345 |
excludeAdjustedPredictions | ブール | (オプション)モデル構築中にエクスポージャーが使用された場合、エクスポージャー調整された予測を予測応答に含めるか予測応答から除外します。 デフォルト値はtrue です(エクスポージャー調整済み予測を除外します)。 |
?excludeAdjustedPredictions=true |
descriptionNumTopClasses | 整数 | (オプション)この引数は多クラスモデルの説明専用であり、explanationClassNames と相互に排他的です。 各行について説明する上位の予測クラスの数。 デフォルト値は 1 です。 |
?explanationNumTopClasses=5 |
descriptionClassNames | 文字列タイプのリスト | (オプション)この引数は多クラスモデルの説明専用であり、explanationNumTopClasses と相互に排他的です。 各行について説明するクラス名のリスト。 クラス名はUTF-8バイトとして渡し、パーセントエンコードする必要があります(この要件に関するHTTP標準を参照してください)。 デフォルトでは、 explanationNumTopClasses=1 が想定されます。 |
?explanationClassNames=classA&explanationClassNames=classB |
残りのパラメーター(passthroughColumns
、passthroughColumnsSet
、predictionWarningEnabled
など)は、予測の説明でも使用できます。
本文¶
データ | タイプ | 例 |
---|---|---|
予想するデータ |
|
|
Response 200¶
バイナリXEMPベースの説明応答の例¶
{
"data": [
{
"predictionValues": [
{
"value": 0.07836511,
"label": 1
},
{
"value": 0.92163489,
"label": 0
}
],
"predictionThreshold": 0.5,
"prediction": 0,
"rowId": 0,
"predictionExplanations": [
{
"featureValue": "male",
"strength": -0.6706725349,
"feature": "Sex",
"qualitativeStrength": "---",
"label": 1
},
{
"featureValue": 62,
"strength": -0.6325465255,
"feature": "Age",
"qualitativeStrength": "---",
"label": 1
},
{
"featureValue": 9.6875,
"strength": -0.353000328,
"feature": "Fare",
"qualitativeStrength": "--",
"label": 1
}
]
}
]
}
バイナリSHAPベースの説明応答の例¶
{
"data":[
{
"deploymentApprovalStatus": "APPROVED",
"prediction": 0.0,
"predictionExplanations": [
{
"featureValue": "9",
"strength": 0.0534648234,
"qualitativeStrength": null,
"feature": "number_diagnoses",
"label": 1
},
{
"featureValue": "0",
"strength": -0.0490243586,
"qualitativeStrength": null,
"feature": "number_inpatient",
"label": 1
}
],
"rowId": 0,
"predictionValues": [
{
"value": 0.3111782477,
"label": 1
},
{
"value": 0.6888217523,
"label": 0.0
}
],
"predictionThreshold": 0.5,
"shapExplanationsMetadata": {
"warnings": null,
"remainingTotal": -0.089668474,
"baseValue": 0.3964062631
}
}
]
}
「qualitativeStrength」インジケーター¶
「qualitativeStrength」は、XEMP計算に基づいて、予測に対する特徴量の値の影響を示します。 次の表に、2つの特徴量を備えたモデルの例を示します。 計算の詳細については、XEMP計算リファレンスを参照してください。
備考
この応答はXEMPのみの特徴量です。
インジケーター... | 説明 |
---|---|
+++ | 絶対スコアが0.75超で、特徴量にPositiveインパクトがあります。 |
--- | 絶対スコアが0.75超で、特徴量にNegativeインパクトがあります。 |
++ | 絶対スコアは(0.25, 0.75)の間で、特徴量にPositiveインパクトがあります。 |
-- | 絶対スコアは(0.25, 0.75)の間で、特徴量にNegativeインパクトがあります。 |
+ | 絶対スコアは(0.001, 0.25)の間で、特徴量にPositiveインパクトがあります。 |
- | 絶対スコアは(0.001, 0.25)の間で、特徴量にNegativeインパクトがあります。 |
<+ | 絶対スコアは(0, 0.001)の間で、特徴量にPositiveインパクトがあります。 |
<- | 絶対スコアは(0, 0.001)の間で、特徴量にNegativeインパクトがあります。 |
エラーリスト¶
HTTPコード | サンプルエラーメッセージ | リーズン |
---|---|---|
404 NOT FOUND | {"message": "Not found"} |
無効なdeploymentId(削除されたデプロイ)が提供されました。 |
404 NOT FOUND | {"message": "Bad request"} |
deploymentIdの形式が正しくありません。 |
422 UNPROCESSABLE ENTITY | {"message": "{'max_codes': DataError(value can't be converted to int)}"} |
サポートされていないデータ型でmaxCodes パラメーターが提供されました(非整数値)。 |
422 UNPROCESSABLE ENTITY | {"message": "{'threshold_high': DataError(value can't be converted to float)}"} |
サポートされていないデータ型でthreshold_high パラメーターが提供されました(非整数値)。 |
422 UNPROCESSABLE ENTITY | {"message": "{'threshold_low': DataError(value can't be converted to float)}"} |
サポートされていないデータ型でthreshold_low パラメーターが提供されました(非整数値)。 |
422 UNPROCESSABLE ENTITY | {"message": "Multiclass models cannot be used for Prediction Explanations"} |
このプロジェクトでサポートされていない多クラス分類問題のデータセットが提供されました。 |
422 UNPROCESSABLE ENTITY | {"message": "This endpoint does not support predictions on time series models. Please use the timeSeriesPredictions route instead."} |
このプロジェクトでサポートされていない時系列プロジェクトのデプロイが提供されました。 |
422 UNPROCESSABLE ENTITY | {"message": "{'exclude\_adjusted\_predictions': DataError(value can't be converted to Bool)}"} |
空の値または非ブール値がexcludeAdjustedPredictions パラメーターで送信されました。 |
422 UNPROCESSABLE ENTITY | {"message": "'predictionWarningEnabled': value can't be converted to Bool"} |
predictionWarningEnabled パラメーターに無効な(非ブール型の)値が提供されました。 |