Ajouter une API de base de connaissances à votre application : le guide développeur
Ajouter une API de base de connaissances à votre application revient à brancher trois briques : un endpoint de recherche ou de réponse, une clé API pour authentifier vos appels, et une interface qui affiche les passages sources à côté de la réponse générée. Ce guide détaille les endpoints REST à prévoir, la gestion des clés, les leviers pour maîtriser la latence et le coût par requête, et la bonne façon de citer les sources dans votre UI.
Pourquoi une API dédiée plutôt qu'un simple appel à un modèle de langage
Interroger directement un modèle de langage sans lui fournir de contexte documentaire produit des réponses plausibles mais non vérifiables : pas de passage source, pas de garantie que l'information vient de vos documents plutôt que de la mémoire générale du modèle. Une API de base de connaissances ajoute l'étape qui manque : elle cherche dans vos documents indexés, récupère les passages pertinents, puis construit une réponse qui s'appuie dessus. Le mécanisme complet (découpage, indexation, recherche, génération) est détaillé dans Comment fonctionne le RAG, étape par étape et dans Qu'est-ce que le RAG (génération augmentée par récupération) ? si vous voulez le mécanisme complet avant de coder.
Côté intégration, cela change la façon de concevoir votre API : au lieu d'un seul endpoint de complétion, vous avez besoin d'au moins deux modes d'appel (recherche brute et réponse sourcée), d'un système de clés pour séparer vos usages, et d'une UI capable d'afficher les citations sans casser l'expérience utilisateur.
Les endpoints essentiels d'une API de base de connaissances
L'endpoint de recherche (mode passages)
Ce mode renvoie les extraits les plus pertinents pour une requête, sans génération de texte. Il est utile quand votre application affiche elle-même les résultats (un moteur de recherche interne, un widget de suggestions) ou quand vous voulez composer la réponse finale avec votre propre logique. La qualité de ce mode dépend directement du moteur de recherche sous-jacent : une recherche purement sémantique rate parfois les correspondances exactes (une référence, un numéro d'article), d'où l'intérêt d'une recherche hybride combinant mots-clés et vecteurs.
L'endpoint de réponse (mode sourcé)
Ce mode renvoie une réponse rédigée, construite à partir des passages récupérés, accompagnée des références exactes à citer. C'est le mode à privilégier dans un chatbot, un assistant de support ou un outil d'aide à la décision, parce qu'il livre directement une réponse exploitable tout en gardant la traçabilité.
L'endpoint d'ingestion
Pour que l'API ait quelque chose à chercher, il faut un endpoint (ou une interface) d'envoi de documents : PDF, Word, texte, Markdown. Ce flux déclenche l'extraction, le découpage en morceaux et l'indexation. Si vous préférez ne pas gérer ce pipeline vous-même, une plateforme comme Kopik s'en charge automatiquement : vous déposez les fichiers depuis la création d'une base et l'indexation se fait côté serveur.
Trois modes d'appel courants
| Mode | Ce qu'il renvoie | Cas d'usage typique |
|---|---|---|
| Recherche (passages) | Liste d'extraits classés par pertinence | Moteur de recherche interne, widget autocomplétion |
| Réponse sourcée | Texte rédigé + citations des passages utilisés | Chatbot, assistant métier, support client |
| Ingestion | Confirmation d'indexation, identifiants de documents | Mise à jour du corpus documentaire |
Clés API et gestion des accès
Une clé API sert à authentifier vos appels et à mesurer la consommation (crédits ou quota) séparément par usage. En pratique, prévoyez plusieurs clés distinctes plutôt qu'une seule partagée partout :
- Une clé par environnement (développement, recherche, production) pour isoler les coûts et éviter qu'un bug en test ne consomme le quota de production
- Une clé par base de connaissances si votre application interroge plusieurs corpus (documentation produit, base juridique, FAQ support)
- Une rotation régulière des clés sensibles, surtout si elles ont transité dans un historique de commits ou un outil tiers
- Jamais de clé exposée côté navigateur : les appels authentifiés doivent passer par votre backend, qui relaie la requête vers l'API
Clé API vs accès MCP
Si votre cible est un agent IA plutôt qu'une application web (Claude, Cursor, un agent interne), l'intégration peut se faire via un serveur MCP plutôt qu'un appel REST classique. Le principe reste le même (authentification, requête, réponse sourcée) mais le client est l'agent lui-même. Voir Connecter Claude, Cursor ou ChatGPT à une base de connaissances.
Latence : ce qui prend du temps et comment l'optimiser
Une requête vers une API de base de connaissances traverse plusieurs étapes, chacune ajoutant quelques dizaines à quelques centaines de millisecondes : transformation de la question en vecteur, recherche dans l'index, éventuel reclassement des résultats, puis génération de la réponse par le modèle de langage. Cette dernière étape est généralement la plus longue, surtout si la réponse est détaillée.
- Utilisez le mode passages seul quand vous n'avez pas besoin de texte rédigé : vous supprimez l'étape de génération, souvent la plus lente
- Activez le streaming de la réponse si votre interface le permet, pour afficher les premiers mots avant la fin de la génération
- Mettez en cache les questions fréquentes côté application, surtout pour une FAQ ou une documentation qui change peu
- Limitez le nombre de passages renvoyés au strict nécessaire : plus le contexte transmis au modèle est long, plus la génération est lente
Une recherche hybride bien réglée (mots-clés plus vecteurs) réduit aussi la latence perçue, parce qu'elle trouve le bon passage dès le premier essai au lieu de nécessiter plusieurs requêtes de reformulation. Le détail de ce mécanisme est expliqué dans Recherche hybride : pourquoi combiner mots-clés et vecteurs bat chaque méthode seule.
Coûts : crédits par question, abonnement, et répartition public/privé
La plupart des API de bases de connaissances facturent soit au crédit prépayé par question posée, soit via un abonnement mensuel avec une jauge d'usage. Le bon modèle dépend du volume et de la prévisibilité de vos appels.
Comparer les modèles de facturation
| Modèle | Avantage | À surveiller |
|---|---|---|
| Crédits prépayés | Vous ne payez que ce que vous consommez | Prévoir une alerte de seuil pour ne pas être coupé en pleine journée de production |
| Abonnement mensuel (ex. 12 €/mois) | Coût fixe et prévisible pour un usage régulier | Vérifier que la jauge couvre bien votre volume de pointe |
| Base publique payante | Les créateurs gardent jusqu'à 70 % du prix fixé par question | Pertinent si vous exposez un savoir que d'autres développeurs veulent interroger |
Si votre application interroge une base privée réservée à votre équipe, seul le coût par question compte. Si à l'inverse vous envisagez de publier une base pour d'autres développeurs (documentation technique, référentiel métier, jurisprudence commentée), vous entrez dans une logique différente, plus proche de la monétisation que de l'intégration pure : voir Vendre son expertise aux agents IA pour la mécanique de prix et de reversement.
Afficher les sources dans votre interface
Une réponse sourcée perd une grande partie de son intérêt si l'utilisateur ne peut pas vérifier d'où elle vient. Trois formats fonctionnent bien en pratique :
- Des notes de bas de page numérotées, cliquables, qui ouvrent le passage exact dans un panneau latéral
- Un passage mis en évidence directement sous la réponse, avec le nom du document et, si possible, le numéro de page ou de section
- Un lien direct vers le document source complet, pour les cas où l'utilisateur veut lire le contexte élargi
Ce travail de vérification ne doit pas reposer uniquement sur l'utilisateur final : côté développeur, il vaut la peine de tester systématiquement si les citations renvoyées correspondent réellement au contenu affiché dans la réponse, surtout avant une mise en production. La méthode est détaillée dans Réponses d'IA avec citations : comment vérifier une réponse sur vos documents.
Ne masquez jamais les sources par défaut
Même si l'interface est pensée pour un usage grand public, gardez au moins un lien discret vers la source. Cela rassure l'utilisateur technique et facilite vos propres audits qualité quand une réponse semble douteuse.
Checklist avant la mise en production
- Séparer les clés API par environnement et par base de connaissances
- Choisir le bon mode d'appel (passages ou réponse sourcée) selon l'usage réel de chaque écran
- Mesurer la latence moyenne et p95 sur un échantillon de questions représentatives de vos utilisateurs
- Fixer une alerte de consommation de crédits avant d'atteindre le plafond mensuel
- Afficher systématiquement au moins une référence à la source dans l'UI, même compacte
- Documenter dans votre backend le format de réponse attendu (texte, citations, métadonnées) pour faciliter la maintenance
Prêt à brancher une base de connaissances sur votre app ?
Créez une base gratuitement, testez les endpoints de recherche et de réponse, puis générez une clé API pour votre environnement de production.
Aller plus loin
Une fois l'API branchée côté application web ou mobile, la même base peut aussi être exposée à des agents IA via un serveur MCP, sans endpoint supplémentaire à maintenir : voir MCP (Model Context Protocol) : explication simple. Vous pouvez aussi parcourir le catalogue de bases existantes pour voir des exemples réels de structuration de réponses avant de concevoir la vôtre.
Questions fréquentes
Quelle est la différence entre une API de recherche et une API de réponse (RAG) ?
L'API de recherche renvoie une liste de passages pertinents sans rédaction, tandis que l'API de réponse (mode RAG) génère un texte rédigé à partir de ces passages et fournit les citations correspondantes. La première est plus rapide et moins coûteuse, la seconde est plus directement exploitable dans un chatbot ou un assistant.
Comment réduire la latence d'une API de base de connaissances dans une application temps réel ?
Privilégiez le mode passages quand une réponse rédigée n'est pas nécessaire, activez le streaming pour afficher la réponse au fur et à mesure, limitez le nombre de passages transmis au modèle, et mettez en cache les questions fréquentes côté application.
Comment facturer l'usage d'une API de base de connaissances à mes propres utilisateurs ?
Deux approches courantes : répercuter un coût fixe via un abonnement, ou facturer à l'usage en fonction des crédits réellement consommés. Si vous exposez une base publique à d'autres développeurs, un prix par question avec reversement au créateur (jusqu'à 70 % sur Kopik) est une option à envisager.
Faut-il toujours afficher les passages sources dans l'interface utilisateur ?
Il est recommandé d'afficher au moins un lien ou une référence vers la source, même discret, pour permettre la vérification et renforcer la confiance. Masquer totalement les sources rend les réponses impossibles à auditer en cas d'erreur.
Peut-on utiliser une API de base de connaissances avec un agent IA comme Claude ou Cursor ?
Oui, via un serveur MCP qui expose la base de connaissances comme un outil interrogeable directement par l'agent, en plus ou à la place de l'intégration REST classique.
Comment sécuriser une clé API de base de connaissances côté application web ?
La clé ne doit jamais être exposée dans le code côté navigateur. Les appels authentifiés doivent transiter par votre backend, qui conserve la clé côté serveur et relaie les requêtes vers l'API.
Recevez la newsletter Kopik
Nouvelles bases de connaissances, guides sur le RAG et nouveautés du produit. Un mail toutes les une à deux semaines, désinscription en un clic.
En vous abonnant, vous acceptez de recevoir notre newsletter. Votre adresse n'est jamais partagée.