Nevis Search API: Practical Exploration of Building Enterprise-Grade Hybrid Search Systems

The nevis-search-api project open-sourced by the Nevis WealthTech team demonstrates the architecture of an AI-driven enterprise-grade hybrid search system. This article deeply analyzes its core design philosophy, technology selection (hexagonal architecture, pgvector semantic search, RRF ranking algorithm), and engineering implementation, addressing the problem that traditional search in fintech scenarios struggles to balance precision and semantic understanding.

Modern wealth management platform search faces unique challenges: users query investment product information using professional terms, vague descriptions, or natural language. Pure text matching easily misses semantically relevant content, while pure vector search ignores key business rule constraints. Therefore, the Nevis team built a hybrid search solution that balances precise matching and semantic understanding.

The project adopts hexagonal architecture, whose core idea is to place business logic at the center and decouple it from external systems through ports and adapters. The domain layer focuses on core rules such as search intent and ranking strategy, without caring about data sources; the infrastructure layer is responsible for technical implementation (e.g., vector database access, API serialization). This design supports independent evolution of components—adding a new vector database in the future only requires adding an adapter.

pgvector (a PostgreSQL extension) is chosen as the semantic search engine to avoid the operational complexity of introducing an additional vector database. Semantic search converts text into dense vectors based on pre-trained models; during queries, text is encoded into vectors and similarity is calculated. pgvector supports metrics like cosine similarity and Euclidean distance, and provides IVFFlat and HNSW indexes to accelerate large-scale retrieval.

The key to hybrid search lies in fusing results from different channels. The project uses the RRF algorithm: each result is assigned a score based on its rank in each recall channel (1/(k + constant)), then re-ranked after accumulation. Its advantages are no need for training, strong robustness, and simple implementation. In Nevis, two typical channels are fused: traditional text matching (e.g., BM25) and vector similarity, balancing precision and flexibility.

Engineering practice focuses on innovation and stability: using the PostgreSQL ecosystem to lower operational thresholds, hexagonal architecture to ensure testability, and RRF to provide out-of-the-box fusion effects. Expansion directions: 1. Introduce query intent recognition to adjust weights between text and semantic search; 2. Add business rules such as real-time filtering and permission control in the financial domain; 3. Migrate vector storage when data scale grows (hexagonal architecture ensures transparent migration).

nevis-search-api provides a practical reference for enterprise-grade hybrid search, showing how to smoothly introduce semantic search based on the existing PostgreSQL tech stack through reasonable architecture and algorithms. The design philosophy is worth learning: start from business needs, choose mature components, and use a clear architecture to ensure evolvability. Hybrid search is an engineering expression after deep understanding of user needs, not a simple pile of technologies.