How to Build a Production RAG System with Cloudflare Workers

Most RAG tutorials show you a working demo and call it done. You copy the code, it runs locally, and then you try to put it in production and everything falls apart.

This tutorial is different. I run a production RAG system (vectorize-mcp-worker) that handles real traffic at a total cost of $5/month. The alternatives I evaluated ranged from $100–$200/month. The difference isn’t magic. It’s architecture.

What You Will Build

By the end of this tutorial, you’ll have a globally deployed RAG API that:

• Accepts a natural language question via HTTP
• Converts it to a vector embedding using Workers AI
• Searches a knowledge base stored in Cloudflare Vectorize
• Passes the retrieved context to an LLM (also on Workers AI) to generate an answer
• Returns a grounded, accurate response (not a hallucination)

Prerequisites

This is an intermediate-level tutorial. You should be comfortable with:

• JavaScript/TypeScript: async/await, promises, basic types
• HTTP APIs: REST, request/response, JSON
• Command line basics: running npm commands, navigating directories

How RAG Works

Before you write any code, you’ll need a clear mental model of what you’re building. This section explains the three core components of a RAG system, how data flows between them, and why this architecture works at scale.

The Mental Model

Think of a traditional LLM like a doctor who studied medicine for years but has been in a remote cabin with no internet since their graduation day. They are brilliant, but they only know what they knew when they left. Ask them about a drug approved last year and they’ll either say they don’t know or – worse – confidently give you wrong information.

RAG gives that doctor access to an up-to-date medical library. Before answering your question, they can look up the relevant pages, read them, and use that information to give you an accurate answer. Their training still matters (that is, they know how to read and interpret the information), but they’re no longer limited to what they memorized years ago.

The Three Components

Every RAG system has three moving parts. Understanding each one will help you debug problems and make better architectural decisions as you build.

The Embedding Model

An embedding model converts text into a vector – an array of numbers that represents the meaning of that text. The model you will use in this tutorial, @cf/baai/bge-base-en-v1.5, outputs 768 numbers for any piece of text you give it.

The critical property of embeddings is that semantically similar text produces numerically similar vectors. “How do I install Node.js?” and “What’s the process for setting up Node?” will produce vectors that are close together. “How do I install Node.js?” and “What is the capital of France?” will produce vectors that are far apart.

The Vector Database

The vector database stores your embeddings and lets you search them by similarity. In this tutorial, you’ll use Cloudflare Vectorize.

When you run a similarity search, you pass in a query vector and Vectorize returns the K most similar vectors it has stored, along with their metadata and similarity scores. This is called approximate nearest neighbor search, and Vectorize is optimized to do it fast even across millions of vectors.

The Language Model

The LLM is responsible for one thing: reading the retrieved context and generating a natural language answer. It doesn’t search anything. It doesn’t decide what’s relevant. It just reads what you give it and writes a response.

How to Set Up Your Project

This section explains how to set up your project, including installing the necessary dependencies and configuring your Cloudflare account.

How to Build the Data Pipeline

This section explains how to build the data pipeline, including how to create and store your knowledge base in Cloudflare Vectorize.

How to Build the Query Pipeline

This section explains how to build the query pipeline, including how to embed the user’s question and search the knowledge base using Cloudflare Vectorize.

How to Add Error Handling and Security

This section explains how to add error handling and security to your RAG system, including how to handle errors and protect against attacks.

Performance and Cost Analysis

This section explains how to analyze the performance and cost of your RAG system, including how to measure latency and cost.

Conclusion

In this tutorial, you’ve learned how to build a production RAG system with Cloudflare Workers. You’ve seen how to set up your project, build the data pipeline, build the query pipeline, add error handling and security, and analyze performance and cost.

With this knowledge, you can build your own RAG system and start answering user questions in a grounded and accurate way.