Synchroniser immédiatement la base de connaissances

Permet de déclencher immédiatement la synchronisation incrémentale des connaissances sourcées d'une base de connaissances ; seule la source Google Drive est actuellement prise en charge.

Remarque :

L'interface répond immédiatement après avoir terminé la validation et la planification ; elle renvoie donc « pris en compte » et non « mis à jour ».

Limite de fréquence : au maximum 1 fois par minute pour chaque Agent / Workflow.

Méthode de requête

POST

Adresse d'appel

Choisissez le chemin correspondant au type de ressource auquel appartient l'API Key. Les paramètres de requête, la structure de réponse et les règles de limitation de débit des deux interfaces sont strictement identiques.

• Agent :

https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync

• Workflow :

https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync

Les descriptions de requête / réponse ci-dessous s'appliquent aux deux chemins ; les exemples sont écrits avec le chemin Agent.

Vérification de l'appel

Consultez les instructions d'authentification de Présentation de l'API.

Requête

Exemple de requête

• Synchroniser des bases de connaissances spécifiées :

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive",
    "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'

                    

• Synchroniser toutes les bases de connaissances de cet Agent :

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive"
}'

                    

En-têtes de requête

Paramètres de requête

Réponse

Exemple de réponse

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "accepted": true,
        "source": "google-drive",
        "matched_knowledge_base_count": 2,
        "matched_doc_count": 37,
        "matched_folder_count": 3,
        "skipped": [
            {
                "reason": "DRIVE_NOT_AUTHORIZED",
                "message": "The document owner has not authorized Google Drive, or the authorization has expired.",
                "knowledge_base_id": "6a44c3512ceb43775567391e",
                "doc_count": 8
            },
            {
                "reason": "KNOWLEDGE_BASE_NOT_FOUND",
                "message": "Knowledge base does not exist or does not belong to this agent.",
                "knowledge_base_id": "deadbeefdeadbeefdeadbeef"
            }
        ],
        "scheduled_round_running": false
    }
}

                    

Réponse en cas de succès

Valeurs de skipped[].reason

Réponse en cas d'échec

Codes d'erreur courants :

Exemple de réponse lorsque source est invalide :

                      
                      {
    "code": 40000,
    "message": "Unsupported source: sharepoint. Supported: google-drive"
}

                    

Notes d'utilisation

Ce qui est renvoyé est « pris en compte », pas « terminé »

L'interface répond immédiatement après avoir terminé la validation et la planification ; la récupération, l'analyse et la vectorisation réelles s'exécutent en arrière-plan de manière asynchrone. Ainsi, matched_doc_count indique « combien de documents seront vérifiés cette fois-ci » et non « combien de documents ont été mis à jour ». Pour confirmer le résultat final, interrogez périodiquement l'interface Obtenir la liste des documents de connaissances pour consulter l'état des documents ; lorsqu'un document passe à l'état AVAILABLE, cela signifie qu'il a fini d'être synchronisé.

Uniquement incrémental, sans consommation répétée du quota

Pour chaque document, le système compare d'abord la date de dernière modification sur Google Drive :

• Document source non modifié : ignoré, sans nouveau téléchargement, nouvelle analyse ni consommation de quota.
• Document source modifié : de nouveau récupéré, réanalysé et revectorisé.
• Nouveaux fichiers dans le dossier lié : automatiquement ajoutés en tant que documents de connaissances.

Par conséquent, appeler cette interface de manière répétée est sûr ; le contenu inchangé n'entraîne aucun coût supplémentaire.

Cette interface ne peut pas réessayer les documents dont l'analyse a échoué

Le jugement incrémental ne regarde que si le document source sur Google Drive a changé, pas l'état actuel du document.

Ainsi, un document dont l'analyse a précédemment échoué (état FAIL) ne sera pas retraité par cette interface tant que son fichier source sur Google Drive n'a pas été modifié — il sera considéré comme « document source non modifié » et directement ignoré, son état restant inchangé, et il n'apparaîtra pas non plus dans skipped.

Pour réessayer les documents dont l'analyse a échoué, utilisez l'interface Réintégrer les documents. Vous pouvez aussi effectuer une modification du fichier source sur Google Drive afin de mettre à jour sa date de dernière modification, ce qui permet à cette interface de le récupérer à nouveau.

La synchronisation supprime des documents de connaissances

Cette interface ne fait pas que des ajouts et des mises à jour ; elle supprime aussi des documents de connaissances selon l'état actuel de Google Drive.

Lorsqu'un dossier Google Drive lié devient vide, tous les documents de connaissances déjà importés depuis ce dossier sont supprimés. La condition de déclenchement est que le dossier reste accessible sur Google Drive mais qu'aucun fichier ne puisse y être listé. Le système vérifie d'abord l'accessibilité du dossier ; s'il ne parvient pas à obtenir les métadonnées du dossier (dossier déplacé, permissions modifiées, temporairement inaccessible, etc.), il ignore la suppression afin d'éviter toute suppression accidentelle.

La portée de la suppression est limitée à « ce dossier + cette base de connaissances ». Lorsqu'un même dossier Google Drive est référencé par plusieurs bases de connaissances, celles-ci n'ont aucune incidence les unes sur les autres.

Ce comportement est identique à celui de la synchronisation planifiée du système ; cette interface ne fait que le déclencher plus tôt. Toutefois, comme cette interface couvre aussi les documents pour lesquels aucun plan de synchronisation planifiée n'a été configuré lors de l'importation (documents que, normalement, aucun flux automatique ne supprimerait), vérifiez avant l'appel que le contenu des dossiers côté Google Drive est conforme à vos attentes.

Portée de la couverture

La portée de la synchronisation couvre tous les documents de la base de connaissances provenant de Google Drive, y compris ceux pour lesquels aucun plan de synchronisation planifiée n'a été configuré lors de l'importation — ces documents ne sont pas traités par les cycles planifiés du système et ne peuvent être mis à jour que via cette interface.

Limitation de débit

• Au maximum 1 fois par minute pour chaque Agent / Workflow. Les deux chemins partagent le même compteur ; changer de chemin ne contourne pas la limitation.
• Soumis également à la limite du nombre de requêtes par minute (RPM) des API de type base de connaissances du forfait de l'organisation, quota partagé avec les autres interfaces de base de connaissances.
• Si la synchronisation précédente du même Agent / Workflow n'est pas encore terminée, un nouvel appel renvoie accepted=false et reason=SYNC_IN_PROGRESS.

Relation avec la synchronisation planifiée

Cette interface et la synchronisation planifiée du système sont indépendantes et ne se bloquent pas mutuellement. Lorsque scheduled_round_running vaut true, la requête est tout de même prise en compte et n'est pas rejetée au motif qu'un cycle planifié est en cours.

Lorsque les deux traitent le même document simultanément, aucun contenu dupliqué n'est produit : le système effectue un jugement incrémental d'après la date de dernière modification du document source, et les fichiers déjà importés ne sont pas recréés.

La synchronisation planifiée s'exécute automatiquement à la fréquence configurée pour chaque base de connaissances, tandis que cette interface ignore cette fréquence et déclenche immédiatement. Les deux sont complémentaires : la synchronisation planifiée assure la mise à jour courante, cette interface répond au besoin de « synchroniser maintenant ».