Leveling the Playing Field: Building a 100% Offline Kubernetes Docs RAG Exam Assistant with Web AI, Gemma 4, and WebGPU
How to enable fair, zero-cost, air-gapped AI assistance in technical classrooms and assessments — running entirely in the browser on everyday student hardware.

The Classroom & Exam Dilemma: How Can We Use AI Fairly?
As educators teaching cloud-native technologies like Kubernetes, we want our assessments to reflect real-world DevOps workflows. In production, engineers don’t memorize every nested field of a Kubernetes YAML manifest — they consult official documentation and use AI assistants to troubleshoot and scaffold configurations.
However, allowing AI in a live classroom test or practical exam immediately introduces three critical pain points:
- The “Pay-to-Win” Equity Gap: Students with paid subscriptions to frontier cloud models (ChatGPT Plus, Claude Pro, Gemini Advanced) gain a massive speed and reasoning advantage over peers relying on free tiers with strict rate limits.
- Internet Access & Academic Integrity: Opening internet access so students can reach cloud AI APIs also opens the door to messaging apps, file-sharing sites, and unauthorized collaboration.
- Cloud API Costs & Data Privacy: Provisioning a centralized school-hosted LLM proxy for hundreds of concurrent exam-takers is expensive, vulnerable to rate-limit bottlenecks when everyone hits “Submit” at the same minute, and raises student privacy concerns.
What if every student’s computer could run an identical, pinned, official-documentation-grounded AI assistant completely offline?
In this article, we’ll walk through the architecture and implementation of Kubernetes WebAI RAG — an open-source, 100% offline Retrieval-Augmented Generation (RAG) system running entirely inside the browser using Gemma 4 E2B, EmbeddingGemma, LiteRT-LM, TensorFlow.js, and WebGPU.
https://medium.com/media/20d1c5f68aadab894d27095275f8dae3/hrefhttps://medium.com/media/74a7213c2a5fb8e8d7bae9fe600461e8/href
Evolving from VectorSearch.js to a Production-Ready Local RAG
This project builds upon Jason Mayes’ VectorSearch.js, which pioneered client-side vector similarity search in the browser using TensorFlow.js and WebGPU.
To transform a general-purpose browser vector search demo into an exam-ready Kubernetes Q&A system, we re-engineered the workflow around a core principle: Prepare once on the maintainer’s machine; run identically and offline on every student’s browser.
Key architectural upgrades in kubernetes-webai-rag include:
- Zero Startup Indexing: Instead of scraping or embedding documents in the student’s browser (which would take hours) or importing massive payloads into IndexedDB on page load, the maintainer prebuilds a normalized 16,483-chunk float32 vector matrix (768 dimensions) alongside a BM25 inverted keyword index.
- Hybrid Search with Reciprocal Rank Fusion (RRF): Combines semantic understanding (EmbeddingGemma) with exact Kubernetes terminology matching (BM25), grouping by headings and enforcing page diversity.
- Bundled Local Documentation Mirror: Strips external scripts, rewrites links, and mirrors the entire readable Kubernetes documentation snapshot locally so students can verify every [1], [2] citation side-by-side.
- On-Device Generation with Gemma 4 E2B & LiteRT-LM: Streams grounded answers and YAML manifests directly from the student’s GPU, backed by atomic Origin Private File System (OPFS) model caching.
Hardware Reality Check: Running on Everyday Student Laptops & Integrated GPUs
A common misconception is that local LLMs require high-end workstations with dedicated NVIDIA RTX GPUs. In a university lab or BYOD (Bring Your Own Device) classroom, students use standard Windows 11 laptops — often running on integrated GPUs (iGPUs) like Intel Iris Xe / Arc or AMD Radeon Graphics.
Because our architecture uses quantized models (4-bit ONNX EmbeddingGemma 300M for query embedding and Gemma 4 E2B (~2.01 GB) via LiteRT-LM + WebGPU), it runs smoothly on commodity student hardware:
- Disk Space: ~8 GiB free disk space (covering the downloaded archives, extracted ~2.4 GiB offline site, and ~2 GB browser OPFS cache).
- Browser Requirement: Any modern Chromium-based browser (Chrome or Edge) on Windows 11 x64 with hardware WebGPU enabled (chrome://gpu).
- Context & Memory Discipline: To prevent out-of-memory (OOM) crashes or sluggishness on integrated GPUs, OfflineAnswerGenerator.js creates a fresh native conversation per turn, caps the grounded prompt at 6,000 UTF-8 bytes within an 8,192-token engine context, and bounds output to 512 tokens. Old retrieved passages never accumulate in GPU memory across turns.
💡 Pro Tip for Exam Day: Students can verify hardware acceleration in seconds before the exam starts — generate one test answer, click a citation, refresh the page to confirm the OPFS disk cache loads instantly, and unplug the Ethernet/Wi-Fi!
Zero-Config Local Deployment & Student Startup Flow
Asking students to install Python, Node.js, npm, or configure SSL certificates before an exam is a recipe for classroom chaos.
To make deployment foolproof on Windows 11, scripts/package-windows.py bundles the unmodified Python 3.14.4 Windows x64 embeddable runtime alongside the prebuilt app and splits the release into <2 GiB ZIP archives (respecting GitHub Release asset limits) verified by SHA-256 checksums.
- Before the Exam (With Internet or via USB): Students download and run Setup-RAG.cmd (or copy the extracted folder from a classroom USB drive / LAN share). The script uses built-in Windows curl.exe, tar.exe, and PowerShell SHA256 verification without requiring Administrator privileges or altering PowerShell execution policies.
- During the Exam (100% Offline): Students double-click Start-RAG.cmd.
- Fixed Origin for Cache Preservation: windows/serve.py starts a lightweight ThreadingHTTPServer strictly bound to http://127.0.0.1:8080 and opens http://localhost:8080/kubernetes.html.
Why is port 8080 strictly enforced instead of falling back to a random port? Because browser OPFS storage is scoped to the exact origin (scheme + hostname + port). By keeping localhost:8080 constant, the 2 GB Gemma 4 model cached in the browser’s OPFS remains immediately accessible across browser refreshes!
Inside the Student Workspace: Grounded Q&A, Side-by-Side Docs & YAML Generation
Once http://localhost:8080/kubernetes.html opens, the interface presents a clean two-panel workspace (web/kubernetes.html):
1. Concept Retrieval & Real-Time Streaming
When a student asks a question (e.g., “What is a Pod in Kubernetes and how do I create a Deployment?”), the app:
- Embeds only the question (plus up to 2 recent user questions for follow-up context) on-device using EmbeddingGemma.
- Searches all 16,483 prebuilt chunks in milliseconds using WebGPU matrix multiplication and BM25 keyword search.
- Streams a grounded explanation from Gemma 4 E2B with inline citations like [1], [2].
2. Side-by-Side Technical Documentation Verification
AI models can hallucinate — so in an educational or exam setting, students must be able to verify answers against primary sources.
- Every turn snapshots its own retrieved sources in web/js/kubernetes.js (so an older turn’s [1] is never overwritten by a newer turn’s [1]).
- Clicking any [1] citation badge in the answer—or clicking View sources—immediately opens the exact local Kubernetes documentation page and scrolls directly to the heading anchor inside the right-hand sandboxed
3. YAML Manifest Generation & One-Click Copy
When students ask for practical configurations or kubectl commands, Gemma 4 generates clean YAML blocks. web/js/answer-citations.js renders the Markdown using locally bundled markdown-it and automatically injects a toolbar with language labels and a one-click Copy code button (with automatic text-selection fallback), allowing students to copy manifests straight into their local test cluster or exam editor.
4. Instant Reset & Clean Shutdown
- New Chat: Clicking New chat clears the conversation transcript in memory without unloading the WebGPU models — ready for the next exam problem in zero seconds.
- Browser Refresh (F5): Wipes the in-memory chat history, reinitializes the GPU, and reloads Gemma 4 straight from the browser’s OPFS disk cache without re-downloading from the Python server.
- Shutting Down: Pressing Ctrl+C in the terminal window stops the static Python server cleanly.
Deep Dive: System Architecture & Data Flow
To understand how kubernetes-webai-rag achieves fast, reliable offline performance, let’s examine its two-phase architecture.
Phase 1: Offline Preparation & Distribution Pipeline (Maintainer Side)

Rather than forcing student laptops to parse HTML and compute thousands of embeddings, the course maintainer runs the build pipeline once:
- Heading-Aware Chunking & Checkpointed CPU Embedding (scripts/build-kubernetes.mjs):
- Downloads the Kubernetes print view (https://kubernetes.io/docs/_print/) and English sitemap.
- Splits documentation by semantic headings into 16,483 chunks (512 max tokens with 64-token overlap) and resolves canonical URLs and heading anchors.
- Runs onnx-community/embeddinggemma-300m-ONNX (q4) to compute 768-dimensional embeddings, normalizes every vector to unit length, and writes a flat binary Float32 matrix (vectors-
.f32) plus BM25 postings (keywords- .json).
2. Sanitized Local Documentation Mirror (scripts/prepare-offline.mjs):
- Verifies that the HTML snapshot SHA-256 matches the indexed corpus.
- Strips all