From keyword search to AI Search

Choose keywords, Vectorize, or managed AI Search from user intent, data scale, explainability, and maintenance cost.

DECISION GUIDEINTERMEDIATE25 minutesOutcome: an explainable search path

Not every CMS, SaaS, or documentation site needs vector retrieval. When a user knows a title, tag, or identifier, keywords and filters are usually faster, cheaper, and easier to explain. Move to semantic retrieval when the user expresses meaning rather than literal words or needs relevant passages across long documents.

Four-level selection ladder

Level	Best for	Main advantage	Main cost
Exact fields	ID, slug, status, author	Deterministic, fast, sortable	Does not understand synonyms
Keywords	Specific terms in title or body	Explainable and easy to debug	Recall depends on wording
Vectorize	You control chunks, embeddings, and retrieval	Flexible and composable	You own indexing and evaluation
AI Search	Managed natural-language retrieval from sites, R2, or uploads	Less pipeline maintenance	Models, indexing, and configuration need observation

Retrieval is not answer generation

Prove that search returns the right sources before generating a summary. A fluent answer without traceable sources is not a reliable search experience.

Minimum useful search experience

Build a user-intent fixture set

Collect real questions with exact titles, synonyms, misspellings, multiple languages, no-answer cases, and content outside the caller's permissions. Define expected sources, not only an expected sentence.

Apply deterministic filtering first

Locale, tenant, publication state, permission, and content type are application filters. A model or vector similarity score cannot replace authorization.

Evaluate retrieval quality

Record top-k sources, rank, no-result rate, and human corrections. Re-run the same fixtures after changing chunks or models instead of trusting one impressive demonstration.

Decide whether to generate an answer

Generated answers need sources and a path to the original document. Return an explicit “not found” when context is insufficient. Keep keyword search as a degradation path.

AI Search boundary

AI Search can connect a website, an R2 bucket, or uploaded documents. It can be managed through the Workers API, CLI, dashboard, Python SDK, or REST API. Each instance connects to an AI Gateway for model-call observation and control.

Do not apply generic caching and rate limiting to the connected Gateway

The primary documentation warns that caching can reuse incorrect embedding results and generic rate limits can interrupt indexing and queries. Use AI Search's own similarity cache for search results and design model-call controls specifically for the instance.

Content model

Canonical content

Keep body and media in your authoritative store. R2 can hold document objects.

Index metadata

Preserve locale, tenant, visibility, source URL, version, and updatedAt.

Retrieval result

Return stable document ID, passage, ranking information, and an openable source.

Evaluation set

Version it with product code without real user secrets or private content.

Completion checkpoint

Choose real queries and implement an exact-field or keyword baseline first. Escalate only the queries that the baseline cannot satisfy to Vectorize or AI Search. Before release, prove that permission filtering happens on a trusted server and that no-answer cases do not invent sources.

Next: add optional AI capabilities.