Compartir a través de

Ciencia de datos Toolkit: Create un modelo personalizado de árbol de decisión de Bonsai

  • Artículo

Digital Platform API le permite crear sus propios modelos predictivos personalizados (anteriormente conocidos como "El licitador programable de AppNexus") y cargarlos directamente en nuestra plataforma abierta. Puede:

  • Haga que los científicos de datos escriban modelos predictivos en Bonsai, un lenguaje específico del dominio (DSL) de alto nivel que es muy similar al popular lenguaje Python.
  • Valide y cargue los modelos a través de nuestra API y asígnelos a las campañas a través de nuestra API o interfaz de usuario.
  • Ejecute sus modelos en nuestros licitadores y benefíciese de la velocidad, la escala, la confiabilidad y los costos más bajos de nuestra infraestructura.

Esta página le ayuda a empezar.

Tipos de modelo personalizados

Actualmente, es posible crear dos tipos de modelos predictivos personalizados:

Precio de la oferta

El modelo de precio de puja usa un árbol de decisión para determinar la oferta de CPM de una campaña. Este tipo de modelo sirve como estrategia de compra de terceros de una campaña, en lugar de estrategias de CPM estándar como "Bid a Base CPM" o "Optimize to a % Margin".

Modificador de puja

El modelo modificador de puja usa un árbol de decisión para ajustar la puja de CPM derivada de la optimización de una campaña hacia arriba o hacia abajo. Este tipo de modelo se usa junto con una estrategia de compra que usa la optimización de Xandr, como "Optimizar a un objetivo de CPA previsto" o "Optimizar a un objetivo de CPC previsto".

Nota:

Las pujas calculadas por el modelo siempre se expresan en la moneda establecida en el anunciante, incluso si ha especificado una moneda diferente para la campaña.

Flujo de trabajo

Nota:

El flujo de trabajo alfa requiere el uso de la API. Se espera que los clientes Alfa hayan completado nuestro proceso de incorporación de API antes de empezar.

Paso 1: Identificar los requisitos

Escribirá el modelo personalizado como árbol de decisión, donde las ramas del árbol expresan condiciones que conducen a salidas específicas (precios de puja en el caso de un modelo de precio de puja y multiplicadores de puja en el caso de un modelo modificador de puja). Las condiciones se pueden basar en un conjunto de características y valores de características de Bonsai. Antes de escribir el árbol:

Ejemplo: Árbol de decisión para los precios de la oferta

Diagrama de un árbol de decisión para los precios de la oferta.

Nota:

Use modelos personalizados para los precios, no para la selección de destino.

Use modelos personalizados para determinar cómo fijar el precio de las impresiones, no cómo dirigirse a ellas. En el caso de las impresiones de destino, debe seguir usando la sección Segmentación de la configuración de la campaña en o el Servicio de perfiles para la segmentación a través de la API.

Paso 2: Create el árbol de decisión

Una vez que sepas las características y los pasos que quieres seguir para fijar o modificar las pujas de una campaña, escríbelas como árbol de decisión en nuestro Idioma Bonsai. Use los ejemplos de esa página, así como el ejemplo sencillo siguiente para empezar a comprender cómo escribir el árbol.

Nota:

Use pestañas para sangría, no espacios.

En Bonsai, la sangría se usa para agrupar expresiones (similares a Python). Asegúrese de usar pestañas para indicar la sangría de línea. Actualmente no se admiten espacios.

Ejemplo: Árbol de Bonsai para precios de pujas

Nota:

En el ejemplo de código siguiente, las líneas que comienzan por # son comentarios que le ayudarán a comprender la lógica de este árbol.

# 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

Paso 3: Codificar el árbol de decisión

Codificación base64 del árbol de decisión.

Ejemplo: codificado en Base64

IyBUaGlzIHRyZWUgZGV0ZXJtaW5lcyBhIGJpZCBwcmljZSBhcyBmb2xsb3dzOgojIDEuIElmIHRoZSB1c2VyIGlzIGluIENhbGlmb3JuaWEsIGFuZCB0aGUgaG91ciBpcyBiZXR3ZWVuIDEycG0gYW5kIDE0cG0gdGhlcmUsIGJpZCAkMS41MC4KIyAyLiBJZiB0aGUgdXNlciBpcyBpbiBOZXcgWW9yaywgYW5kIHRoZSBob3VyIGlzIGJldHdlZW4gMWFtIGFuZCAzYW0gdGhlcmUsIGJpZCAkMC4xMC4KIyAzLiBPdGhlcndpc2UsIGJpZCAkMC41MC4KCmlmIGV2ZXJ5IHJlZ2lvbiA9ICJVUzpDQSIsIHVzZXJfaG91ciByYW5nZSAoMTIsMTQpOgoJMS41CmVsaWYgZXZlcnkgcmVnaW9uID0gIlVTOk5ZIiwgdXNlcl9ob3VyIHJhbmdlICgxLDMpOgoJMC4xCmVsc2U6CgkwLjU=

Paso 4: Comprobar si hay errores en el árbol de decisión

Use el servicio de analizador de modelos personalizados para comprobar la validez del árbol de decisión.

  • En la solicitud JSON, coloque el árbol codificado en base64 en el model_text campo como una cadena.
  • Si hay errores, use el error campo en la respuesta para ayudarle a identificar y resolver errores de características o sintaxis de Bonsai. Para obtener instrucciones, consulte Mensajes de error.
  • Si no hay errores, el size campo de la respuesta muestra el tamaño del árbol en Lisp (el formato que usamos para almacenar árboles). Asegúrese de que es size menor que 3 MB o 3 145 728 bytes.

Nota:

Si el árbol es mayor que 3 MB, no podrá agregarlo.

Ejemplo: archivo JSON que contiene el árbol codificado en base64

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

Ejemplo: POST al custom-model-parser servicio

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

Paso 5: Agregar el árbol de decisión como modelo personalizado

Una vez que haya confirmado que el árbol es válido, use custom model service para cargar el árbol de decisión codificado. Asegúrese de:

  • Establezca el tipo de modelo personalizado correcto en el model_output campo:
    • Para un modelo de precio de puja, use "bid".
    • Para un modelo de modificador de puja, use "bid_modifier".
  • Coloque el árbol codificado en base64 en el model_text campo como una cadena.
  • Proporcione un único name. Esto es necesario y facilitará la selección del modelo correcto en .
  • Proporcione al advertiser_id que pertenece el modelo personalizado. Solo podrá usar el modelo en campañas de este anunciante.

Ejemplo: archivo JSON que define el modelo personalizado

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

Ejemplo: POST para el custom-model servicio

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

Paso 6: Asignar el modelo personalizado a una campaña

Este paso cambia en función del tipo de modelo personalizado que use y de si usa la API o la interfaz de usuario para asignar el modelo a una campaña. Expanda la siguiente opción correspondiente para obtener instrucciones.

Modelo de precio de puja

Uso de la API

Usa el Servicio de campaña para asignar tu modelo personalizado a una campaña. Asegúrese de:

  • Establezca en cpm_bid_type"custom_model".

  • Proporcione el id del modelo personalizado en el bid_model objeto .

  • Establezca en inventory_type"real_time".

    Archivo JSON que define la campaña

    $ 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 para el servicio de campaña

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

Modelo modificador de puja

Uso de la API

Usa el Servicio de campaña para asignar tu modelo personalizado a una campaña. Asegúrese de:

  • Establezca cpm_bid_type en una estrategia de compra basada en la optimización ("predicted" o "margin") y en los campos necesarios correspondientes.

    • En el json siguiente, por ejemplo, establecemos cpm_bid_type en "predicted" y cpc_click_goal en 1.00 para optimizar las pujas de CPM con un objetivo de CPC previsto de 1,00 USD.

  • En el bid_modifier_model objeto , proporcione el id del modelo personalizado que modificará las pujas de CPM de la campaña.

  • Establezca en inventory_type"real_time".

    Archivo JSON que define la campaña

    $ 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 para el servicio de campaña

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