Building Unravel: Learning RAG Through Visualization
Source: Dev.to
Introduction
When I started learning about Retrieval‑Augmented Generation (RAG), I quickly hit a wall. Not because of missing documentation or tutorials, but because I couldn’t see what was actually happening under the hood.
RAG systems are everywhere now:
- Chatbots that answer questions about your documentation
- Search engines that understand context
- Assistants that retrieve relevant information before generating responses
Understanding how they work—and the trade‑offs between different approaches—proved surprisingly difficult.
The Problem with Most RAG Tutorials
Typical tutorials follow this pattern:
- Install a vector database.
- Chunk your documents.
- Generate embeddings.
- Query the index.
The code runs, you get results, but crucial questions remain unanswered:
- Chunking – Why did my strategy return 15 chunks instead of 20?
- Overlap – How much overlap do my chunks have, and is that actually helping?
- Embedding space – What does it look like? Are similar documents clustering together?
- Semantic search – Why did it return these specific chunks for my query?
- Sparse vs. dense retrieval – How different are the results between BM25 and dense retrieval?
These aren’t academic curiosities. Each decision—chunk size, overlap percentage, embedding model, retrieval strategy—creates trade‑offs that affect accuracy, speed, and reliability. Yet most frameworks abstract these details away, leaving you to tune parameters without understanding their effects.
My Solution: Unravel
Instead of just implementing RAG pipelines, I built Unravel, a tool that visualizes every step of the pipeline in real‑time. As I learned each concept, I added it to the visualization. When I discovered a new retrieval strategy, I implemented it and compared it visually against the others.
What Unravel Shows
| Stage | Visualization | Key Insights |
|---|---|---|
| Document ingestion | PDF → structured elements (headers, paragraphs, tables, images) | See exactly what the RAG system sees; toggle OCR to make scanned text searchable. |
| Chunking | Cards for each chunk with metadata (token count, section breadcrumbs, source page, overlap) | Compare hierarchical vs. hybrid chunking side‑by‑side. |
| Embeddings | 3‑D UMAP projection, k‑means colour‑coding, outlier highlighting | Hover to preview a chunk; watch query vectors appear and connect to results. |
| Retrieval | BM25, dense, hybrid (weighted sum / reciprocal rank fusion), query expansion, cross‑encoder reranking | Compare similarity scores, source locations, and exact chunks returned. |
| Export | Production‑ready Python code with all settings baked in | Ready to integrate into your application. |
How Unravel Changed My Understanding
- Chunk overlap isn’t free – Overlap improves context continuity but increases storage, embedding cost, and retrieval noise. Visual overlap highlighting makes this trade‑off concrete.
- Embedding models behave differently – Some produce tight, well‑separated clusters; others generate diffuse, overlapping embeddings. The 3‑D view lets you pick the best model before running a single query.
- Hybrid retrieval isn’t always better – Dense retrieval shines on semantic nuance; BM25 excels on keyword‑heavy queries. Side‑by‑side visual comparison shows when each is appropriate.
- Local LLMs are viable – Running Ollama locally with Unravel proved you don’t need cloud APIs to build effective RAG pipelines; the performance gap is narrowing.
Who Is Unravel For?
- Learners who want to understand the mechanics of RAG, not just copy‑paste code.
- Experimenters comparing document parsing, embedding models, or retrieval strategies.
- Developers needing a quick way to prototype and export production‑ready pipelines.
All processing happens locally:
- Documents never leave your machine.
- Vectors are stored in a local Qdrant instance.
- You can choose cloud LLM APIs or local models via Ollama or LM Studio.
Future Roadmap
While Unravel currently focuses on education and experimentation, I envision it evolving into a comprehensive RAG evaluation platform. Planned extensions include:
- Systematic evaluation metrics – precision, recall, MRR, NDCG.
- Ground‑truth datasets and automated benchmarking.
- Performance profiling – latency, throughput, cost per query.
- Full‑stack RAG support – semantic cache, HyDE, advanced reranking, multi‑vector retrieval.
- Comparative analysis across embedding models, chunking strategies, and retrieval methods.
The goal: a single tool that helps you design, debug, evaluate, and deploy RAG systems with confidence.
Ready to see what’s really happening inside your RAG pipeline? Try Unravel today.
Unravel – Visualize, Test, and Optimize Retrieval‑Augmented Generation (RAG)
Unravel helps you not just understand RAG, but rigorously evaluate and optimize your implementation for production. It is open‑source and ready to use.
Installation
pip install unravel
unravelRunning unravel launches a web app in your browser.
What the App Does
The interface walks you through five steps:
- Document upload – add your own files or use the provided samples.
- Chunk visualization – see how documents are split into chunks.
- Embedding exploration – inspect vector representations and similarity.
- Query testing – run queries against the indexed data and view results.
- Code export – generate ready‑to‑run Python code for your pipeline.
Feel free to experiment with different configurations and watch how changes propagate through the entire pipeline.
Who Is This For?
- Learners – gain a clearer picture of RAG concepts and trade‑offs.
- Builders – make informed, evidence‑backed decisions rather than relying on guesswork.
The source code lives on GitHub, and contributions are welcome. I’d love to hear how you use Unravel!
Links
- GitHub:
- PyPI:
About the Author
A developer who learned RAG by building visualization tools and decided to share the journey.