例: 特徴抽出モデルを使用したバッチ・スコアリング
これは、特徴抽出モデルのバッチ・スコアリング・ジョブの発行例です。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/NMF_MOD" \
--header "Authorization: Bearer ${token}" | jq '.modelId'この例では、モデルURIはNMF_MODです。
GETリクエストは次のものを返します:
returns: "555c4718-853b-4d56-8ef9-268fd87ac25b"
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 -X POST "<oml-cloud-service-location-url>/omlmod/v1/jobs" \
--header "Authorization: Bearer ${token}" \
--header 'Content-Type: application/json' \
--data '{
"jobSchedule": {
"jobStartDate": "2023-03-23T21:10:40Z", # job start date and time
"jobEndDate": "2023-05-23T21:10:40Z", # job end date and time
"repeatInterval": "FREQ=MONTHLY", # job frequency
"maxRuns": "2" # max runs within the schedule
},
"jobProperties": {
"jobName": "FE_MOD1", # job name
"jobType": "MODEL_SCORING", # job type; MODEL_SCORING
"modelId": "555c4718-853b-4d56-8ef9-268fd87ac25b", # ID of the model used for scoring
"jobServiceLevel": "HIGH", # database service level
"inputData": "CUSTOMERS360", # table or view to read input for the batch scoring job
"outputData": "FE_PRED1", # output table to store the scoring results in the format {jobID}_{outputData}
"supplementalColumnNames": ["CUST_ID", # array of columns from the input data used to identify rows in the output
"AFFINITY_CARD",
"CUST_CREDIT_LIMIT",
"CUST_GENDER"],
"topN": 2, # filters the results by returning the top N features with the highest probability
"topNDetails": 2, # provides prediction details contributing to the probability scores
"recompute": "true" # flag to determine whether to overwrite the results table
}
}' | jq - 使用されているモデルは、
YRS_RESIDENCEを予測するためにCUSTOMERS360データセットでトレーニングされました。この例を再現する場合は、CUSTOMERS360表を作成する必要があります。詳細は、CUSTOMERS360表の作成を参照してください - モデルURIは
NMF_MODです modelIdは555c4718-853b-4d56-8ef9-268fd87ac25bですjobNameはFE_MOD1ですjobTypeはMODEL_SCORINGですjobScheduleは月次に設定され、最大2回実行されます。inputDataは、バッチ・スコアリング・ジョブの入力を読み取る表であるCUSTOMERS360ですoutputDataは、ジョブ結果を格納する出力表であるFE_PRED1ですjobServiceLevelはHIGHに設定されていますsupplementalColumnNamesは、inputDataから2つの列をリストし、行識別の結果とともに返しますtopNDetailsは2に設定されています。これにより、上位2件の予測に対するリクエストが設定され、それらの予測に影響する詳細が示されます。recomputeはtrueに設定されているので、実行するたびに結果表が置き換えられます
ジョブ・リクエストのレスポンス
ジョブが正常に発行されると、jobIdがレスポンスとして届きます。ジョブ詳細の取得やジョブに対する処理の実行などのリクエストを送信するために、jobIdをメモしておきます。
レスポンスの例を次に示します:
returns:
{
"jobId": "OML$D66F5559_CA57_4B85_B832_A21A26660725",
"links": [
{
"rel": "self",
"href": "<oml-cloud-service-location-url>/omlmod/v1/jobs/OML%24D66F5559_CA57_4B85_B832_A21A26660725"
}
]
}5: 発行されたジョブの詳細の表示
発行済ジョブの詳細を表示するには、/omlmod/v1/jobs/{jobID}エンドポイントにGETリクエストを送信します。ここで、jobIdは、前のステップでデータ・モニタリング・ジョブの正常発行に対するレスポンスとして表示されたIDです。次のコマンドを実行すると、ジョブの詳細が表示されます:
- まず、ジョブIDをエクスポートして変数に保存します:
$ export jobid='OML$D66F5559_CA57_4B85_B832_A21A26660725' # 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
発行済ジョブの詳細を表示するには、/omlmod/v1/jobs/{jobID}エンドポイントにGETリクエストを送信します。ここで、jobIdは、前のステップでデータ・モニタリング・ジョブの正常発行に対するレスポンスとして表示されたIDです。
ジョブ・リクエストのレスポンス
次に、ジョブ詳細リクエストのレスポンスを示します:
{
"jobId": "OML$D66F5559_CA57_4B85_B832_A21A26660725",
"jobRequest": {
"jobSchedule": {
"jobStartDate": "2023-03-23T21:10:40Z",
"repeatInterval": "FREQ=MONTHLY",
"jobEndDate": "2023-05-23T21:10:40Z",
"maxRuns": 2
},
"jobProperties": {
"jobType": "MODEL_SCORING",
"inputSchemaName": null,
"outputSchemaName": null,
"outputData": "FE_PRED1",
"jobDescription": null,
"jobName": "FE_MOD1",
"disableJob": false,
"jobServiceLevel": "HIGH",
"inputData": "CUSTOMERS360",
"supplementalColumnNames": [
"CUST_ID",
"AFFINITY_CARD",
"CUST_CREDIT_LIMIT",
"CUST_GENDER"
],
"topN": 2,
"recompute": true,
"modelId": "555c4718-853b-4d56-8ef9-268fd87ac25b",
"topNDetails": 2
}
},
"jobStatus": "CREATED",
"dateSubmitted": "2023-03-23T21:05:24.644571Z",
"links": [
{
"rel": "self",
"href": "<oml-cloud-service-location-url>/omlmod/v1/jobs/OML%24D66F5559_CA57_4B85_B832_A21A26660725"
}
],
"jobFlags": [],
"state": "SCHEDULED",
"enabled": true,
"runCount": 0,
"nextRunDate": "2023-03-23T21:10:40Z"
}6: バッチ・スコアリング・ジョブの出力の表示
ジョブが実行されると、outputDataパラメータを使用してジョブ・リクエストに指定した表に結果を表示できます。表のフルネームは{jobid}_{outputData}です。詳細を表示するリクエストを送信することで、ジョブが終了しているかどうかを確認できます。
%sql
SELECT * FROM OML$D66F5559_CA57_4B85_B832_A21A26660725_FE_PRED1
ORDER BY CUST_ID
FETCH FIRST 5 ROWS ONLY;OML$FEATURE_ID1列には、最も確率が高い特徴が含まれますOML$WEIGHT1列には、最上位の加重の特徴の確率が含まれます。OML$FEATURE_ID2列には、2番目に高い確率の特徴が含まれます。OML$WEIGHT2列には、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