RAG Sandbox: Understanding the Internal Mechanisms of Retrieval-Augmented Generation via Visual Interaction

RAG Sandbox is an interactive web application based on Streamlit, LangChain, and FAISS. It demonstrates the complete workflow of Retrieval-Augmented Generation (RAG) (from document chunking to vector retrieval to answer generation) via a real-time visual debugger, helping developers and learners gain an in-depth understanding of RAG's working principles and solve the hallucination, knowledge timeliness, and traceability issues faced by traditional large models.

RAG has become a key architectural pattern for modern large model applications, but many developers only understand it at the conceptual level. Traditional large models have three major pain points: hallucination (prone to generating incorrect content due to reliance on parameter memory), knowledge timeliness (inability to access the latest information), and lack of traceability. RAG Sandbox allows users to observe each link in the RAG pipeline step by step and adjust parameters in real time to see their impact through interactive visual tools.

RAG Sandbox divides the RAG process into two stages: indexing and retrieval-generation.

Indexing Phase

1. Document Loading: Preloaded datasets including NASA Artemis Moon Landing Program, Internet Development History, and Quantum Computing Basics
2. Text Chunking: Using a recursive character splitter (default ~200 characters)
3. Vector Embedding: Generating 1536-dimensional vectors via OpenAI models
4. Vector Storage: Storing vectors and original text using the FAISS library

Retrieval-Generation Phase

1. Query Embedding: Converting user questions into vectors using the same model
2. Similarity Search: Calculating L2 Euclidean distance to return Top-K similar chunks
3. Context Injection: Inserting retrieved content into the prompt template
4. LLM Synthesis: GPT-4o-mini generating answers based on context

The core features of RAG Sandbox include:

• Step Visualizer: Dynamically highlights workflow stages; click to view technical explanations
• Two-Mode Operation: Simulation mode (no API key needed to demo the workflow) and production mode (requires OpenAI key for real operations)
• Hyperparameter Control: Adjustable Chunk Size, Chunk Overlap (10%-20% recommended), and Top-K Chunks
• Technical Inspector: View details like original prompts and embedding configurations Parameter tuning requires tradeoffs: Chunk size (small for precise positioning vs large for context preservation), Top-K (high for more context vs low for conciseness and speed)

Core tech stack:

• Streamlit: Quickly build interactive web interfaces
• LangChain: Provides RAG components (document loading, splitting, embedding, vector storage)
• FAISS: Efficient similarity search library
• OpenAI API: Text embedding (text-embedding-ada-002, etc.) and generation (GPT-4o-mini) Installation steps: Clone the repository → Create a virtual environment → Install dependencies → Configure API key → Run streamlit run app.py (local port 8501)

Educational value: Preloaded multi-domain datasets and example questions; simulation mode has no API costs, making it suitable for learning. Practical significance: Helps developers diagnose configuration issues (chunking strategies, embedding models, retrieval quantity, etc.) and build reliable production systems.

RAG Sandbox turns RAG from a black box into a white box, demonstrating each link in the workflow and fostering the ability to understand principles. It is suitable for beginners to learn and engineers to optimize systems, emphasizing that understanding principles is more important than copying code.