ai_rag_api

AI RAG API turns your Drupal site into an OpenAI-compatible chat completions API with Retrieval Augmented Generation (RAG), so headless frontends and AI tools can ask questions and get answers grounded in your own content.

You point any OpenAI SDK (Python, JavaScript, or anything that speaks the OpenAI wire format) at your Drupal site instead of at OpenAI. The module retrieves the most relevant content from a vector search index, feeds it to the large language model of your choice, and returns the answer in the standard OpenAI response format — including streaming, the sources used (title, URL, entity ID) for rendering source links, and optionally the retrieved text chunks for evaluation tools such as RAGAS. No custom API integration is needed on the frontend: if it works with OpenAI, it works with your Drupal site.

Everything builds on the AI module ecosystem: retrieval runs on an AI Search (Search API) vector index, generation goes through the AI provider abstraction (so any provider works), and AI guardrails are applied the way the AI module intends. The module is heavily inspired by AI Search Block and brings the same RAG approach to headless setups.

Features

OpenAI-compatible endpoints: POST /api/ai-rag/v1/chat/completions and GET /api/ai-rag/v1/models, usable with the official OpenAI SDKs by setting base_url.
RAG profiles: configuration entities bundling all settings — the RAG LLM agent message (system prompt), AI Search index (vector database), score threshold, minimum/maximum results and temperature. The OpenAI model parameter can be used to expose multiple differently tuned RAG endpoints (one per profile).
Streaming: real Server-Sent Events (SSE) with chat.completion.chunk events and data: [DONE] termination, matching OpenAI’s streaming format.
Sources always included: every response carries the deduplicated source entities (title, URL, entity ID) so you can render source links in a Next.js or other frontend. The full retrieved chunks can be returned on request via extra_body, for example as retrieved_contexts for RAGAS evaluation.
Per-request overrides (opt-in per profile): allow overriding score threshold, result limits, render mode, or disabling extra_body per request. The underlying search index is never client-overridable.
Secure by default: bearer API keys stored via the Key module, an optional permission-protected session endpoint, and Drupal entity access checks so unpublished or restricted content never leaks through the API — responses reflect exactly what an anonymous user can see.
Guardrails: per-profile guardrails, with globally configured AI module guardrails applied as well. Blocks surface as the OpenAI finish_reason: "content_filter" in responses.
Multi-turn conversations: conversation history is passed through to the LLM; retrieval always runs on the latest user message while still taking prior turns into account.
Fully covered by unit, kernel and functional tests.

Typical use cases: a chat interface on a decoupled/headless frontend answering questions from site content, benchmarking RAG quality with RAGAS or similar test suites, and exposing curated site knowledge to external tools that already speak the OpenAI API.

Post-installation

Make sure you have a working AI setup: a chat provider and an AI Search index on a vector database with your content indexed.
Create a key holding your API token at Configuration → System → Keys (an environment variable provider is usually recommended for production).
Create a RAG profile at Configuration → AI → RAG API profiles (/admin/config/ai/rag-api). Select the AI Search index, LLM model, thresholds, the agent message and the API key.
Connect with any OpenAI SDK by pointing base_url at your Drupal site and using the profile machine name as the model:

from openai import OpenAI

client = OpenAI(
    base_url="https://your-drupal-site.example.com/api/ai-rag/v1",
    api_key="YOUR-KEY",
)

response = client.chat.completions.create(
    model="my_profile",
    messages=[{"role": "user", "content": "What is this site about?"}],
    extra_body={"rag": {"return_contexts": True}},
)

Additional requirements

AI module (1.4 or higher) with a configured chat provider and the AI Search submodule.
Search API.
Key.
A vector database provider such as PostgreSQL VDB Provider (pgvector) or Milvus.
The league/html-to-markdown library (installed automatically via Composer).

Recommended modules/libraries

Any AI provider module for your LLM of choice (OpenAI, LiteLLM, Ollama, etc.).
The AI module’s guardrails for input/output filtering on the endpoint.
RAGAS (Python) for evaluating answer quality with the returned contexts.

Similar projects

AI Search Block — the main inspiration for this module; provides a RAG-powered search block inside your Drupal theme. AI RAG API provides the same RAG capabilities over an OpenAI-compatible API instead.
AI Agents API / AI Chatbot (AI module submodules) — agent-driven chat experiences rendered within Drupal; this module targets decoupled frontends and external tools instead.
AI Search — site-facing conversational search; not an API endpoint.
AI API — exposes raw AI providers over an OpenAI-compatible API, without retrieval or source passthrough.

Support & development

Development happens in the project issue queue; feature requests and merge requests are very welcome.

Community & documentation

The module README contains full usage examples for the OpenAI Python SDK, curl, streaming, the rag request/response objects and a RAGAS evaluation recipe.