Science des données Toolkit - Flux de travail du modèle personnalisé Bonsai

Cette page décrit un workflow de modèle personnalisé Bonsai classique et fournit des exemples de code.

É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 sont écrites dans notre langue Bonsai et basées sur un ensemble de caractéristiques et de valeurs de caractéristiques Bonsai . Avant d’écrire votre arborescence :

• Examinez de près les fonctionnalités Bonsai disponibles.
• Esquissez la façon dont vous souhaitez utiliser les fonctionnalités d’arborescence pour déterminer les sorties.
• Veillez à tirer parti des données de création de rapports pour identifier les fonctionnalités et valeurs appropriées. Pour plus d’informations, consultez Flux de données au niveau du journal et « Rapports standard » dans la documentation.

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

É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.

Exemple : arbre Bonsai pour la tarification des enchères

# 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.  Base64 est un algorithme d’encodage qui vous permet de transformer des chiffres binaires en un alphabet composé de lettres latines, de chiffres, de symboles plus et de barres obliques. Il existe plusieurs convertisseurs web qui peuvent encoder votre contenu 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.

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

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

Exemple : POST vers le service 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": {
            ...
        }
    }
}

É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):
 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"
        }
    }
}

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

Modèle de prix d’enchère

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

Modèle de modificateur d’enchère

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