Compartir a través de

Ciencia de datos Toolkit: flujo de trabajo del modelo personalizado de Bonsai

  • Artículo

En esta página se describe un flujo de trabajo de modelo personalizado de Bonsai típico y se proporcionan ejemplos de código.

Nota:

El flujo de trabajo beta cerrada requiere el uso de la API. Se espera que los clientes beta cerrados 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 escriben en nuestro lenguaje Bonsai y se basan en un conjunto de características y valores de características de Bonsai . Antes de escribir el árbol:

  • Eche un vistazo a las características de Bonsai que están disponibles.
  • Esboce cómo desea usar las operaciones de árbol para determinar las salidas.
  • Asegúrese de aprovechar las ventajas de los datos de informes para identificar las características y los valores adecuados. Para obtener más información, consulte Fuentes de distribución de datos de nivel de registro y "Informes estándar" en la documentación.

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

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

Nota:

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 profile service para dirigirse 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.  Base64 es un algoritmo de codificación que le permite transformar dígitos binarios en un alfabeto que consta de letras latinas, dígitos, signos más y símbolos de barra diagonal. Hay varios convertores basados en web que pueden codificar el contenido en Base64.

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

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

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

Modelo de precio de puja

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

Modelo modificador de puja

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