How to Create a Bid Model
There are 3 steps to creating a bid model: creating the data model offline, uploading the bid model to S3, and uploading the bid model to buzz. These 3 steps are outlined below. For a more in depth walk through, see our Bid Models tutorial on Github.
How To Create a Bid Model (offline)
- 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 bid model consists of 2 files: the manifest file and the prediction file.
- Creating the Prediction File: Prediction files are the table that contains the bid model. The fields currently supported in prediction files can be found here. Prediction files should be kept to a maximum size of 100MB each, and an accumulative maximum size of 4GB per Bid Model, 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 CPM Bid or Bid Multiplier for that row
- 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)
- max file size = 100MB
- Prediction files can only include values that are bids or multipliers
- 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.
How to Upload a Bid Model
- In order to use a bid 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/`. An example file structure would be :
How To Create a Bid Model in Buzz
- The final step to creating and using bid models is to create the bid model in the UI. API instructions can be found here. First, select +New> Bid Model
- Enter the bid model name, select the value type as either ‘bid’ or ‘multiplier’, and press “Save and Continue”
3. Create a first Bid Model Version for the Bid Model by entering the location of the previously uploaded manifest file and an option name. Press "Save All".
4. The model will automatically go into ‘PENDING’ status. This status signifies the version is being validated and prepared to receive traffic.
5. The final step is to associate the bid model with a line item. On the line item overview screen, select either "Flat CPM", "Flat CPM with Pacing" or "Optimized CPM with Pacing" as the bid strategy; the bid model will default to this when there’s no match on the bid model.
6. Continue through the targeting and onto the ‘Bid Modifier’ view. Select ‘Create New’ and set the ‘Max Bid’. This value will override the Bid Model and should be used as a control to prevent accidentally bidding with an extremely high CPM.
7. Select the model in the Bid Model field
8. Finish setting up the line item, and set active.
Please note that updated versions of the bid model table can be uploaded to the same bid model object in buzz, and the most recent upload version will be used unless otherwise specified.