How to Build a Content-Based Recommendation System: A Practical Guide With Python Code

Content-Based vs Collaborative vs Hybrid Recommendations

How a Content-Based Recommender Works

1. 1. Represent Each Item. Turn each item's content into a vector: TF-IDF weights for words, embeddings from a language or image model, plus encoded categories, tags and numeric attributes.
2. 2. Build a User Profile. Combine the vectors of items the user viewed, saved or bought, weighting stronger signals (purchase over view) and recent actions more heavily.
3. 3. Measure Similarity. Compare the user profile, or the item being viewed, with all candidate items, usually with cosine similarity.
4. 4. Rank and Filter. Take the top matches, remove items already seen or out of stock, and apply rules such as availability, region or price range.
5. 5. Serve and Learn. Show recommendations, log clicks and conversions, and use that feedback to tune weights or move to a hybrid model.

Item-to-Item vs User-Profile Recommendations

Build a Content-Based Recommender in Python, Step by Step

The example below recommends products, but the same code works for articles, jobs, courses or properties. It uses pandas and scikit-learn (pip install pandas scikit-learn).

1. Step 1: Prepare Item Data. Put one row per item with an ID and the fields that describe it: title, category, tags and description. Clean the text (remove HTML, fix duplicates) and fill missing values; poor metadata is the most common reason content-based recommendations look random.
2. Step 2: Turn Items Into Vectors. Combine the text fields and convert them to TF-IDF vectors, which weight words that are frequent in one item but rare across the catalogue.
3. Step 3: Find Similar Items. Compare one item's vector with all others using cosine similarity and return the closest matches.
4. Step 4: Build User Profiles. Average the vectors of items a user interacted with, giving stronger actions such as purchases more weight than views.
5. Step 5: Rank, Filter and Serve. Remove items the user already has, apply business rules and return the top results through an API.

import numpy as np
import pandas as pd
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity

# 1. Item data: one row per item
items = pd.DataFrame({
    "item_id": [1, 2, 3, 4, 5],
    "title": ["Trail running shoes", "Road running shoes", "Waterproof hiking boots",
              "Lightweight running jacket", "Yoga mat"],
    "category": ["shoes", "shoes", "boots", "apparel", "fitness"],
    "description": [
        "Grippy trail shoes with rock plate for off-road running",
        "Cushioned road shoes for daily running and marathons",
        "Leather hiking boots, waterproof, ankle support for trails",
        "Breathable, packable jacket for running in wind and rain",
        "Non-slip mat for yoga and home workouts",
    ],
})

# 2. Turn each item into a vector (title + category + description)
items["text"] = items["title"] + " " + items["category"] + " " + items["description"]
vectorizer = TfidfVectorizer(stop_words="english", ngram_range=(1, 2))
item_vectors = vectorizer.fit_transform(items["text"])

# 3. "More like this": items similar to one item
def similar_items(item_id, top_n=3):
    idx = items.index[items["item_id"] == item_id][0]
    scores = cosine_similarity(item_vectors[idx], item_vectors).ravel()
    scores[idx] = -1  # don't recommend the item itself
    best = np.argsort(scores)[::-1][:top_n]
    return items.iloc[best][["item_id", "title"]].assign(score=scores[best].round(3))

# 4 and 5. "For you": a weighted user profile, then rank and filter
def recommend_for_user(interactions, top_n=3):
    # interactions: {item_id: weight}, e.g. view=1, add to cart=3, purchase=5
    idx = [items.index[items["item_id"] == i][0] for i in interactions]
    weights = np.array(list(interactions.values()), dtype=float)
    profile = np.asarray(item_vectors[idx].T.dot(weights) / weights.sum()).reshape(1, -1)
    scores = cosine_similarity(profile, item_vectors).ravel()
    scores[idx] = -1  # hide items the user already has
    best = np.argsort(scores)[::-1][:top_n]
    return items.iloc[best][["item_id", "title"]].assign(score=scores[best].round(3))

print(similar_items(1))                  # road running shoes ranks first
print(recommend_for_user({1: 5, 4: 1}))  # bought trail shoes, viewed a jacket

TF-IDF only matches exact words, so “trail” and “trails” or “sneakers” and “running shoes” look unrelated. That is why most teams now move to embeddings.

Upgrade to Embeddings for Better Results

Text embeddings place items with similar meaning close together even when they use different words, and multimodal models such as CLIP can compare product images too. Swap the TF-IDF step for an embedding model (pip install sentence-transformers):

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")  # small, fast, runs on CPU
item_vectors = model.encode(items["text"].tolist(), normalize_embeddings=True)

# With normalised vectors, cosine similarity is a dot product
scores = item_vectors @ item_vectors[0]  # similarity to item 1

For large catalogues, store the vectors in a vector index and query the nearest neighbours instead of comparing every item. With PostgreSQL and pgvector:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE items (id bigint PRIMARY KEY, title text, embedding vector(384));
CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

-- 10 items most similar to item 42
SELECT id, title, 1 - (embedding <=> (SELECT embedding FROM items WHERE id = 42)) AS score
FROM items
WHERE id <> 42
ORDER BY embedding <=> (SELECT embedding FROM items WHERE id = 42)
LIMIT 10;

Choosing How to Represent Items

How to Evaluate Your Recommender

Test offline first by hiding each user's most recent interactions and checking whether the system recommends them, then confirm with an A/B test against your current experience (for example “most popular”).

Common Problems and How to Fix Them

Recommendations Are Too Similar

Add diversity re-ranking such as maximal marginal relevance, mix in popular or trending items, and limit how many items come from one category or brand.

New Users Have No History

Ask for interests during onboarding, use the current session or search query, and fall back to popular items in the user's region.

Poor Item Metadata

Enrich listings with consistent categories and tags; an LLM can generate structured attributes and summaries from messy descriptions.

Some Features Matter More Than Others

Weight fields separately (for example title higher than description) or learn the weights from click data.

Stale or Unavailable Items

Filter by stock, date, location and eligibility at query time, not when vectors are built.

Slow Responses at Scale

Precompute item-to-item neighbours, use approximate nearest-neighbour indexes and cache results for popular items.

Scaling to Millions of Items

Adding LLMs to Content-Based Recommendations

Better item understanding

use an LLM to extract attributes, tags and summaries from long descriptions before embedding them.

Natural-language requests

let users ask for “a waterproof jacket like this but cheaper” and turn the request into a vector search plus filters.

Explanations

generate short, honest reasons such as “because you read three articles on EV batteries”.

Keep the LLM out of the hot path

for speed and cost, use it offline or for re-ranking a short list, not for scoring the whole catalogue.

Where Content-Based Recommendations Work Best

How Much Does It Cost to Build a Recommendation System?

Running costs are usually modest: embedding a catalogue of 100,000 items with an open-source model costs little more than a few hours of compute, and a managed vector database typically costs from $50 to a few hundred dollars a month at that size.

Related Reading

• AI development company
• AI integration services
• Generative AI development services
• Ecommerce app development cost
• AI MVP development