次の方法で共有

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"。
  • 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 の入札を最適化します。

  • オブジェクトで 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"
    }
}