RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa
by Vespa
The RAG tutorial that teaches ranking — phased retrieval, recall evaluation, and a trained first-phase ranker.
Overview
The RAG Blueprint is Vespa's reference tutorial for production-grade retrieval-augmented generation, and it opens by stating plainly what it is not: 'not a Deploy RAG in 5 minutes tutorial.' It works a single use case end to end — a synthetic corpus of roughly 100 company documents carrying markdown text plus structured signals such as timestamps and engagement metrics — and uses it to teach the design decisions that separate a demo from a system. The sections run: data modelling, covering how to pick your searchable unit, chunk selection, using multiple text fields and considering multiple embeddings, and modelling metadata and signals as structured fields; LLM generation through an OpenAI-compatible client; structuring the Vespa application using query profiles, with separate hybrid, rag and deepresearch profiles and separated rank profiles; Vespa's phased ranking model; configuring the match phase for retrieval, covering the choice between vector, text and hybrid strategies, embedding model selection, binary vectors for recall, float-binary for ranking, and recall evaluation broken out for semantic, weakAnd and hybrid queries, followed by retrieval tuning; first-phase ranking, including collecting training data and fitting a logistic-regression ranking model; second-phase ranking; and an optional global-phase ranking stage. The stack is Vespa itself with the Vespa CLI, the pyvespa Python client, scikit-learn for the ranking model, and Docker or Podman for local deployment. Companion code ships in the vespa-engine/sample-apps repository alongside forty-plus other reference applications.
At a Glance
- Topic
- RAG
- Level
- Advanced
- Format
- Tutorial
- Cost
- Free
- Duration
- ~4-6 hours hands-on, self-paced — explicitly not a 'RAG in 5 minutes' quickstart
- Provider
- Vespa
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Choose a searchable unit and chunking strategy before writing any retrieval code
- ✓Model timestamps and engagement signals as structured fields that ranking can actually use
- ✓Configure Vespa's match, first, second and optional global ranking phases as one pipeline
- ✓Measure retrieval recall separately for semantic, weakAnd and hybrid query formulations
- ✓Apply binary vector quantization for recall and float-binary rescoring for ranking precision
- ✓Collect training features and fit a logistic-regression first-phase ranking model
- ✓Separate hybrid, rag and deepresearch behaviour into distinct reusable query profiles
Highlights
- •Explicitly refuses the five-minute framing and teaches ranking, which most RAG tutorials skip entirely
- •One of the few public walkthroughs that trains a learned first-phase ranker end to end
- •Treats recall evaluation as a first-class step rather than an afterthought bolted on later
- •Backed by runnable code in vespa-engine/sample-apps, alongside 40+ other reference applications
- •Written by the engine's own team, so retrieval and ranking advice matches production defaults
Who It’s For
Best For
- ✓Engineers whose RAG prototype works in demos but ranks badly on a real corpus
- ✓Search engineers moving from BM25-only or vector-only retrieval to hybrid pipelines
- ✓Teams evaluating Vespa against Elasticsearch, Qdrant or a pgvector-based stack
Prerequisites
- •Comfort with Python and running containers via Docker or Podman
- •Working understanding of embeddings, BM25 scoring and vector similarity search
- •Basic machine-learning literacy — the tutorial fits a ranking model with scikit-learn
FAQ
What is RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa?
A production-grade RAG reference tutorial from the Vespa team that deliberately refuses the five-minute quickstart framing. It walks one synthetic corpus through data modelling, hybrid retrieval, recall evaluation and Vespa's full phased ranking pipeline, including collecting features and training a first-phase ranking model. For engineers whose RAG prototype demos well but ranks badly on real data, it covers the missing half of the problem: after working through it you can design chunking, retrieval strategy and multi-phase ranking as one deliberate system rather than a stack of defaults.
Is RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa free?
RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa is free to access.
What level is RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa for?
RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa is aimed at a advanced audience. Recommended background: Comfort with Python and running containers via Docker or Podman, Working understanding of embeddings, BM25 scoring and vector similarity search, Basic machine-learning literacy — the tutorial fits a ranking model with scikit-learn.
How long does RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa take?
Expect roughly ~4-6 hours hands-on, self-paced — explicitly not a 'RAG in 5 minutes' quickstart. Most learners work through it at their own pace.
What will I learn from RAG Blueprint — Production-Grade Retrieval and Ranking with Vespa?
You'll learn: Choose a searchable unit and chunking strategy before writing any retrieval code; Model timestamps and engagement signals as structured fields that ranking can actually use; Configure Vespa's match, first, second and optional global ranking phases as one pipeline; Measure retrieval recall separately for semantic, weakAnd and hybrid query formulations; Apply binary vector quantization for recall and float-binary rescoring for ranking precision; Collect training features and fit a logistic-regression first-phase ranking model; Separate hybrid, rag and deepresearch behaviour into distinct reusable query profiles.
Topics
Sources
This page was written from 2 sources, 1 on domains other than docs.vespa.ai.