DataRobot予測API¶

このセクションでは、DataRobotの予測APIを使用して、専用予測サーバーとスタンドアロン予測サーバーの両方で予測を作成する方法について説明します。予測APIリファレンスドキュメントが必要な場合は、ここから入手できます。スタンドアロンサーバーには特定の要件があることに注意してください。

DataRobotの予測APIは、（デプロイIDを指定することによって）モデルデプロイ上で予想を作成する場合に使用できます。この場合、高度なモデル管理機能（ターゲットまたはデータドリフト検出など）を活用できます。DataRobotのモデル管理機能は予測APIから安全に分離されているので、予測の速度や信頼性を損なうことなくメリットを活用できます。モデルデプロイの作成の詳細については、デプロイセクションを参照してください。

予測APIで予測を生成する前に、予測を最も高速に実行するために推奨されるベストプラクティスを確認してください。

予測の作成¶

予測APIを使用して新しいデータで予測を作成するには、次のものが必要です。

• モデルのデプロイID。IDは、デプロイ > 予測 > 予測APIタブのサンプルコード出力にあります（インターフェイスは「APIクライアント」に設定されています）。
• APIキー。

予測リクエストがPOSTリクエストとしてリソースに対して送信されます。 次に例を示します。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions" \
-H "Authorization: Bearer <API key>" -F \
file=@~/.home/path/to/dataset.csv

予測応答行の順序は、送信されたデータの順序と同じです。

この応答は次のようになります。

HTTP/1.1 200 OKContent-Type: application/jsonX-DataRobot-Execution-Time: 38
X-DataRobot-Model-Cache-Hit: true

{"data":[...]}

持続的HTTP接続の使用¶

すべての予測リクエストは安全な接続(SSL/TLS)を介して行われるので、接続のセットアップ時間が長くなることがあります。この時間は、予測インスタンスへのネットワーク遅延に応じて 30msから100～150msです。

この問題への対処として、予測APIでHTTP Keep-Aliveがサポートされていて、最後の予測リクエストの後、最大1分間システムで接続を開いたままにしておくことができます。

Pythonのrequestsモジュールを使用して、requests.Sessionから予測リクエストを実行します。

import json
import requests

data = [
    json.dumps({'Feature1': 42, 'Feature2': 'text value 1'}),
    json.dumps({'Feature1': 60, 'Feature2': 'text value 2'}),
]

api_key = '...'
api_endpoint = '...'

session = requests.Session()
session.headers = {
    'Authorization': 'Bearer {}'.format(api_key),
    'Content-Type': 'text/json',
}

for row in data:
    print(session.post(api_endpoint, data=row).json())

現在の統合で持続的接続（パーシステントコネクション）を使用する方法については、使用するHTTPライブラリのドキュメントを参照してください。

予想入力¶

APIは、JSONとCSVの両方の形式の入力データをサポートします（高品質のJSONパーサーで作成されている場合はJSONの使用が推奨されます）。データは、リクエストボディまたはファイルアップロード（マルチパートフォーム）を介してポストすることができます。

JSON入力¶

JSON入力は、キーが特徴量名で、値がデータセット内の値となるオブジェクト配列としてフォーマットされています。

例えば､CSVファイルで以下のように表示されている場合：

a,b,c
1,2,3
7,8,9

JSONの場合は以下のように表示されます：

[{"a": 1, "b": 2, "c": 3},
{"a": 7, "b": 8, "c": 9}]

データを/predApi/v1.0/deployments/<deploymentId>/predictionsエンドポイントに送信して、JSON配列を予測APIにサブミットします。例:

$ curl -H "Content-Type: application/json" -X POST --data '[{"a": 4, "b": 5, "c": 6}\]' \-H "Authorization: Bearer <API key>" \
https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions

ファイル入力¶

この例では、ヘッダーと予測を行うデータの行を含むCSVファイルdataset.csvを使用します。コンテンツタイプはURLによって自動的に設定されます。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions" \
-H "Authorization: Bearer <API key>" -F \
file=@~/.home/path/to/dataset.csv

HTTP/1.1 200 OK
Date: Fri, 08 Feb 2019 10:00:00 GMT
Content-Type: application/json
Content-Length: 60624
Connection: keep-alive
Server: nginx/1.12.2
X-DataRobot-Execution-Time: 39
X-DataRobot-Model-Cache-Hit: true
Access-Control-Allow-Methods: OPTIONS, POST
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: Content-Type,Content-Length,X-DataRobot-Execution-Time,X-DataRobot-Model-Cache-Hit,X-DataRobot-Model-Id,X-DataRobot-Request-Id
Access-Control-Allow-Headers: Content-Type,Authorization,datarobot-key
X-DataRobot-Request-ID: 9e61f97bf07903b8c526f4eb47830a86

{"data":
    [{"predictionValues":
        [{"value": 0.2570950924, "label": 1.0},
         {"value": 0.7429049076, "label": 0.0}],
         "predictionThreshold": 0.5,
         "prediction": 0.0,
         "rowId": 0},
     {"predictionValues":
         [{"value": 0.7631880558, "label": 1.0},
          {"value": 0.2368119442, "label": 0.0}],
          "predictionThreshold": 0.5,
          "prediction": 1.0,
          "rowId": 1}
    ]
 }

インボディテキスト入力¶

この例には、リクエストボディ内にCSVファイルが含まれます。この形式では、フォームデータのContent-Typeをに設定する必要がありますtext/plain。

$ curl -H "content-type: text/plain" -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions" -H "Authorization: Bearer <API key>" --data-binary $'a,b,c\n1,2,3\n7,8,9\n'

予測オブジェクト¶

以下のセクションでは、さまざまな予測オブジェクトのコンテンツについて説明します。

リクエストスキーマ¶

リクエストスキーマは、すべての種類の予測の標準です。 使用可能なヘッダーを以下に示します。

以下の点に注意してください。

• データの元のストリームとして予測を送信する場合、;charset=<encoding>をContent-Typeヘッダーに追加してエンコーディングを指定できます。有効な値の一覧については、Pythonの標準エンコーディングを参照してください。DataRobotでは、デフォルトでutf8が使用されます。

• データのエンコード済みストリームを送信する場合は、 Content-Encodingヘッダーを指定する必要があります。

• Authorizationフィールドは、Bearerトークンと呼ばれるセキュリティトークンが関与するBearer HTTP認証スキームです。ユーザー名＋APIトークンのペア（基本認証）またはAPIトークンのみでも認証できますが、これらの認証方法は廃止されているので推奨されません。

URIクエリーパラメーターを使用してリクエストをパラメーター化することができます。

以下の点に備考してください。

• passthroughColumnsおよびpassthroughColumnsSetパラメーターの両方を同じリクエストで渡すことはできません。
• passthroughColumnsクエリパラメーターで渡すことのできる列名の数に制限はありませんが、HTTPリクエストラインの制限があります（現在の制限は8192バイト）。　

次の例は、複数のパススルー列の使用を示しています。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions?passthroughColumns=Latitude&passthroughColumns=Longitude" \-H "Authorization: Bearer <API key>" \
-H "datarobot-key: <DataRobot key>" -F \file=@~/.home/path/to/dataset.csv

応答スキーム¶

サンプルの応答本文を以下に示します（時系列応答本文の追加例も参照してください）。

{
  "data": [
    {
      "predictionValues": [
        {"value": 0.6856798909, "label": 1.0},
        {"value": 0.3143201091, "label": 0.0}
      ],
      "predictionThreshold": 0.5,
      "prediction": 1.0,
      "rowId": 0,
      "passthroughValues": {
        "Latitude": -25.433508,
        "Longitude": 22.759397
      }
    },
    {
      "predictionValues": [
        {"value": 0.765656753, "label": 1.0},
        {"value": 0.234343247, "label": 0.0}
      ],
      "predictionThreshold": 0.5,
      "prediction": 1.0,
      "rowId": 1,
      "passthroughValues": {
        "Latitude": 41.051128,
        "Longitude": 14.49598
      }
    }
  ]
}

次の表にDataRobotのカスタムヘッダーの一覧を示します。

以下の表にJSON配列の応答予測行を示します。

PredictionValueスキーマ¶

以下の表にJSON応答配列のPredictionValueスキーマを示します。

時系列での予測の作成¶

時系列デプロイと通常の非時系列デプロイの予測のURLは同じです。唯一の違いは、予測ポイント、予測開始/終了日、またはその他の時系列固有のURLパラメーターをオプションで指定できることです。デプロイIDを使用して、サーバーは、デプロイされたモデルを時系列デプロイとして自動的に検出し、それに応じて処理します。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions" \
    -H "Authorization: Bearer <API key>" -F \file=@~/.home/path/to/dataset.csv

複数系列プロジェクトのサンプル応答本文を以下に示します。

HTTP/1.1 200 OKContent-Type: application/jsonX-DataRobot-Execution-Time: 1405
X-DataRobot-Model-Cache-Hit: false

{"data":[{"seriesId":1.0,
          "forecastPoint":"2018-01-09T00:00:00Z","rowId": 365,
          "timestamp":"2018-01-10T00:00:00.000000Z","predictionValues":[{"value":45180.4041874386,"label":"target (actual)"}

          ],"forecastDistance":1,"prediction":45180.4041874386},
          {"seriesId":1.0,"forecastPoint":"2018-01-09T00:00:00Z","rowId":366,"timestamp":"2018-01-11T00:00:00.000000Z","predictionValues":[{"value":47742.9432499386,"label":"target (actual)"}

          ],"forecastDistance":2,"prediction":47742.9432499386},{"seriesId":1.0,"forecastPoint":"2018-01-09T00:00:00Z","rowId":367,"timestamp":"2018-01-12T00:00:00.000000Z","predictionValues":[{"value":46394.5698978878,"label":"target (actual)"}

          ],"forecastDistance":3,"prediction":46394.5698978878},{"seriesId":2.0,"forecastPoint":"2018-01-09T00:00:00Z","rowId":697,"timestamp":"2018-01-10T00:00:00.000000Z","predictionValues":[{"value":39794.833199375,"label":"target (actual)"}
          .
          .
          .
          ]
}

リクエストパラメーター¶

URIクエリパラメーターを使用して、時系列予測リクエストをパラメーター化することができます。 たとえば、デフォルトの推測予測ポイントを上書きすると、次のようになります。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions?forecastPoint=1961-01-01T00:00:00?relaxKnownInAdvanceFeaturesCheck=true" \
-H "Authorization: Bearer <API key>" -F \
file=@~/.home/path/to/dataset.csv

時系列固有のパラメーターの詳細なリストについては、デプロイの時系列予測を参照してください。

応答スキーム¶

応答スキームは標準の予測と一貫性がありますが、各PredictionRowオブジェクトにいくつかの列が追加されます。

予測の説明の作成¶

DataRobotの予測の説明機能を使用すると、例外的に高い予測値や例外的に低い予測値が発生する特定の入力の属性に関するインサイトを得ることができます。

予測の説明を初期化するには、予測の説明タブを使用します。

予測の説明の作成は、標準の予測リクエストに非常に似ています。最初に、予測の説明リクエストがPOSTリクエストとしてリソースに送信されます。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictionExplanations" \-H "Authorization: Bearer <API key>" -F \
file=@~/.home/path/to/dataset.csv

応答本文のサンプルを以下に示します。

HTTP/1.1 200 OKContent-Type: application/jsonX-DataRobot-Execution-Time: 841
X-DataRobot-Model-Cache-Hit: true

{"data":[{"predictionValues":
            [{"value":0.6634830442,"label":1.0},             {"value":0.3365169558,"label":0.0}],          "prediction":1.0,          "rowId":0,          "predictionExplanations":            [{"featureValue": 49,
              "strength":0.6194461777,
              "feature":"driver_age",
              "qualitativeStrength":"+++",
              "label":1.0
             },             {"featureValue":1,
              "strength":0.3501610895,
              "feature":"territory",
              "qualitativeStrength":"++",
              "label":1.0},             },             {"featureValue": "M",
              "strength":-0.171075409,
              "feature":"gender",
              "qualitativeStrength":"--",
              "label":1.0
              }]         },         {"predictionValues":
             [{"value":0.3565584672,"label":1.0},              {"value":0.6434415328,"label":0.0}],          "prediction":0.0,          "rowId":1,          "predictionExplanations":[]         }]}

リクエストパラメーター¶

URIクエリーパラメーターを使用して、予測の説明の予測リクエストをパラメーター化することができます。

パラメーター化されたリクエストの例を以下に示します。

$ curl -i -X POST "https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictionExplanations?maxExplanations=2&thresholdLow=0.2&thresholdHigh=0.5"-H "Authorization: Bearer <API key>" -F \
file=@~/.home/path/to/dataset.csv

DataRobotのヘッダースキーマは予測応答のものと同じです。応答スキームは標準の予測と一貫性がありますが、PredictionExplanationsの配列「predictionExplanations」が各PredictionRowオブジェクトに追加されます。

PredictionExplanationsスキーマ¶

オブジェクトの応答JSON配列:

信頼性の監視を備えた予測の作成¶

信頼性の監視を備えた予測では、ユーザー定義の信頼性ルールを使用して予測を監視できます。

予測が「不確かな予測」トリガーに対して提供されたしきい値の範囲外になると、トリガーに割り当てられたアクションがデフォルトになります。トリガーがアクティブになると、信頼性キーが予測応答の本文に追加されます。

以下に示すのは、サンプルの応答本文です。これは、（）の連続値プロジェクトUncertain Prediction Triggerの応答ですAction - No Operation。

    {
        "data": [

            {
        "predictionValues": [
                    {
                        "value": 122.8034057617,
                        "label": "length"
                    }
                   ],
                   "prediction": 122.8034057617,
                   "rowId": 99,
                   "humility": [
                        {
                        "ruleId": "5ebad4735f11b33a38ff3e0d",
                        "triggered": true,
                        "ruleName": "Uncertain Prediction Trigger"
                        }
                        ]
        }
        ]
        .
        .
        .
    }

以下に示すのは、連続値モデルデプロイの応答本文の例です。これは、「エラーを発生」アクションが設定された「不確かな予測」トリガーを使用します。

    480 Error: {"message":"Humility ReturnError action triggered."}

以下に示すのは、連続値モデルデプロイの応答本文の例です。これは、「予測のオーバーライド」アクションが設定された「不確かな予測」トリガーを使用します。

    {
           "data": [

                {
                    "predictionValues": [
                            {
                                "value": 122.8034057617,
                                "label": "length"
                            }
                    ],
                    "prediction": 5220.0,
                    "rowId": 99,
                    "humility": [
                            {
                                "ruleId": "5ebad4735f11b33a38ff3e0d",
                                "triggered": true,
                                "ruleName": "Uncertain Prediction Trigger"
                            }
                        ]
                }

        ]
        .
        .
        .
    }

応答スキーム¶

応答スキーマは標準の予測と一貫性がありますが、各Humilityオブジェクトの列のサブセットを含む新しい信頼性列が追加されます。

エラーレスポンス¶

エラーはすべて200コード属性以外で表示されます。4XXで始まるコードはリクエストエラーであることを示します（列の欠損、間違った資格情報、不明なモデルIDなど）。メッセージ属性は、4XXコードが発生した場合、エラーの詳細説明を表示します。例:

$ curl -H "Content-Type: application/json" -X POST --data '' \-H "Authorization: Bearer <API key>" \
https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>

HTTP/1.1 400 BAD REQUESTDate: Fri, 08 Feb 2019 11:00:00 GMTContent-Type: application/jsonContent-Length: 53
Connection: keep-aliveServer: nginx/1.12.2X-DataRobot-Execution-Time: 332
X-DataRobot-Request-ID: fad6a0b62c1ff30db74c6359648d12fd
{"message":"The requested URL was not found on the server.  If you entered the URL manually please check your spelling and try again."}

5XXで始まるコードはサーバー側のエラーを示します。リクエストを再度試行するか、DataRobot担当者にお問い合わせください。

制限に関する説明¶

ここでは、専用予測インスタンスのサイズおよびタイムアウト制限について説明します。

• 専用の予測サーバーに送信できるデータの最大量は、50 MBです。

• 行数の制限はありませんが、以下のタイムアウト制限があります。

  • オンプレミスデプロイ: 設定に応じて異なります
  • マネージドAIクラウド：600s

  リクエストがタイムアウトを超える場合、または専用予測サーバーを使用して大きなファイルのスコアリングを行う場合は、バッチスコアリングパッケージの使用を検討してください。

• HTTPリクエストラインのサイズに制限があります（現在の制限は 8192バイトです）。

• クラウドプラットフォームでは、600秒以上アイドル状態になっていると、専用予測APIサーバーが持続的HTTP接続を自動で終了します。持続接続を使用するには、クライアント側でこれらの切断を正しく処理できる必要があります。次の例は、送信が失敗した場合にHTTPリクエストを自動的に再試行するようPython HTTPライブラリrequestsを設定します。

  import requests
  import urllib3
  
  # create a transport adapter that will automatically retry GET/POST/HEAD requests on failures up to 3 times
  adapter = requests.adapters.HTTPAdapter(
      max_retries=urllib3.Retry(
          total=3,
          method_whitelist=frozenset(['GET', 'POST', 'HEAD'])
      )
  )
  
  # create a Session (a pool of connections) and make it use the given adapter for HTTP and HTTPS requests
  session = requests.Session()
  session.mount('http://', adapter)
  session.mount('https://', adapter)
  
  # execute a prediction request that will be retried on transport failures, if needed
  api_token = '<your api token>'
  dr_key = '<your datarobot key>'
  response = session.post(
      'https://example.datarobot.com/predApi/v1.0/deployments/<deploymentId>/predictions',
      headers={
          'Authorization': 'Bearer %s' % api_token,
          'DataRobot-Key': dr_key,
          'Content-Type': 'text/csv',
      },
  data='<your scoring data>',
  )
  
  print(response.content)
  

モデルのキャッシュ¶

専用予測サーバーは、必要に応じてDataRobotクラスターからモデルをフェッチします。同じモデルを使用する後続の予測の処理速度を向上させるために、DataRobotは特定の数のモデルをメモリーに格納（キャッシュ）します。キャッシュがいっぱいになった場合に新しいモデルリクエストをするには、キャッシュ内の既存のモデルを1つ削除する必要があります。DataRobotでは、最も以前に使用されたモデルが削除されます（必ずしもキャッシュ内に最も長く格納されているモデルではありません）

オンプレミスインストールの場合、キャッシュのデフォルトサイズは16モデルですが、このサイズはインストールごとに異なります。特定のインストールのキャッシュサイズに関する質問については、DataRobotサポートに問い合わせてください。

予測サーバーは、複数の予測処理を実行します。それぞれの予測処理には、独自の排他的モデルキャッシュがあります。予測処理は相互に共有されません。そのため、2つのリクエストを連続して予測サーバーに送信した場合、それぞれのリクエストでモデルデータをダウンロードする必要が生じることがあります。

予測サーバーからの各応答には、使用されたモデルがキャッシュ内にあったかどうかを示す1つのヘッダー（X-DataRobot-Model-Cache-Hit）が含まれます。モデルがキャッシュにあった場合、ヘッダーの値はTrueです。値がFalseの場合、モデルはキャッシュにありませんでした。

予測をすばやく作成するためのベストプラクティス¶

以下のチェックリストに予測をすばやく作成するための推奨事項をまとめます。

• 永続的HTTP接続を実装する。これで予測APIへのネットワークラウンドトリップ（遅延）が削減されます。

• CSVデータを使用する。大量のデータのJSONシリアル化はCSVを使用するよりも長い時間がかかるので、予測入力にCCSVを使用することを検討してください。

• リクエストされたモデルの数を少なくする。これで予測APIでモデルキャッシュを使用できるようになります。

• データをチャンクにまとめる。可能な限り多くの行をバッチにまとめます（50 MBのリクエスト制限を超えないよう注意してください）。大きなファイルをスコアリングする場合は、ローカルファイルのスコアリングに加えて、S3とデータベース間のスコアリングもサポートするバッチ予測APIの使用を検討してください。

スタンドアロン予測サーバーを使用する場合の前提条件¶

スタンドアロン予測サーバーを使用するには、最初にDataRobotのモデル移行機能とプロセスを理解する必要があります。スタンドアロン予測サーバーで予測を作成する前に、最初にモデル開発サーバーからモデルを正常に移行する必要があります。移行したモデルのインポートIDを特定します。これは、ユーザープロファイルドロップダウンメニューからアクセスできるDataRobot UIの「予測の管理」ページにあります。