DataRobot APIのリソース > APIリファレンスドキュメント > APIで予測を作成 > 予測APIリファレンス > デプロイの予測の説明

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

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

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

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

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つの方法がサポートされます。 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ファイルなど）
コンテンツエンコーディング	オプション。文字列型現在、デフォルトのデータ拡張を含むgzipエンコーディングだけがサポートされています。	gzip

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

クエリ引数（説明固有）¶

備考

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

キー	タイプ	説明	例
maxExplanations	整数または文字列	オプションです。サーバーによって返される説明の数を制限します。以前は`maxCodes`と呼ばれていました（使用非推奨）。 SHAPの説明については、特別な定数`all`のみも受け入れられます。	`?maxExplanations=5` `?maxExplanations=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など）は、予測の説明でも使用できます。

本文¶

データ	タイプ	例
予想するデータ	元のテキスト form-data	PassengerId,Pclass,Name,Sex,Age,SibSp,Parch,Ticket,Fare,Cabin,Embarked 892,3,"Kelly, Mr. James",male,34.5,0,0,330911,7.8292,,Q 893,3,"Wilkes, Mrs. James (Ellen Needs)",female,47,1,0,363272,7,,S 894,2,"Myles, Mr. Thomas Francis",male,62,0,0,240276,9.6875,,Q キー：ファイル、値：file_with_data_to_predict.csv

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`パラメーターに無効な（非ブール型の）値が提供されました。

更新しました November 17, 2023

このページは役に立ちましたか？

ありがとうございます。どのような点が役に立ちましたか？

より良いコンテンツを提供するには、どうすればよいでしょうか？

アンケートにご協力いただき、ありがとうございました。