Learn how to implement hybrid search in Laravel using BM25 + vector embeddings with re-ranking, relevance tuning, and safe index lifecycle management.
by Rizwan
When SaaS teams add vector search to improve relevance, they often replace a proven lexical engine with a semantic one. That works for fuzzy intent, but it can underperform on exact terms, product names, error codes, and documentation phrasing where BM25 shines.
A hybrid approach-BM25 plus vector embeddings-keeps lexical precision while adding semantic matching. The result is better query understanding, more stable ranking, and fewer “almost right” results that cost conversions.
In a typical SaaS search flow, users search for a feature, a setting name, or a troubleshooting phrase. Lexical scoring handles exact matches and close variants. Vector search handles meaning, synonyms, and paraphrases.
Hybrid search combines both signals, then applies re-ranking to refine ordering. This is where ranking quality becomes consistent across documentation, blog posts, and in-app knowledge base content.
| Capability | BM25 (lexical) | Vector embeddings (semantic) | Hybrid search (BM25 + vector + re-ranking) |
|---|---|---|---|
| Exact term matches (e.g., “rate limit exceeded”) | Strong | Variable | Strong |
| Synonyms and paraphrases (e.g., “throttle” vs “rate limit”) | Needs tuning | Strong | Strong |
| Query understanding | Limited to token overlap | Meaning-based | Meaning + token overlap |
| Relevance tuning | Field boosts, analyzers | Similarity thresholds, embedding model | Weights + re-ranking model |
| Ranking evaluation | Deterministic scoring | Distribution-based behavior | More robust across query types |
| API latency | Usually lower | Often higher | Higher than BM25 alone, but controllable with top-k + re-ranking |
Laravel search is commonly implemented via Laravel Scout with a backend such as Elasticsearch or OpenSearch. For teams that prefer a relational approach, pgvector can store embeddings in Postgres and still support hybrid strategies.
The best choice depends on your operational constraints, your existing stack, and your latency budget.
Use BM25-style lexical queries and vector similarity queries in the same search request. Then apply re-ranking using a second pass (either a script-based scoring blend or an external re-ranker service).
This is often the fastest path to production because the ecosystem already supports BM25-like scoring and vector search primitives.
With pgvector, you can store embeddings alongside content metadata and run vector similarity queries. For lexical matching, you can rely on Postgres full-text search or store additional fields for token-based matching.
Hybrid scoring is achievable, but you must design the query carefully to avoid slow scans and to keep API latency predictable.
This section focuses on a production-grade approach: keep indexing reliable, combine retrieval signals, and re-rank results for stable ordering.
Design fields so BM25 and vector search both have what they need. For BM25, include analyzed text fields (title, body, headings, tags). For vector search, store vector embeddings for the same logical content unit.
Key decision: embed the right granularity. For SaaS content, embed either the full page or structured chunks (e.g., sections). Chunking improves recall and reduces “one wrong paragraph dominates” issues.
Generate embeddings in a background job and store them in your search backend. Ensure the embedding model version is recorded with each document so you can re-index when you change models.
Common mistake: embedding only at creation time. If your content updates frequently, you need an index lifecycle strategy that re-embeds on updates and deletes embeddings for removed content.
Stage 1 retrieves a candidate set using hybrid retrieval. Stage 2 re-ranks candidates using a refined scoring function that blends lexical relevance, semantic similarity, and field-level signals.
Typical candidate sizes are small enough to control latency: retrieve top 50-200, then re-rank down to top 10-20 for the UI.
Hybrid search quality depends on weights. Start with a baseline blend: lexical score + semantic similarity. Then adjust weights per content type (docs vs blog vs in-app help) using ranking evaluation on a labeled query set.
Relevance tuning should include synonyms and query understanding. For example, “SSO” and “single sign-on” should map to the same intent even if the exact tokens differ.
Vector search handles many synonym cases, but it is not a substitute for explicit synonym handling in technical domains. Users search using product jargon, abbreviations, and error messages.
Use a synonym strategy that combines lexical expansion and semantic normalization.
Before vector search, normalize user queries: trim whitespace, standardize casing, and optionally expand known abbreviations. This improves query understanding and reduces embedding mismatch.
Do not over-normalize. If you remove critical tokens (like error codes), you will harm both lexical and semantic retrieval.
Hybrid search breaks quietly when your index drifts. The UI still returns results, but relevance degrades because vectors represent old content.
Index lifecycle is the difference between “it works in staging” and “it works every week.”
Add checks that compare content updated_at timestamps against index timestamps. If they diverge beyond a threshold, alert the team.
Common mistake: relying only on queue success. If a job fails after writing some fields, you can end up with partial documents that look indexed but rank poorly.
Retrieval returns candidates; re-ranking decides the final order. Without re-ranking, your blended score may not reflect user intent across different query types.
Re-ranking can be implemented as a second scoring pass using a more expressive function than the initial retrieval blend.
Build a small labeled dataset from actual search logs. Include queries where users click the correct result and queries where they bounce. Use it for ranking evaluation before and after changes.
Track metrics like click-through rate, zero-result rate, and “first result satisfaction” (did the user click the top result?).
Hybrid search adds work: two retrieval signals and possibly a re-ranking pass. You must manage API latency so search remains responsive.
Latency control is mostly about limiting candidate sizes and avoiding expensive operations on the full corpus.
Break down timing into lexical retrieval, vector retrieval, and re-ranking. This makes it clear whether you need fewer candidates, a faster embedding model, or a cheaper scoring function.
Teams often optimize the wrong stage because they only look at total response time.
If you embed entire pages, a single irrelevant section can dilute similarity. For docs and KB content, embed sections or chunks and store pointers to the parent page.
BM25 relevance depends on analyzers. If you treat code identifiers as stopwords or split them incorrectly, lexical scoring will underperform.
Vector similarity is powerful, but technical queries often require exact token matches. Start with balanced weights and tune with ranking evaluation.
If embeddings lag behind content updates, your hybrid search will “feel haunted.” Implement re-embedding on updates and monitor drift.
If you are building the broader search and indexing foundation in your Laravel SaaS, pair hybrid retrieval with solid crawl and indexing mechanics. For example, review Technical SEO Playbook for SaaS Dashboards: Indexing, Pagination & Crawl Budget for App Pages to ensure your content is discoverable, not just searchable.
For AI-driven operational workflows that keep search relevance fresh, connect your indexing pipeline to your SEO reporting automation using AI Automation for SEO Reporting: Self-Updating Looker Studio + Sheets Pipeline (GSC + GA4).
Finally, if you are exposing search results through an SEO-friendly Laravel API, align rendering strategy with crawler behavior using Build an SEO-Friendly Laravel API: SSR vs Prerender vs Edge Rendering for Crawlers.
Hybrid search is not a single feature toggle. It is a system: retrieval, re-ranking, relevance tuning, and index lifecycle working together to deliver ranking quality you can measure.
If you want SaaS search that ranks reliably across technical queries, product names, and paraphrased intent, implement hybrid search with BM25 + vector embeddings and a deliberate re-ranking step. It costs more than BM25 alone, but the relevance lift and ranking stability are worth it when you control candidate sizes and evaluate changes against real queries.
Ready to start your project? Let's work together to make it happen! Get in touch with us today and let's bring your ideas to life.
Get In Touch