Référence d’application. Il s’agit d’une architecture illustrative et d’une liste de contrôle du périmètre, et non d’un projet client vérifié ou d’un déploiement mesuré. Les technologies, le périmètre d’intégration et les éléments livrés sont définis en fonction du cahier des charges réel.
Scénario et contraintes
Une entreprise souhaite obtenir des réponses générées par l’IA à partir de sa propre documentation produit, de ses politiques ou de son historique de support. Les exigences qui déterminent réellement l’architecture sont les suivantes : les réponses doivent citer leur source, le système doit indiquer qu’il ne sait pas plutôt que d’inventer une réponse, le coût par conversation doit être plafonné, et la qualité doit être mesurable avant et après toute modification du prompt ou du modèle.
Architecture
Couches et responsabilités
| Couche | Technologie | Responsabilité |
|---|---|---|
| Ingestion | Workers Python | Analyse des documents, découpage en segments, génération des embeddings et extraction des métadonnées. S’exécute sous forme de pipeline afin qu’une réindexation soit une opération courante, et non une reconstruction. |
| Stockage vectoriel | PostgreSQL + pgvector | Stockage des embeddings des segments avec les métadonnées relationnelles. Une seule base de données, plutôt qu’un service vectoriel distinct, simplifie la gestion des autorisations et des sauvegardes à cette échelle. |
| Récupération | Service Go | Recherche hybride : similarité vectorielle et correspondance par mots-clés, puis reranking. Le rappel par mots-clés détecte les numéros de pièces et les codes exacts que les embeddings manquent régulièrement. |
| Génération des réponses | Service Go appelant l’API du modèle | Assemblage du prompt avec le contexte récupéré, application des citations, réponse en streaming et budget de tokens par requête. |
| Garde-fous | Couche applicative | Vérification du périmètre, refus lorsque la confiance de récupération est faible, filtrage des données personnelles et transmission à une file d’attente humaine. |
| Administration | Panneau d’administration Vue | Gestion des documents, déclenchement des réindexations, revue des conversations, jeu d’évaluation et tableau de bord des coûts. |
Modèle de données
Les tables ci-dessous portent les règles dont dépend tout le reste. Une mauvaise conception transforme une démonstration fonctionnelle en un système impossible à étendre.
Entités principales
| Entité | Champs clés, relations et règles |
|---|---|
| document / version | Document source avec historique des versions et dates d’entrée en vigueur, afin qu’une réponse puisse être rattachée à la révision du document qui l’a produite. |
| chunk | Segment de texte avec vecteur d’embedding, chemin de titres, nombre de tokens et pointeur vers son document et sa position — c’est la position qui permet à une citation de pointer vers le bon emplacement plutôt que vers le fichier entier. |
| access_scope | Rôles ou locataires autorisés à récupérer un segment. Le filtrage s’effectue dans la requête de récupération, jamais après la génération ; sinon du contenu restreint peut se retrouver dans une réponse avant l’exécution du contrôle. |
| conversation / message | Historique des échanges avec les identifiants des segments récupérés, le modèle utilisé, le nombre de tokens et la latence par message, ce qui permet d’attribuer les coûts et la qualité à chaque conversation. |
| feedback | Votes positifs ou négatifs, corrections et indicateurs d’escalade pour chaque réponse, alimentant le jeu d’évaluation au lieu de disparaître dans un fichier journal. |
| eval_case | Question, source attendue et note d’acceptation. Exécuté à chaque modification du prompt ou du modèle afin que les régressions soient détectées avant la livraison plutôt que par les clients. |
Interfaces clés
Points de terminaison portant les règles métier
| Point de terminaison | Objectif et notes sur la concurrence |
|---|---|
| POST /api/v1/ingest | Met un document en file pour analyse, découpage en segments et génération d’embeddings ; idempotent par (document, version), de sorte qu’une nouvelle soumission remplace l’existante au lieu de créer un doublon. |
| POST /api/v1/chat | Diffuse une réponse en streaming. Applique le périmètre d’accès à la récupération, plafonne les tokens du contexte, impose les citations et renvoie un refus lorsque la confiance de récupération est inférieure au seuil configuré. |
| POST /api/v1/chat/{id}/escalate | Transmet la conversation avec tout son contexte à une file d’attente humaine — la soupape qui permet à un système plafonné de rester honnête au lieu de le forcer à répondre à tout. |
| POST /api/v1/eval/run | Exécute le jeu d’évaluation avec la configuration actuelle et indique le taux de réussite et la précision des citations pour chaque cas. |
| GET /api/v1/usage | Comptabilisation des tokens et des coûts par locataire et par période, base des limites de débit et des alertes budgétaires. |
Décisions techniques
- Récupération hybride, et non vectorielle uniquement. Une récupération exclusivement vectorielle peut manquer des identifiants exacts tels que des numéros de pièces, des codes d’erreur ou des références d’articles. Comparez les approches de récupération sur les questions d’évaluation réelles. La correspondance par mots-clés comble cette lacune et le reranking fusionne les deux résultats.
- Citations imposées, et non simplement demandées. Demander poliment à un modèle de citer ses sources n’est pas fiable. Les réponses sont validées par rapport aux identifiants des segments récupérés et rejetées lorsqu’elles ne citent rien ; c’est ce qui distingue un système auquel vous pouvez faire confiance d’un système qui semble seulement plausible.
- Seuil de refus fondé sur la confiance de récupération. Une réponse erronée formulée avec assurance coûte plus cher qu’une absence de réponse. En dessous du seuil, le système indique qu’il ne sait pas et propose une escalade.
- pgvector plutôt qu’une base de données vectorielle dédiée. Pour les volumes de documents typiques d’une seule entreprise, une instance PostgreSQL gère à la fois les vecteurs et les métadonnées, ce qui regroupe l’exploitation, les autorisations et les sauvegardes dans un seul système. Un stockage dédié ne justifie sa complexité qu’à une échelle bien plus importante.
- Jeu d’évaluation dès la première semaine. Sans lui, chaque modification de prompt est une conjecture et les régressions sont découvertes par les utilisateurs. C’est le contrôle qualité le moins coûteux d’un projet d’IA et celui qui est le plus souvent négligé.
- Accès au modèle derrière notre backend. Les clés d’API n’atteignent jamais le client, tandis que la limitation de débit, les plafonds budgétaires et le changement de modèle restent des paramètres côté serveur plutôt que de devenir une nouvelle version de l’application.
Objectifs de conception hypothétiques
Les éléments ci-dessous sont des exemples hypothétiques de planification de capacité, et non des résultats clients mesurés, une recommandation de dimensionnement validée ou un SLA. Définissez les objectifs d’acceptation propres au projet après avoir précisé la charge de travail, les appareils, les données, le matériel et les dépendances tierces ; vérifiez-les au moyen d’un pilote et de tests de charge avant de vous engager sur un objectif de production.
Objectifs de capacité et de performance
| Objectif | Valeur et hypothèse |
|---|---|
| Latence du premier token | Définir un budget hypothétique pour le premier token, puis le mesurer avec le fournisseur choisi, le pipeline de récupération et le jeu d’évaluation. La latence du fournisseur échappe au contrôle de l’application ; le streaming peut afficher la progression sans promettre un délai de réponse. |
| Récupération | Moins de 200 ms pour la recherche hybride et le reranking sur un corpus de quelques centaines de milliers de segments, avec un index pgvector approprié. |
| Coût par conversation | Plafonné par une limite de tokens de contexte et un budget par locataire avec alertes ; le montant réel dépend du choix du modèle et de la longueur des conversations et est mesuré pendant le pilote. |
| Qualité des réponses | Suivie au moyen du taux de réussite et de la précision des citations sur le jeu d’évaluation. La référence est établie pendant le pilote plutôt que promise à l’avance. |
Ce que comprend la livraison
- Code source du pipeline d’ingestion, du service de récupération et de génération des réponses, ainsi que du panneau d’administration, dans votre dépôt
- Schéma de base de données comprenant les tables des segments, des périmètres et des évaluations, ainsi que la configuration des index
- Modèles de prompts et jeu d’évaluation, tous deux versionnés avec le code
- Tableau de bord des coûts et de l’utilisation, configuration des limites de débit et des alertes budgétaires
- Notes de déploiement, procédure de gestion des clés et méthode documentée de changement de modèle
Planifier cela pour votre entreprise
Les modules ci-dessus constituent un point de départ, et non un package fixe. Nous réduisons généralement la première version à un workflow principal et un workflow d’administration, puis nous l’étendons lorsque l’utilisation réelle montre où se situent effectivement la charge et les cas limites. Envoyez un cahier des charges ciblé et nous le comparerons à cette architecture pour vous indiquer quelles parties ne sont pas encore nécessaires.