Bulletproof RAG: Production Curriculum

Module 01: Introduction

Module 02: Naive RAG

Module 03: Data Engineering

Module 04: Query Intelligence

Module 05: Advanced Retrieval

Module 06: Agentic Architectures

Module 07: Evaluation

RAG Logging and Observability

HyDE: Hypothetical Document Embeddings

Mitigating the asymmetric query gap by generating a synthetic answer before performing vector searches.

HyDE (Hypothetical Document Embeddings) is a high-recall retrieval technique that solves the "Asymmetric Query Gap." In a standard RAG system, we compare a short user query (e.g., "What's the protocol?") to a long document chunk (e.g., a 1000-character technical spec). HyDE bridges this gap by first generating a hypothetical, synthetic answer and then using the vector of that answer to search for similar documents. We are essentially matching "document-to-document" rather than "query-to-document."

Engineering Trade-offs

Feature	Technical Impact
Pros	Dramatically improves recall for broad or conceptual queries; bypasses the keyword mismatch problem.
Cons	Double LLM latency (one to generate the HyDE, one to answer); synthetic answer might hallucinate, leading to an incorrect search vector.

Architecture Overview

The HyDE data flow converts a query into a rich, semantic search vector:

       [USER Query]
             │
     ┌───────▼───────┐
     │ HyDE Generator│ (LLM: "Write a technical answer for...")
     └───────┬───────┘
             │
    ┌────────▼────────┐
    │ Synthetic Spec  │ (A fake document snippet)
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Document Search │ (Vectorize Spec -> Find Real Matching Chunks)
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Valid Retrieval │ (Only the real content is used for the answer)
    └─────────────────┘

Implementation Walkthrough

The following steps trace the lifecycle of a query being transformed into a high-fidelity synthetic vector.

Synthetic Answer Generation

We use a high-temperature model (GPT-4o-mini) to generate a speculative response. This "fake" response contains the semantic keywords we expect to find in the real documents.

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
 
const userQuery = "What is the security model of Phoenix?";
const { text: hydeResponse } = await generateText({
  model: openai('gpt-4o-mini'),
  prompt: `Write a 1-paragraph technical specification that answers: "${userQuery}". Do not include warnings.`,
});
 
console.log(`[INFO] HyDE generated: ${hydeResponse.length} chars.`);

Synthetic-to-Real Retrieval

We vectorize the synthetic response and use it to perform a cosine similarity search against our actual knowledge base.

import { embed, cosineSimilarity } from 'ai';
 
const { embedding: syntheticVector } = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: hydeResponse,
});
 
// SEARCH: Using syntheticVector to find REAL documents in your vector store...
console.log(`[SYS] Search vector generated from hypothetical answer.`);

Complete Production Script

This script implements a full HyDE-enabled RAG pipeline to demonstrate high-recall retrieval.

import { generateText, embed, cosineSimilarity } from 'ai';
import { openai } from '@ai-sdk/openai';
import 'dotenv/config';
 
/**
 * HyDE (Hypothetical Document Embeddings) Pipeline.
 */
async function hydeSearch() {
  const logger = {
    info: (msg) => console.log(`[INFO]  ${new Date().toISOString()} | ${msg}`),
    timer: (label) => console.time(`[TIME]  ${label}`),
  };
 
  const userQuery = "Fault tolerance mechanism in Phoenix v2?";
  
  try {
    logger.info(`Source Query: "${userQuery}"`);
    
    // 1. Generate Hypothetical Answer
    logger.timer("hyde-gen");
    const { text: hydeDoc } = await generateText({
      model: openai('gpt-4o-mini'),
      prompt: `Please write a technical paragraph describing the ${userQuery}. Focus on architecture.`,
    });
    console.timeEnd("hyde-gen");
    logger.info("Synthetic document created for semantic matching.");
 
    // 2. Vectorize the Synthetic Doc
    const { embedding: hydeVector } = await embed({
      model: openai.embedding('text-embedding-3-small'),
      value: hydeDoc,
    });
 
    // 3. Retrieval and Grounding (Simulated store lookup)
    logger.info("Executing search using synthetic vector...");
    
    // In production, matching here using hydeVector instead of queryVector
    logger.info(`HyDE search size: ${hydeVector.length} dims.`);
    console.log(`\n--- HyDE RETRIEVAL SUCCESS ---\nSynthetic Doc Sample:\n"${hydeDoc.slice(0, 100)}..."\n-----------------------------\n`);
 
  } catch (error) {
    console.error(`[FATAL] Pipeline failed: ${error.message}`);
  }
}
 
hydeSearch();

Summary of Impact

Metric	Basic RAG Retrieval	HyDE-Enabled Retrieval
Search Space	Query Vector	Rich Document Vector
Recall (R@5)	Moderate (40-55%)	High (75-88%)
System Latency	Baseline (~2.5s)	Baseline + ~1.5s (Synthetic Generation)

When to Use This

When building RAG applications for non-technical users asking generic questions.
In low-recall scenarios where standard cosine similarity fails to find the right chunk.
For discovery-based retrieval systems where semantic clustering is more important than specific keywords.

Next PageAdvanced Reranking Logic

On This Page

Engineering Trade-offs Architecture Overview Implementation Walkthrough Complete Production Script Summary of Impact When to Use This

Connect with the Author

Have questions or suggestions? Feel free to reach out.

Feature

Technical Impact

Pros

Dramatically improves recall for broad or conceptual queries; bypasses the keyword mismatch problem.

Cons

Double LLM latency (one to generate the HyDE, one to answer); synthetic answer might hallucinate, leading to an incorrect search vector.

Architecture Overview

The HyDE data flow converts a query into a rich, semantic search vector:

       [USER Query]
             │
     ┌───────▼───────┐
     │ HyDE Generator│ (LLM: "Write a technical answer for...")
     └───────┬───────┘
             │
    ┌────────▼────────┐
    │ Synthetic Spec  │ (A fake document snippet)
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Document Search │ (Vectorize Spec -> Find Real Matching Chunks)
    └────────┬────────┘
             │
    ┌────────▼────────┐
    │ Valid Retrieval │ (Only the real content is used for the answer)
    └─────────────────┘

Implementation Walkthrough

The following steps trace the lifecycle of a query being transformed into a high-fidelity synthetic vector.

Synthetic Answer Generation

We use a high-temperature model (GPT-4o-mini) to generate a speculative response. This "fake" response contains the semantic keywords we expect to find in the real documents.

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
 
const userQuery = "What is the security model of Phoenix?";
const { text: hydeResponse } = await generateText({
  model: openai('gpt-4o-mini'),
  prompt: `Write a 1-paragraph technical specification that answers: "${userQuery}". Do not include warnings.`,
});
 
console.log(`[INFO] HyDE generated: ${hydeResponse.length} chars.`);

Synthetic-to-Real Retrieval

We vectorize the synthetic response and use it to perform a cosine similarity search against our actual knowledge base.

import { embed, cosineSimilarity } from 'ai';
 
const { embedding: syntheticVector } = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: hydeResponse,
});
 
// SEARCH: Using syntheticVector to find REAL documents in your vector store...
console.log(`[SYS] Search vector generated from hypothetical answer.`);

Complete Production Script

This script implements a full HyDE-enabled RAG pipeline to demonstrate high-recall retrieval.

import { generateText, embed, cosineSimilarity } from 'ai';
import { openai } from '@ai-sdk/openai';
import 'dotenv/config';
 
/**
 * HyDE (Hypothetical Document Embeddings) Pipeline.
 */
async function hydeSearch() {
  const logger = {
    info: (msg) => console.log(`[INFO]  ${new Date().toISOString()} | ${msg}`),
    timer: (label) => console.time(`[TIME]  ${label}`),
  };
 
  const userQuery = "Fault tolerance mechanism in Phoenix v2?";
  
  try {
    logger.info(`Source Query: "${userQuery}"`);
    
    // 1. Generate Hypothetical Answer
    logger.timer("hyde-gen");
    const { text: hydeDoc } = await generateText({
      model: openai('gpt-4o-mini'),
      prompt: `Please write a technical paragraph describing the ${userQuery}. Focus on architecture.`,
    });
    console.timeEnd("hyde-gen");
    logger.info("Synthetic document created for semantic matching.");
 
    // 2. Vectorize the Synthetic Doc
    const { embedding: hydeVector } = await embed({
      model: openai.embedding('text-embedding-3-small'),
      value: hydeDoc,
    });
 
    // 3. Retrieval and Grounding (Simulated store lookup)
    logger.info("Executing search using synthetic vector...");
    
    // In production, matching here using hydeVector instead of queryVector
    logger.info(`HyDE search size: ${hydeVector.length} dims.`);
    console.log(`\n--- HyDE RETRIEVAL SUCCESS ---\nSynthetic Doc Sample:\n"${hydeDoc.slice(0, 100)}..."\n-----------------------------\n`);
 
  } catch (error) {
    console.error(`[FATAL] Pipeline failed: ${error.message}`);
  }
}
 
hydeSearch();

Metric

Basic RAG Retrieval

HyDE-Enabled Retrieval

Search Space

Query Vector

Rich Document Vector

Recall (R@5)

Moderate (40-55%)

High (75-88%)

System Latency

Baseline (~2.5s)

Baseline + ~1.5s (Synthetic Generation)