Hybrid search

Last updated Oct 1, 2026 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.

Hybrid search is enabled by default.

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 opt out of 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:

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",
        },
    },
});

Note

Requesting a retrieval_type that is not compatible with the instance index_method returns an error.

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.

Was this helpful?

YesNo

On this page

Hybrid search - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/configuration/indexing/hybrid-search/#page","headline":"Hybrid search","description":"Combine vector and keyword search in AI Search for broader, more accurate retrieval results.","url":"https://developers.cloudflare.com/ai-search/configuration/indexing/hybrid-search/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/configuration/indexing/hybrid-search/og.png?v=1a78e799dc4497aa","dateModified":"2026-10-01","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Enable BM25 keyword search in AI Search to match documents containing exact query terms. title: Keyword search image: https://developers.cloudflare.com/ai-search/configuration/indexing/keyword-search/og.png?v=0ed21bf4322c3741

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-search/llms.txt
Use this file to discover all available pages before exploring further.