How to create a Delivery Model and upload via S3
Creating and uploading a Delivery Model is very similar to the steps for creating a Bid Model. If you would like to get started using Delivery Models or Modifiers, please reach out to either your Beeswax account manager, sales representative or firstname.lastname@example.org, all of whom can enable this for your account.
1. The first step is to create the model offline. This can be done by training a model using Beeswax log data, or a different first/third party data source, or any other modeling technique. The delivery model consists of 2 files: the manifest file and the prediction file.
2. Creating the Prediction File: Prediction files are the table that contains the delivery model. The fields currently supported in prediction files can be found here. Prediction files should be kept to a maximum of 100 rows to optimize loading performance and should be in the below format:
- pipe-delimited ("|") text files
- no compression
- first row of each file contains headers
- at least one bid request key field
- a required field called "value", which represents either the relative delivery weight for that row, from 0 to 1000
- null values should be left blank
- an asterisk (*) can optionally be used to match any value (note: a maximum of three wildcard fields are supported
3. Creating the Manifest File: The manifest file is a .json file with the below format. The model predictions object includes a list of S3 paths to all prediction files (previous step) associated with this model version. The files live under the following path: s3://beeswax-data-<region>/bid_models/<buzz key>/. The metadata.fields object contains a list of feature fields that are included in this model version and, optionally, the fields which contain wildcards. A sample manifest can be downloaded here.
Note: When creating the Prediction File you should assure that each row is mutually exclusive in criteria. If multiple rows could be matched to a given auction, then delivery may not match your expectations.
How to Upload a Delivery Model:
- In order to use a delivery model, the files must be uploaded to S3. Please reach out to your support alias if you are not set up for this and request access. Instructions on how to access S3 buckets for upload can be found here.
- Once access is granted, follow the API documentation to upload the manifest and data files to s3://beeswax-data-<region>/bid_models/<buzz key>/. Regardless of which region you upload the files to, the data will be replicated to each region in which your bidder is live.
- File structure is largely flexible, but please note that manifest files must be under the following path: s3://beeswax-data-<region>/bid_models/<buzz key>/customer_manifests/.
How to Create a Delivery Model in Buzz
The final step to creating and using delivery models is to create the delivery model in the UI. API instructions can be found here
- Select Create > Model.
- Enter all the required (marked with asterisk) field values such as Model Name and Value Type; then select Save and Continue.
- In Model Versions, create the first Delivery Model version by entering the Manifest S3 Path (location of the pre-loaded manifest file) and Model Version Name
- The model will automatically go into ‘PENDING’ status. This status signifies the version is being validated and prepared to receive traffic.
- Now, you have to attach the Delivery Model to a new “Modifier” object. Go to “Create > Delivery Modifier” and do the following:
- Select Modifier Type > With Model.
- Associate the Delivery Model you created previously from the Delivery Model field dropdown.
- Specify the Fallback Weight, which is the weight to be used if no “row” in the model matches.
- Select Save Delivery Modifier.
- Go to the Line Item (or Campaign), and associate the Delivery Modifier from the “Optimization” page.
- Select Save Delivery Modifier to continue setting up the line item.
Note: The updated versions of the delivery model table can be uploaded to the same delivery model object in Buzz, and the most recent upload version will be used unless otherwise specified.
See Delivery Modifier Overview for more info.