RAG en PHP avec le Laravel AI SDK : construire un agent de recherche documentaire
Le Retrieval-Augmented Generation (RAG) s'impose progressivement comme une approche incontournable pour les applications qui doivent interroger de grandes bases de documents. Jusqu'ici, mettre en place un pipeline RAG en PHP impliquait souvent de déléguer une partie du travail à des scripts Python ou à des services tiers. Avec le Laravel AI SDK, l'équipe Laravel propose une solution native qui change la donne.
Qu'est-ce que le Laravel AI SDK ?
Le Laravel AI SDK est un package officiel qui unifie plusieurs fournisseurs d'IA — OpenAI, Anthropic, Gemini et d'autres — derrière une interface unique et cohérente. L'installation se fait via Composer, et la configuration se limite à renseigner les clés API dans le fichier .env.
Trois fonctionnalités du SDK structurent une architecture RAG solide :
- Queue support : le traitement des fichiers uploadés se fait de manière asynchrone via
->queue(), sans bloquer le cycle HTTP.
- Embeddings vectoriels : le SDK génère et stocke les vecteurs sémantiques dans une base PostgreSQL avec l'extension
pgvector.
- Streaming : les réponses du modèle sont envoyées au navigateur en temps réel, avant même que le modèle ait terminé de générer sa réponse complète.
Ces trois briques permettent de construire un agent de recherche documentaire robuste et entièrement dans l'écosystème PHP/Laravel.
Architecture d'un agent de recherche documentaire
L'article source de Laravel décrit un cas d'usage concret : permettre à des utilisateurs de déposer des fichiers (wiki de support, documentation interne, archives juridiques), puis d'interroger ces documents en langage naturel.
Le flux de traitement se déroule en plusieurs étapes :
- Upload du fichier : l'utilisateur dépose un document via l'interface web.
- Traitement asynchrone : un job Laravel est dispatché en queue pour extraire le texte, le découper en chunks, puis générer les embeddings via l'API du fournisseur choisi.
- Stockage vectoriel : les vecteurs sont persistés dans PostgreSQL grâce à
pgvector, une extension qui permet les recherches par similarité cosinus directement en SQL.
- Requête utilisateur : lorsqu'un utilisateur pose une question, sa requête est elle-même convertie en vecteur, puis une recherche de similarité retrouve les chunks les plus pertinents.
- Génération augmentée : les chunks retrouvés sont injectés dans le contexte du modèle de langage, qui génère une réponse précise et sourcée.
- Streaming vers le navigateur : la réponse s'affiche progressivement, sans attendre la fin de la génération.
Cette architecture est typique du pattern RAG, mais sa mise en œuvre reste ici entièrement dans Laravel, sans dépendance externe à un orchestrateur Python comme LangChain ou LlamaIndex.
Points techniques à retenir
Sécurité des clés API
L'article insiste sur un point souvent négligé en phase de développement : garder les clés API hors du versioning. Laravel Cloud propose un stockage chiffré des variables d'environnement, ce qui élimine le risque d'exposer accidentellement une clé OpenAI dans un dépôt Git.
Pour les projets hébergés ailleurs, le principe reste le même : utiliser un gestionnaire de secrets (AWS Secrets Manager, Vault, etc.) plutôt que de stocker les clés en clair dans un .env commité.
pgvector et PostgreSQL
L'extension pgvector transforme PostgreSQL en base de données vectorielle. Elle permet de stocker des vecteurs de haute dimension et d'effectuer des recherches par similarité (cosinus, distance euclidienne, produit scalaire) directement via SQL standard.
Pour une application Laravel, cela signifie qu'on peut utiliser Eloquent et les migrations habituelles pour gérer les embeddings, sans avoir à introduire une base de données spécialisée comme Pinecone ou Weaviate. C'est un avantage non négligeable en termes de simplicité opérationnelle.
Traitement asynchrone et scalabilité
L'embedding d'un document peut prendre plusieurs secondes, voire davantage pour des fichiers volumineux. Traiter cette opération de manière synchrone dans un contrôleur HTTP dégraderait l'expérience utilisateur et risquerait des timeouts. L'utilisation des queues Laravel permet de découpler l'upload de l'indexation, et de scaler indépendamment le nombre de workers selon la charge.
Pourquoi c'est important pour les développeurs PHP ?
Pendant longtemps, l'intégration de l'IA dans des projets PHP se heurtait à un problème pratique : l'essentiel de l'outillage (frameworks d'agents, gestion des embeddings, orchestration de prompts) était centré sur l'écosystème Python. Les développeurs PHP devaient soit apprendre Python, soit recourir à des API REST tierces en perdant le bénéfice de leur framework habituel.
Le Laravel AI SDK comble ce fossé. En proposant une abstraction sur les principaux fournisseurs d'IA et en s'intégrant nativement aux mécanismes Laravel (queues, événements, Eloquent), il permet de construire des fonctionnalités IA sans sortir de l'écosystème PHP.
Pour les équipes travaillant sur des projets Symfony, des solutions comparables émergent également (AI Bundle, intégrations Symfony HTTP Client), mais le Laravel AI SDK représente aujourd'hui l'une des intégrations les plus complètes et les mieux documentées côté PHP.
Conclusion
Le RAG n'est plus réservé aux équipes disposant d'une expertise Python ou d'un budget pour des services SaaS spécialisés. Avec le Laravel AI SDK, les développeurs PHP peuvent implémenter un pipeline complet — upload, embedding, recherche vectorielle, génération augmentée et streaming — dans un environnement qu'ils maîtrisent déjà.
Le tutoriel original publié par l'équipe Laravel constitue une excellente base de départ, avec un exemple concret déployable sur Laravel Cloud. Pour les équipes MulerTech souhaitant intégrer des capacités de recherche sémantique dans leurs projets PHP/Symfony, il vaut la peine d'étudier cette approche et d'en tirer les patterns applicables dans d'autres contextes.
📖 Source originale : Laravel AI Integration: Build a Document Search Agent — Laravel Blog
