turbovec_vdb_provider

Turbovec VDB Provider integrates turbovec-docker - a lightweight, self-hosted vector database - as a Vector Database (VDB) provider for the Drupal AI module. It enables similarity-based semantic search across your Drupal content using embeddings, with no external cloud dependency.

turbovec-docker is a Dockerised HTTP API built on top of RyanCodrai/turbovec. It wraps turbovec's fast binary quantisation index in a FastAPI service and exposes a REST interface that this module communicates with to store, search, and delete vectors.

Key Features

• Semantic vector search - Plug turbovec into the AI Search backend to power similarity-based content discovery using embeddings from any AI provider supported by the Drupal AI module.
• Lightweight and self-hosted - turbovec-docker runs as a single Docker container with no external cloud account required. Data is persisted to local files on the host, making it ideal for development, staging, and small-to-medium production deployments.
• Full CRUD operations -Supports creating and dropping collections, inserting entities with arbitrary metadata fields, filtered vector search, metadata-only queries, and entity deletion.
• Entity ID filtering — Pass an allowlist of Drupal entity IDs to restrict vector search to a specific set of nodes (e.g. after access-check retries), ensuring results are scoped to content the current user is permitted to see.
• Offset and pagination support - Both vector search and metadata query endpoints support limit and offset, allowing the AI Search backend to page through results and apply access-check retries.
• Optional bearer token authentication - Set API_BEARER_TOKEN on the turbovec-docker container to require authentication. Store the token securely using the Key module and select it in the provider configuration form.
• DDEV friendly - From inside a DDEV container, point the server URL at http://host.docker.internal:8000 to reach turbovec running on the host machine without any extra network configuration.
• Orphan-safe - The provider guards against corrupted index state (vectors present in the index but missing metadata) that would otherwise crash Drupal's entity access checks.

Requirements

• AI module (including the ai_search sub-module)
• Key module
• A running turbovec-docker instance (docker compose up --build)
• Drupal 10.2 or 11

Getting started

Start turbovec-docker on the host machine:

docker compose up --build

Enable the module and clear caches:

drush en ai_vdb_provider_turbovec
drush cr

Visit /admin/config/ai/vdb_providers/turbovec and set the server URL (e.g. http://localhost:8000 or http://host.docker.internal:8000 from inside DDEV). The form tests connectivity on save.

Then create a Search API server using the AI Search backend, select Turbovec as the VDB provider, enable the AI Embeddings processor on your index, and index your content.