Comment implémenter et dépanner la recherche IA dans Drupal 10

À la fin, vous aurez une implémentation de recherche IA fonctionnelle qui comprend l'intention de l'utilisateur, gère les fautes de frappe et les synonymes, et livre des résultats pertinents même quand les utilisateurs ne connaissent pas les mots-clés exacts à utiliser.

Prérequis

Avant de commencer l'implémentation de la recherche IA, assurez-vous d'avoir :

• Drupal 10.1 ou supérieur installé et fonctionnel
• Composer disponible pour l'installation de modules
• Drush installé pour les opérations en ligne de commande
• Accès administrateur à votre site Drupal
• Identifiants API d'au moins un fournisseur (OpenAI, Anthropic ou similaire)
• Compréhension de base du système de modules Drupal et de la gestion de configuration

Nous avons constaté que les équipes qui commencent avec des fournisseurs infonuagiques comme OpenAI ont une configuration initiale plus facile, tandis que celles ayant des exigences de confidentialité préfèrent souvent les options auto-hébergées utilisant Ollama et des bases de données vectorielles locales.

Vous devrez aussi décider de votre base de données vectorielle. Les choix populaires incluent :

• Pinecone (infonuagique, configuration facile)
• Milvus (auto-hébergé ou infonuagique)
• PostgreSQL avec pgvector (si vous utilisez déjà PostgreSQL)
• Zilliz (service infonuagique Milvus géré)

Implémentation étape par étape

Étape 1 : Installer les modules requis

Commencez par installer les modules principaux nécessaires pour la fonctionnalité de recherche IA :

composer require drupal/ai drupal/key drupal/search_api

Ces trois modules forment la base :

• drupal/ai fournit le cadre IA et inclut le sous-module ai_search
• drupal/key stocke vos identifiants API de façon sécurisée
• drupal/search_api crée l'infrastructure de recherche

Selon vos fournisseurs choisis, ajoutez des modules spécifiques :

# Pour les utilisateurs OpenAI
composer require drupal/ai_provider_openai

# Pour la base de données vectorielle Milvus
composer require drupal/ai_vdb_provider_milvus

# Pour PostgreSQL avec pgvector
composer require drupal/ai_vdb_provider_postgres

# Pour Ollama auto-hébergé
composer require drupal/ai_provider_ollama

Étape 2 : Activer les modules

Après l'installation, activez les modules en utilisant Drush :

drush en ai ai_search ai_api_explorer key search_api

Ensuite, activez vos modules de fournisseurs spécifiques :

# Exemple pour une configuration OpenAI et Pinecone
drush en ai_provider_openai ai_vdb_provider_pinecone

Videz la cache pour vous assurer que toutes les configurations se chargent correctement :

drush cr

Étape 3 : Configurer les clés API

Naviguez vers Configuration > Système > Clé dans votre interface d'administration Drupal. Créez une nouvelle clé pour chaque service API que vous utilisez :

1. Cliquez sur « Ajouter une clé »
2. Donnez-lui un nom descriptif (p. ex., « Clé API OpenAI »)
3. Sélectionnez « Type de clé » comme « Authentification »
4. Choisissez « Fournisseur de clé » (nous recommandons « Configuration » pour le développement, « Fichier » pour la production)
5. Entrez la valeur de votre clé API
6. Sauvegardez la configuration

Répétez ce processus pour votre clé API de base de données vectorielle si vous utilisez un service infonuagique.

Étape 4 : Configurer le fournisseur IA

Allez à Configuration > IA > Paramètres du fournisseur et configurez votre fournisseur choisi :

Pour OpenAI :

1. Sélectionnez « OpenAI » comme fournisseur
2. Choisissez la clé API que vous avez créée plus tôt
3. Entrez votre ID d'organisation OpenAI (utilisez l'ID, pas le nom de l'organisation)
4. Sélectionnez votre modèle préféré (text-embedding-3-small fonctionne bien pour la plupart des cas d'usage)
5. Sauvegardez la configuration

Étape 5 : Configurer la base de données vectorielle

Naviguez vers Configuration > IA > Fournisseurs VDB et configurez votre base de données vectorielle :

Pour Milvus :

Hôte : votre-serveur-milvus.com
Port : 19530
Base de données : default
Collection : drupal_content
Dimension : 1536 (pour les embeddings OpenAI)
Métrique de similarité : Cosinus

Pour PostgreSQL avec pgvector :

Hôte : localhost
Port : 5432
Base de données : drupal_vectors
Table : content_embeddings
Dimension : 1536

Testez la connexion avant de sauvegarder pour vous assurer que tout se connecte correctement.

Étape 6 : Créer le serveur Search API

1. Naviguez vers Configuration > Recherche et métadonnées > Search API
2. Cliquez sur « Ajouter un serveur »
3. Entrez un nom comme « Serveur de recherche IA »
4. Pour le backend, sélectionnez « AI Search »
5. Configurez ces paramètres :

• Moteur d'embeddings : Votre fournisseur IA (p. ex., OpenAI)
• Modèle : text-embedding-3-small (ou votre modèle préféré)
• Base de données vectorielle : Votre fournisseur VDB configuré
• Taille de segment : 512 jetons (ajustez selon votre contenu)
• Chevauchement : 50 jetons (aide à maintenir le contexte entre les segments)

Étape 7 : Créer et configurer l'index de recherche

1. Dans Search API, cliquez sur « Ajouter un index »
2. Nommez-le de façon descriptive comme « Index de contenu IA »
3. Sélectionnez les types de contenu à indexer (Articles, Pages, etc.)
4. Choisissez votre serveur de recherche IA
5. Configurez les champs soigneusement :

Champ de contenu principal (celui-ci est segmenté et intégré) :

• Sélectionnez votre champ de corps ou zone de contenu principal
• Il sera divisé en segments pour le traitement

Champs contextuels (ajoutés à chaque segment pour une meilleure compréhension) :

• Titre
• Résumé/accroche
• Étiquettes ou catégories
• Information sur l'auteur

Champs filtrables (pour la recherche à facettes) :

• Type de contenu
• Date de publication
• Termes de catégorie

Étape 8 : Indexer votre contenu

Après avoir configuré l'index, vous devez traiter votre contenu :

1. Allez à l'onglet « Voir » de votre index
2. Cliquez sur « Indexer maintenant » pour commencer le traitement
3. Pour les sites avec beaucoup de contenu, ajustez la taille du lot :

// Dans settings.php pour les gros sites
$config['search_api.index.ai_content_index']['options']['batch_size'] = 5;

Surveillez le progrès de l'indexation. Chaque élément de contenu :

• Est divisé en segments
• Est envoyé au fournisseur IA pour générer l'embedding
• Est stocké dans la base de données vectorielle avec les métadonnées

Étape 9 : Tester votre implémentation

Utilisez l'explorateur API IA pour vérifier que tout fonctionne :

1. Naviguez vers /admin/config/ai/explorers/vector_db_generator
2. Entrez une requête de test
3. Vérifiez que les résultats retournent avec des scores de pertinence
4. Vérifiez que le contenu correspond à vos attentes

Exemples de requêtes de test à essayer :

• Une question sur votre contenu
• Un terme de recherche mal orthographié
• Une requête conceptuelle utilisant des mots différents de votre contenu

Étape 10 : Ajouter l'interface de recherche

Finalement, ajoutez l'interface de recherche à votre site :

Pour un bloc de recherche :

1. Allez à Structure > Mise en page des blocs
2. Cliquez sur « Placer un bloc » dans la région désirée
3. Recherchez le bloc « AI Search »
4. Configurez les paramètres du bloc
5. Sauvegardez et testez sur votre site

Pour une page de recherche dédiée, créez une vue personnalisée utilisant l'index Search API.

Exemples de code avec explications

Implémentation de recherche personnalisée

Voici comment interroger votre recherche IA par programmation :

use Drupal\search_api\Entity\Index;

function custom_ai_search($query_text) {
  // Charger votre index de recherche IA
  $index = Index::load('ai_content_index');
  
  // Créer la requête
  $query = $index->query();
  
  // Définir la chaîne de recherche
  $query->keys($query_text);
  
  // Définir la limite de résultats
  $query->range(0, 10);
  
  // Exécuter la recherche
  $results = $query->execute();
  
  // Traiter les résultats
  $items = [];
  foreach ($results->getResultItems() as $item) {
    $items[] = [
      'title' => $item->getField('title')->getValues()[0],
      'excerpt' => $item->getExcerpt(),
      'score' => $item->getScore(),
      'url' => $item->getOriginalObject()->toUrl()->toString(),
    ];
  }
  
  return $items;
}

Exemple de génération d'embedding

Si vous devez générer des embeddings directement :

use Drupal\ai\Service\AiProviderManager;

function generate_embedding($text) {
  // Obtenir le service du fournisseur IA
  $ai_manager = \Drupal::service('ai.provider_manager');
  
  // Obtenir votre fournisseur configuré
  $provider = $ai_manager->getProvider('openai');
  
  // Générer l'embedding
  $embedding = $provider->embeddings($text, [
    'model' => 'text-embedding-3-small',
  ]);
  
  return $embedding;
}

Requête de base de données vectorielle

Requêtes directes de base de données vectorielle pour des implémentations personnalisées :

use Drupal\ai_vdb_provider\Service\VectorDatabaseManager;

function search_vectors($embedding, $limit = 10) {
  // Obtenir le service de base de données vectorielle
  $vdb_manager = \Drupal::service('ai.vdb_manager');
  
  // Obtenir votre base de données configurée
  $vdb = $vdb_manager->getDatabase('milvus');
  
  // Effectuer une recherche de similarité
  $results = $vdb->search([
    'vector' => $embedding,
    'limit' => $limit,
    'metric' => 'cosine',
  ]);
  
  return $results;
}

Erreurs courantes à éviter

1. Configuration incorrecte des champs

Le problème le plus fréquent que nous voyons est une mauvaise configuration des champs dans l'index de recherche. Assurez-vous que :

• Un seul champ est défini comme « Contenu principal » (le champ qui est segmenté)
• Les champs contextuels sont marqués comme « Contextuel » et non « Principal »
• N'indexez pas de champs inutiles qui gonflent vos vecteurs

2. Problèmes de clé API et d'ID d'organisation

Lors de l'utilisation d'OpenAI, utilisez toujours l'ID d'organisation (commence par « org- »), pas le nom de l'organisation. Vous pouvez le trouver dans les paramètres de votre compte OpenAI.

3. Segments trop volumineux

Garder des segments trop gros entraîne :

• Des coûts API plus élevés
• Des résultats de recherche moins précis
• Des erreurs de délai d'attente lors de l'indexation

Commencez avec des segments de 512 jetons et ajustez selon la structure de votre contenu.

4. Gestion d'erreurs manquante

Implémentez toujours des solutions de repli :

try {
  $results = custom_ai_search($query);
} catch (\Exception $e) {
  // Repli sur la recherche standard
  \Drupal::logger('ai_search')->error('La recherche IA a échoué : @message', [
    '@message' => $e->getMessage(),
  ]);
  $results = fallback_keyword_search($query);
}

5. Ignorer les limites de taux

Notre expérience montre que les limites de taux API prennent beaucoup d'équipes par surprise. Surveillez votre utilisation et implémentez une limitation :

// Ajouter des délais entre les opérations par lot
$config['ai.settings']['batch_delay'] = 1000; // millisecondes

Étapes de test et de vérification

1. Vérifier l'installation des modules

Exécutez cette commande pour confirmer que tous les modules sont activés :

drush pm:list --type=module --status=enabled | grep -E "ai|search_api|key"

2. Tester la connectivité API

Utilisez l'explorateur API IA à /admin/config/ai/explorers/ai_provider pour tester :

• Envoyez un texte simple pour l'embedding
• Vérifiez que vous recevez un tableau de vecteurs en retour
• Vérifiez que les dimensions du vecteur correspondent à votre configuration

3. Valider la base de données vectorielle

Testez les opérations de base de données vectorielle à /admin/config/ai/explorers/vector_db :

1. Créez une collection de test
2. Insérez un vecteur échantillon
3. Effectuez une recherche de similarité
4. Supprimez la collection de test

4. Vérifier le statut de l'index

Surveillez votre index de recherche à /admin/config/search/search-api :

• Vérifiez que les éléments sont indexés
• Recherchez les messages d'erreur
• Examinez le journal de l'index pour les problèmes

5. Liste de vérification des tests de requête

Testez ces types de requêtes pour assurer une fonctionnalité complète :

• Correspondance exacte de mot-clé
• Recherche de synonymes (p. ex., « auto » trouvant « automobile »)
• Tolérance aux fautes de frappe (p. ex., « drupla » trouvant « Drupal »)
• Recherche basée sur des questions
• Recherche conceptuelle (trouver du contenu connexe sans termes exacts)

6. Surveillance de la performance

Suivez ces métriques :

• Vitesse d'indexation (éléments par minute)
• Temps de réponse des requêtes
• Utilisation et coûts API
• Utilisation du stockage de base de données vectorielle

Guide de dépannage

Les équipes avec lesquelles nous travaillons signalent ces problèmes le plus fréquemment :

Aucun résultat retourné

1. Vérifiez si le contenu est indexé : /admin/config/search/search-api/index/[votre_index]
2. Vérifiez que les embeddings existent dans la base de données vectorielle
3. Testez avec des requêtes plus larges
4. Vérifiez les paramètres de seuil de similarité

Indexation lente

• Réduisez la taille du lot à 5 éléments ou moins
• Ajoutez des délais entre les lots
• Vérifiez les limites de taux API
• Considérez la mise à niveau du niveau API

Erreurs de mémoire

// Augmenter la limite de mémoire dans settings.php
ini_set('memory_limit', '512M');

// Ou dans .htaccess
php_value memory_limit 512M

Délais d'attente de connexion

Augmentez les valeurs de délai d'attente :

// Dans settings.php
$config['ai.settings']['timeout'] = 60; // secondes
$config['ai.settings']['connect_timeout'] = 10;

Débogage des appels API

Activez la journalisation détaillée :

// Dans settings.local.php pour le développement
$config['ai.settings']['debug'] = TRUE;
$config['system.logging']['error_level'] = 'verbose';

Vérifiez les journaux à /admin/reports/dblog filtrés par type « ai » ou « search_api ».

Conclusion

L'implémentation de la recherche IA dans Drupal 10 apporte de vraies améliorations à la façon dont les utilisateurs trouvent du contenu sur votre site. En suivant ce guide, vous avez configuré une recherche intelligente qui comprend le contexte, gère les variations dans la façon dont les gens recherchent et livre des résultats pertinents même avec des requêtes imparfaites.

Les points clés à retenir :

• Commencez avec un plan clair pour déterminer quels fournisseurs et bases de données correspondent à vos besoins
• Configurez les champs soigneusement - une segmentation appropriée et des données contextuelles font une énorme différence
• Testez minutieusement à chaque étape avant d'avancer

Notre expérience montre que les implémentations réussies de recherche IA nécessitent un raffinement continu. Surveillez vos analyses de recherche, recueillez les commentaires des utilisateurs et ajustez votre approche de segmentation et vos modèles d'embedding au fur et à mesure que vous apprenez ce qui fonctionne le mieux pour votre contenu et votre audience spécifiques.

Construire une recherche IA pour Drupal demande une attention particulière à la configuration API, au mappage des champs et aux paramètres d'index. Si vous planifiez d'implémenter une recherche sémantique pour votre site Drupal et souhaitez de l'aide pour évaluer quels modèles d'embedding et bases de données vectorielles serviraient le mieux votre structure de contenu et vos modèles de recherche, nous pouvons examiner vos exigences et recommander une approche d'implémentation qui équilibre performance, coût et qualité de recherche pour votre cas d'usage spécifique.

By the end, you'll have a working AI search implementation that understands user intent, handles typos and synonyms, and delivers relevant results even when users don't know the exact keywords to use.

Prerequisites

Before you begin implementing AI search, make sure you have:

• Drupal 10.1 or higher installed and running
• Composer available for module installation
• Drush installed for command-line operations
• Admin access to your Drupal site
• API credentials from at least one provider (OpenAI, Anthropic, or similar)
• Basic understanding of Drupal's module system and configuration management

We've found that teams starting with cloud-based providers like OpenAI have an easier initial setup, while those with privacy requirements often prefer self-hosted options using Ollama and local vector databases.

You'll also need to decide on your vector database. Popular choices include:

• Pinecone (cloud-based, easy setup)
• Milvus (self-hosted or cloud)
• PostgreSQL with pgvector (if you already use PostgreSQL)
• Zilliz (managed Milvus cloud service)

Step-by-Step Implementation

Step 1: Install Required Modules

Start by installing the core modules needed for AI search functionality:

composer require drupal/ai drupal/key drupal/search_api

These three modules form the foundation:

• drupal/ai provides the AI framework and includes the ai_search submodule
• drupal/key securely stores your API credentials
• drupal/search_api creates the search infrastructure

Depending on your chosen providers, add specific modules:

# For OpenAI users
composer require drupal/ai_provider_openai
# For Milvus vector database
composer require drupal/ai_vdb_provider_milvus
# For PostgreSQL with pgvector
composer require drupal/ai_vdb_provider_postgres
# For self-hosted Ollama
composer require drupal/ai_provider_ollama

Step 2: Enable the Modules

After installation, enable the modules using Drush:

drush en ai ai_search ai_api_explorer key search_api

Then enable your specific provider modules:

# Example for OpenAI and Pinecone setup
drush en ai_provider_openai ai_vdb_provider_pinecone

Clear the cache to ensure all configurations load properly:

drush cr

Step 3: Configure API Keys

Navigate to Configuration > System > Key in your Drupal admin interface. Create a new key for each API service you're using:

1. Click "Add key"
2. Give it a descriptive name (e.g., "OpenAI API Key")
3. Select "Key type" as "Authentication"
4. Choose "Key provider" (we recommend "Configuration" for development, "File" for production)
5. Enter your API key value
6. Save the configuration

Repeat this process for your vector database API key if using a cloud service.

Step 4: Set Up the AI Provider

Go to Configuration > AI > Provider settings and configure your chosen provider:

For OpenAI:

1. Select "OpenAI" as the provider
2. Choose the API key you created earlier
3. Enter your OpenAI organization ID (use the ID, not the organization name)
4. Select your preferred model (text-embedding-3-small works well for most use cases)
5. Save the configuration

Step 5: Configure Vector Database

Navigate to Configuration > AI > VDB Providers and set up your vector database:

For Milvus:

Host: your-milvus-server.com
Port: 19530
Database: default
Collection: drupal_content
Dimension: 1536 (for OpenAI embeddings)
Similarity Metric: Cosine

For PostgreSQL with pgvector:

Host: localhost
Port: 5432
Database: drupal_vectors
Table: content_embeddings
Dimension: 1536

Test the connection before saving to ensure everything connects properly.

Step 6: Create the Search API Server

1. Navigate to Configuration > Search and metadata > Search API
2. Click "Add server"
3. Enter a name like "AI Search Server"
4. For backend, select "AI Search"
5. Configure these settings:

• Embeddings engine: Your AI provider (e.g., OpenAI)
• Model: text-embedding-3-small (or your preferred model)
• Vector Database: Your configured VDB provider
• Chunk size: 512 tokens (adjust based on your content)
• Overlap: 50 tokens (helps maintain context between chunks)

Step 7: Create and Configure the Search Index

1. In Search API, click "Add index"
2. Name it something descriptive like "AI Content Index"
3. Select the content types to index (Articles, Pages, etc.)
4. Choose your AI Search Server
5. Configure fields carefully:

Main content field (this gets chunked and embedded):

• Select your body field or main content area
• This will be split into chunks for processing

Contextual fields (added to each chunk for better understanding):

• Title
• Summary/teaser
• Tags or categories
• Author information

Filterable fields (for faceted search):

• Content type
• Publication date
• Category terms

Step 8: Index Your Content

After configuring the index, you need to process your content:

1. Go to your index's "View" tab
2. Click "Index now" to start processing
3. For sites with lots of content, adjust the batch size:

// In settings.php for large sites
$config['search_api.index.ai_content_index']['options']['batch_size'] = 5;

Monitor the indexing progress. Each piece of content gets:

• Split into chunks
• Sent to the AI provider for embedding generation
• Stored in the vector database with metadata

Step 9: Test Your Implementation

Use the AI API Explorer to verify everything works:

1. Navigate to /admin/config/ai/explorers/vector_db_generator
2. Enter a test query
3. Check that results return with relevance scores
4. Verify the content matches your expectations

Example test queries to try:

• A question about your content
• A misspelled search term
• A conceptual query using different words than your content

Step 10: Add Search Interface

Finally, add the search interface to your site:

For a search block:

1. Go to Structure > Block layout
2. Click "Place block" in your desired region
3. Search for "AI Search" block
4. Configure the block settings
5. Save and test on your site

For a dedicated search page, create a custom view using the Search API index.

Code Examples with Explanations

Custom Search Implementation

Here's how to programmatically query your AI search:

use Drupal\search_api\Entity\Index;
function custom_ai_search($query_text) {
  // Load your AI search index
  $index = Index::load('ai_content_index');
  
  // Create query
  $query = $index->query();
  
  // Set the search string
  $query->keys($query_text);
  
  // Set result limit
  $query->range(0, 10);
  
  // Execute search
  $results = $query->execute();
  
  // Process results
  $items = [];
  foreach ($results->getResultItems() as $item) {
    $items[] = [
      'title' => $item->getField('title')->getValues()[0],
      'excerpt' => $item->getExcerpt(),
      'score' => $item->getScore(),
      'url' => $item->getOriginalObject()->toUrl()->toString(),
    ];
  }
  
  return $items;
}

Embedding Generation Example

If you need to generate embeddings directly:

use Drupal\ai\Service\AiProviderManager;
function generate_embedding($text) {
  // Get the AI provider service
  $ai_manager = \Drupal::service('ai.provider_manager');
  
  // Get your configured provider
  $provider = $ai_manager->getProvider('openai');
  
  // Generate embedding
  $embedding = $provider->embeddings($text, [
    'model' => 'text-embedding-3-small',
  ]);
  
  return $embedding;
}

Vector Database Query

Direct vector database queries for custom implementations:

use Drupal\ai_vdb_provider\Service\VectorDatabaseManager;
function search_vectors($embedding, $limit = 10) {
  // Get vector database service
  $vdb_manager = \Drupal::service('ai.vdb_manager');
  
  // Get your configured database
  $vdb = $vdb_manager->getDatabase('milvus');
  
  // Perform similarity search
  $results = $vdb->search([
    'vector' => $embedding,
    'limit' => $limit,
    'metric' => 'cosine',
  ]);
  
  return $results;
}

Common Mistakes to Avoid

1. Incorrect Field Configuration

The most frequent issue we see is misconfigured fields in the search index. Make sure:

• Only one field is set as "Main content" (the field that gets chunked)
• Contextual fields are marked as "Contextual" not "Main"
• Don't index unnecessary fields that bloat your vectors

2. API Key and Organization ID Issues

When using OpenAI, always use the organization ID (starts with "org-"), not the organization name. You can find this in your OpenAI account settings.

3. Oversized Chunks

Keeping chunks too large leads to:

• Higher API costs
• Less precise search results
• Timeout errors during indexing

Start with 512 token chunks and adjust based on your content structure.

4. Missing Error Handling

Always implement fallbacks:

try {
  $results = custom_ai_search($query);
} catch (\Exception $e) {
  // Fall back to standard search
  \Drupal::logger('ai_search')->error('AI search failed: @message', [
    '@message' => $e->getMessage(),
  ]);
  $results = fallback_keyword_search($query);
}

5. Ignoring Rate Limits

Our experience shows that API rate limits catch many teams off guard. Monitor your usage and implement throttling:

// Add delays between batch operations
$config['ai.settings']['batch_delay'] = 1000; // milliseconds

Testing and Verification Steps

1. Verify Module Installation

Run this command to confirm all modules are enabled:

drush pm:list --type=module --status=enabled | grep -E "ai|search_api|key"

2. Test API Connectivity

Use the AI API Explorer at /admin/config/ai/explorers/ai_provider to test:

• Send a simple text for embedding
• Verify you receive a vector array back
• Check the vector dimensions match your configuration

3. Validate Vector Database

Test vector database operations at /admin/config/ai/explorers/vector_db:

1. Create a test collection
2. Insert a sample vector
3. Perform a similarity search
4. Delete the test collection

4. Check Index Status

Monitor your search index at /admin/config/search/search-api:

• Verify items are being indexed
• Check for any error messages
• Review the index log for issues

5. Query Testing Checklist

Test these query types to ensure full functionality:

• Exact keyword match
• Synonym search (e.g., "car" finding "automobile")
• Typo tolerance (e.g., "drupla" finding "Drupal")
• Question-based search
• Conceptual search (finding related content without exact terms)

6. Performance Monitoring

Track these metrics:

• Indexing speed (items per minute)
• Query response time
• API usage and costs
• Vector database storage usage

Troubleshooting Guide

Teams we work with report these issues most frequently:

No Results Returned

1. Check if content is indexed: /admin/config/search/search-api/index/[your_index]
2. Verify embeddings exist in vector database
3. Test with broader queries
4. Check similarity threshold settings

Slow Indexing

• Reduce batch size to 5 or fewer items
• Add delays between batches
• Check API rate limits
• Consider upgrading API tier

Memory Errors

// Increase memory limit in settings.php
ini_set('memory_limit', '512M');
// Or in .htaccess
php_value memory_limit 512M

Connection Timeouts

Increase timeout values:

// In settings.php
$config['ai.settings']['timeout'] = 60; // seconds
$config['ai.settings']['connect_timeout'] = 10;

Debugging API Calls

Enable verbose logging:

// In settings.local.php for development
$config['ai.settings']['debug'] = TRUE;
$config['system.logging']['error_level'] = 'verbose';

Check logs at /admin/reports/dblog filtered by type "ai" or "search_api".

Conclusion

Implementing AI search in Drupal 10 brings real improvements to how users find content on your site. Following this guide, you've set up intelligent search that understands context, handles variations in how people search, and delivers relevant results even with imperfect queries.

The key points to remember:

• Start with a clear plan for which providers and databases fit your needs
• Configure fields thoughtfully - proper chunking and contextual data make a huge difference
• Test thoroughly at each step before moving forward

Our experience shows that successful AI search implementations require ongoing refinement. Monitor your search analytics, gather user feedback, and adjust your chunking approach and embedding models as you learn what works best for your specific content and audience.

Building AI search for Drupal requires careful attention to API configuration, field mapping, and index settings. If you're planning to implement semantic search for your Drupal site and want help evaluating which embedding models and vector databases would best serve your content structure and search patterns, we can review your requirements and recommend an implementation approach that balances performance, cost, and search quality for your specific use case.