RAG avec Laravel : interroger vos documents avec l'IA

Un modèle de langage connaît le monde, mais pas vos documents : procédures internes, catalogue, base de connaissances, contrats. Le RAG (Retrieval-Augmented Generation, génération augmentée par la recherche) résout ce problème : on retrouve d'abord les passages pertinents dans vos données, puis on les fournit au modèle pour qu'il réponde en s'appuyant dessus. Laravel dispose désormais d'outils natifs pour la recherche vectorielle, ce qui rend l'approche accessible sans infrastructure exotique.

Le principe en trois temps

Indexer : découper les documents en passages, calculer un embedding (un vecteur numérique qui représente le sens du texte) pour chacun, et les stocker.
Retrouver : à chaque question, calculer son embedding et chercher les passages dont le vecteur est le plus proche.
Générer : transmettre la question et les passages retrouvés au modèle, avec la consigne de répondre uniquement à partir d'eux et de citer ses sources.

1. Préparer la base de données

La recherche vectorielle de Laravel s'appuie sur PostgreSQL avec l'extension pgvector (ou MariaDB 11.7 et plus récent), et sur le SDK IA de Laravel pour générer les embeddings. D'après la documentation officielle, la migration ressemble à ceci :

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});

Le nombre de dimensions dépend du modèle d'embeddings choisi : il doit correspondre exactement. L'appel à index() crée un index HNSW, qui accélère nettement la recherche sur de gros volumes. Côté modèle, un cast dédié convertit la colonne :

protected function casts(): array
{
    return [
        'embedding' => AsVector::class,
    ];
}

2. Découper les documents

Ne stockez pas un PDF de 80 pages dans une seule ligne : le vecteur serait trop vague. Découpez en passages de quelques centaines de mots, avec un léger chevauchement pour ne pas couper une idée en deux, et conservez pour chacun la source (titre du document, page, section). Ces métadonnées permettront de citer l'origine des réponses. Réalisez l'indexation dans des jobs en file d'attente : elle appelle une API externe et peut durer longtemps. Notre article sur les files d'attente et les jobs idempotents détaille la méthode.

3. Générer les embeddings

Pour un texte unique, Laravel fournit un raccourci ; pour plusieurs passages, utilisez le SDK pour les envoyer en un seul appel :

use Illuminate\Support\Str;
use Laravel\Ai\Embeddings;

$embedding = Str::of('Texte du passage')->toEmbeddings();

$response = Embeddings::for([
    'Premier passage',
    'Deuxième passage',
])->generate();

$response->embeddings; // un tableau de vecteurs

Vérifiez le fournisseur et le modèle d'embeddings configurés : si vous changez de modèle plus tard, il faudra recalculer tous les vecteurs.

4. Rechercher par similarité

La requête de recherche se fait avec le constructeur de requêtes, comme pour n'importe quelle autre donnée :

$passages = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $question, minSimilarity: 0.4)
    ->limit(5)
    ->get();

Quelques points importants :

passer directement une chaîne de caractères génère l'embedding de la question automatiquement ;
le seuil minSimilarity est compris entre 0 et 1 : en dessous, le passage est écarté, ce qui évite de répondre avec des résultats hors sujet ;
les filtres classiques (ici l'équipe de l'utilisateur) se combinent à la recherche : c'est essentiel pour ne jamais exposer les documents d'un autre client ou service.

5. Construire la réponse

Une fois les passages retrouvés, vous composez le message envoyé au modèle, via le SDK IA ou le client de votre choix. Une consigne efficace précise :

de répondre uniquement à partir des extraits fournis ;
de dire « je ne sais pas » lorsque les extraits ne contiennent pas la réponse ;
de citer la source (titre et page) de chaque affirmation.

Renvoyez à l'utilisateur la réponse et les passages utilisés : il peut ainsi vérifier. Un RAG sans sources citées est difficile à croire, et plus difficile encore à corriger.

6. Garder les données chez vous si nécessaire

Si vos documents sont confidentiels, vous pouvez calculer les embeddings et générer les réponses avec un modèle hébergé en local : nous détaillons cette approche dans notre guide Ollama + Laravel. Et si vous voulez que des assistants externes puissent interroger cette base de connaissances de façon contrôlée, regardez comment exposer un serveur MCP avec Laravel ; le panorama Laravel et MCP donne le contexte.

7. Évaluer et surveiller

Constituez un jeu de 20 à 30 questions réelles avec leurs réponses attendues, et relancez-le à chaque changement (découpage, modèle, seuil).
Journalisez les questions sans réponse : elles révèlent les documents manquants.
Contrôlez les droits d'accès avant la recherche, jamais après.
Surveillez le coût des appels et le temps de réponse.

Conclusion

Un RAG utile n'est pas un exploit technique : c'est une chaîne simple (découper, vectoriser, rechercher, répondre en citant) dont chaque maillon se règle. Avec pgvector et les outils vectoriels de Laravel, vous pouvez bâtir un premier prototype en un après-midi, puis consacrer le reste du temps à ce qui fait la différence : la qualité des documents et l'évaluation des réponses.