L’API prend en charge les workflows de gestion des collections et des documents, de traitement du contenu et d’application de fonctionnalités d’IA telles que les réponses aux questions, la synthèse, la recherche et l’extraction structurée. Utilisez cette page pour comprendre le fonctionnement de ces éléments, puis consultez la référence d’API pour les détails de mise en œuvre au niveau des points d’entrée.
Vérifiez les points suivants :
Si vous n’avez pas configuré l’accès API, consultez la rubrique Configuration de l’accès à l’API Knowledge Base.
Un workflow type de l’API Knowledge Base suit cette séquence :
Authentification → Collection → Document → Index → Inférence → Réponse
Une collection définit le domaine de connaissances sur lequel votre application fonctionne. Lorsque vous créez une collection, la réponse inclut son espace de noms unique, que vous utilisez pour les opérations suivantes.
Par exemple :
{
"namespace": "<collection-namespace>",
"name": "example-collection"
}
Conservez l’espace de noms de la collection pour les requêtes de document et d’inférence.
Les documents sont chargés dans les collections et se voient attribuer des identifiants de document uniques.
Une réponse de chargement identifie le document afin que votre application puisse suivre le traitement et le référencer dans les demandes ultérieures.
{
"document_id": "<document-id>",
"document_name": "example.pdf"
}
Charger un document et l’indexer sont des étapes distinctes.
Le chargement transfère le fichier vers Knowledge Base. L’indexation extrait son contenu et traite ce contenu pour une utilisation par les opérations d’IA.
Votre application doit confirmer que le traitement est terminé avant de soumettre des demandes d’inférence sur le document.
Les opérations d’inférence appliquent les fonctionnalités d’IA de Knowledge Base au contenu traité.
Les opérations disponibles incluent :
Utilisez la référence API pour déterminer le point d’entrée et le schéma de requête pour l’opération que vous souhaitez effectuer.
Les réponses d’inférence renvoient le résultat généré et peuvent inclure des informations d’attribution supplémentaires.
Selon l’opération, les données d’attribution peuvent identifier le contenu source, la page et les coordonnées associées au résultat. Votre application détermine la façon dont ces informations sont présentées à l’utilisateur.
Le workflow d’application le plus simple consiste à créer une collection, ajouter un document, attendre le traitement, puis exécuter une opération d’inférence.
Créez la collection qui contiendra les documents sources pour votre application.
Conservez l’espace de noms renvoyé dans la réponse :
collection_namespace = <returned-namespace>
Vous utiliserez cette valeur lorsque vous ajouterez des documents et que vous effectuerez des opérations sur la collection.
Chargez un document dans la collection et conservez l’ID de document renvoyé :
document_id = <returned-document-id>
L’ID de document identifie le document chargé indépendamment de son nom de fichier.
Démarrez l’opération d’indexation requise, puis vérifiez le statut du document jusqu’à ce que le traitement se termine.
Ne partez pas du principe qu’un chargement réussi signifie que le document est prêt pour les opérations d’IA.
Un flux d’application typique est le suivant :
Charger le document
↓
Démarrer l’indexation
↓
Vérifier le statut de traitement
↓
Terminé
Si le traitement échoue, résolvez le problème de traitement du document avant de soumettre une requête d’inférence.
Une fois le traitement terminé, soumettez l’espace de noms de la collection, l’ID de document et toute entrée spécifique à l’opération requise par le point d’entrée.
Par exemple, une demande de questions-réponses fournit conceptuellement :
Collection : <collection-namespace>
Document : <document-id>
Question : Quelles sont les conclusions clés ?
Utilisez la référence API pour le schéma de demande réel.
Utilisez la réponse renvoyée ou les données extraites dans votre application.
Si la réponse inclut des informations d’attribution, vous pouvez les utiliser pour relier les informations générées au contenu du document source.
Le cycle de vie du document influe sur le moment où votre application peut utiliser le contenu chargé.
| Intermédiaire | Ce qu’il se passe | Action d’application |
|---|---|---|
| Télécharger | Le fichier est ajouté à Knowledge Base et reçoit un ID de document. | Conservez l’ID du document. |
| Indexation | Le contenu est extrait et traité pour une utilisation par l’IA. | Surveillez le statut du document. |
| Terminer | Le contenu traité est disponible pour l’inférence. | Soumettez les requêtes IA. |
| Echec | Le traitement a échoué. | Corrigez l’erreur avant de continuer. |
Cette distinction est particulièrement importante pour les workflows automatisés. Une application doit vérifier le statut de traitement plutôt que d’envoyer immédiatement une requête d’inférence après le chargement.
Choisissez une opération en fonction de ce que votre application doit faire avec le contenu source.
Utilisez les Q&R pour soumettre des questions en langage naturel sur la collection ou le contenu du document.
L’API fournit des Q&R en streaming et sans streaming.
Q&R en streaming renvoie la réponse de manière incrémentale au fur et à mesure qu’elle est générée. Utilisez-la lorsque votre interface doit afficher le contenu généré progressivement.
Le mode Q&R en streaming permet également de déterminer si les instructions personnalisées doivent être appliquées à la demande. Vous pouvez également contrôler si un raisonnement est généré pour une réponse de questions-réponses en streaming.
Questions-réponses sans streaming attend que la génération soit terminée et renvoie la réponse finale. Utilisez cette option lorsque votre application n’a pas besoin d’afficher une sortie partielle.
Utilisez la synthèse pour générer une représentation condensée du contenu du document.
La référence API définit les exigences de demande actuelles et les entrées prises en charge.
Utilisez la recherche contextuelle pour récupérer le contenu pertinent par rapport au texte de recherche spécifié.
Cela peut aider les applications à identifier le matériel source pertinent sans générer de réponse conversationnelle.
Utilisez l’extraction lorsque votre application a besoin de valeurs structurées provenant du contenu du document.
Une définition d’extraction peut identifier des informations telles que :
Nom de propriété : contract_value
Type : entier
Description : Valeur du contrat d’accord
Prompt : Extrayez la valeur d’accord la plus importante en dollars.
Le résultat renvoyé peut inclure la valeur extraite, les informations confidentielles et l’attribution source.
L’API fournit plusieurs moyens de déterminer quel contenu participe à une requête.
Utilisez les identifiants de collection et de document pour définir le contenu principal disponible pour une opération.
Les balises sont associées aux documents plutôt qu’aux collections.
Les balises de document sont disponibles uniquement via l’API Knowledge Base et ne sont pas exposées dans l’interface utilisateur standard.
Vous pouvez utiliser les balises avec les opérations prises en charge pour filtrer les documents pris en compte pour une requête. Par exemple, une application pourrait baliser un groupe de documents comme documents financiers et restreindre une question aux documents portant cette balise.
Les pièces jointes sont séparées des documents de la collection.
L’ajout d’une pièce jointe à une conversation n’ajoute pas ce fichier à la collection. La pièce jointe peut toujours contribuer au contexte d’une réponse générée, ainsi qu’au contenu de la collection et à l’historique de chat.
Utilisez les points d’entrée de pièce jointe lorsque votre application a besoin de contenu temporaire ou spécifique à une conversation sans l’ajouter de façon permanente à une collection.
Les réponses d’inférence peuvent inclure des informations d’attribution qui relient la sortie générée au contenu source d’appui.
Les données d’attribution peuvent inclure des informations telles que :
L’API fournit ces informations sous forme de données. Votre application est responsable de décider comment les présenter.
Par exemple, une application peut utiliser les coordonnées renvoyées pour créer une fonctionnalité de mise en évidence des sources qui identifie l’emplacement correspondant à une réponse générée.
Les opérations d’API utilisent les autorisations disponibles pour l’identité authentifiée.
Une demande peut échouer si l’identité authentifiée n’a pas accès à la collection, au document ou à l’opération demandée.
Lors du dépannage :
Le X-Request-ID identifie la demande à travers les services de Knowledge Base et peut faciliter l’enquête sur une demande ayant échoué.
Utilisez la démonstration Python lorsque vous souhaitez des exemples pratiques qui illustrent ces concepts dans une application.
Prise en main de la démo Python de Knowledge Base
Utilisez la référence API lorsque vous êtes prêt à implémenter une opération spécifique.
