Wissensdatenbank sofort synchronisieren

Löst sofort die inkrementelle Synchronisierung des verbundenen Wissens einer Wissensdatenbank aus; derzeit wird nur Google Drive als Quelle unterstützt.

Hinweis:

Die Schnittstelle kehrt sofort nach Abschluss von Prüfung und Planung zurück; zurückgegeben wird daher „angenommen“ und nicht „aktualisiert“.

Frequenzbegrenzung: höchstens 1-mal pro Minute je Agent / Workflow.

Anfragemethode

POST

Anfrage-URL

Wählen Sie den passenden Pfad je nach Ressourcentyp, zu dem der API Key gehört. Anfrageparameter, Antwortstruktur und Drosselungsregeln der beiden Schnittstellen sind vollständig identisch.

• Agent:

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

• Workflow:

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

Die nachfolgenden Erläuterungen zu Anfrage / Antwort gelten für beide Pfade; die Beispiele sind mit dem Agent-Pfad geschrieben.

Authentifizierung der Anfrage

Einzelheiten finden Sie in den Erläuterungen zur Authentifizierung in der API-Übersicht.

Anfrage

Beispielanfrage

• Bestimmte Wissensdatenbanken synchronisieren:

                      
                      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"]
}'

                    

• Alle Wissensdatenbanken dieses Agent synchronisieren:

                      
                      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"
}'

                    

Anfrage-Header

Anfrageparameter

Antwort

Beispielantwort

                      
                      {
    "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
    }
}

                    

Erfolgreiche Antwort

Werte von skipped[].reason

Fehlerantwort

Häufige Fehlercodes:

Beispielantwort bei ungültigem source:

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

                    

Nutzungshinweise

Zurückgegeben wird „angenommen“, nicht „abgeschlossen“

Die Schnittstelle kehrt sofort nach Abschluss von Prüfung und Planung zurück; der eigentliche Abruf, das Parsen und die Vektorisierung erfolgen asynchron im Hintergrund. Daher gibt matched_doc_count an, „wie viele Dokumente diesmal geprüft werden“, nicht „wie viele Dokumente aktualisiert wurden“. Um das Endergebnis zu bestätigen, rufen Sie die Schnittstelle Dokumentenliste abrufen per Polling ab und prüfen den Dokumentstatus; wechselt der Status zu AVAILABLE, ist das Dokument fertig synchronisiert.

Nur inkrementell, kein wiederholter Guthabenverbrauch

Für jedes Dokument vergleicht das System zuerst die letzte Änderungszeit in Google Drive:

• Quelldokument unverändert: übersprungen, kein erneuter Download, kein erneutes Parsen, kein Guthabenverbrauch.
• Quelldokument geändert: erneut abgerufen sowie erneut geparst und vektorisiert.
• Neue Dateien im gebundenen Ordner: automatisch als Wissensdokument hinzugefügt.

Daher ist ein wiederholter Aufruf dieser Schnittstelle sicher; für unveränderte Inhalte entstehen keine zusätzlichen Kosten.

Diese Schnittstelle kann fehlgeschlagene Dokumente nicht erneut parsen

Die inkrementelle Beurteilung betrachtet nur, ob sich das Quelldokument in Google Drive geändert hat, nicht den aktuellen Status des Dokuments.

Ein Dokument, das zuvor fehlgeschlagen ist (Status FAIL), wird daher – solange seine Quelldatei in Google Drive nicht geändert wurde – beim Aufruf dieser Schnittstelle nicht erneut verarbeitet: Es wird als „Quelldokument unverändert“ direkt übersprungen, der Status bleibt unverändert und es erscheint auch nicht in skipped.

Um fehlgeschlagene Dokumente erneut zu parsen, verwenden Sie die Schnittstelle Fehlgeschlagene Dokumente neu einbetten. Oder nehmen Sie in Google Drive eine Änderung an der Quelldatei vor, damit sich ihre letzte Änderungszeit aktualisiert; dann kann diese Schnittstelle sie erneut abrufen.

Die Synchronisierung löscht Wissensdokumente

Diese Schnittstelle fügt nicht nur hinzu und aktualisiert, sondern löscht Wissensdokumente auch gemäß dem aktuellen Zustand in Google Drive.

Wird ein gebundener Google-Drive-Ordner leer, werden alle bereits importierten Wissensdokumente unter diesem Ordner vollständig gelöscht. Auslösebedingung ist, dass der Ordner in Google Drive weiterhin zugänglich ist, aber keine Dateien aufgelistet werden können. Das System prüft zunächst die Zugänglichkeit des Ordners; kann es die Ordnermetadaten nicht abrufen (Ordner verschoben, Berechtigung geändert, vorübergehend nicht erreichbar usw.), wird das Löschen übersprungen, um versehentliches Löschen zu vermeiden.

Der Löschumfang ist auf „diesen Ordner + diese Wissensdatenbank“ beschränkt. Wird derselbe Google-Drive-Ordner von mehreren Wissensdatenbanken referenziert, beeinflussen sich die einzelnen Wissensdatenbanken nicht gegenseitig.

Dieses Verhalten entspricht der geplanten Systemsynchronisierung; diese Schnittstelle lässt es nur früher eintreten. Da diese Schnittstelle jedoch auch Dokumente abdeckt, für die beim Import kein Plan für die geplante Synchronisierung konfiguriert wurde (diese würden von keinem automatischen Prozess gelöscht), bestätigen Sie vor dem Aufruf, dass der Ordnerinhalt auf der Google-Drive-Seite den Erwartungen entspricht.

Abdeckungsbereich

Der Synchronisierungsbereich umfasst alle Dokumente aus Google Drive in der Wissensdatenbank, einschließlich derjenigen, für die beim Import kein Plan für die geplante Synchronisierung konfiguriert wurde – diese Dokumente werden von den geplanten Systemrunden nicht verarbeitet und können nur über diese Schnittstelle aktualisiert werden.

Drosselung

• Höchstens 1-mal pro Minute je Agent / Workflow. Beide Pfade teilen sich denselben Zähler; ein Pfadwechsel umgeht die Drosselung nicht.
• Zusätzlich gilt die Begrenzung der Anfragen pro Minute (RPM) für Wissensdatenbank-APIs gemäß dem Organisationstarif; dieses Kontingent wird mit anderen Wissensdatenbank-Schnittstellen geteilt.
• Läuft die vorige Synchronisierung desselben Agent / Workflow noch, gibt ein erneuter Aufruf accepted=false und reason=SYNC_IN_PROGRESS zurück.

Verhältnis zur geplanten Synchronisierung

Diese Schnittstelle und die geplante Systemsynchronisierung sind voneinander unabhängig und blockieren sich nicht gegenseitig. Ist scheduled_round_running gleich true, wird die aktuelle Anfrage dennoch angenommen und nicht deshalb abgelehnt, weil gerade eine geplante Runde ausgeführt wird.

Wenn beide gleichzeitig dasselbe Dokument verarbeiten, entstehen keine doppelten Inhalte: Das System führt die inkrementelle Beurteilung anhand der letzten Änderungszeit des Quelldokuments durch, und bereits importierte Dateien werden nicht doppelt erstellt.

Die geplante Synchronisierung wird automatisch mit der von der Wissensdatenbank selbst konfigurierten Frequenz ausgeführt, während diese Schnittstelle diese Frequenz ignoriert und sofort auslöst. Beide ergänzen sich: Die geplante Synchronisierung übernimmt die reguläre Aktualisierung, diese Schnittstelle das Szenario „jetzt sofort synchronisieren“.