RAG (Retrieval-Augmented Generation) is the backbone of modern AI applications — but setting it up properly requires stitching together embeddings, vector stores, text splitters, LLM providers, and streaming responses. Most tutorials show you how to do it in a Jupyter notebook or a 50-line Python script.

I wanted a production-ready, modular, TypeScript-first template that I could drop into any NestJS project. So I built easy-rag.

---

The Investigation: Vercel AI SDK vs LangChain.js

Before writing a single line of code, I spent a full SDD Explore phase comparing the two main orchestration libraries:

Aspect	Vercel AI SDK	LangChain.js
GitHub Stars	24,550 ⭐	17,734 ⭐
npm downloads/week	12.9M	4.2M
Providers	~30+ official	~15 official + community
Streaming	First-class	Functional but verbose
Vector stores	❌ Not native	✅ 20+ integrations
Document loaders	❌ Not native	✅ PDF, CSV, HTML, Markdown…
Text splitters	❌ Not native	✅ RecursiveCharacter, Token…
Retrievers	❌ Not native	✅ MultiQuery, ParentDocument…
Client ID	Functional, clean DX	Class-based, more verbose

The Hybrid Decision

Neither library won outright. Instead, I chose a hybrid architecture:

Vercel AI SDK (orchestration core)
    ├── generateText / streamText / embed
    ├── @ai-sdk/openai → DeepSeek (OpenAI-compatible API)
    ├── @ai-sdk/anthropic, @ai-sdk/google (extensible)
    └── @ai-sdk/langchain (official bridge)
          └── LangChain text splitters + document loaders

Why? AI SDK has 3x more downloads, better streaming, and a cleaner DX. LangChain has the mature RAG ecosystem (text splitters, document loaders, retrievers). The official @ai-sdk/langchain adapter lets you use both without friction.

---

Architecture

Design Decisions (6 ADRs)

ADR	Decision	Rationale
001	Vercel AI SDK as core	Streaming first-class, 30+ providers, clean DX
002	LangChain only for RAG components	Via @ai-sdk/langchain adapter
003	pgvector without ORM	Raw pg Pool, full control over vector queries
004	DeepSeek via OpenAI-compatible API	@ai-sdk/openai with custom baseURL
005	Modules by domain, not by layers	Clean Architecture, extractable packages
006	Zod for config validation	Shared peer dependency with AI SDK

Module Design

src/
├── config/          # Zod-validated env vars (13 vars)
├── ai/              # AiService (generateText, streamText, embed)
├── embeddings/      # EmbeddingsService (abstract + implementation)
├── vector-store/    # VectorStoreService (abstract + pgvector)
└── rag/             # RagService + IngestionService + RagController
    ├── ingestion/   # chunk → embed → store pipeline
    └── query/       # embed → search → context → stream

Data Flow

Ingestion:

POST /rag/ingest { content: "text..." }
  → RecursiveCharacterTextSplitter → [chunks]
  → EmbeddingsService.embed(chunk) → [vectors]
  → VectorStoreService.storeChunks() → { chunks: N, ids: [...] }

Query (streaming):

POST /rag/query { question: "What is X?" }
  → embed(question) → [vector]
  → similaritySearch(vector, topK) → context docs
  → buildPrompt(question, context)
  → AiService.streamText(prompt) → SSE stream

The SSE stream is sent as text/event-stream with data: {chunk}\n\n format. The client receives tokens in real-time as the LLM generates them.

---

Implementation Details

Vector Schema (pgvector)

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE embeddings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content TEXT NOT NULL,
  source TEXT,
  metadata JSONB DEFAULT '{}',
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_embeddings_vector
  ON embeddings USING ivfflat (embedding vector_cosine_ops);

Provider Abstraction

The AiService auto-detects which provider to use:

// DeepSeek (default, via OpenAI-compatible API)
const deepseek = createOpenAI({
  baseURL: 'https://api.deepseek.com/v1',
  apiKey: process.env.DEEPSEEK_API_KEY,
});

// Or OpenAI (set OPENAI_API_KEY env var)
const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

The client can switch providers simply by setting different environment variables. The @ai-sdk/openai package handles both DeepSeek and OpenAI through the same API surface.

---

Stats & Testing

• Test suites: 6 (config, ai, embeddings, vector-store, ingestion + e2e)
• Tests: 42 passing (32 unit + 10 e2e via supertest)
• E2E coverage: POST /rag/ingest, POST /rag/query (SSE), GET /api/health, 404 handling
• CI: GitHub Actions — builds and runs all tests on push/PR to main
• Source files: 28 TypeScript files
• Dependencies: 13 production + 13 development
• Build: tsup ESM, 16KB bundle

---

Try It

git clone https://github.com/fxckcode/easy-rag.git
cd easy-rag
pnpm install
docker compose up -d    # starts pgvector
cp .env.example .env    # set your DEEPSEEK_API_KEY
pnpm start:dev

Then test it:

# Ingest a document
curl -X POST http://localhost:3000/rag/ingest \
  -H "Content-Type: application/json" \
  -d '{"content": "NestJS is a framework for building efficient Node.js server-side applications.", "source": "docs"}'

# Query with streaming
curl -X POST http://localhost:3000/rag/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is NestJS?"}'

The project is MIT licensed and available on GitHub.

RAG (Retrieval-Augmented Generation) es la columna vertebral de las aplicaciones de IA modernas — pero configurarlo correctamente requiere unir embeddings, vector stores, text splitters, providers de LLM y respuestas en streaming. La mayoría de los tutoriales muestran cómo hacerlo en un Jupyter notebook o un script de Python de 50 líneas.

Yo quería un template listo para producción, modular y TypeScript-first que pudiera usar en cualquier proyecto NestJS. Así que construí easy-rag.

---

La Investigación: Vercel AI SDK vs LangChain.js

Antes de escribir una sola línea de código, pasé una fase completa de SDD Explore comparando las dos bibliotecas de orquestación principales:

Aspecto	Vercel AI SDK	LangChain.js
GitHub Stars	24,550 ⭐	17,734 ⭐
Descargas npm/semana	12.9M	4.2M
Providers	~30+ oficiales	~15 oficiales + comunidad
Streaming	Excelente	Funcional pero verboso
Vector stores	❌ No nativo	✅ 20+ integraciones
Document loaders	❌ No nativo	✅ PDF, CSV, HTML, Markdown…
Text splitters	❌ No nativo	✅ RecursiveCharacter, Token…
Retrievers	❌ No nativo	✅ MultiQuery, ParentDocument…

La Decisión Híbrida

Ninguna biblioteca ganó rotundamente. En su lugar, elegí una arquitectura híbrida:

Vercel AI SDK (orquestación principal)
    ├── generateText / streamText / embed
    ├── @ai-sdk/openai → DeepSeek (API compatible OpenAI)
    ├── @ai-sdk/anthropic, @ai-sdk/google (extensible)
    └── @ai-sdk/langchain (puente oficial)
          └── LangChain text splitters + document loaders

¿Por qué? AI SDK tiene 3x más descargas, mejor streaming y mejor DX. LangChain tiene el ecosistema RAG maduro (text splitters, document loaders, retrievers). El adapter oficial @ai-sdk/langchain permite usar ambos sin fricción.

---

Arquitectura

Decisiones de Diseño (6 ADRs)

ADR	Decisión	Razón
001	Vercel AI SDK como core	Streaming nativo, 30+ providers, DX limpio
002	LangChain solo para RAG	Via adapter @ai-sdk/langchain
003	pgvector sin ORM	pg Pool nativo, control total de queries vectoriales
004	DeepSeek via API compatible OpenAI	@ai-sdk/openai con baseURL custom
005	Módulos por dominio, no por capas	Clean Architecture, paquetes extraíbles
006	Zod para validación de config	Peer dependency compartida con AI SDK

Diseño de Módulos

src/
├── config/          # Env vars validadas con Zod (13 vars)
├── ai/              # AiService (generateText, streamText, embed)
├── embeddings/      # EmbeddingsService (abstracto + implementación)
├── vector-store/    # VectorStoreService (abstracto + pgvector)
└── rag/             # RagService + IngestionService + RagController
    ├── ingestion/   # Pipeline: chunk → embed → store
    └── query/       # Pipeline: embed → search → context → stream

Flujo de Datos

Ingestión:

POST /rag/ingest { content: "texto..." }
  → RecursiveCharacterTextSplitter → [chunks]
  → EmbeddingsService.embed(chunk) → [vectors]
  → VectorStoreService.storeChunks() → { chunks: N, ids: [...] }

Query (streaming):

POST /rag/query { question: "¿Qué es X?" }
  → embed(question) → [vector]
  → similaritySearch(vector, topK) → docs de contexto
  → buildPrompt(question, context)
  → AiService.streamText(prompt) → stream SSE

El stream SSE se envía como text/event-stream con formato data: {chunk}\n\n. El cliente recibe tokens en tiempo real mientras el LLM los genera.

---

Detalles de Implementación

Esquema Vectorial (pgvector)

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE embeddings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content TEXT NOT NULL,
  source TEXT,
  metadata JSONB DEFAULT '{}',
  embedding vector(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_embeddings_vector
  ON embeddings USING ivfflat (embedding vector_cosine_ops);

Abstracción de Providers

AiService detecta automáticamente qué provider usar:

// DeepSeek (default, via API compatible OpenAI)
const deepseek = createOpenAI({
  baseURL: 'https://api.deepseek.com/v1',
  apiKey: process.env.DEEPSEEK_API_KEY,
});

// O OpenAI (setear OPENAI_API_KEY)
const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

El cliente puede cambiar de provider simplemente cambiando variables de entorno.

---

Stats & Testing

• Suites de test: 6 (config, ai, embeddings, vector-store, ingestion + e2e)
• Tests: 42 pasando (32 unit + 10 e2e via supertest)
• Cobertura E2E: POST /rag/ingest, POST /rag/query (SSE), GET /api/health, manejo 404
• CI: GitHub Actions — build y tests en push/PR a main
• Archivos fuente: 28 archivos TypeScript
• Dependencias: 13 producción + 13 desarrollo
• Build: tsup ESM

---

Probarlo

git clone https://github.com/fxckcode/easy-rag.git
cd easy-rag
pnpm install
docker compose up -d    # inicia pgvector
cp .env.example .env    # configurar DEEPSEEK_API_KEY
pnpm start:dev

# Ingestionar un documento
curl -X POST http://localhost:3000/rag/ingest \
  -H "Content-Type: application/json" \
  -d '{"content": "NestJS es un framework para construir aplicaciones Node.js del lado del servidor.", "source": "docs"}'

# Query con streaming
curl -X POST http://localhost:3000/rag/query \
  -H "Content-Type: application/json" \
  -d '{"question": "¿Qué es NestJS?"}'

El proyecto tiene licencia MIT y está disponible en GitHub.