Data Science ツールキット - Bonsai カスタム モデル ワークフロー
このページでは、一般的な Bonsai カスタム モデル ワークフローについて説明し、コード例を示します。
注:
クローズド ベータ ワークフローでは、API を使用する必要があります。 終了したベータ 版クライアントは、開始する前に API オンボード プロセスを 完了している必要があります。
手順 1: 要件を特定する
カスタム モデルをデシジョン ツリーとして記述します。ここでは、ツリーの分岐が特定の出力につながる条件を表します (入札価格モデルの場合は入札価格、入札修飾子モデルの場合は入札乗数)。 条件は 、Bonsai 言語 で記述され、一連の Bonsai 特徴 と特徴値に基づいています。 ツリーを書き込む前に:
- 利用できる Bonsai 機能を詳しく見てみましょう。
- ツリーフィーチャを使用して出力を決定する方法をスケッチします。
- レポート データを活用して、適切な特徴と値を特定してください。 詳細については、ドキュメントの 「ログ レベルのデータ フィード 」と「標準レポート」を参照してください。
例: 入札価格のデシジョン ツリー
注:
カスタム モデルを使用して、インプレッションをターゲットにする方法ではなく、インプレッションの価格を設定する方法を決定します。 ターゲティングインプレッションの場合は、API を使用してターゲット設定を行うために プロファイル サービス を引き続き使用する必要があります。
手順 2: デシジョン ツリーを作成する
キャンペーンの価格や入札の変更に従う必要がある機能と手順がわかったら、 Bonsai 言語のデシジョン ツリーとして記述します。 そのページの例と、次の簡単な例を使用して、ツリーの書き方について理解を始めます。
注:
スペースではなくインデントにタブを使用します。
Bonsai では、インデントを使用して式をグループ化します (Python に似ています)。 行インデントを示すには、必ずタブを使用してください。 スペースは現在サポートされていません。
例: 入札価格の Bonsai ツリー
注:
次のコード例では、 で #
始まる行は、このツリーのロジックを理解するのに役立つコメントです。
# This tree determines a bid price as follows:
# 1. If the user is in California, and the hour is between 12pm and 14pm there, bid $1.50.
# 2. If the user is in New York, and the hour is between 1am and 3am there, bid $0.10.
# 3. Otherwise, bid $0.50.
if every region = "US:CA", user_hour range (12,14):
1.5
elif every region = "US:NY", user_hour range (1,3):
0.1
else:
0.5
手順 3: デシジョン ツリーをエンコードする
デシジョン ツリーを Base64 エンコードします。 Base64 は、2 進数字をラテン文字、数字、プラス記号、スラッシュ記号で構成されるアルファベットに変換できるエンコード アルゴリズムです。 コンテンツを Base64 にエンコードできる Web ベースのコンバーター がいくつかあります。
例: Base64 でエンコード
IyBUaGlzIHRyZWUgZGV0ZXJtaW5lcyBhIGJpZCBwcmljZSBhcyBmb2xsb3dzOgojIDEuIElmIHRoZSB1c2VyIGlzIGluIENhbGlmb3JuaWEsIGFuZCB0aGUgaG91ciBpcyBiZXR3ZWVuIDEycG0gYW5kIDE0cG0gdGhlcmUsIGJpZCAkMS41MC4KIyAyLiBJZiB0aGUgdXNlciBpcyBpbiBOZXcgWW9yaywgYW5kIHRoZSBob3VyIGlzIGJldHdlZW4gMWFtIGFuZCAzYW0gdGhlcmUsIGJpZCAkMC4xMC4KIyAzLiBPdGhlcndpc2UsIGJpZCAkMC41MC4KCmlmIGV2ZXJ5IHJlZ2lvbiA9ICJVUzpDQSIsIHVzZXJfaG91ciByYW5nZSAoMTIsMTQpOgoJMS41CmVsaWYgZXZlcnkgcmVnaW9uID0gIlVTOk5ZIiwgdXNlcl9ob3VyIHJhbmdlICgxLDMpOgoJMC4xCmVsc2U6CgkwLjU=
手順 4: デシジョン ツリーでエラーがないか確認する
カスタム モデル パーサー サービスを使用して、デシジョン ツリーの有効性をチェックします。
- JSON 要求で、base64 でエンコードされたツリーを文字列としてフィールドに
model_text
配置します。 - エラーがある場合は、応答の フィールドを
error
使用して、Bonsai 構文または機能エラーを特定して解決するのに役立ちます。 ガイダンスについては、「 エラー メッセージ」を参照してください。 - エラーがない場合、
size
応答のフィールドには、ツリーのサイズが Lisp に表示されます (ツリーの格納に使用する形式)。 が 3 MB 未満か、3,145,728 バイト未満であることを確認しますsize
。
注:
ツリーが 3 MB を超える場合、ツリーを追加することはできません。
例: base64 でエンコードされたツリーを含む JSON ファイル
$ cat check_tree.json
{
"custom-model-parser": {
"model_text": "IyBUaGlzIHRyZWUgZGV0ZXJtaW5lcyBhIGJpZCBwcmljZSBhcyBmb2xsb3dzOgojIDEuIElmIHRoZSB1c2VyIGlzIGluIENhbGlmb3JuaWEsIGFuZCB0aGUgaG91ciBpcyBiZXR3ZWVuIDEycG0gYW5kIDE0cG0gdGhlcmUsIGJpZCAkMS41MC4KIyAyLiBJZiB0aGUgdXNlciBpcyBpbiBOZXcgWW9yaywgYW5kIHRoZSBob3VyIGlzIGJldHdlZW4gMWFtIGFuZCAzYW0gdGhlcmUsIGJpZCAkMC4xMC4KIyAzLiBPdGhlcndpc2UsIGJpZCAkMC41MC4KCmlmIGV2ZXJ5IHJlZ2lvbiA9ICJVUzpDQSIsIHVzZXJfaG91ciByYW5nZSAoMTIsMTQpOgoJMS41CmVsaWYgZXZlcnkgcmVnaW9uID0gIlVTOk5ZIiwgdXNlcl9ob3VyIHJhbmdlICgxLDMpOgoJMC4xCmVsc2U6CgkwLjU="
}
}
例: POST
custom-model-parser サービスに
$ curl -b cookies -c cookies -X POST -d @check_tree.json 'https://api.appnexus.com/custom-model-parser'
{
"response": {
"service": "custom-model-parser",
"method": "post",
"custom-model-parser": {
"model_text": "IyBUaGlzIHRyZWUgZGV0ZXJtaW5lcyBhIGJpZCBwcmljZSBhcyBmb2xsb3dzOgojIDEuIElmIHRoZSB1c2VyIGlzIGluIENhbGlmb3JuaWEsIGFuZCB...",
"size": 111
},
"dbg_info": {
...
}
}
}
手順 5: カスタム モデルとしてデシジョン ツリーを追加する
ツリーが有効であることを確認したら、 カスタム モデル サービス を使用してエンコードされたデシジョン ツリーをアップロードします。 必ず、次の作業を行ってください。
- フィールドに適切なカスタム モデルの種類を
model_output
設定します。- Bid Price モデルの場合は、 を使用します
"bid"
。 - 入札修飾子モデルの場合は、 を使用します
"bid_modifier"
。
- Bid Price モデルの場合は、 を使用します
- base64 でエンコードされたツリーを
model_text
文字列としてフィールドに配置します。 - 一意
name
の を指定します。 これは必須であり、正しいモデルを簡単に選択できます。 - カスタム モデルが
advertiser_id
属する を指定します。 このモデルは、この広告主のキャンペーンでのみ使用できます。
例: カスタム モデルを定義する JSON ファイル
$ cat custom_model.json
{
"custom_model": {
"name": "Bid by Region/Hour of Day",
"member_id": 958,
"advertiser_id": 39776,
"custom_model_structure": "decision_tree",
"model_output": "bid",
"model_text": "aWYgZXZlcnkgZGV2aWNlX3R5cGUgPSAiT3RoZXJzIChpbmNsdWRpbmcgUEMpIiwgdXNlcl9ob3VyIHJhbmdlICg5LDE4KToKCTEuNQplbGlmIGV2ZXJ5IGRldmljZV90eXBlIGluICgiVGFibGV0IiwgIlBob25lIiksIHVzZXJfaG91ciBpbiAoNSw2LDcsOCwxOSwyMCwyMSwyMik6CgkyCmVsc2U6CgkwLjU="
}
}
例: POST
to custom-model
service
$ curl -b cookies -c cookies -X POST -d @custom_model.json 'https://api.appnexus.com/custom-model'
{
"response": {
"status": "OK",
"count": 1,
"id": "329",
"start_element": 0,
"num_elements": 100,
"custom_model": {
"id": 329,
"name": "Bid by Region/Hour of Day",
"member_id": 958,
"advertiser_id": 39776,
"custom_model_structure": "decision_tree",
"model_output": "bid",
"model_text": "aWYgZXZlcnkgcmVnaW9uID0gIlVTOkNBIiwgdXNlcl9ob3VyIHJhbmdlICgxMiwxNCk6CgkxLjUKZWxpZiBldmVyeSByZWdpb24gPSAiVVM6TlkiLCB1c2VyX2hvdXIgcmFuZ2UgKDEsMyk6CgkwLjEKZWxzZToKCTAuNQ=",
"original_text": "if every region = \"US:CA\", user_hour range (12,14):
1.5
elif every region = \"US:NY\", user_hour range (1,3):
0.1
else:
0.5",
"active": true,
"last_modified": "2015-09-22 20:52:53"
},
"dbg_info": {
"instance": "64.bm-hbapi.prod.nym2",
"s1ave_hit": true,
"db": "10.3.129.206",
"awesomesauce_cache_used": false,
"count_cache_used": false,
"warnings": [
],
"time": 39.799213409424,
"start_microtime": 1438028779.7596,
"version": "1.15.572",
"s1ave_lag": 0,
"member_last_modified_age": 21425,
"output_term": "custom_model"
}
}
}
手順 6: カスタム モデルをキャンペーンに割り当てる
入札価格モデル
キャンペーン サービスを使用して、カスタム モデルをキャンペーンに割り当てます。 必ず、次の作業を行ってください。
を に設定
cpm_bid_type
します"custom_model"
。オブジェクトに
id
カスタム モデルの をbid_model
指定します。を に設定
inventory_type
します"real_time"
。キャンペーンを定義する JSON ファイル
$ cat campaign.json { "campaign": { "name": "Custom Model Campaign - Bid by Region/Hour of Day", "cpm_bid_type": "custom_model", "bid_model": { "id": 329 }, "line_item_id": 34287, "inventory_type": "real_time" } }
入札修飾子モデル
キャンペーン サービスを使用して、カスタム モデルをキャンペーンに割り当てます。 必ず、次の作業を行ってください。
最適化ベースの購買戦略 (
"predicted"
または"margin"
) と、対応する必須フィールドに設定cpm_bid_type
します。- たとえば、次の JSON では、 と を
"predicted"
cpc_click_goal
に1.00
設定cpm_bid_type
して、予測される $1.00 CPC 目標に CPM の入札を最適化します。
- たとえば、次の JSON では、 と を
オブジェクトで
bid_modifier_model
、キャンペーンの CPM 入札を変更するカスタム モデルの を指定id
します。を に設定
inventory_type
します"real_time"
。キャンペーンを定義する JSON ファイル
$ cat campaign.json { "campaign": { "name": "Custom Model Campaign - Modify Bid Based on Region/Hour of Day", "cpm_bid_type": “predicted”, “cpc_goal”: 1.00, "bid_modifier_model": { "id": 148 }, "line_item_id": 34287, "inventory_type": "real_time" } }