Hybrid search

Hybrid search runs vector and keyword search in parallel and merges the results. It requires keyword search to be enabled. For an overview of search modes, refer to Search modes.

Enable hybrid search

Set both index_method.vector and index_method.keyword to true:

const instance = await env.AI_SEARCH.create({
  id: "my-instance",
  index_method: {
    vector: true,
    keyword: true,
  },
  fusion_method: "rrf",
});

To disable hybrid search, set index_method.keyword to false. The keyword index is deleted.

For each search method, you can configure the following to adjust retrieval behavior:

Vector search: Configure the embedding model.
Keyword search: Configure the tokenizer and match mode.

Fusion method

The fusion_method field controls how vector and keyword results are merged.

Value	Default	Description
`rrf`	Yes	Reciprocal Rank Fusion. Scores results based on rank position across both search methods. Recommended for most use cases.
`max`	No	Takes the higher of the normalized vector and keyword scores. Use when one search method is consistently more relevant.

Reranking

After fusion, you can optionally apply reranking to further reorder results by semantic relevance. Reranking uses a cross-encoder model that evaluates the query and each chunk together, which can improve precision beyond what fusion alone provides.

Reranking is disabled by default. Refer to Reranking to enable and configure it.

Per-request overrides

Override search settings on individual requests using ai_search_options.retrieval.

Field	Type	Description
`retrieval_type`	`"vector"`, `"keyword"`, or `"hybrid"`	Force a specific search mode. Must be compatible with `index_method`.
`fusion_method`	`"rrf"` or `"max"`	Override the fusion method.

const instance = env.AI_SEARCH.get("my-instance");

const results = await instance.search({
  messages: [{ role: "user", content: "What is Cloudflare?" }],
  ai_search_options: {
    retrieval: {
      retrieval_type: "hybrid",
      fusion_method: "rrf",
    },
  },
});

Scoring details

When hybrid search is active, each chunk includes a scoring_details object:

Field	Type	Description
`vector_score`	number	Vector similarity score (0 to 1).
`keyword_score`	number	Raw BM25 keyword score.
`vector_rank`	number	Rank position in the vector result set.
`keyword_rank`	number	Rank position in the keyword result set.
`fusion_method`	string	Fusion method used (`rrf` or `max`).
`reranking_score`	number	Score from the reranking model, if enabled.

Limits

Instances with keyword search enabled support up to 500,000 files per instance on the Workers Paid tier, compared to 1,000,000 for vector-only instances. Refer to Limits and pricing for the full list of limits.