Skip to content

デプロイしたモデルによる予測の説明

エンドポイント: /deployments/<deploymentId>/predictions?maxExplanations=<number>

予測の説明では、指定されたモデルで特定の予測が作成される理由を識別します。 予測の説明を計算するには、裸の予測の計算に使用したのと同じエンドポイントを使用します。 maxExplanationsURIパラメーターが正の整数値に設定されています。 For specific calculation information, review the main Prediction Explanations documentation.

予測の説明は次のいずれかになります。

  • XEMP-based(デフォルト)。 To use XEMP-based explanations, first calculate feature impact and initialize Prediction Explanations to provide a qualitative indicator (qualitativeStrength) of the effect variables have on the predictions. 説明は、特徴量のインパクトスコアによってランク付けされた上位50の特徴量について計算されます(特徴量のインパクトがゼロの特徴量は含まれません)。

  • SHAP-based. To use SHAP-based explanations, calculating feature impact is not required. [qualitativeStrength]{0}インジケーターはSHAPでは使用できません。

予測の説明に関する注意事項

  • XEMPまたはSHAPの説明は、画像には使用できません(つまり、画像の説明はありません)。

  • 多クラスプロジェクトでは、SHAPベースの予測の説明を生成できません。 Only XEMP is supported for multiclass projects.

説明の操作に関する注意事項については、こちらを参照してください。

XEMPベースの説明のパフォーマンスに関する注意事項

XEMPベースの説明は、通常の予測に比べて100倍遅くなることがあります。 低レイテンシーが重要となるユースケースではXEMPベースの説明を使用しないでください。 SHAPベースの説明は、はるかに高速ですが、若干のレイテンシーが発生することもあります。

リクエストメソッド: POST

リクエストURL:デプロイ済みURL、例:https://your-company.orm.datarobot.com/predApi/v1.0

リクエストパラメーター

ヘッダー

キー 説明
Datarobot-key DR-key-12345abcdb-xyz6789
Authorization 必須。文字列

次の3つの方法がサポートされます。
  • Bearer認証
  • (使用非推奨)基本認証:User_emailおよびAPIトークン
  • (使用非推奨)APIトークン
  • Bearer認証方法の例:Bearer API_key-12345abcdb-xyz6789
  • (使用非推奨)User_emailおよびAPIトークン方法の例:Basic Auth_basic-12345abcdb-xyz6789
  • (使用非推奨)APIトークン方法の例:Token API_key-12345abcdb-xyz6789
Content-Type オプション。文字列型
  • textplain; charset=UTF-8
  • text/csv
  • application/JSON
  • multipart/form-data(データを含むファイル。.csvや.txtファイルなど)
Content-Encoding オプション。文字列型

現在、デフォルトのデータ拡張を含むgzipエンコーディングだけがサポートされています。
gzip

Datarobot-key:このヘッダーはマネージドAIプラットフォームでのみ必須です。 これは、他の検証済みDataRobotユーザーからユーザーのデータを保護するための対策です。 キーはDataRobot APIに対する次のリクエストで取得することもできます。
`GET /api/v2/modelDeployments/

クエリ引数(説明固有)

備考

予測の説明をトリガーするには、リクエストはNが0より大きいmaxExplanations=Nを送信する必要があります。

キー タイプ 説明
maxExplanations 整数または文字列
  • ?maxExplanations=5
  • ?maxExplanations=all
thresholdLow 浮動小数 ?thresholdLow=0.678
thresholdHigh 浮動小数 ?thresholdHigh=0.345
excludeAdjustedPredictions ブール ?excludeAdjustedPredictions=true
descriptionNumTopClasses 整数 ?explanationNumTopClasses=5
descriptionClassNames 文字列タイプのリスト ?explanationClassNames=classA&explanationClassNames=classB
explanationAlgorithm 文字列 Defines the Prediction Explanation algorithm used, SHAP or XEMP.
  • ?explanationAlgorithm=shap
  • explanationAlgorithm=xemp

残りのパラメーター(passthroughColumnspassthroughColumnsSetpredictionWarningEnabledなど)は、予測の説明でも使用できます。

本文

データ タイプ
予想するデータ
  • 元のテキスト
  • form-data

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つの特徴量を備えたモデルの例を示します。 See the XEMP calculation reference for full calculation details.

備考

この応答は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 このプロジェクトでサポートされていない時系列プロジェクトのデプロイが提供されました。
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パラメーターに無効な(非ブール型の)値が提供されました。