Data Science ツールキット - Bonsai デシジョンツリーのカスタムモデルを作成する

[アーティクル]
02/23/2024

Digital Platform API を使用すると、独自のカスタム予測モデル (以前は "AppNexus Programmable Bidder" と呼ばれて) を作成し、オープンプラットフォームに直接アップロードできます。次の操作を行うことができます:

データサイエンティストに、一般的な Python 言語とよく似た高レベルのドメイン固有言語 (DSL) である Bonsai で予測モデルを記述させます。
API を使用してモデルを検証してアップロードし、API または UI を使用してキャンペーンに割り当てます。
入札者に対してモデルを実行し、インフラストラクチャの速度、規模、信頼性、コスト削減の恩恵を受けます。

このページは、作業の開始に役立ちます。

カスタムモデル型

現時点では、次の 2 種類のカスタム予測モデルを作成できます。

入札価格

入札価格モデルでは、デシジョンツリーを使用してキャンペーンの CPM 入札を決定します。この種類のモデルは、"ベース CPM の入札" や "% マージンへの最適化" などの標準的な CPM 戦略の代わりに、キャンペーンのサードパーティの購入戦略として機能します。

入札条件

入札修飾子モデルでは、デシジョンツリーを使用して、キャンペーンの最適化に由来する CPM の入札を上下に調整します。この種類のモデルは、Xandr の最適化を使用する購入戦略と組み合わせて使用されます。"予測された CPA 目標に最適化する" や "予測された CPC 目標に最適化する" などです。

注:

モデルによって計算される入札は、キャンペーンに別の通貨を指定した場合でも、常に広告主に設定された通貨で表されます。

ワークフロー

注:

アルファワークフローでは、API を使用する必要があります。アルファクライアントは、開始する前に API オンボードプロセスを完了している必要があります。

手順 1: 要件を特定する

カスタムモデルをデシジョンツリーとして記述します。ここでは、ツリーの分岐が特定の出力につながる条件を表します (入札価格モデルの場合は入札価格、入札修飾子モデルの場合は入札乗数)。条件は、一連の 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 でエンコード

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": "(if (and (region = 3922) (user_hour range 12 14)) 1.5 (if (and (region = 3950) (user_hour range 1 3)) 0.1 0.5))",
            "size": 111
        },
        "dbg_info": {
            ...
        }
    }
}

手順 5: カスタムモデルとしてデシジョンツリーを追加する

ツリーが有効であることを確認したら、カスタムモデルサービスを使用してエンコードされたデシジョンツリーをアップロードします。必ず、次の作業を行ってください。

フィールドに適切なカスタムモデルの種類を model_output 設定します。
- Bid Price モデルの場合は、を使用します "bid"。
- 入札修飾子モデルの場合は、を使用します "bid_modifier"。
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):\n\t1.5\nelif every region = \"US:NY\", user_hour range (1,3):\n\t0.1\nelse:\n\t0.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: カスタムモデルをキャンペーンに割り当てる

この手順は、使用しているカスタムモデルの種類と、API または UI を使用してモデルをキャンペーンに割り当てるかどうかによって変わります。手順については、以下の関連オプションを展開します。

入札価格モデル

API の使用

キャンペーンサービスを使用して、カスタムモデルをキャンペーンに割り当てます。必ず、次の作業を行ってください。

をに設定 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"
    }
}

POST キャンペーンサービスへ

$ curl -b cookies -c cookies -X POST -d @campaign.json 'https://api.appnexus.com/campaign?advertiser_id=45278'

{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": 0,
        "num_elements": 100,
        "campaign": {
            "id": 9061978,
            "state": "active",
            "parent_inactive": false,
            "code": null,
            "advertiser_id": 45278,
            "line_item_id": 34287,
            "creative_id": null,
            "pixel_id": null,
            "short_name": null,
            "name": "Custom Model Campaign - Bid Based on Region/Hour of Day",
            "profile_id": 31746900,
            "start_date": "2015-06-03 00:00:00",
            "end_date": null,
            "timezone": "EST5EDT",
            "priority": 5,
            "cadence_modifier_enabled": false,
            "cpc_goal": null,
            "cpm_bid_type": "custom_model",
            "base_bid": 0,
            "min_bid": null,
            "max_bid": null,
            "bid_margin": 0,
            "roadblock_creatives": false,
            "roadblock_type": "no_roadblock",
            "inventory_type": "real_time",
            "last_modified": "2015-06-03 16:25:15",
            "max_learn_bid": null,
            "cadence_type": "advertiser",
            "member_id": 958,
            "click_url": null,
            "require_cookie_for_tracking": true,
            "allow_unverified_ecp": false,
            "defer_to_li_prediction": false,
            "ecp_learn_divisor": null,
            "projected_learn_events": null,
            "learn_threshold": 3,
            "cpc_payout": null,
            "comments": null,
            "optimization_version": "v7",
            "learn_override_type": null,
            "base_cpm_bid_value": null,
            "impression_limit": null,
            "bid_multiplier": null,
            "remaining_days": null,
            "total_days": null,
            "supply_type_action": "exclude",
            "supply_type": null,
            "creatives": null,
            "pixels": null,
            "optimization_lookback": null,
            "campaign_modifiers": null,
            "labels": null,
            "broker_fees": null,
            "valuation": null,
            "bid_model": {
                "id": 329,
                "name": "Bid Based on Region/Hour of Day",
                "active": "1"
            },
            "lifetime_budget": null,
            "lifetime_budget_imps": null,
            "daily_budget": null,
            "daily_budget_imps": null,
            "enable_pacing": null,
            "allow_safety_pacing": null,
            "lifetime_pacing": null,
            "lifetime_pacing_span": null
        },
        "dbg_info": {
            "instance": "61.bm-hbapi.prod.nym2",
            "s1ave_hit": true,
            "db": "10.3.129.211",
            "awesomesauce_cache_used": false,
            "count_cache_used": false,
            "warnings": [
            ],
            "time": 48.674821853638,
            "start_microtime": 1436503279.2047,
            "version": "1.15.558",
            "s1ave_lag": 0,
            "member_last_modified_age": 1395,
            "output_term": "campaign"
        }
    }
}

入札修飾子モデル

API の使用

キャンペーンサービスを使用して、カスタムモデルをキャンペーンに割り当てます。必ず、次の作業を行ってください。

最適化ベースの購買戦略 ("predicted"または"margin") と、対応する必須フィールドに設定cpm_bid_typeします。
- たとえば、次の JSON では、とを "predicted"cpc_click_goal に1.00設定cpm_bid_typeして、予測される $1.00 CPC 目標に CPM の入札を最適化します。
オブジェクトで 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"
    }
}

POST キャンペーンサービスへ

$ curl -b cookies -c cookies -X POST -d @campaign.json 'https://api.appnexus.com/campaign?advertiser_id=45278'

{
    "response": {
        "status": "OK",
        "count": 1,
        "id": 10101640,
        "start_element": 0,
        "num_elements": 100,
        "campaign": {
            "id": 10101640,
            "state": "inactive",
            "parent_inactive": false,
            "code": null,
            "advertiser_id": 45278,
            "line_item_id": 34287,
            "creative_id": null,
            "pixel_id": null,
            "short_name": null,
            "name": "Custom Model Campaign - Modify Bid Based on Region/Hour of Day",
            "profile_id": null,
            "start_date": null,
            "end_date": null,
            "timezone": "EST5EDT",
            "priority": 5,
            "cadence_modifier_enabled": true,
            "cpc_goal": 1,
            "cpm_bid_type": "predicted",
            "base_bid": null,
            "min_bid": null,
            "max_bid": null,
            "bid_margin": 0,
            "roadblock_creatives": false,
            "roadblock_type": "no_roadblock",
            "inventory_type": "real_time",
            "last_modified": "2015-08-10 20:59:49",
            "max_learn_bid": null,
            "cadence_type": "advertiser",
            "member_id": 958,
            "click_url": null,
            "require_cookie_for_tracking": true,
            "allow_unverified_ecp": false,
            "defer_to_li_prediction": false,
            "ecp_learn_divisor": null,
            "projected_learn_events": null,
            "learn_threshold": 3,
            "cpc_payout": null,
            "comments": null,
            "optimization_version": "v7",
            "learn_override_type": null,
            "base_cpm_bid_value": null,
            "impression_limit": 40000,
            "bid_multiplier": 1,
            "remaining_days": null,
            "total_days": null,
            "supply_type_action": null,
            "supply_type": null,
            "creatives": null,
            "pixels": null,
            "optimization_lookback": null,
            "campaign_modifiers": null,
            "labels": null,
            "broker_fees": null,
            "valuation": null,
            "bid_model": null,
            "bid_modifier_model": {
                "id": 148,
                "name": "Modify Bid Based on Region/Hour of Day",
                "active": "1"
            },
            "lifetime_budget": null,
            "lifetime_budget_imps": null,
            "daily_budget": null,
            "daily_budget_imps": null,
            "enable_pacing": null,
            "allow_safety_pacing": null,
            "lifetime_pacing": null,
            "lifetime_pacing_span": null
        },
        "dbg_info": {
            "instance": "64.bm-hbapi.prod.nym2",
            "s1ave_hit": false,
            "db": "master",
            "awesomesauce_cache_used": false,
            "count_cache_used": false,
            "warnings": [
            ],
            "time": 1010.1411342621,
            "start_microtime": 1439240389.0273,
            "version": "1.15.580",
            "s1ave_lag": 0,
            "member_last_modified_age": 1439240389,
            "output_term": "campaign"
        }
    }
}

次の方法で共有

Data Science ツールキット - Bonsai デシジョンツリーのカスタムモデルを作成する

カスタムモデル型

入札価格

入札条件

ワークフロー

手順 1: 要件を特定する

例: 入札価格のデシジョンツリー

手順 2: デシジョンツリーを作成する

例: 入札価格の Bonsai ツリー

手順 3: デシジョンツリーをエンコードする

例: Base64 でエンコード

手順 4: デシジョンツリーでエラーがないか確認する

例: base64 でエンコードされたツリーを含む JSON ファイル

例: `POST` サービスへ`custom-model-parser`

手順 5: カスタムモデルとしてデシジョンツリーを追加する

例: カスタムモデルを定義する JSON ファイル

例: `POST` to `custom-model` service

手順 6: カスタムモデルをキャンペーンに割り当てる

入札価格モデル

入札修飾子モデル

その他のリソース

次の方法で共有

Data Science ツールキット - Bonsai デシジョン ツリーのカスタム モデルを作成する

カスタム モデル型

入札価格

入札条件

ワークフロー

手順 1: 要件を特定する

例: 入札価格のデシジョン ツリー

手順 2: デシジョン ツリーを作成する

例: 入札価格の Bonsai ツリー

手順 3: デシジョン ツリーをエンコードする

例: Base64 でエンコード

手順 4: デシジョン ツリーでエラーがないか確認する

例: base64 でエンコードされたツリーを含む JSON ファイル

例: POST サービスへcustom-model-parser

手順 5: カスタム モデルとしてデシジョン ツリーを追加する

例: カスタム モデルを定義する JSON ファイル

例: POST to custom-model service

手順 6: カスタム モデルをキャンペーンに割り当てる

入札価格モデル

入札修飾子モデル

関連項目

その他のリソース

Data Science ツールキット - Bonsai デシジョンツリーのカスタムモデルを作成する

カスタムモデル型

例: 入札価格のデシジョンツリー

手順 2: デシジョンツリーを作成する

手順 3: デシジョンツリーをエンコードする

手順 4: デシジョンツリーでエラーがないか確認する

例: `POST` サービスへ`custom-model-parser`

手順 5: カスタムモデルとしてデシジョンツリーを追加する

例: カスタムモデルを定義する JSON ファイル

例: `POST` to `custom-model` service

手順 6: カスタムモデルをキャンペーンに割り当てる