README

Gives the Drupal Canvas page builder agent a vector search tool over an index of AI generated image descriptions.

Follow the steps in order. Each step ends with a check. Do not continue until the check passes.

1. Add a pgvector database

ddev add-on get robertoperuzzo/ddev-pgvector
ddev restart

The add-on creates a Postgres service with these values:

Check: ddev describe lists a pgvector service.

2. Create the vector extension

ddev exec bash -c 'PGPASSWORD=ddev_password psql -h pgvector -U ddev_user -d ddev_embedding_db -c "CREATE EXTENSION IF NOT EXISTS vector;"'

Check: the same command with -c "\dx" in place of the CREATE statement lists vector.

3. Set the database environment variables

ddev config --web-environment-add="VECTOR_DB_HOST=pgvector,VECTOR_DB_PORT=5432,VECTOR_DB_USER=ddev_user,VECTOR_DB_PASSWORD=ddev_password,VECTOR_DB_NAME=ddev_embedding_db"
ddev restart

Check: ddev exec printenv VECTOR_DB_NAME prints ddev_embedding_db.

4. Install the supporting recipes

ddev composer require drupal/ai_recipe_vdb_provider_postgres drupal/ai_recipe_image_search_vector

Check: recipes/ai_recipe_vdb_provider_postgres and recipes/ai_recipe_image_search_vector exist.

5. Set a default embeddings model

Any provider that exposes an embeddings model works. The commands below are an example for a LiteLLM proxy that exposes openai/text-embedding-3-small:

ddev drush config:set ai.settings default_providers.embeddings.provider_id litellm
ddev drush config:set ai.settings default_providers.embeddings.model_id openai/text-embedding-3-small

Substitute your own provider ID and model ID if you use a different provider.

Check: ddev drush config:get ai.settings default_providers.embeddings prints a provider and model.

6. Generate the image descriptions

The image classification recipe adds an Image Description field to the image media type, along with an automator that sends the image to a chat with vision model, gets a description back and fills the field with it. These descriptions are what get indexed into the vector database, and what lets the Canvas agent search the media library and find images.

The site needs a default chat with vision model before the recipe will apply.

ddev drush recipe ../recipes/ai_recipe_image_classification

The automator runs when a media item is saved, so existing media have to be resaved. At /admin/content/media, select the image media items and run the Save media bulk action.

Descriptions are only generated for media whose Image Description field is empty.

Check: open an image media item and confirm the Image Description field holds a generated description.

7. Configure the vector database provider

ddev drush recipe ../recipes/ai_recipe_vdb_provider_postgres

Press Enter at each prompt to accept the values from step 3.

Check: ddev drush config:get ai.settings default_vdb_provider prints postgres.

8. Rebuild the cache

ddev drush cr

Check: the command completes with a success message.

9. Create the search server and index

ddev drush recipe ../recipes/ai_recipe_image_search_vector

Press Enter to accept ddev_embedding_db.

Check: /admin/config/search/search-api lists the server Image Database (Vector) and the index Image Database Index (Vector).

10. Run database updates

ddev drush updatedb

Check: ddev drush updatedb:status reports no pending updates.

11. Index the images

ddev drush search-api:index image_database_index_vector

Check: the command reports all items indexed, and /admin/config/search/search-api/index/image_database_index_vector shows 100% indexed.

12. Apply this recipe

ddev drush recipe ../recipes/ai_recipe_canvas_ai_image_search --input=ai_recipe_canvas_ai_image_search.index_id=image_database_index_vector

Check: /admin/config/ai/agents/canvas_dev_page_builder_agent lists RAG/Vector Search among the enabled tools.

13. Confirm the agent can search

Open a Canvas page, start the AI chat, and ask for an image that exists in your media library, for example "add an image of a person cooking".

Check: the agent places an existing media item rather than a placeholder.

Re-indexing

New and updated image media are indexed on cron. To index immediately:

ddev drush search-api:index image_database_index_vector

AI disclosure

This recipe and its documentation were generated with AI assistance.