Why this series exists
Large language models are astonishing — until you ask them about your data. Ask a chatbot about your company’s refund policy and it will invent one, confidently and fluently. That gap — between a model that writes beautifully and a model that actually knows your facts — is where most real-world AI projects live or die.
The technique that bridges it is RAG — Retrieval-Augmented Generation. In one sentence: before you ask the model to answer, go fetch the relevant information from your own documents and hand it over, so the answer comes from your data instead of the model’s imagination.
This series teaches RAG the way it actually sticks — by building it, layer by layer, in plain PHP and MySQL 8. No frameworks doing the magic for you, no vector-database subscription, no exotic infrastructure. Just the language and database you almost certainly already have, and the honest understanding of every moving part.
Who this is for
You’ll feel right at home if you:
- Write PHP comfortably and know your way around MySQL.
- Have maybe called an AI API once or twice, but have never built a RAG system.
- Want to understand what’s happening, not just paste in a library and hope.
You do not need any machine-learning background, any math beyond multiplication, or any prior experience with embeddings or vector search. Every AI term is explained the moment it appears. If you’ve never heard the words “embedding,” “vector,” or “token,” that’s exactly who this series is written for.
What you’ll have built by the end
Two working projects that share almost all their code — because the whole point is that RAG is a reusable pattern, not a one-off trick.
1. Nimbus HelpDesk AI — a customer support bot. It answers questions strictly from a company’s real knowledge base (FAQs, policies, help articles), cites the source of every answer, and honestly says “I don’t know — here’s how to reach a human” when the answer isn’t in its documents. By the finale it’s evaluated, guardrailed, and running in a browser.
2. A Local News Assistant (bonus). The same skeleton pointed at live data — pulling fresh articles from an open news API and answering questions about today’s news with recency-aware, multi-source citations.
Two very different bots, one shared engine. Build the first and the second is mostly configuration.
The roadmap
Eight core episodes take you from concept to a deployed bot, and two bonus posts prove the pattern transfers to live data. Work through them in order — each one builds on the last.
| # | Episode | What it covers |
|---|---|---|
| 1 | What Is RAG, and Why Should You Care? | The problem, the two-phase architecture, and your first grounded answer. |
| 2 | Preparing the Knowledge Base: Loading & Chunking Your Docs | Loading documents (Markdown + PDF) and splitting them into searchable chunks. |
| 3 | Embeddings & Your First Similarity Search | Turning text into meaning-vectors and matching by meaning, not keywords. |
| 4 | Scaling the Vector Search in MySQL | Pushing the similarity math into the database so it scales. |
| 5 | Retrieval: Top-K, Thresholds & Filtering | Returning the right chunks — and nothing when there aren’t any. |
| 6 | Generation: Grounded Answers with Citations | The full loop: grounded, cited answers, and a graceful “I don’t know.” |
| 7 | Improving Quality: Hybrid Search, Reranking & Guardrails | Handling exact terms, and defending against prompt injection. |
| 8 | Evaluating & Shipping | Measuring answer quality, watching cost, and deploying with a web UI. |
| Bonus 1 | Local News RAG: Pointing the Pattern at Live Data | Aim the same skeleton at a live news API — freshness, dedup, ingestion. |
| Bonus 2 | Local News RAG: Recency-Aware Answers & Multi-Source Citations | Recency-aware generation, multi-article citations, and edge cases. |
Before you start: prerequisites
A quick checklist to have ready. Don’t worry about the AI parts — we set those up as we go.
- PHP 8.0+ with cURL enabled (
php -vto check). We use plain PHP — no framework required. - MySQL 8.0+ (
SELECT VERSION();). Everything runs on stock MySQL 8 — no MySQL 9, no plugins, no cloud vector service. - Composer — PHP’s package manager, for one small PDF library in Episode 2. (getcomposer.org)
- An OpenAI API key — for embeddings and answer generation. You’ll add a little credit; the whole series costs cents to run.
- A free GNews API key (only for the bonus) — grab it later when you reach Bonus 1.
- A code editor and a terminal. That’s it.
💡 On cost: building this series end to end uses fractions of a cent per question. Embeddings are cheap and computed once; a few dollars of API credit covers everything with room to spare.
⚠️ On “MySQL 8 only”: you may read that MySQL 9 added a native
VECTORtype. You don’t need it — the function that actually compares vectors isn’t available in standard MySQL 9 anyway, so we build a solution that works perfectly on the MySQL 8 you already have. More on that in Episode 4.
How to read this series
- Build along. Reading about RAG and building RAG are different experiences. Keep a terminal open.
- Don’t skip the “Try it yourself” boxes. Breaking things on purpose — bad chunk sizes, wrong thresholds, missing guardrails — teaches more than any explanation.
- Trust the order. Each episode’s checkpoint is the next episode’s starting point.
Ready? Let’s start with the question everything else depends on: what is RAG, and why should you care? That’s Episode 1.