Why semantic search beats keyword matching
Traditional search matches the literal characters a user types, so a query for “cheap flights” never finds a page titled “budget airfare deals” even though they mean the same thing. AI-powered search fixes this by converting both your content and the user’s query into embeddings — lists of numbers that capture meaning — and ranking results by how close those numbers are. The payoff is search that understands synonyms, paraphrases, and intent out of the box, with no manually maintained synonym lists. In Next.js it slots in cleanly: embed content in a background job, embed the query in a server route, and render ranked results on the client.
How it works
There are two phases. At index time you loop over every document, send its text to an embeddings model once, and store the returned vector next to the original text. You only repeat this when content changes. At query time a user types a search; your server route embeds that query string into a vector of the same shape, then computes cosine similarity between the query vector and every stored document vector. Cosine similarity returns a score where higher means more similar in meaning. You sort the documents by that score, drop anything below a relevance threshold, and return the top handful as JSON. The interactive demo below runs this exact pipeline on a small sample corpus using a transparent keyword-overlap proxy so you can see ranking and scoring behave the way real embeddings would, without needing an API key.
Tips and gotchas
Keep your API key server-side: query embedding must run in a route handler or server action, never in the browser. Cache index-time embeddings aggressively — re-embedding unchanged content on every deploy wastes money and time. Set a minimum similarity threshold so irrelevant results are hidden rather than shown at the bottom with a near-zero score. For up to a few thousand documents, an in-memory similarity scan is fast enough and far simpler than running a vector database; reach for pgvector or a managed vector store only when your corpus or traffic grows. Finally, show the relevance percentage in the UI — users trust ranked results far more when they can see why one result outranked another.
Try the ranking demo
Enter a search query below. The demo embeds it against a sample knowledge base and ranks results by similarity, exactly as a real Next.js semantic-search route would.