Overview
FastRAG is a production-ready RAG (Retrieval-Augmented Generation) starter kit built with Next.js, LangChain, Pinecone, Claude Haiku, and Voyage AI embeddings. It eliminates 40+ hours of boilerplate — vector ingestion pipelines, streaming responses, context window management, and a mobile-ready chat UI — so you can focus on building your actual product.
Prerequisites
You need four API keys. All services have generous free tiers — you can run FastRAG at zero cost during development.
ANTHROPIC_API_KEYRequiredPowers Claude Haiku streaming chat. Get your key from console.anthropic.com — requires a payment method but Haiku is very affordable.
Get keyVOYAGEAI_API_KEYRequiredVoyage AI is Anthropic's recommended embeddings provider. voyage-3.5 gives you 200M free tokens — roughly 400,000 document pages at no cost.
Get keyPINECONE_API_KEYRequiredVector database for storing and querying embeddings. The free Starter plan supports 1 index and up to 100K vectors — sufficient for most projects.
Get keyInstallation
Clone or unzip the project
If you have GitHub repo access (included with all purchases):
git clone fastrag.git
cd fastragInstall dependencies
npm installnpm install --legacy-peer-deps — common due to LangChain's rapid release cadence.Environment Setup
Rename .env.example to .env.local and fill in your four keys:
# Anthropic Claude — console.anthropic.com
ANTHROPIC_API_KEY=sk-ant-...
# Voyage AI embeddings — dash.voyageai.com
VOYAGEAI_API_KEY=pa-...
# Pinecone vector DB — app.pinecone.io
PINECONE_API_KEY=pcsk_...
# Must match the index name you create in Pinecone (case-sensitive)
PINECONE_INDEX=fast-ragANTHROPIC_API_KEYPowers Claude Haiku for streaming chat. Add a payment method at console.anthropic.com — Haiku costs fractions of a cent per message.
VOYAGEAI_API_KEYPowers voyage-3.5 embeddings for both ingestion and retrieval. First 200M tokens are free.
PINECONE_API_KEYUsed to upsert vectors during ingestion and query them during chat.
PINECONE_INDEXMust exactly match the index name in Pinecone — case-sensitive. "fast-rag" ≠ "Fast-RAG".
Pinecone Setup
Go to app.pinecone.io and sign in
Click "Create Index"
Use these exact settings:
Click Create — wait ~30 seconds for the index to initialise
voyage-3.5 model outputs 1024-dimensional vectors natively. This is the correct dimension — no forcing or truncation required. It also keeps Pinecone storage costs lower than 1536-dim alternatives.Running Locally
npm run devOpen http://localhost:3000 in your browser.
Architecture
FastRAG is a standard two-phase RAG pipeline. Ingestion happens once per document; retrieval and generation happen on every chat message.
Ingestion (once per document)
Retrieval (every message)
Three Next.js API routes handle everything:
pages/api/ingest-pdf.jsMultipart PDF upload, text extraction, chunking, Voyage AI embedding, Pinecone upsertpages/api/ingest-url.jsCheerio web scraping, content extraction, chunking, embedding, Pinecone upsertpages/api/chat.jsVoyage AI query embedding, Pinecone similarity search, Claude Haiku SSE streamingpages/api/demo-status.jsReturns current IP-based usage counters and reset timestamp for the demo UIPDF Ingestion
Handled by pages/api/ingest-pdf.js. Accepts a single PDF up to 20MB via multipart form upload.
Upload Parsing Formidable handles the multipart upload and writes the file to a temp path on the server filesystem.
Text Extraction pdf-parse reads the buffer and extracts all raw text, page by page.
Chunking RecursiveCharacterTextSplitter cuts text into 1000-character chunks with 200-character overlap. Overlap preserves sentence context across chunk boundaries.
Embedding embedBatch() sends all chunks to Voyage AI voyage-3.5 with inputType: "document". LangChain handles batch splitting automatically.
Storage Vectors are upserted to Pinecone under the specified namespace (default: "demo"). Each vector carries source filename and chunkIndex as metadata.
Cleanup The temp file is deleted from disk immediately after processing. Returns { chunksIngested, totalCharacters, source } to the frontend.
URL Ingestion
Handled by pages/api/ingest-url.js. No headless browser required — Cheerio runs natively in Node.js with zero ESM conflicts on Vercel.
Fetch A standard fetch() call with a 15-second timeout retrieves the raw HTML. User-Agent is set to avoid basic bot blocking.
Parse & Clean Cheerio loads the HTML and removes script, style, nav, footer, header, noscript, and iframe elements.
Semantic Targeting Content is extracted preferentially from <main>, <article>, or [role="main"] before falling back to <body> — ensuring clean signal over boilerplate.
Text Normalisation Whitespace is collapsed, excessive newlines are trimmed, and the result is validated for minimum length (50 chars).
Chunk → Embed → Store The same chunking → Voyage AI embedding → Pinecone upsert pipeline as PDF ingestion. Source URL is stored as metadata for citations.
Chat & Retrieval
Handled by pages/api/chat.js. Every user message triggers a full retrieval cycle before Claude is called.
Rate Limit Check IP is extracted from x-forwarded-for headers. incrementUsage() checks and increments the message counter — returns 429 with resetAt if over limit.
Query Embedding The user's message is embedded using Voyage AI voyage-3.5 with inputType: "query" — a separate embedder instance optimised for asymmetric retrieval.
Pinecone Query Top-5 matching chunks are retrieved via similarity search. Matches below a 0.3 cosine score threshold are filtered out.
First SSE Event Before streaming begins, a JSON event is written containing sources[], hasContext flag, and current usage counters — so the UI can render citations and update meters immediately.
System Prompt Retrieved chunks are joined and injected into Claude's system prompt inside <context> tags. If no chunks pass the threshold, Claude is instructed to say so rather than hallucinate.
Claude Haiku Stream anthropic.messages.stream() streams response deltas as SSE text_delta events. The final event carries done: true and token usage stats.
Frontend
The demo UI lives in pages/demo.js with components in components/. A two-column layout: left panel for ingestion, right panel for chat.
Deploy to Vercel
FastRAG is optimised for Vercel. No special configuration needed — deployment takes about 5 minutes.
Push your code to GitHub
git init && git add .
git commit -m "initial"
git remote add origin https://github.com/you/fastrag.git
git push -u origin mainImport to Vercel
Go to vercel.com/new, import your GitHub repo, and select Next.js as the framework preset.
Add environment variables
In Vercel project → Settings → Environment Variables, add all four keys:
ANTHROPIC_API_KEYVOYAGEAI_API_KEYPINECONE_API_KEYPINECONE_INDEXClick Deploy — live in ~2 minutes
Troubleshooting
Click any error to expand the cause and fix.