例: 回帰モデルを使用したバッチ・スコアリング
これは、回帰モデルのバッチ・スコアリング・ジョブの発行例です。OML Servicesでは、回帰、分類、クラスタリングおよび特徴抽出モデルのバッチ・スコアリングがサポートされています。
スコアリングに使用するモデルのモデルIDが必要です。GETリクエストをデプロイメント・エンドポイントに送信し、モデルURIを指定することで、モデルIDを取得できます。モデルURIは、AutoML UIを使用してモデルをデプロイするとき、またはRESTクライアントを介してモデルをデプロイするときにユーザーが指定します。
バッチ・スコアリング・ワークフロー
- AutoML UIを使用したモデルのデプロイ
- データベース・ユーザーの認証、およびアクセス・トークンの取得
- スコアリングに使用するモデルのモデルIDの取得
- バッチ・スコアリング・ジョブの作成
- バッチ・スコアリング・ジョブの詳細および出力の表示
- バッチ・スコアリング・ジョブの更新、無効化および削除
ノート:
RESTコールを実行するには、LinuxまたはMac端末、またはPostmanなどの他のRESTクライアントでcURLを使用します。
1. モデルのデプロイ
- そのために、機械学習モデルを自動的に構築する方法を選択する場合は、AutoML UIに移動してAutoML実験を作成します。
- モデルをデプロイします
2: データベース・ユーザーの認証およびアクセス・トークンの取得
OML Servicesにリクエストを送信するには、Oracle Machine Learning (OML)アカウントの資格証明を使用して認証トークンを取得する必要があります。トークンを認証および取得するには、-dオプションを指定したcURLを使用して、Oracle Machine Learningユーザー管理クラウド・サービスRESTエンドポイント/oauth2/v1/tokenにOracle Machine Learningアカウントの資格証明を渡します。次のコマンドを実行して、アクセス・トークンを取得します:
$ curl -X POST --header 'Content-Type: application/json' \
--header 'Accept: application/json' \
-d '{"grant_type":"password", "username":"'<yourusername>'","password":"'<yourpassword>'"}'
"<oml-cloud-service-location-url>/omlusers/api/oauth2/v1/token"-X POSTで、HTTPサーバーとの通信時にPOSTリクエストを使用することを指定します-headerで、リクエストに必要なヘッダー(application/json)を定義します-dで、ユーザー名およびパスワードの認証資格証明をPOSTリクエストのデータとしてHTTPサーバーに送信しますContent-Typeで、レスポンス形式(JSON).を定義しますAcceptでは、レスポンス形式(JSON).を定義しますyourusernameは、デフォルトのOML_DEVELOPERロールを持つOracle Machine Learningユーザーのユーザー名ですyourpasswordは、ユーザー名のパスワードですoml-cloud-service-location-urlは、テナンシIDおよびデータベース名を含むOracle Machine Learningユーザー管理クラウド・サービスのインスタンスURLのRESTサーバー部分を含むURLです。URLは、Oracle Autonomous Databaseインスタンスのサービス・コンソールの「開発」タブから取得できます。
3: モデルIDの取得
modelIdを取得するには、デプロイメント・エンドポイントにGETリクエストを送信し、モデルURIを指定します。
ノート:
モデルURIは、AutoML UIを使用してモデルをデプロイするとき、またはRESTクライアントを介してモデルをデプロイするときにユーザーが指定します。modelIdを取得するGETリクエストの例:
$ curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/REGR_MOD" \
--header "Authorization: Bearer ${token}" | jq '.modelId'この例では、モデルURIはREGR_MODです。
GETリクエストは次のものを返します:
returns: "074f5554-fc75-4647-9392-a376056c1f03"
4: バッチ・スコアリング・ジョブの作成および発行
アクセス・トークンを取得した後、OML ServicesにPOSTリクエストを送信してバッチ・スコアリング・ジョブを作成できます。
バッチ・スコアリング・ジョブは、POSTリクエストを/omlmod/v1/jobsエンドポイントに送信することで開始されます。バッチ・スコアリングの詳細は、必須およびオプションのパラメータを含めてjobPropertiesパラメータで指定します。
必須パラメータ
jobNameで、送信したジョブの名前を指定します。jobTypeで、実行するジョブのタイプを指定します。バッチ・スコアリング・ジョブの場合はMODEL_SCORINGです。inputDataは、バッチ・スコアリング・ジョブの入力を読み取る表またはビューの名前です。outputDataは、バッチ・スコアリングの結果を格納する{jobId}_{outputData}形式の結果表です。modelIdは、スコアリングに使用するモデルのIDです。supplementalColumnNamesは、出力表の行を識別するのに使用する入力表またはビューの列の配列です。
オプション・パラメータ
jobStartDate:は、ジョブ実行の開始日時です。指定しないと、ジョブは即時に実行されます。jobEndDate:は、ジョブ実行の終了日時です。disableJob:は、発行時にジョブを無効にするフラグです。設定しないと、ジョブは発行時に有効になります。maxRuns:は、スケジュールに従ってジョブが実行される回数です。inputSchemaName:は、入力表またはビューを所有するデータベース・スキーマです。指定しないと、トークンを取得したユーザーと同じ入力スキーマになります。outputSchemaName:は、出力表を所有するデータベース・スキーマです。指定しないと、出力スキーマは入力スキーマと同じになります。jobDescription:は、ユーザーが指定したジョブの説明です。jobServiceLevel:は、ジョブのデータベース・サービス・レベルで、LOW、MEDIUMまたはHIGHのいずれかを指定できます。recompute:は、出力表を置き換えるかどうかを示すフラグです。デフォルトは、trueです。topN:分類の結果をフィルタ処理して、上位N個の確率を返すか、クラスタリングの場合は上位N個の確率の高いクラスタ割当を返します。topNDetails:では、確率スコアに影響した予測の詳細が表示されます。
$ curl -i -X POST "<oml-cloud-service-location-url>/omlmod/v1/jobs" \
--header "Authorization: Bearer ${token}" \
--header 'Content-Type: application/json' \
--data '{
"jobSchedule": {
"jobStartDate": "2023-03-23T20:05:22Z", # job start date and time
"jobEndDate": "2023-03-25T20:05:22Z" # job end date and time
"repeatInterval": "FREQ=HOURLY", # job frequency
"maxRuns": "50" # max runs within the schedule
},
"jobProperties": {
"jobName": "REG_PRED1", # job name
"jobType": "MODEL_SCORING", # job type; MODEL_SCORING
"modelId": "074f5554-fc75-4647-9392-a376056c1f03", # ID of the model used for scoring
"inputData": "CUSTOMERS360", # table or view to read input for the batch scoring job
"outputData": "REG_PRED_OUT1", # output table to store the scoring results in the format {jobID}_{outputData}
"supplementalColumnNames": ["CUST_ID","YRS_RESIDENCE"], # array of columns from the input data used to identify rows in the output
"topNDetails": 2, # flag to return the top N most important predictors and their weight
"recompute": "true" # flag to determine whether to overwrite the results table
}
}' | jq- 使用されているモデルは、
YRS_RESIDENCEを予測するためにCUSTOMERS360データセットでトレーニングされました。この例を再現する場合は、CUSTOMERS360表を作成する必要があります。詳細は、CUSTOMERS360表の作成を参照してください - モデルURIは
REGR_MODです modelIdは074f5554-fc75-4647-9392-a376056c1f03ですjobNameはREG_PRED1ですjobTypeはMODEL_SCORINGですjobScheduleは毎時に設定され、最大50回実行されます。inputDataは、バッチ・スコアリング・ジョブの入力を読み取る表であるCUSTOMERS360ですoutputDataは、ジョブ結果を格納する出力表であるREG_PRED_OUT1ですrecomputeはtrueに設定されているので、実行するたびに結果表が置き換えられます
ジョブ・リクエストのレスポンス
ジョブが正常に発行されると、jobIdがレスポンスとして届きます。ジョブ詳細の取得やジョブに対する処理の実行などのリクエストを送信するために、jobIdをメモしておきます。レスポンスの例を次に示します:
{
"jobId": "OML$21FACAC2_B345_4485_B287_DBDADC3A1BC0",
"links": [
{
"rel": "self",
"href": "<oml-cloud-service-location-url>/omlmod/v1/jobs/OML%2421FACAC2_B345_4485_B287_DBDADC3A1BC0"
}
]
}5: 発行済バッチ・スコアリング・ジョブの詳細の表示
/omlmod/v1/jobs/{jobID}エンドポイントにGETリクエストを送信すれば、発行済回帰バッチ・スコアリング・ジョブの詳細を表示できます。ここで、jobIdは、前のステップで正常に発行されたバッチ・スコアリング・ジョブのレスポンスに表示されているIDです。ジョブの発行時に指定されたパラメータと、発行時に指定されなかったオプション・パラメータのデフォルト値などの詳細が返されます。
- まず、ジョブIDをエクスポートして変数に保存します:
$ export jobid='OML$21FACAC2_B345_4485_B287_DBDADC3A1BC0' # save job ID to variable - GETリクエストを
/omlmod/v1/jobs/{jobID}エンドポイントに送信します:$ curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/jobs/${jobid}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer ${token}" | jq
ジョブ・リクエストのレスポンス
{
"jobId": "OML$21FACAC2_B345_4485_B287_DBDADC3A1BC0",
"jobRequest": {
"jobSchedule": {
"jobStartDate": "2023-03-23T20:05:22Z",
"repeatInterval": "FREQ=HOURLY",
"jobEndDate": "2023-03-25T20:05:22Z",
"maxRuns": 50
},
"jobProperties": {
"jobType": "MODEL_SCORING",
"inputSchemaName": null,
"outputSchemaName": null,
"outputData": "REG_PRED_OUT1",
"jobDescription": null,
"jobName": "REG_PRED1",
"disableJob": false,
"jobServiceLevel": null,
"inputData": "CUSTOMERS360",
"supplementalColumnNames": [
"CUST_ID",
"YRS_RESIDENCE"
],
"topN": null,
"recompute": true,
"modelId": "074f5554-fc75-4647-9392-a376056c1f03",
"topNDetails": 2
}
},
"jobStatus": "CREATED",
"dateSubmitted": "2023-03-23T20:04:06.157516Z",
"links": [
{
"rel": "self",
"href": "<oml-cloud-service-location-url>/omlmod/v1/jobs/OML%2421FACAC2_B345_4485_B287_DBDADC3A1BC0"
}
],
"jobFlags": [],
"state": "SCHEDULED",
"enabled": true,
"runCount": 0,
"nextRunDate": "2023-03-23T20:05:22Z"
}6: バッチ・スコアリング・ジョブの出力の表示
ジョブが実行されると、outputDataパラメータを使用してジョブ・リクエストに指定した表に結果を表示できます。表のフルネームは{jobid}_{outputData}です。詳細を表示するリクエストを送信することで、ジョブが終了しているかどうかを確認できます。
%sql
SELECT * FROM OML$21FACAC2_B345_4485_B287_DBDADC3A1BC0_REG_PRED_OUT1
ORDER BY CUST_ID
FETCH FIRST 5 ROWS ONLY;このスクリプトは、この例に関連付けられている出力表を問い合せます。回帰予測は、次の列を含む表に返されます:
OML$PREDICTION列およびサプリメンタル列名。OML$DETAIL1列には、予測の詳細の中で最も重要な列が含まれます。OML$DETAILWEIGHT1列には、予測の詳細で最も重要な列の加重が含まれます。OML$DETAIL2列には、予測の詳細の2番目に重要な列が含まれます。OML$DETAILWEIGHT2には、予測の詳細で2番目に重要な列の加重が含まれます
バッチ・スコアリング・ジョブの更新、無効化および削除
DBMS_SCHEDULERと対話してジョブに関するアクションを実行します。アクションには、次の4つのオプションがあります:
DISABLE: このアクションはジョブを無効にします。有効なジョブが無効になると、そのスケジュールに従って実行されなくなります。ノート:
disableJobフラグをtrueに設定することで、ジョブの発行時にDISABLEDに設定できます。ENABLE: このアクションにより、ジョブが有効になります。無効なジョブを有効にすると、スケジューラによってスケジュールどおりにジョブが実行されます。RUN: ジョブをテストしたり、スケジュール外で実行する場合は、このアクションで即時にジョブを実行できます。STOP: このアクションは、現在実行中のジョブを停止します。
デフォルトでは、ジョブが正常に発行されると、その状態がENABLEDに設定されます。つまり、DISABLEDなど、別の状態に更新されないかぎり、ジョブの発行時に指定したスケジュールに従って実行されます。これは、/omlmod/v1/jobs/{jobid}/actionエンドポイントにリクエストを送信すれば実行できます。
バッチ・スコアリング・ジョブの無効化
次に、ジョブ・ステータスをDISABLEDに更新するアクションの例を示します:
--header "Authorization: Bearer ${token}" \ --header 'Content-Type: application/json' \ --data '{ "action": "DISABLE" }'
ノート:
正常にジョブが発行されると、本文なしの204レスポンスが届きます。バッチ・スコアリング・ジョブの更新
バッチ・スコアリング・ジョブの発行後に、ジョブ・スケジュールを更新することもできます。これは、更新したオプションを設定したPOSTリクエストを/omlmod/v1/jobs/{jobID}エンドポイントに送信すれば実行できます。
jobStartDatejobEndDaterepeatIntervalmaxRuns
$ curl -i -X POST "<oml-cloud-service-location-url>/omlmod/v1/jobs/${jobid}" \
--header "Authorization: Bearer ${token}" \
--header 'Content-Type: application/json' \
--data '{
"jobSchedule": {
"jobStartDate": "2023-03-28T21:00:00Z",
"jobEndDate": "2023-03-30T21:00:00Z",
"repeatInterval": "FREQ=DAILY",
"maxRuns": "2"
}
}' | jqノート:
正常にジョブが発行されると、本文なしの204レスポンスが届きます。バッチ・スコアリング・ジョブの削除
以前に発行したジョブを削除するには、DELETEリクエストをジョブIDとともに/omlmod/v1/jobsエンドポイントに送信します。
$ curl -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/jobs/${jobid}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${token}" | jq