例: 分類モデルを使用したバッチ・スコアリング
これは、ニューラル・ネットワーク・モデルのバッチ・スコアリング・ジョブの発行例です。OML Servicesでは、回帰、分類、クラスタリングおよび特徴抽出モデルのバッチ・スコアリングがサポートされています。
スコアリングに使用するモデルのモデルIDが必要です。GETリクエストをデプロイメント・エンドポイントに送信し、モデルURIを指定することで、モデルIDを取得できます。モデルURIは、AutoML UIを使用してモデルをデプロイするとき、またはRESTクライアントを介してモデルをデプロイするときにユーザーが指定します。
OML Servicesでは、回帰、分類、クラスタリングおよび特徴抽出モデルのバッチ・スコアリングがサポートされています。
バッチ・スコアリング・ワークフロー
- 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/NN_MOD" \
--header "Authorization: Bearer ${token}" | jq '.modelId'この例では、モデルURIはNN_MODです。
GETリクエストは次のモデルIDを返します:
returns: "35a97c7b-0ff4-4940-96f5-bfb29f64d223"
2: バッチ・スコアリング・ジョブの作成および発行
アクセス・トークンを取得した後、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-13T21:10:23Z", # job start date and time
"jobEndDate": "2023-03-17T21:10:23Z", # job end date and time
"repeatInterval": "FREQ=DAILY", # job frequency
"maxRuns": "4" # max runs within the schedule
},
"jobProperties": {
"jobName": "NN_MOD1", # job name
"jobType": "MODEL_SCORING", # job type; MODEL_SCORING
"modelId": "35a97c7b-0ff4-4940-96f5-bfb29f64d223", # ID of the model used for scoring
"inputData": "CUSTOMERS360", # table or view to read input for the batch scoring job
"outputData": "CLASS_PRED1", # output table to store the scoring results in the format {jobID}_{outputData}
"supplementalColumnNames": ["CUST_ID", "AFFINITY_CARD"], # array of columns from the input data used to identify rows in the output
"jobServiceLevel": "MEDIUM", # The database service level for the job. The default is LOW.
"topN": 2, # filters the results by returning the highest N probabilities
"topNDetails": 2, # provides prediction details contributing to the probability scores
"recompute": "true" # flag to determine whether to overwrite the result table
}
- この例で使用されているモデルは、アフィニティ・カードのロイヤルティ・プログラムに肯定的に反応する可能性が最も高い顧客を予測するために、
CUSTOMERS360データセットでトレーニングされました。この例を再現する場合は、CUSTOMERS360表を作成する必要があります。詳細は、CUSTOMERS360表の作成を参照してください - モデルURIは
NN_MODです modelIdは35a97c7b-0ff4-4940-96f5-bfb29f64d223ですjobNameはNN_MOD1ですjobTypeはMODEL_SCORINGですjobScheduleは日次に設定され、最大4回実行されます。inputDataは、バッチ・スコアリング・ジョブの入力を読み取る表であるCUSTOMERS360ですoutputDataは、ジョブ結果を格納する出力表であるCLASS_PRED1ですsupplementalColumnNamesでは、CUST_IDおよびAFFINITY_CARD列が返され、行を特定するための予測、上位2つの予測およそれらの予測に影響する詳細も含まれます。recomputeはtrueに設定されているので、実行するたびに結果表が置き換えられますjobServiceLevelはMEDIUMに設定されています。Oracle Autonomous Databaseでは、HIGH、MEDIUMおよびLOWの3つのサービス・レベルがサポートされています。デフォルトのLOWでは並列化されませんが、データベース・サービス・レベルはMEDIUMまたはHIGHに変更できます。HIGHのサービス・レベルでは並列度が最大になりますが、同時実行ジョブ数が大幅に制限されます。MEDIUMレベルでは一部の並列処理が有効になりますが、ジョブ処理の同時実行数は多くなります。
ジョブ・リクエストのレスポンス
jobIdがレスポンスとして届きます。ジョブ詳細の取得やジョブに対する処理の実行などのリクエストを送信するために、jobIdをメモしておきます。レスポンスの例を次に示します:
{
"jobId": "OML$385E413C_7219_41A4_B5A2_DC6B91B3DD8E",
"links": [
{
"rel": "self",
"href": "<oml-cloud-service-location-url>/omlmod/v1/jobs/OML%24385E413C_7219_41A4_B5A2_DC6B91B3DD8E"
}
]
}
3: 発行済ジョブの詳細の表示
/omlmod/v1/jobs/{jobID}エンドポイントへのGETリクエストを使用して、発行済バッチ・スコアリング・ジョブの詳細を表示できます。ここで、jobIdは、前のステップで正常に発行されたバッチ・スコアリング・ジョブのレスポンスに表示されているIDです。ジョブの発行時に指定されたパラメータと、発行時に指定されなかったオプション・パラメータのデフォルト値などの詳細が返されます。
次のコマンドを実行すると、ジョブの詳細が表示されます:
- まず、ジョブIDをエクスポートして変数に保存します:
$ export jobid='OML$385E413C_7219_41A4_B5A2_DC6B91B3DD8E' # 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$385E413C_7219_41A4_B5A2_DC6B91B3DD8E",
"jobRequest": {
"jobSchedule": {
"jobStartDate": "2023-03-23T20:32:35Z",
"repeatInterval": "FREQ=DAILY",
"jobEndDate": "2023-03-27T20:32:35Z",
"maxRuns": 4
},
"jobProperties": {
"jobType": "MODEL_SCORING",
"inputSchemaName": null,
"outputSchemaName": null,
"outputData": "CLASS_PRED1",
"jobDescription": null,
"jobName": "NN_MOD1",
"disableJob": false,
"jobServiceLevel": "MEDIUM",
"inputData": "CUSTOMERS360",
"supplementalColumnNames": [
"CUST_ID",
"AFFINITY_CARD"
],
"topN": 2,
"recompute": true,
"modelId": "35a97c7b-0ff4-4940-96f5-bfb29f64d223",
"topNDetails": 2
}
},
"jobStatus": "CREATED",
"dateSubmitted": "2023-03-23T20:28:55.233217Z",
"links": [
{
"rel": "self",
"href": "<oml-cloud-service-location-url>/omlmod/v1/jobs/OML%24385E413C_7219_41A4_B5A2_DC6B91B3DD8E"
}
],
"jobFlags": [],
"state": "SCHEDULED",
"enabled": true,
"runCount": 0,
"nextRunDate": "2023-03-23T20:32:35Z"
}
4: バッチ・スコアリング・ジョブの出力の表示
ジョブが実行されると、outputDataパラメータを使用してジョブ・リクエストに指定した表に結果を表示できます。表のフルネームは{jobid}_{outputData}です。詳細を表示するリクエストを送信することで、ジョブが終了しているかどうかを確認できます。
%sql
SELECT * FROM OML$385E413C_7219_41A4_B5A2_DC6B91B3DD8E_CLASS_PRED1
ORDER BY CUST_ID
FETCH FIRST 5 ROWS ONLY;OML$PREDICTION1列には、最も確率が高いクラスが含まれますOML$PROBABILITY1列には、最上位クラスの確率が含まれますOML$DETAIL1列には、予測の詳細の中で最も重要な列が含まれますOML$PROBABILITY2列には、2番目のクラスの確率が含まれます。OML$DETAIL2列には、予測の詳細の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