An ML pipeline defines the end to end flow of the model inference process. Wyvern’s ML pipeline is comprised of:
  • Retrieval (Mostly for Search & Discovery use cases like recommendations and ranking)
  • Offline feature retrieval
  • Realtime feature generation
  • Model inference
  • Business logic
  • Event logging
The pipeline orchestrates all the feature data going into the model, data getting out of the model, and logging all the data to a standard format. Let’s see how to define and set up a Machine Learning Pipeline with Wyvern

​
Define ML Pipeline

First, let’s think about the product ranking problem in a marketplace. Your marketplace has thousands or even millions of products and you’re using Elasticsearch or Algolia to do basic search. Now you want to build a ranking pipeline to add personalization. Assuming your search returns thousands of products. You would use your ranking model to factor in more than just text relevance: Image relevance, Newness of products, popularity of products, user personalization, session personalization. We’re going to build a linear ranking model considering these factors:
  • the search score of the product
  • similarity between the query and the category of the product
  • similarity between the query and the brand of the product
  • similarity between the query and the title of the product
  • similarity between the query and the description of the product
  • relevance between the query and the image
  • newness of the product
  • popularity of the product
  • relevance between user’s purchase history and the product
  • relevance between session’s search history and the product
Here’s the formula of the model: 
model_score =
    2 * search_score
    + 10 * query_category_similarity
    + 20 * query_brand_similarity
    + 22 * query_title_similarity
    + 13 * query_description_similarity
    + 15 * query_image_relevance
    + 4 * product_newness
    + 18 * product_popularity
    + 26 * product_purchase_history_relevance
    + 30 * product_session_search_relevance
What the pipeline does is to get all the features for each product and pass them to the model. As a result, the model returns the score of every product and the pipeline returns the list of ranked products.

​
Requests

To start building a Wyvern Pipeline, we should define the request schema first. In the ranking case, we start by defining the product and the ranking request schemas:
pipelines/product_ranking/schemas.py
from wyvern import ProductEntity, RankingRequest


class Product(ProductEntity):
    brand: str | None = None
    category: str | None = None
    categories: list[str] = []
    title: str | None = None
    description: str | None = None
    price: float | None = None
    number_in_stock: int | None = None
    search_score: float | None = None


class MyRankingRequest(RankingRequest[Product]):
    candidates: list[Product]
Here we’re using the default RankingRequest with the Product entity we just defined. This actually translates to the following API request schema: 
{
  "user_page_size": 0,
  "user_page": 0,
  "candidate_page_size": 0,
  "candidate_page": 0,
  "request_id": "string",
  "include_events": false,
  "query": {
    "query": "string"
  },
  "candidates": [
    {
      "product_id": "string",
      "brand": "string",
      "category": "string",
      "categories": [],
      "title": "string",
      "description": "string",
      "price": 0,
      "number_in_stock": 0,
      "search_score": 0
    }
  ]
}
Here are the ranking API attributes:
  • user_page_size: Integer. The max number of candidates that ranking API returns. If the number of candidates returned is smaller than wyvernPageSize, it’s the last wyvernPage.
  • user_page: Integer. It’s the zero-based index for the ranked “page” of the candidates that are passed to our ranking API. Defaults to 0.
  • candidate_page_size: Integer. This is the number of candidates/products your retrieval/search (Elasticsearch for example) returns. It’s the same as the “Elastic size” parameter sent to Elasticsearch. We’re adding a constraint.
  • candidate_page: Integer. This is the zero-indexed page number for our candidate set.
  • request_id: String. Unique identifier for the request, to join this with the user interaction.
  • include_events: Optional booleon. It measn whether the event logs will be included in the response. It is false by default.
  • query: The Query object. The search term inputted by the user.
  • candidates: The list of products. The product object schema is defined by users. In this example, only the product_id is a required field and other fields are optional in this example.
Next, let’s see how data hydration and feature retrieval work to understand how and why Wyvern can make it easy to orchestrates ML features. We will come back to talk about how to set up a wyvern ML pipeline later.