Super Agent Stack
DocsHome
New

Hybrid Search

Combines vector semantic search with BM25 keyword search for the best of both worlds.

Overview

Hybrid search combines two powerful search techniques: vector semantic search (finds conceptually similar content) and BM25 keyword search (finds exact term matches). This gives you accurate results whether users search with specific terms or general concepts.

Search Modes

vector

Semantic similarity search using embeddings.

Best for: Conceptual queries, natural language

keyword

BM25 keyword matching algorithm.

Best for: Exact terms, technical names

hybrid ⭐

Combines both with configurable weights.

Best for: General use, balanced results

Basic Usage

hybrid-search.ts
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://www.superagentstack.com/api/v1',
  apiKey: process.env.OPENROUTER_KEY,
  defaultHeaders: { 'superAgentKey': process.env.SUPER_AGENT_KEY },
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'How do I configure webpack?' }],
  useRAG: true,
  searchMode: 'hybrid',     // 'vector' | 'keyword' | 'hybrid'
  keywordWeight: 0.3,       // Weight for keyword search (0-1)
});

Parameters

ParameterTypeDefaultDescription
searchModestring"vector""vector" | "keyword" | "hybrid"
keywordWeightnumber0.3Weight for keyword results in hybrid mode (0-1)

Weight Configuration

In hybrid mode, keywordWeight: 0.3 means 30% keyword + 70% vector. Increase for more exact matching, decrease for more semantic matching.

When to Use Each Mode

Use Vector Search When:

  • Users ask questions in natural language
  • Searching for conceptually similar content
  • The exact wording doesn't matter
typescript
// "How do I make my app faster?" finds docs about "performance optimization"
searchMode: 'vector'

Use Keyword Search When:

  • Searching for specific technical terms
  • Looking for exact function/class names
  • Users know exactly what they're looking for
typescript
// "useEffect" finds docs containing exactly "useEffect"
searchMode: 'keyword'

Use Hybrid Search When:

  • You want the best of both worlds
  • Users might use either approach
  • Building general-purpose search
typescript
// Finds both exact matches AND conceptually related content
searchMode: 'hybrid',
keywordWeight: 0.3

Examples

Technical Documentation Search

tech-docs-search.ts
// Higher keyword weight for technical docs
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'What is the useState hook?' }],
  useRAG: true,
  searchMode: 'hybrid',
  keywordWeight: 0.5,  // 50% keyword for exact term matching
});

Customer Support Search

support-search.ts
// Lower keyword weight for natural language queries
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'My order hasn\'t arrived yet' }],
  useRAG: true,
  searchMode: 'hybrid',
  keywordWeight: 0.2,  // 20% keyword, 80% semantic
});

How Hybrid Search Works

  1. Query is sent to both vector and BM25 search engines
  2. Vector search returns semantically similar results with scores
  3. BM25 search returns keyword-matched results with scores
  4. Scores are normalized and combined using the weight formula
  5. Results are re-ranked by combined score
  6. Top results are returned to the AI for context
text
Combined Score = (1 - keywordWeight) × vectorScore + keywordWeight × keywordScore

Example with keywordWeight = 0.3:
Combined = 0.7 × vectorScore + 0.3 × keywordScore