Partager via

Science des données Toolkit - Create un modèle personnalisé d’arbre de décision Bonsai

L’API De plateforme numérique vous permet de créer vos propres modèles prédictifs personnalisés (précédemment appelés « soumissionnaire programmable AppNexus ») et de les charger directement sur notre plateforme ouverte. Vous pouvez :

  • Vos scientifiques des données écrivent des modèles prédictifs dans Bonsai, un langage DSL (high-level domain-specific language) très similaire au langage Python populaire.
  • Validez et chargez vos modèles via notre API et affectez-les à des campagnes via notre API ou notre interface utilisateur.
  • Exécutez vos modèles sur nos soumissionnaires et bénéficiez de la vitesse, de la mise à l’échelle, de la fiabilité et des coûts réduits de notre infrastructure.

Cette page vous aide à démarrer.

Types de modèles personnalisés

Actuellement, il est possible de créer deux types de modèles prédictifs personnalisés :

Prix de l’offre

Le modèle Prix de l’offre utilise un arbre de décision pour déterminer l’offre CPM d’une campagne. Ce type de modèle sert de stratégie d’achat tierce d’une campagne, à la place des stratégies CPM standard comme « Bid a Base CPM » ou « Optimize to a % Margin ».

Modificateur d’enchère

Le modèle de modificateur d’enchère utilise un arbre de décision pour ajuster l’offre CPM dérivée de l’optimisation d’une campagne à la hausse ou à la baisse. Ce type de modèle est utilisé conjointement avec une stratégie d’achat qui utilise l’optimisation de Xandr, comme « Optimiser pour un objectif CPA prédit » ou « Optimiser pour un objectif DEP prédit ».

Remarque

Les enchères calculées par le modèle sont toujours exprimées dans la devise définie sur l’annonceur, même si vous avez spécifié une autre devise pour la campagne.

Flux de travail

Remarque

Le workflow Alpha nécessite l’utilisation de l’API. Les clients alpha sont censés avoir terminé notre processus d’intégration d’API avant de commencer.

Étape 1 : Identifier vos besoins

Vous allez écrire votre modèle personnalisé en tant qu’arbre de décision, où les branches de l’arborescence expriment des conditions qui mènent à des sorties spécifiques (prix des enchères dans le cas d’un modèle de prix d’enchère et multiplicateurs d’enchère dans le cas d’un modèle de modificateur d’enchère). Les conditions peuvent être basées sur un ensemble de caractéristiques et de valeurs de caractéristiques Bonsai. Avant d’écrire votre arborescence :

Exemple : arbre de décision pour la tarification des enchères

Diagramme d’un arbre de décision pour la tarification des enchères.

Remarque

Utilisez des modèles personnalisés pour la tarification, et non pour le ciblage.

Utilisez des modèles personnalisés pour déterminer comment évaluer les impressions, et non comment les cibler. Pour les impressions de ciblage, vous devez continuer à utiliser la section Ciblage de la configuration de la campagne dans ou le service de profil pour le ciblage via l’API.

Étape 2 : Create votre arbre de décision

Une fois que vous connaissez les fonctionnalités et les étapes que vous souhaitez suivre pour prix ou modifier les enchères pour une campagne, écrivez-les en tant qu’arbre de décision dans notre langue Bonsai. Utilisez les exemples de cette page ainsi que l’exemple simple ci-dessous pour commencer à comprendre comment écrire votre arborescence.

Remarque

Utilisez des onglets pour la mise en retrait, et non des espaces.

Dans Bonsai, la mise en retrait est utilisée pour regrouper les expressions (comme Python). Veillez à utiliser des onglets pour indiquer la mise en retrait de ligne. Les espaces ne sont actuellement pas pris en charge.

Exemple : arbre Bonsai pour la tarification des enchères

Remarque

Dans l’exemple de code ci-dessous, les lignes commençant par # sont des commentaires pour vous aider à comprendre la logique de cette arborescence.

# 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

Étape 3 : Encoder votre arbre de décision

Codez votre arbre de décision en base64.

Exemple : encodé en base64

IyBUaGlzIHRyZWUgZGV0ZXJtaW5lcyBhIGJpZCBwcmljZSBhcyBmb2xsb3dzOgojIDEuIElmIHRoZSB1c2VyIGlzIGluIENhbGlmb3JuaWEsIGFuZCB0aGUgaG91ciBpcyBiZXR3ZWVuIDEycG0gYW5kIDE0cG0gdGhlcmUsIGJpZCAkMS41MC4KIyAyLiBJZiB0aGUgdXNlciBpcyBpbiBOZXcgWW9yaywgYW5kIHRoZSBob3VyIGlzIGJldHdlZW4gMWFtIGFuZCAzYW0gdGhlcmUsIGJpZCAkMC4xMC4KIyAzLiBPdGhlcndpc2UsIGJpZCAkMC41MC4KCmlmIGV2ZXJ5IHJlZ2lvbiA9ICJVUzpDQSIsIHVzZXJfaG91ciByYW5nZSAoMTIsMTQpOgoJMS41CmVsaWYgZXZlcnkgcmVnaW9uID0gIlVTOk5ZIiwgdXNlcl9ob3VyIHJhbmdlICgxLDMpOgoJMC4xCmVsc2U6CgkwLjU=

Étape 4 : Rechercher des erreurs dans votre arbre de décision

Utilisez le service d’analyseur de modèle personnalisé pour case activée la validité de votre arbre de décision.

  • Dans la requête JSON, placez votre arborescence encodée en base64 dans le model_text champ sous forme de chaîne.
  • En cas d’erreurs, utilisez le error champ dans la réponse pour vous aider à identifier et à résoudre les erreurs de syntaxe ou de fonctionnalité Bonsai. Pour obtenir des conseils, consultez Messages d’erreur.
  • S’il n’y a pas d’erreur, le size champ dans la réponse vous indique la taille de votre arborescence dans Lisp (le format que nous utilisons pour stocker les arborescences). Vérifiez que la size valeur est inférieure à 3 Mo ou 3 145 728 octets.

Remarque

Si l’arborescence est supérieure à 3 Mo, vous ne pourrez pas ajouter l’arborescence.

Exemple : fichier JSON contenant votre arborescence encodée en base64

$ cat check_tree.json 
 
{
    "custom-model-parser": {
                "model_text": "IyBUaGlzIHRyZWUgZGV0ZXJtaW5lcyBhIGJpZCBwcmljZSBhcyBmb2xsb3dzOgojIDEuIElmIHRoZSB1c2VyIGlzIGluIENhbGlmb3JuaWEsIGFuZCB0aGUgaG91ciBpcyBiZXR3ZWVuIDEycG0gYW5kIDE0cG0gdGhlcmUsIGJpZCAkMS41MC4KIyAyLiBJZiB0aGUgdXNlciBpcyBpbiBOZXcgWW9yaywgYW5kIHRoZSBob3VyIGlzIGJldHdlZW4gMWFtIGFuZCAzYW0gdGhlcmUsIGJpZCAkMC4xMC4KIyAzLiBPdGhlcndpc2UsIGJpZCAkMC41MC4KCmlmIGV2ZXJ5IHJlZ2lvbiA9ICJVUzpDQSIsIHVzZXJfaG91ciByYW5nZSAoMTIsMTQpOgoJMS41CmVsaWYgZXZlcnkgcmVnaW9uID0gIlVTOk5ZIiwgdXNlcl9ob3VyIHJhbmdlICgxLDMpOgoJMC4xCmVsc2U6CgkwLjU="
    }
}

Exemple : POST vers le custom-model-parser service

$ 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": {
            ...
        }
    }
}

Étape 5 : Ajouter votre arbre de décision en tant que modèle personnalisé

Une fois que vous avez confirmé que votre arborescence est valide, utilisez le service de modèle personnalisé pour charger votre arbre de décision encodé. Veillez à :

  • Définissez le type de modèle personnalisé correct dans le model_output champ :
    • Pour un modèle de prix d’enchère, utilisez "bid".
    • Pour un modèle de modificateur d’enchère, utilisez "bid_modifier".
  • Placez votre arborescence encodée en base64 dans le model_text champ sous forme de chaîne.
  • Fournissez un unique name. Cela est obligatoire et facilite la sélection du modèle approprié dans.
  • Fournissez le advertiser_id auquel appartient le modèle personnalisé. Vous pourrez utiliser le modèle uniquement dans les campagnes de cet annonceur.

Exemple : fichier JSON définissant votre modèle personnalisé

$ 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="
    }
}

Exemple : POST pour le 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"
        }
    }
}

Étape 6 : Affecter votre modèle personnalisé à une campagne

Cette étape change en fonction du type de modèle personnalisé que vous utilisez et si vous utilisez l’API ou l’interface utilisateur pour affecter votre modèle à une campagne. Développez l’option appropriée ci-dessous pour obtenir des instructions.

Modèle de prix d’enchère

Utilisation de l’API

Utilisez le service Campaign pour affecter votre modèle personnalisé à une campagne. Veillez à :

  • Définissez sur cpm_bid_type"custom_model".

  • Fournissez le id de votre modèle personnalisé dans l’objet bid_model .

  • Définissez sur inventory_type"real_time".

    Fichier JSON définissant votre campagne

    $ 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 vers le service de campagne

    $ 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"
        }
    }
}

Modèle de modificateur d’enchère

Utilisation de l’API

Utilisez le service Campaign pour affecter votre modèle personnalisé à une campagne. Veillez à :

  • Définissez sur cpm_bid_type une stratégie d’achat basée sur l’optimisation ("predicted" ou "margin") et tous les champs requis correspondants.

    • Dans le code JSON ci-dessous, par exemple, nous définissons cpm_bid_type sur "predicted" et cpc_click_goal sur 1.00 pour optimiser les enchères CPM pour atteindre un objectif de 1,00 $ AUT prédit.

  • Dans l’objet bid_modifier_model , fournissez le id du modèle personnalisé qui modifiera les enchères CPM de la campagne.

  • Définissez sur inventory_type"real_time".

    Fichier JSON définissant votre campagne

    $ 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 vers le service de campagne

    $ 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"
        }
    }
}
  • Last updated on