Módulo 5: Hybrid Search — combinando keyword + semantic para queries que necesitan ambas

Descripción del módulo

Hasta ahora todo tu retrieval depende de embeddings y cosine similarity. Funciona muy bien para queries semánticas — preguntas sobre conceptos, parafraseadas con palabras distintas a las del documento, en distintos idiomas. Pero hay una clase de queries donde semantic search falla sistemáticamente: queries que requieren match exacto de tokens específicos.

"¿cómo configuro OAuth2PasswordBearer con scopes personalizados?" "error code: ERR_NETWORK_TIMEOUT_504" "diferencia entre pd.merge y pd.concat"

Estas queries tienen identificadores exactos (nombres de clases, códigos de error, funciones específicas) que el usuario sabe y quiere encontrar literalmente. Los embeddings parafrasean — OAuth2PasswordBearer y "dependency de OAuth2 con username/password" terminan cerca en el espacio vectorial. Para queries conceptuales eso es genial. Para queries con identificadores exactos, es la diferencia entre encontrar el documento correcto o uno que solo "habla del tema".

Hybrid search resuelve este problema combinando dos métodos en paralelo: BM25 (keyword search clásico, que prioriza match exacto) + semantic search (embeddings, que prioriza significado), fusionando los rankings con técnicas como Reciprocal Rank Fusion (RRF). El resultado: precision +15-18% y recall +10-15% sobre semantic-only, especialmente en contenido técnico.

Este módulo te enseña a implementar hybrid search desde cero, calibrar el balance entre keyword y semantic con tu dataset específico, y reconocer cuándo hybrid search se justifica vs cuándo semantic puro alcanza.

Al finalizar este módulo serás capaz de:

✅ Identificar las queries donde semantic search falla y BM25 gana
✅ Implementar BM25 sobre tu corpus con rank_bm25 o Elasticsearch
✅ Combinar rankings de BM25 + semantic con Reciprocal Rank Fusion
✅ Tunear el balance entre los dos métodos con peso α (weighted hybrid)
✅ Decidir cuándo hybrid search agrega valor vs cuándo es complejidad innecesaria
✅ Construir un motor de hybrid search production-ready con métricas de A/B testing

Tiempo estimado del módulo: 2-3 horas (8 cápsulas).

Por qué hybrid search existe: las queries que rompen semantic search

Vamos a hacer el problema concreto. Tres queries reales y qué pasa con cada método:

Query 1 — semántica pura

"¿cómo manejo autenticación de usuarios?"

Método	Top result	¿Bueno?
Semantic (cosine)	"FastAPI authentication tutorial: OAuth2 flows, JWT tokens, password hashing..."	✅ Match perfecto
BM25 (keyword)	"Manejo de autenticación: principios básicos..." (más vago)	🟡 Match decente pero genérico

Para queries semánticas, semantic gana. El usuario quiere conceptos, los embeddings los entienden bien.

Query 2 — identificador exacto

"¿cómo uso OAuth2PasswordBearer?"

Método	Top result	¿Bueno?
Semantic (cosine)	"Para autenticación con username/password en FastAPI usar la dependency adecuada..." (cosine 0.85)	❌ Parafrasea. No menciona `OAuth2PasswordBearer` literal
BM25	"OAuth2PasswordBearer is the FastAPI security class for password flow. Import from..."	✅ Match exacto del identificador

Para queries con identificadores, BM25 gana. Semantic search "normalizó" OAuth2PasswordBearer a un concepto similar pero perdió la especificidad.

Query 3 — error code

"error: ERR_NETWORK_TIMEOUT_504"

Método	Top result	¿Bueno?
Semantic	"Network errors and how to handle timeouts in production..." (genérico)	❌ No hay match del código específico
BM25	"Troubleshooting ERR_NETWORK_TIMEOUT_504: this error indicates..."	✅ Encuentra exactamente la guía

Para errores y códigos, BM25 es esencial. Embeddings los tratan como "palabras raras" sin significado, BM25 los busca literalmente.

El insight: ninguno gana siempre

                Semantic (cosine)    BM25 (keyword)
─────────────────────────────────────────────────────
Queries conceptuales:      ✅ gana            🟡 OK
Queries con paráfrasis:    ✅ gana            ❌ falla
Queries cross-language:    ✅ gana            ❌ falla
Queries con identificadores: ❌ pierde         ✅ gana
Queries con códigos:       ❌ falla            ✅ gana
Queries de exact-match:    ❌ falla            ✅ gana

Hybrid search corre los dos en paralelo y combina rankings. Cuando semantic gana, sus resultados dominan. Cuando BM25 gana, los suyos. Cuando los dos están de acuerdo (caso óptimo), refuerzan el ranking del documento correcto.

El stack técnico del hybrid search

                    Query
                     │
        ┌────────────┴────────────┐
        │                         │
        ▼                         ▼
┌───────────────┐        ┌───────────────────┐
│ BM25          │        │ Semantic search   │
│ (keyword)     │        │ (cosine)          │
│               │        │                   │
│ rank_bm25 o   │        │ ChromaDB,         │
│ Elasticsearch │        │ Pinecone, etc.    │
│               │        │                   │
│ Top-K BM25    │        │ Top-K semantic    │
└───────┬───────┘        └─────────┬─────────┘
        │                          │
        └──────────────┬───────────┘
                       │
                       ▼
              ┌──────────────────┐
              │ Fusion (RRF / α) │
              │ Combina rankings │
              └────────┬─────────┘
                       │
                       ▼
              Top-K híbrido final

Los componentes:

BM25 — algoritmo clásico de keyword search. Variante moderna del TF-IDF, considera frecuencia de términos y rareza global. Implementación: rank_bm25 en Python (in-memory, simple) o Elasticsearch (production scale).
Semantic search — el que ya tienes. Cosine similarity sobre embeddings.
Fusion — cómo combinar dos rankings:
- RRF (Reciprocal Rank Fusion): combina rankings ignorando scores absolutos. Default razonable.
- Weighted (α blending): pondera los scores de ambos con un parámetro α. Más control, requiere calibración.

Roadmap del módulo

Cápsula	Tema	Por qué importa	Tiempo
01 (estás acá)	Introducción al módulo	Por qué hybrid search existe y panorama del módulo	10-15 min
02	Limitaciones de semantic-only	Cuándo y por qué falla cosine similarity con keywords exactos	25-30 min
03	BM25 keyword search	Cómo funciona BM25, implementación con `rank_bm25`	30-35 min
04	Reciprocal Rank Fusion (RRF)	Combinar rankings sin tunear pesos	25-30 min
05	Weighted hybrid blending (α)	Tunear el balance keyword vs semantic	30-35 min
06	Elasticsearch integration	BM25 a escala con Elasticsearch	30-35 min
07	Comparación de strategies	Decision framework: cuándo cada técnica	25-30 min
08	Proyecto integrador	Hybrid Search Engine con A/B testing	45-60 min

Total estimado: 3-4 horas. Es un módulo intensivo en código — vale la pena hacerlo en 2-3 sesiones.

Mejora esperada con hybrid search

Sobre datasets con queries mixtas (semánticas + identificadores), benchmarks típicos:

Strategy	Precision@5	Recall@50	Latency p95	Cuándo usarlo
Semantic only	87%	72%	200ms	Queries conceptuales puras (raro en producción)
BM25 only	81%	65%	50ms	Queries exact-match puras (raro en producción)
Hybrid (RRF)	94%	84%	240ms	Default para contenido técnico
Hybrid + reranking	96%	86%	400ms	Casos críticos

Lectura clave:

Hybrid no es "promedio" de los dos — es mejor que ambos por separado.
La latencia extra es ~40ms (BM25 es muy rápido).
Recall sube notablemente — recuperas docs que ningún método individual encontraba.

Cuándo SÍ usar hybrid search

Caso	¿Hybrid?
Documentación técnica con nombres de clases/funciones	✅ Sí
Buscador de error codes / messages	✅ Sí
Catálogo de productos con SKUs / códigos	✅ Sí
Soporte multilingüe con identificadores exactos	✅ Sí
Code search (Stack Overflow, GitHub)	✅ Sí
Preguntas conceptuales puras (humanidades, filosofía)	❌ No, semantic alcanza
Corpus narrativo (literatura, periodismo)	❌ No, semantic alcanza
MVP donde aún no mides problemas con keywords	❌ No, agregar después si hace falta

Default razonable: si tu corpus tiene cualquier contenido técnico (código, errores, IDs, nombres específicos), hybrid search vale la complejidad extra.

Conexión con módulos previos y siguientes

Módulos previos relevantes:
  ├─ Módulo 1: Pipeline RAG completo
  │   └─ Hybrid search se inserta acá, en la fase de retrieval
  ├─ Módulo 2: Chunking strategies
  │   └─ El chunking afecta cómo BM25 indexa keywords
  ├─ Módulo 3: Query optimization
  │   └─ Query expansion + hybrid search se complementan
  └─ Módulo 4: Re-ranking
      └─ Hybrid + re-ranking es el patrón "estado del arte"

Este módulo prepara para:
  ├─ Módulo 6: Metadata filtering
  │   └─ Combinar hybrid + filters por metadata = retrieval avanzado
  ├─ Módulo 7: Production con Pinecone
  │   └─ Pinecone soporta hybrid search nativo
  └─ Módulo 8: RAG evaluation
      └─ Cómo medir si hybrid está mejorando vs solo agrega complejidad

Patrón "estado del arte" RAG production-ready (mayo 2026):

Query
  ↓
Query optimization (expansion, rewriting) [M03]
  ↓
Hybrid search (BM25 + semantic + RRF) [este módulo]
  ↓
Metadata filtering [M06]
  ↓
Re-ranking (cross-encoder o Cohere) [M04]
  ↓
LLM generation

Cada componente agrega 5-15% de precision. Combinados, el sistema pasa de "MVP funcional" (precision 75%) a "producción seria" (precision 94%+).

Pre-requisitos antes de empezar el módulo

Asegúrate de tener:

✅ Pipeline RAG funcional con cosine retrieval (M01)
✅ Re-ranking implementado (M04) — hybrid + rerank es el patrón completo
✅ Eval set propio con al menos 50 queries con ground truth, idealmente con categoría asignada
✅ ChromaDB o vector DB con embeddings ya generados
✅ Python 3.10+ con pip install rank-bm25

Si tu eval set no diferencia "queries con identificadores" de "queries semánticas", constrúyelo antes — sin esa segmentación, no vas a poder medir si BM25 está aportando donde debe.

Setup técnico para el módulo

# Cápsulas 03-05 (rank_bm25 in-memory)
pip install rank-bm25

# Cápsula 06 (Elasticsearch, opcional para escala)
pip install elasticsearch

# Para Docker local de Elasticsearch
# Crear docker-compose.yml según cápsula 06

Variables de entorno:

# .env
OPENAI_API_KEY=sk-...
# Si usas ES en cápsula 06:
ES_HOST=http://localhost:9200

Auto-verificación antes de avanzar

Antes de empezar la cápsula 02, asegúrate de poder responder:

¿Por qué semantic search falla con queries que tienen identificadores exactos como OAuth2PasswordBearer?
¿Qué hace fusion (RRF o weighted) en hybrid search?
¿Cuándo NO conviene agregar hybrid search a un sistema RAG existente?

Respuestas

Los embeddings normalizan paráfrasis. OAuth2PasswordBearer y "dependency de OAuth2 con username/password" terminan en regiones cercanas del espacio vectorial — el modelo "entiende" que son lo mismo. Para queries conceptuales eso es genial, pero cuando el usuario sabe el nombre exacto y quiere encontrar ese identificador específico, la normalización trabaja en contra. BM25, que prioriza match exacto de tokens, encuentra literalmente la mención del identificador.
Fusion combina dos rankings (uno de BM25, uno de semantic) en un ranking unificado. RRF lo hace ignorando los scores absolutos (porque BM25 y semantic tienen escalas distintas que no son comparables) — solo mira la posición de cada documento en cada ranking. Weighted blending sí mira los scores pero requiere normalizarlos y tunear un parámetro α (peso entre los dos métodos).
Cuando tu corpus es puramente conceptual (literatura, filosofía, narrativa) y los identificadores exactos no son parte del dominio. Agregar hybrid en ese caso es complejidad innecesaria — semantic alcanza. Cuando estás en MVP y todavía no mediste problemas concretos con keywords. Agregar componentes preventivamente sin datos lleva a sistemas sobre-ingeniados.

Próximo paso: Cápsula 02

La siguiente cápsula profundiza en las limitaciones de semantic-only. Vas a ver más casos donde cosine similarity falla concretamente, con benchmarks sobre datasets reales. Es la justificación pedagógica completa del módulo — sin entender por qué semantic falla en estos casos, las cápsulas técnicas que vienen después suenan a "agregar complejidad porque sí".

Recursos

BM25 — The Probabilistic Relevance Framework (Robertson & Zaragoza) — Paper foundational sobre BM25
Reciprocal Rank Fusion (Cormack et al., 2009) — Paper original de RRF
Pinecone — Hybrid Search Guide — Overview accesible
Elasticsearch — Hybrid Search — Documentación oficial
rank_bm25 Python Library — Implementación in-memory simple
Anthropic — Contextual Retrieval — Técnica complementaria a hybrid search

Tiempo estimado: 10-15 minutos Siguiente: 02-limitations-of-semantic-only-search.md

Notas finales

Este módulo asume que vas a integrar hybrid search en un pipeline RAG existente. Si recién estás construyendo tu primer RAG, considera empezar por M01 (pipeline básico) antes de agregar hybrid — la complejidad extra solo se justifica cuando el problema "queries con identificadores fallan" es medible en tu producto.

El patrón final que vas a tener al cerrar el módulo es: semantic + BM25 → RRF → cross-encoder rerank → LLM. Es la arquitectura "estado del arte" para RAG production en mayo 2026, validada por equipos como Anthropic, OpenAI, Pinecone y los principales proveedores de RAG-as-a-service.

← AnteriorCápsula 08: Proyecto integrador — sistema de re-ranking con A/B testing Siguiente →Cápsula 02: Por qué semantic search solo no alcanza — los modos de falla concretos