Skip to content
Français

Content-based recommendations

  • Lesson 17
  • 35 min
  • Module 6: Content, hybrids and cold start

Where we are

Collaborative methods need interactions. A product that nobody has bought yet has none. In this lesson, we turn product text and attributes into embeddings, and we find similar products with no history at all.

Plays from YouTube. Nothing loads from YouTube until you press play. Privacy

What you will be able to do

Suggest products from what they are, not from who bought them. Turn each product’s text into a list of numbers, find the closest products, and build a customer’s list from the products they touched. Then measure what this gives Larkfield, and what it does not.

NotebookDo this lesson in a notebookColab · Kaggle · GitHub

The notebook loads Larkfield’s product vectors and finds the closest products of an armchair and of a new product. Then you measure how often a new product’s closest product is in its own subcategory. Its setup cells download about 3 MB of practice data. No model download. About 15 minutes.

Colab and Kaggle open your own copy. They need a free Google or Kaggle account. Stuck? See the solution notebook.

Before you startWhat to know and to have readyAbout 35 minutes

What you need to know

What you need on your computer (only for the project steps)

  • Your larkfield-recs project at the end of Module 5, with its virtual environment active. recs check prints Setup check passed.
  • The practice files in ../nextia-learning-labs, beside the project folder. You copy one file from its snapshot end-of-m06.

Tested on macOS with Python 3.12. The Windows (PowerShell) commands were not run.

A garden shop gets a new product on Monday morning: a charcoal cool box with wheels. Nobody has bought it yet. The till has no history for it.

A good shop assistant still knows what to do with it. She reads the label: “hard-shell cool box, wheels, charcoal”. She remembers a customer who bought a soft cool bag last summer. She shows him the new box. She did not need a single sale of the box. She used what the product is.

The methods of Modules 4 and 5 cannot do this. They learn only from who bought what.

Item-item collaborative filtering finds neighbours through shared customers. ALS learns a vector for each product from the customers who touched it. Both need events. A product with no events has an empty column in the matrix. It cannot be anybody’s neighbour, and ALS learns nothing for it.

Larkfield saw this on 1 May 2026, the first day of the launch period. It launched a summer range of 240 products that day. Before 1 May, those products had 0 views, 0 basket adds and 0 orders. We replay the first two weeks. We learn from the events before 1 May, and we score the orders of 1 to 14 May for 2,113 customers.

Method Launched products in any list (of 240) New products in the lists
als 0 0.0%
trending 0 0.0%
hybrid-blend (next lessons) 0 0.1%
two-stage (Module 7) 0 0.5%

Every method that learns from history shows none of the 240 products. Hana, the merchandising lead, paid for a new range, and the home page hides all of it. This launch is a practice problem we made on purpose: the whole shop log is synthetic, made by our code.

The idea: describe each product with numbers

Section titled “The idea: describe each product with numbers”

A product has text: a title, a description, a category, a style and a colour. If we can turn that text into numbers, we can compare products without any history.

An embedding is a list of numbers that a language model makes from a text. The model is trained so that texts with a similar meaning get similar lists. “Hard-shell cool box” and “rigid cooler” get close lists, although they share no word. “Velvet cushion” gets a list far from both. A list of numbers like this is also called a vector.

A content-based method suggests products whose content is close to the products a customer liked. “Content” means the product’s own text and attributes. The name says what it uses, and what it does not use: other customers.

Product text (title, description, category, subcategory, style, colour) goes into a small language model, run once by the course team. The model gives an embedding of 384 numbers. The embedding is compared with the vector of every other product by cosine similarity, which gives the closest products, with no history needed. A new product on its first day also has text, so it also has a vector.
From product text to similar products. A new product has text on its first day, so it gets a vector on its first day.
Text description of the diagram

The diagram is a flow from left to right. Product text, with the title, description, category, subcategory, style and colour, goes into a small language model. The course team ran the model once. The model gives an embedding of 384 numbers. The embedding is compared with the vector of every other product by cosine similarity. That gives the closest products: similar text, with no history needed. A separate box with a thick border says “a new product on its first day”. A dashed arrow joins it to the embedding: it has text, so it has a vector too.

How do we say that two vectors are “close”? In Module 4 you met cosine similarity: it compares the direction of two vectors. Here the vectors have length 1, so the cosine is simple: multiply the matching numbers and add the products. The result is 1 for the same direction and smaller for vectors that point apart.

A tiny example we made, with only 2 numbers per product instead of 384. Think of the first number as “for cold drinks outside” and the second as “soft, for the living room”:

Product Vector Cosine with the cool box
Cool box (0.95, 0.31) 1 (itself)
Cool bag (0.87, 0.49) 0.95 × 0.87 + 0.31 × 0.49 = 0.98
Cushion (0.20, 0.98) 0.95 × 0.20 + 0.31 × 0.98 = 0.49
Three products and one customer profile as arrows (a tiny example we made). A small angle between two arrows means a high cosine.
Text description of the chart

Four arrows start at zero. The cool box points along the first axis, at (0.95, 0.31). The cool bag points almost the same way, at (0.87, 0.49): a small angle, cosine 0.98. The cushion points up, at (0.20, 0.98): a large angle from the cool box, cosine 0.49. The customer profile, at (0.80, 0.60), lies between the cool bag and the cushion, closer to the cool bag.

A customer is not a product, so we need one more step. A customer’s profile is the weighted sum of the vectors of the products they touched, scaled back to length 1. The project weights a view 1, a basket add 3 and an order 5, as in Module 2. Old events count less: their weight halves every 30 days.

In the tiny example, a customer ordered the cool bag (weight 5) and viewed the cushion (weight 1). The sum is 5 × (0.87, 0.49) + 1 × (0.20, 0.98) = (4.55, 3.43). Scaled to length 1, the profile is about (0.80, 0.60), the fourth arrow in the picture.

Now score each product with the profile. The cool box gets 0.95 × 0.80 + 0.31 × 0.60 = 0.95. The cushion gets 0.20 × 0.80 + 0.98 × 0.60 = 0.75. So the new cool box goes first in the list. It needed no sale at all: only its text.

The course team made one embedding per product with a small open model: IBM’s granite-embedding-97m-multilingual-r2 (licence Apache-2.0, as its model card states). It is the same model as in the search course’s lesson Search by meaning. Each product’s title, description, category, subcategory, style and colour became 384 numbers. This took 8.6 seconds for all 2,994 products, on a laptop processor.

The vectors are in the practice files: data/embeddings/products.npy, 2.3 MB, one row per product. So the project never loads the language model. Note one more thing: the product titles and descriptions were written by a language model from our attributes. They are synthetic, like the rest of the shop.

Embeddings for search in RAG: Building AI That Uses Your Data explains how such models are trained and how to search many vectors fast. Here, 2,994 vectors fit in one small NumPy array, so we compare with all of them every time.

Look at a launched product and its closest products by text. recs similar prints the five closest products:

P10117 Charcoal Wheeled Hard-Shell Cool Box (Picnic and cool boxes, 47.99 dollars)
1. P11543 0.950 Black Hard-Shell Personal Cool Box (Picnic and cool boxes)
2. P10832 0.941 Green Large Chest Cool Box (Picnic and cool boxes)
3. P11997 0.940 Red Hard-Sided Cool Box (Picnic and cool boxes)
4. P12299 0.940 Terracotta Wheeled Cool Box (Picnic and cool boxes)
5. P12652 0.929 Walnut Compact Rigid Cool Box (Picnic and cool boxes)

Five other cool boxes. On 1 May, the product had no history, and this list was the same: it uses only the text. Now compare the neighbours by shared customers (item-item collaborative filtering), seven weeks later, when the box had a history:

P10117 Charcoal Wheeled Hard-Shell Cool Box (Picnic and cool boxes, 47.99 dollars)
1. P11046 0.336 White Slim Can Cooler Box (Picnic and cool boxes) shared customers 26
2. P11789 0.314 Blush Pink Soft Cooler Bag (Picnic and cool boxes) shared customers 24
3. P10314 0.307 Copper Stainless Steel Drink Cooler (Picnic and cool boxes) shared customers 23
4. P12068 0.288 Cream Canvas Lunch Cooler (Picnic and cool boxes) shared customers 18
5. P12466 0.283 Brass-Tone Foldable Cooler Tote (Picnic and cool boxes) shared customers 20

The text neighbours look like the product. The customer neighbours are products that the same people looked at: soft bags and small coolers, the other options for the same trip.

Text has its own blind spots. Here are the closest products of the Driftwood armchair from Module 4:

P10020 Driftwood Blush Pink Wingback Armchair (Armchairs, 432.99 dollars)
1. P10971 0.929 Blush Pink Rattan Headboard Bed (Beds)
2. P11681 0.922 Driftwood Blush Pink Woven-Rattan Mirror (Mirrors)
3. P12503 0.920 Blush Pink Velvet Tub Armchair (Armchairs)
4. P11924 0.916 Belmont Blush Pink Fluted Bedside Table (Bedside tables)
5. P11108 0.915 Saltmarsh Blush Pink Compact Wardrobe (Wardrobes)

The colour words “Blush Pink” pull a bed, a mirror and a wardrobe close. By shared customers, all five neighbours of this armchair are armchairs. Text knows what words a product has. It does not know what people buy instead of it.

For the 240 launched products, the closest product by text is in the same subcategory for 211 of them (87.9%). The notebook asks you to measure this number.

Now the project’s content method gives each customer a list: the products closest to the profile, without the products that are not on sale. A customer with no events has no profile. They get the trending list, as with ALS.

The chart places each method by two measures on the test period. Up is recall@10. Right is coverage: the share of the products on sale that appear in at least one list.

Recall@10 and coverage on the test period (2,118 customers). Content shows the most products, but finds fewer orders than trending.
Text description of the chart

A scatter plot with coverage from 0 to 100% across and recall@10 from 0 to 0.2 up. Popular: coverage 0.3%, recall 0.106. Trending: coverage 0.3%, recall 0.156, the highest point. ALS: 33.0%, 0.142. Item-cf: 53.2%, 0.088. User-user: 54.2%, 0.145. Content, in another colour: coverage 84.1%, the point furthest to the right, recall 0.119.

Content has recall@10 0.119 (0.106 to 0.132): below trending (0.156) and ALS (0.142). But it shows 84.1% of the products on sale, more than any other method. Its novelty is 7.30 bits, the highest after random and lift: the products it shows are less known.

By segment, content has 0.151 for new customers, 0.085 for occasional customers and 0.102 for loyal ones. The new-customer number looks good, but be careful. 633 of the 952 new customers had no event at all, so they got the trending list.

And the launch? Content puts 182 of the 240 launched products in somebody’s list. History methods showed none. New products fill 6.2% of all places. But of the 665 orders of new products in the launch period, the lists contain only 1.5%. Content can show new products. It is bad at guessing which new product a person will buy. The next lesson works on that.

  1. In your larkfield-recs folder, with the virtual environment active, copy the content method:

    Terminal window
    S=../nextia-learning-labs/C37/snapshots/end-of-m06
    cp $S/larkfield_recs/methods/content.py larkfield_recs/methods/

    The project finds methods by file, so recs evaluate --list now shows a new line:

    content content-based: products with text close to the customer's products (embeddings)
  2. Show the closest products of the launched cool box by text:

    Terminal window
    recs similar P10117 --method content --n 5

    You see the five cool boxes above. Leave out --method content to get the neighbours by shared customers.

  3. Score content on the test period:

    Terminal window
    recs evaluate content --by segment
    Method content (content-based: products with text close to the customer's products (embeddings)), test period
    Customers scored: 2,118; trained on events before 2026-06-22
    recall@10 0.119 (95% interval 0.106 to 0.132), NDCG@10 0.088, MAP@10 0.071, precision@10 0.018, hit rate 15.3%
    coverage 84.1% of the products on sale, novelty 7.30 bits, diversity 0.59, new products in the lists 16.2%
    time: fit 0.0 s, suggestions 0.1 s
    segment customers recall@10 NDCG@10 95% interval (recall)
    new 952 0.151 0.103 0.131 to 0.173
    occasional 556 0.085 0.074 0.063 to 0.106
    loyal 610 0.102 0.076 0.080 to 0.123
    new products: 647 orders of new products in the period; recall@10 on them 0.164

    The fit takes no time: the vectors are already made. Each list is one multiplication of the profile with 2,994 vectors.

  4. Score it on the launch period, the first two weeks of the new range:

    Terminal window
    recs evaluate content --period launch
    Method content (content-based: products with text close to the customer's products (embeddings)), launch period (new range)
    Customers scored: 2,113; trained on events before 2026-05-01
    recall@10 0.112 (95% interval 0.100 to 0.125), NDCG@10 0.086, MAP@10 0.072, precision@10 0.016, hit rate 14.1%
    coverage 85.1% of the products on sale, novelty 7.45 bits, diversity 0.57, new products in the lists 6.2%
    time: fit 0.0 s, suggestions 0.1 s
  5. Run the tests with python -m pytest -q. You still see 20 passed: the tests of this module come in the last lesson, with the hybrids.

Change one thing: the product. The launched product P10122 is an “Arc Terracotta Pendant Light” in the subcategory Outdoor lights. Before you run it, predict: how many of its five closest products by text are also outdoor lights?

Terminal window
recs similar P10122 --method content --n 5
Show the answer
P10122 Arc Terracotta Pendant Light (Outdoor lights, 76.99 dollars)
1. P10259 0.933 Terracotta Metal Cage Pendant (Ceiling lights)
2. P10445 0.912 Hartley Terracotta Glass Schoolhouse Light (Ceiling lights)
3. P12451 0.912 Terracotta Ceramic Candle Lantern (Candles and scents)
4. P12000 0.909 Harbour Terracotta Coastal Table Lantern (Outdoor lights)
5. P12284 0.908 Sora Terracotta Glass Lantern Flush Light (Ceiling lights)

Only one: place 4. All five are terracotta lights or lanterns, but three hang inside the house and one is a candle lantern. The words “Terracotta” and “Pendant” decide more than the place where the light hangs. This is one of the 29 launched products whose closest product is in another subcategory. For a customer who wants a light for the garden, this list is close, but not right.

Use it where history is missing or thin:

  • New products, from their first day. This is the main reason for content at Larkfield.
  • Products with few buyers. Item-item neighbours of a product with three buyers are noise. Text neighbours are not.
  • “Similar products” on a product page, where a customer compares options. Text neighbours explain themselves: “another cool box”.

Do not use it alone for the home page. On the test period, it finds fewer orders than trending. Its lists are narrow (diversity 0.59): the closest products to a profile are often the same kind of product. It also knows nothing about what sells now: no season and no trend.

What it costs:

  • The vectors are made once, in seconds on a laptop, and stored in 2.3 MB. Scoring needs no training: fit takes 0.0 s, and the peak memory is 530 MB, mostly the shop log.
  • A new product needs its vector before it goes on sale. In a real shop, the catalogue system calls the model when somebody adds a product. That step needs the model itself (a download of several hundred megabytes). This course ships ready-made vectors, so it does not build that step.
  • The text decides everything. Poor or copied descriptions give poor neighbours. Ten titles in Larkfield’s catalogue are the same for different products, and colour words pull unrelated products together.

Common mistake

'Unknown method content'

Symptom: recs similar P10020 --method content or recs evaluate content stops with:

Unknown method 'content'. Methods: trending, popular-category, als, bpr, cooc, lift, item-cf, user-user, popular, random

Cause: the file larkfield_recs/methods/content.py is not in your project. The project finds each method by its file.

Fix: do step 1 of the guided practice, then run the command again.

Common mistake

Content looks great for new customers

Symptom: content has recall@10 0.151 for new customers, almost as good as trending (0.169). Tomás concludes that text understands new customers.

Cause: most new customers have no events at all, and the method gives them the trending list. Only the new customers who viewed something get a real content list.

Fix: before you credit a method, check which customers it really served. The next lesson measures the switch from popularity to personal lists by the number of events.

Check your understanding

A product was added to Larkfield this morning. Why can item-item collaborative filtering not suggest it, while content can?

Show the answer

Item-item collaborative filtering finds neighbours through customers who touched both products. A new product has no events, so its column in the matrix is empty: it has no neighbours and no score. Content uses only the product’s text. The text exists on the first day, so the product has a vector on the first day and can be compared with every other product. On the launch period, ALS and trending showed 0 of the 240 launched products, and content showed 182.

Check your understanding

In the tiny example, a customer ordered the cool bag (0.87, 0.49) and viewed the cushion (0.20, 0.98). Why is the cool box scored higher than the cushion for this customer?

Show the answer

The profile is the weighted sum of the vectors: 5 × the cool bag (an order) + 1 × the cushion (a view). That is (4.55, 3.43), or about (0.80, 0.60) at length 1. The order weighs five times more than the view, so the profile points close to the cool bag. The cool box points almost the same way as the cool bag. So its cosine with the profile is high: 0.95 × 0.80 + 0.31 × 0.60 = 0.95. The cushion gets 0.75.

Check your understanding

Content shows 84.1% of the products on sale, and trending only 0.3%. Should Larkfield replace trending with content on the home page? Use the test period numbers.

Show the answer

No, not alone. Content finds fewer orders: recall@10 0.119 against 0.156 for trending, and lower for occasional and loyal customers. Its lists are narrow (diversity 0.59), and it knows nothing about the season. Its strengths are coverage and new products: it puts 182 of the 240 launched products in somebody’s list. A better plan uses content where history is missing and combines it with other methods, which the next two lessons do.

Recap

  • Methods that learn from history show 0 of the 240 products launched on 1 May: a new product has no events.
  • An embedding is a list of numbers made from text by a language model; similar text gives close vectors. Larkfield’s 2,994 products have 384 numbers each, made once and shipped as a 2.3 MB file.
  • Cosine similarity of vectors of length 1: multiply the matching numbers and add. A customer’s profile is the weighted sum of the vectors of their products.
  • Text neighbours look like the product; customer neighbours are what the same people buy. Colour words can pull a bed close to an armchair.
  • On the test period, content has recall@10 0.119 and coverage 84.1%. On the launch period, it shows 182 launched products, but finds only 1.5% of the orders of new products.
  • Your project now has methods/content.py.

Content shows new products, but it does not know which ones people will buy, and it does nothing for a customer with no events. Next, you look at both kinds of cold start together.

Next: Cold start for new products and new customers