A Practical Guide to AI Embeddings — Beyond the Hype

// Two sentences with similar meaning
const embedding1 = await embed("How do I return a product?");
// → [0.023, -0.41, 0.87, 0.12, ... ] (1536 numbers)
 
const embedding2 = await embed("What's your return policy?");
// → [0.025, -0.39, 0.85, 0.14, ... ] (similar numbers!)
 
const embedding3 = await embed("The weather is nice today");
// → [-0.71, 0.33, -0.12, 0.56, ...] (very different numbers)
 
// Cosine similarity
cosineSimilarity(embedding1, embedding2); // 0.94 (very similar)
cosineSimilarity(embedding1, embedding3); // 0.11 (not related)

// ✗ Bad: fixed-size chunks that split sentences
function badChunking(text: string, size: number = 500): string[] {
  const chunks = [];
  for (let i = 0; i < text.length; i += size) {
    chunks.push(text.slice(i, i + size)); // Might cut mid-sentence
  }
  return chunks;
}
 
// ✓ Good: semantic chunking that respects document structure
function semanticChunking(markdown: string): Chunk[] {
  const chunks: Chunk[] = [];
  
  // Split by headers first (natural document boundaries)
  const sections = markdown.split(/\n#{1,3}\s/);
  
  for (const section of sections) {
    if (section.length < 200) {
      // Too small — merge with previous chunk
      if (chunks.length > 0) {
        chunks[chunks.length - 1].content += "\n" + section;
      }
    } else if (section.length > 1000) {
      // Too large — split by paragraphs
      const paragraphs = section.split(/\n\n/);
      let currentChunk = "";
      
      for (const para of paragraphs) {
        if ((currentChunk + para).length > 800) {
          chunks.push({ content: currentChunk.trim() });
          currentChunk = para;
        } else {
          currentChunk += "\n\n" + para;
        }
      }
      if (currentChunk.trim()) chunks.push({ content: currentChunk.trim() });
    } else {
      chunks.push({ content: section.trim() });
    }
  }
 
  return chunks;
}

function chunkWithOverlap(paragraphs: string[], targetSize: number = 600, overlap: number = 100): string[] {
  const chunks: string[] = [];
  let current = "";
 
  for (const para of paragraphs) {
    if ((current + para).length > targetSize && current.length > 0) {
      chunks.push(current);
      // Start next chunk with overlap from end of current
      current = current.slice(-overlap) + "\n\n" + para;
    } else {
      current += (current ? "\n\n" : "") + para;
    }
  }
  if (current) chunks.push(current);
  return chunks;
}

-- Enable the extension
CREATE EXTENSION IF NOT EXISTS vector;
 
-- Create table with vector column
CREATE TABLE documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content TEXT NOT NULL,
  embedding vector(1536),  -- Match your model's dimensions
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW()
);
 
-- Create index for fast similarity search
CREATE INDEX ON documents 
  USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);  -- Tune: sqrt(row_count) is a good starting point
 
-- Query: find similar documents
SELECT id, content, 1 - (embedding <=> $1::vector) AS similarity
FROM documents
WHERE metadata->>'category' = 'returns'  -- Filter first, then vector search
ORDER BY embedding <=> $1::vector
LIMIT 5;

// Complete embedding pipeline for a knowledge base
async function indexDocuments(documents: Document[]) {
  for (const doc of documents) {
    // 1. Chunk the document
    const chunks = semanticChunking(doc.content);
 
    // 2. Generate embeddings in batches
    const embeddings = await batchEmbed(chunks.map(c => c.content), {
      batchSize: 100,  // Most APIs accept batches
    });
 
    // 3. Store with metadata
    await vectorDB.upsert(
      chunks.map((chunk, i) => ({
        id: `${doc.id}-chunk-${i}`,
        embedding: embeddings[i],
        metadata: {
          documentId: doc.id,
          title: doc.title,
          chunkIndex: i,
          category: doc.category,
          updatedAt: doc.updatedAt,
        },
        content: chunk.content,
      }))
    );
  }
}
 
// Search with metadata filtering
async function search(query: string, filters?: SearchFilters) {
  const queryEmbedding = await embed(query);
 
  return vectorDB.search(queryEmbedding, {
    topK: 5,
    minScore: 0.7,  // Only return relevant results
    filter: filters ? buildFilter(filters) : undefined,
  });
}