Drupal RAG Architecture: What to Build and What to Manage

A Drupal RAG architecture is more than a chatbot. A Drupal-native build normally needs content extraction, chunking, embeddings, vector retrieval, Search API configuration, an LLM, citations, access checks, refresh jobs, an interface, and operations. A managed public-site service moves several layers outside Drupal; the right boundary depends on data access and who owns failures.

Michael Shamanoff Founder, Achla AI Who: written for Drupal owners, architects, and implementers evaluating semantic search or cited answers. How: based on official Drupal project pages and current Achla product files reviewed on 3 August 2026, plus an original ownership matrix and pilot scorecard. AI assistance was used in drafting; material factual claims are mapped in the accompanying ledger. Why: installation guides name components, but decision-makers also need to know who operates each layer, how it can fail, and which requirements rule out a managed public-crawl path.

The Drupal RAG architecture, layer by layer

RAG has two flows. Indexing converts content into retrievable records. Querying converts a question into retrieval, context, generation, and inspectable evidence.

Indexing flow: content to retrievable chunks

1. Select Drupal entities, fields, and view modes that contain useful source material.
2. Extract text while retaining identity, language, URL, access metadata, and update or deletion signals.
3. Split long content into chunks with enough context to remain meaningful.
4. Generate embeddings and store them in a vector-capable backend.
5. Update, replace, or delete records when Drupal content changes.

The official AI Search project integrates vector embeddings with Search API and documents a vector backend, chunking, score thresholds, post-query entity access checks, hybrid search, and RAG integration. These are building blocks, not a complete operating model.

Query flow: question to cited answer

1. Convert or route the question into the selected retrieval method.
2. Retrieve candidate chunks and apply thresholds, filters, or hybrid-search logic.
3. Assemble context for the LLM without dropping source identity or access constraints.
4. Generate a response or an honest empty result.
5. Render citations and log enough evidence to diagnose retrieval separately from generation.

Keep retrieved sources, generated text, and visitor-visible citations as distinct evidence: relevant retrieval can still be summarized badly, while fluent wording can rely on the wrong source.

What Search API does—and what it does not do alone

Search API is Drupal’s extensible search framework. It defines indexes and works with backends, fields, processors, Views, filters, and facets. It does not by itself choose an embedding model, operate every backend, assemble an LLM prompt, generate an answer, design a chat interface, or evaluate groundedness.

Its official project page also states an important security boundary: Search API cannot provide generic access restrictions for every use case. Site owners remain responsible for ensuring only accessible items are indexed or displayed, although node-access alteration and additional checks are available in parts of the ecosystem.

A semantic results page does not have to become chat. Decide whether visitors need ranked semantic results, a cited answer, a conversation, or several surfaces.

Current Drupal project status must shape the risk decision

Release labels and security coverage change, so refresh this table before human approval and again before any implementation decision. The following was observed on official Drupal.org project pages on 3 August 2026.

A 1.0.x number is not a substitute for security coverage. Review maturity, maintenance, Drupal versions, provider dependencies, and security-policy status separately.

DIY path: the components your team must own

A Drupal-native build keeps more control close to Drupal, but it also creates more operational owners. The RAG Search project illustrates a Search API vector index feeding prompt assembly and an LLM, with optional exact and semantic caches, rate limiting, and access rechecks before cached chunks are served. Its security-policy exclusion remains a material warning.

Drupal as RAG demonstrates another path using Drupal 11, PostgreSQL with pgvector, and Ollama on a local or network host. Its observed release was alpha and outside advisory coverage, so it is an architecture example, not a recommendation.

The ownership question is broader than module installation:

The broader trade-off between infrastructure control and managed operations is covered in enterprise AI search versus DIY.

Managed path: which layers move outside Drupal

A managed public-site path moves crawling, indexing, retrieval, model calls, answer delivery, and some monitoring to a service operator. Drupal supplies public pages and a script or connector. This reduces the in-Drupal stack but loses Drupal-native knowledge of fields, revisions, roles, and access decisions unless explicitly implemented and verified.

Achla’s inspected product files describe a Drupal 10/11 connector delivered through Composer, a PHP 8.3 validation matrix, and automatic updates marked available as last reviewed on 16 July 2026. Its managed path crawls and indexes the public site and displays source-linked answers through a widget. The widget supports bubble, inline, and attach placement.

Achla is not a Search API backend. It is a separate managed public-crawl and widget path. It must not be presented as the route for private or authenticated Drupal content, role-aware retrieval, row-level permissions, or transactional Drupal actions. See the broader managed setup without a developer for that operating boundary.

Build or manage? Use requirements, not fashion

Include infrastructure, updates, security review, provider keys, observability, content operations, incident response, and proof that access restrictions work—not only software licence cost.

Protect access, citations, and refresh behavior

Private content is a hard architectural fork. Search API’s generic framework does not automatically solve all access restrictions. AI Search documents post-query entity access checks; RAG Search documents role-aware cache keys and source-access rechecks. Those are module-specific mechanisms that still require tests with real roles, unpublished content, changed permissions, and cached answers.

The AI RAG Search Chat project shows why the production surface is larger than retrieval: it adds search and chat pages, sessions, permissions, rate limiting, providers, and linked sources. Its observed 1.0.7 release was outside Drupal security advisory coverage.

For any architecture, retain source URLs and identifiers through chunking, verify that each citation supports the answer, define an honest miss, and test update and deletion propagation. A source-linked answer is easier to inspect, but retrieval and citations do not eliminate model error. Use this guide to judge whether AI search is trustworthy when defining review criteria.

Use a reproducible pilot scorecard

Build the evaluation set from real tasks. Twenty to thirty representative questions is a planning method, not a benchmark or promised threshold.

1. Record the question, expected source page, content/access class, and acceptable “not found” outcome.
2. Include exact terms, paraphrases, conflicting pages, stale or removed content, and a question whose answer is absent.
3. For a Drupal-native private-content test, use accounts with different roles and fail on any inaccessible-source exposure.
4. Record retrieved sources separately from generated wording and visitor-visible citations.
5. Test index refresh after edit and deletion, then repeat after relevant caches could be involved.
6. Add keyboard, mobile, outage, empty-result, and fallback checks for the chosen interface.
7. Assign each failure to ingestion, retrieval, generation, citation/UI, access, or operations—and name who fixes it under each architecture.

Fail the pilot on exposed restricted content, invented sources, broken citation links, failure to acknowledge an absent answer, or stale deleted content that remains beyond the documented refresh window. Do not invent a universal accuracy score. The reusable RAG evidence sheet provides a place to separate claim, source, expected behavior, and observed result.

Common architecture mistakes

• Treating an LLM as retrieval instead of measuring the retrieved evidence.
• Indexing private fields or content without preserving and testing access rules.
• Dropping URLs, language, revision, or entity identity during chunking.
• Testing additions but not edits, deletions, cache invalidation, and honest misses.
• Calling a version “safe” because it lacks an alpha suffix while ignoring advisory coverage.
• Calling a public crawler a Search API backend or a private-content integration.
• Comparing licence price while omitting infrastructure and incident ownership.

A practical next step for a public Drupal site

Prototype DIY when Drupal-native fields, permissions, provider control, and an existing Search API operation are central requirements. Evaluate managed public-site search when the source is deliberately public and the team wants another operator to own the RAG service layers.

If your requirement is cited answers over public Drupal pages and documents without operating the RAG stack inside Drupal, evaluate Achla’s Drupal setup. Achla is not a Search API backend and is not the private-content path described above.

Questions Drupal teams ask

Do I need Search API?

For a Drupal-native route built around Search API modules, yes. A separate managed public-crawl service can use its own index instead. These are different architectures; a connector or widget does not make the managed index a Search API backend.

Do I always need a vector database?

Not for every search experience. Keyword or faceted search can use other backends. The official AI Search module uses vector-capable backends for semantic retrieval, while a managed service may hide its retrieval infrastructure behind the service boundary.

Can semantic search work without chat?

Yes. Semantic retrieval can return ranked results through a search interface. Add generation only when a written answer serves the task and you can preserve sources, handle honest misses, and test the wording separately from retrieval.

What about private content?

Keep access-controlled requirements in the architecture decision from the start. A Drupal-native design may preserve Drupal permissions if its complete indexing, retrieval, cache, and display path is tested. Achla’s path in this article is limited to public crawlable content.

How do I compare pilots?

Use the same question set, source expectations, access cases, refresh tests, citation checks, interface conditions, and failure categories. Compare evidence and ownership, not a vendor-selected demo or an unsupported universal score.

Shared illustration

A RAG architecture decision assigns extraction, retrieval, generation, citations and operations to different owners.