How to Set Up Drupal AI Search with RAG on Varbase

Drupal AI Search with RAG replaces keyword matching with semantic retrieval, so a visitor can ask a full question and get the passage that answers it. On Varbase 11, the AI foundation ships as a recipe, which means the work left is retrieval configuration rather than plumbing. Every step below was executed on a live build, including the parts that only break in real testing.

Why Does Keyword Search Fall Short on a Content-Heavy Drupal Site?

Keyword search falls short because it scores pages on keyword frequency, so a long overview that repeats a term outranks the short, direct answer that uses it once. The AI Search module documentation names the same failure.

Two failure modes consistently appear on a large content site. Vocabulary mismatch: the user says "sign-in," the content says "authentication," and keyword search returns nothing useful. And question-shaped queries: users increasingly type or speak full questions, which keyword indexes were never built to parse.

Semantic retrieval addresses both, because embeddings place near-synonyms close together, and place a question close to its answer even when they share few words.

What Do You Need to Run AI Search on Varbase 11?

AI Search on Varbase 11 needs six pieces: the AI foundation recipe, the search backend, the assistant layer, a vector database provider, the vector database itself, and an API key for embeddings.

Should You Self-Host Milvus or Use Zilliz Cloud?

Self-host Milvus if you want local development with no third-party account and full control over where vectors live; use Zilliz Cloud if you would rather not run the database yourself. Both connect to the same Milvus VDB Provider module, so the only practical differences are the endpoint and whether you supply an API key.

Milvus is the most widely used vector database provider in the Drupal community, going by module usage statistics on drupal.org.

In the public-sector and nonprofit work we do, the choice usually gets made on residency rather than convenience. Once content embeddings leave your infrastructure, they fall under whatever jurisdiction the provider sits in, and for a government or health-sector client that is a procurement question before it is a technical one. Self-hosting keeps that conversation short. The walkthrough below uses a self-hosted container, and notes the Zilliz Cloud equivalent at each point where they differ.

Where Do RAG Builds Actually Succeed or Fail?

Our view: the modules are the fast part. Any competent Drupal team can enable this stack in an afternoon. What separates an assistant people trust from one they abandon is four decisions downstream of the module list: chunking with contextual embedding, a prompt that makes searching mandatory before it makes grounding mandatory, where the chatbot renders under Drupal Canvas, and the retrieval threshold plus its keyword fallback. Each one is covered below, because each one only shows up as a problem in real testing.

How Do You Set Up AI Search with RAG on Varbase 11?

Set up AI Search with RAG on Varbase 11 in three phases: apply the AI recipe, connect the vector database, then build the RAG index and the assistant. The steps assume a Varbase 11 site with content already in place.

1. Apply the Varbase AI Base Recipe

Varbase 11 ships the recipe in the project, so there is nothing to require. Apply it with your provider and key:

ddev drush recipe /var/www/html/recipes/varbase_ai_base \
  --input=drupal_cms_ai.provider=openai \
  --input=drupal_cms_ai.openai_api_key=YOUR_OPENAI_KEY -y

This installs the AI core, stores the key in the Key module, sets OpenAI as the default chat provider, and applies the Varbase AI sub-recipes for image alt text, the CKEditor assistant, and taxonomy tagging.

2. Enable the AI Search Stack

ddev composer require 'drupal/ai_vdb_provider_milvus:~1.0'
ddev drush en ai_search ai_chatbot ai_assistant_api ai_vdb_provider_milvus -y

3. Run Milvus

Create .ddev/docker-compose.milvus.yaml:

services:
  milvus:
    container_name: ddev-${DDEV_SITENAME}-milvus
    image: milvusdb/milvus:v2.4.15
    command: ["milvus", "run", "standalone"]
    security_opt: [ "seccomp:unconfined" ]
    environment:
      ETCD_USE_EMBED: "true"
      ETCD_DATA_DIR: /var/lib/milvus/etcd
      ETCD_CONFIG_PATH: /milvus/configs/embedEtcd.yaml
      COMMON_STORAGETYPE: local
    volumes:
      - milvus-data:/var/lib/milvus
      - ./milvus/embedEtcd.yaml:/milvus/configs/embedEtcd.yaml
      - ./milvus/user.yaml:/milvus/configs/user.yaml
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      start_period: 90s
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT

volumes:
  milvus-data:

And .ddev/milvus/embedEtcd.yaml:

listen-client-urls: http://0.0.0.0:2379
advertise-client-urls: http://0.0.0.0:2379
quota-backend-bytes: 4294967296
auto-compaction-mode: revision
auto-compaction-retention: '1000'

Then run ddev restart. The web container reaches Milvus at http://milvus:19530.

4. Configure the Milvus Provider

At /admin/config/ai/vdb_providers/milvus, set the server to http://milvus and the port to 19530. For Zilliz Cloud, use your public endpoint, port 443, and the API key from the Key module. Clear caches, which matters at this stage.

5. Add the AI Search Server

At /admin/config/search/search-api/add-server, create "AI Search Server" with the AI Search backend:

6. Build the RAG Index and Map the Field Roles

Create a Search API index called "RAG Index" on the Content datasource, select the bundles that hold your knowledge (here, blog posts and pages), and attach it to the AI Search Server. Then give every field one of the three vector database roles. This mapping is what decides retrieval quality.

Set the cron batch size to 5 or 10, since each batch makes embedding API calls, then index:

ddev drush search-api:index rag_index --batch-size=5

7. Create the Assistant With a RAG Action

At /admin/config/ai/ai-assistant, add "Site Assistant" and enable its RAG action pointed at the RAG Index: score threshold 0.3, 1 to 5 results, output mode chunks. Model: OpenAI gpt-4o, temperature 0.2.

How Do You Keep the Chatbot From Making Things Up?

Keep the chatbot grounded with a prompt that makes searching mandatory first and grounding mandatory second. This is the configuration that makes or breaks the assistant, and one lesson only shows up in real testing.

In AI module 1.4, the assistant first makes a decision call: answer directly, or run an action? If your instructions only say "answer solely from retrieved content, otherwise say you found nothing," the model takes the shortcut at decision time and returns the fallback sentence without ever searching. The instructions have to make the search itself compulsory:

1. For every user question about any topic, product, feature, or content, you must first run the RAG Actions search with the user's question as the query. Never answer a content question without searching first.
2. After searching, answer only from the retrieved passages. Quote or closely paraphrase them, and never add facts from your own general knowledge.
3. Every retrieved passage includes a "Page URL" line. Include a markdown link to it as the source.
4. Only if the search returned no usable passages, reply: "I could not find matching information on this site for that question."
5. For purely conversational messages such as greetings and thanks, reply briefly without searching.

The effect is an assistant that either answers from your content with a working citation or tells the user it does not know. That boundary is the whole point: a traceable non-answer beats a confident wrong one.

Where Does the Chatbot Block Go on Varbase 11?

On Varbase 11 the chatbot cannot go in a block region. Canvas renders the pages, including the global header and footer, so block layout regions never print. On a classic theme you would drop the AI DeepChat Chatbot block into a region and be done. Here, two things change.

• Render it from code. Use a small custom module and hook_page_bottom(), which runs on every route regardless of Canvas.
• Render it through a lazy builder. The chatbot markup carries a per-session CSRF token for /api/deepchat. If the render array gets cached without a session context, every visitor is served the first visitor's token and every chat message fails with a 403. A #lazy_builder with #create_placeholder: TRUE regenerates the token per request.

function ai_chatbot_launcher_page_bottom(array &$page_bottom) {
  if (\Drupal::service('router.admin_context')->isAdminRoute()) {
    return;
  }
  $page_bottom['ai_chatbot_launcher'] = [
    '#lazy_builder' => ['ai_chatbot_launcher.lazy_builder:build', []],
    '#create_placeholder' => TRUE,
  ];
}

The lazy builder loads the DeepChat block plugin with the block's saved settings, checks access, and returns its build with #cache: max-age 0.

How Do You Add Semantic Results to Your Normal Search Page?

Add semantic results to a normal search page by enabling the "Database boost by AI Search" processor on the keyword index and pointing it at your RAG index. Use minimum relevance 0.4 and top 10 results.

On Varbase 11, the search page at /search is a Search API view on the database index, so it gains hybrid semantics without a rebuild. Semantic matches are prepended to keyword results, which means question-shaped queries work while exact-match precision stays.

The search box itself is a Canvas component. Add the search view's exposed-filter block (views_exposed_filter_block:search-page) to the global header through Canvas's page region (canvas.page_region.<theme>.header), so it appears on every page.

We styled ours as a collapsed magnifier in the navbar that expands into a minimal underline field, with Enter to submit. The submit button stays in the DOM but is visually hidden, so keyboard and screen reader users keep real control. Partial-match highlighting was switched off on the Highlight processor so excerpts only bold whole matched words.

How Do You Know It Is Working?

Verify the build with acceptance tests that check grounding and refusal, not just that the chatbot returns something. These are the tests we ran in a real browser, with Playwright driving Chrome.

The France test is the one worth copying. An assistant that cannot refuse is not grounded; it is just fluent.

Package It Once, Reuse It Everywhere

Everything above is configuration plus one small custom module, which is exactly the shape of a future Varbase AI Search recipe. Until that ships, this is the tested path on Varbase 11. For teams running this in production, the decisions that matter are retrieval quality and a review cadence, not the module list, and that is where the time goes.

That direction is the reason to run this on Varbase rather than a bare Drupal install. Varbase already ships the AI foundation as a maintained recipe, and its AI and search pieces are built and supported by the same team, so the moving parts are meant to work together.

If you are planning an AI-powered search experience on Drupal and want a second set of eyes on the retrieval design before you build, Vardot's team works on exactly this on Varbase.

Vardot is the Varbase maintainer, a Drupal Diamond Certified Partner, and a Drupal AI Initiative Gold Sponsor.