Die API unterstützt Workflows zum Verwalten von Sammlungen und Dokumenten, zur Verarbeitung von Inhalten und zur Anwendung von KI-Funktionen wie Frage-Antwort, Zusammenfassung, Suche und strukturierte Extraktion. Erfahre auf dieser Seite, wie diese Komponenten zusammenarbeiten, und verwende dann die API-Referenz für Implementierungsdetails auf Endpunkt-Ebene.
Stelle sicher, dass du Folgendes hast:
Falls du noch keinen API-Zugriff konfiguriert hast, siehe API-Zugriff für Knowledgebase einrichten.
Ein typischer Knowledgebase-API-Workflow folgt dieser Sequenz:
Authentifizierung → Sammlung → Dokument → Index → Inferenz → Antwort
Eine Sammlung definiert die Wissensdomäne, mit der deine Anwendung arbeitet. Wenn du eine Sammlung erstellst, enthält die Antwort ihren eindeutigen Namespace, den du in nachfolgenden Operationen verwendest.
Beispiel:
{
"namespace": "<collection-namespace>",
"name": "example-collection"
}
Behalte den Sammlungs-Namespace für Dokument- und Inferenz-Anfragen.
Dokumente werden in Sammlungen hochgeladen und erhalten eindeutige Dokumentkennungen.
Eine Upload-Antwort gibt das Dokument an, damit deine Anwendung die Verarbeitung verfolgen und es in späteren Anfragen referenzieren kann.
{
„Document_id“: „<document-id>“,
„document_Name“: „Beispiel.pdf“
}
Das Hochladen eines Dokuments und seine Indizierung sind separate Schritte.
Das Hochladen überträgt die Datei zur Knowledgebase. Die Indizierung extrahiert den Inhalt und verarbeitet ihn zur Verwendung durch KI-Operationen.
Deine Anwendung sollte bestätigen, dass die Verarbeitung abgeschlossen ist, bevor sie Inferenz-Anfragen für das Dokument sendet.
Inferenzoperationen wenden KI-Funktionen der Knowledgebase auf verarbeitete Inhalte an.
Verfügbare Operationen umfassen:
Verwende die API-Referenz, um den Endpunkt und das Anfrage-Schema für die gewünschte Operation zu bestimmen.
Inferenz-Antworten geben das generierte Ergebnis zurück und können unterstützende Attributionsinformationen enthalten.
Je nach Operation können Attribution-Daten den Quellinhalt, die Seite und die Koordinaten angeben, die mit dem Ergebnis verknüpft sind. Deine Anwendung bestimmt, wie diese Informationen dem Benutzer präsentiert werden.
Der einfachste Anwendungs-Workflow ist das Erstellen einer Sammlung, das Hinzufügen eines Dokuments, das Warten auf die Verarbeitung und das anschließende Ausführen einer Inferenz-Operation.
Erstelle die Sammlung, die die Quelldokumente für deine Anwendung enthalten wird.
Behalte den in der Antwort zurückgegebenen Namespace bei:
collection_namespace = <zurückgegebener-namespace>
Du verwendest diesen Wert beim Hinzufügen von Dokumenten und beim Aufrufen von Operationen, die mit der Sammlung ausgeführt werden.
Lade ein Dokument in die Sammlung hoch und bewahre die zurückgegebene Dokument-ID auf:
Document_id = <returned-document-id>
Die Dokument-ID identifiziert das hochgeladene Dokument unabhängig von seinem Dateinamen.
Starte die erforderliche Indizierung und überprüfe dann den Dokumentstatus, bis die Verarbeitung abgeschlossen ist.
Gehe nicht davon aus, dass ein erfolgreiches Hochladen bedeutet, dass das Dokument für KI-Operationen bereit ist.
Ein typischer Anwendungsablauf ist:
Dokument hochladen
↓
Indizierung starten
↓
Verarbeitungsstatus prüfen
↓
Abgeschlossen
Falls die Verarbeitung fehlschlägt, löse das Problem bei der Dokumentverarbeitung, bevor du eine Inferenzanfrage sendest.
Nach Abschluss der Verarbeitung übermittle den Sammlungs-Namespace, die Dokument-ID und alle operationsspezifischen Eingaben, die vom Endpunkt benötigt werden.
Zum Beispiel liefert eine Frage-Antwort-Anfrage konzeptionell:
Sammlung: <collection-namespace>
Dokument: <document-id>
Frage: Was sind die wichtigsten Erkenntnisse?
Verwende die API-Referenz für das tatsächliche Anfrageschema.
Verwende die zurückgegebene Antwort oder extrahierten Daten in deiner Anwendung.
Wenn die Antwort Attributionsinformationen enthält, kannst du sie verwenden, um generierte Informationen mit dem zugehörigen Dokumentinhalt zu verknüpfen.
Der Dokumentenlebenszyklus beeinflusst, wann deine Anwendung hochgeladenen Inhalt verwenden kann.
| Phase | Was passiert | Anwendungsaktion |
|---|---|---|
| Hochladen | Die Datei wird zur Knowledgebase hinzugefügt und erhält eine Dokument-ID. | Behalte die Dokument-ID. |
| Indizierung | Inhalt wird für die KI-Nutzung extrahiert und verarbeitet. | Überwache den Dokumentstatus. |
| Fertig | Der verarbeitete Inhalt ist zur Inferenz verfügbar. | Reiche KI-Anfragen ein. |
| Fehlgeschlagen | Die Verarbeitung wurde nicht erfolgreich abgeschlossen. | Behebe den Fehler, bevor du fortfährst. |
Diese Unterscheidung ist besonders für automatisierte Workflows wichtig. Eine Anwendung sollte den Verarbeitungsstatus prüfen, anstatt sofort nach dem Upload eine Inferenz-Anfrage zu senden.
Wähle eine Operation basierend darauf, was deine Anwendung mit dem Quellinhalt machen muss.
Verwende F&A, um Fragen in natürlicher Sprache zu Sammlungs- oder Dokumentinhalten zu stellen.
Die API bietet sowohl Streaming- als auch Non-Streaming-F&A.
Streaming F&A gibt die Antwort schrittweise zurück, während sie generiert wird. Verwende es, wenn deine Benutzeroberfläche generierten Inhalt schrittweise anzeigen soll.
Bei Streaming F&A wird auch kontrolliert, ob benutzerdefinierte Anweisungen auf die Anfrage angewendet werden. Du kannst auch steuern, ob eine Begründung für eine Streaming-F&A-Antwort generiert wird.
Non-Streaming-F&A wartet auf den Abschluss der Generierung und gibt die fertige Antwort zurück. Verwende diese Option, wenn deine Anwendung keine Teilausgaben anzeigen muss.
Verwende die Zusammenfassung, um eine kompakte Darstellung von Dokumentinhalten zu generieren.
Die API-Referenz definiert die aktuellen Anforderungen und unterstützten Eingaben.
Verwende die Kontextsuche, um Inhalte abzurufen, die für den angegebenen Suchtext relevant sind.
Dadurch können Anwendungen einfacher relevantes Quellmaterial identifizieren, ohne eine gesprächsbasierte Antwort zu generieren.
Verwende die Extraktion, wenn deine Anwendung strukturierte Werte aus Dokumentinhalten benötigt.
Eine Extraktionsdefinition kann Informationen wie die folgenden identifizieren:
Eigenschaftsname: contract_value
Typ: integer
Beschreibung: Vertragswert der Vereinbarung
Prompt: Extrahiere den größten Vereinbarungswert in Dollar.
Das zurückgegebene Ergebnis kann den extrahierten Wert, Konfidenzinformationen und Quellenattribution enthalten.
Die API bietet verschiedene Möglichkeiten, um zu bestimmen, welche Inhalte an einer Anfrage beteiligt sind.
Verwende Sammlungs- und Dokumentkennungen, um die primären Inhalte zu definieren, die für eine Operation verfügbar sind.
Tags sind mit Dokumenten und nicht mit Sammlungen verknüpft.
Dokumenttags sind nur über die Knowledgebase-API verfügbar und werden in der standardmäßigen Benutzeroberfläche nicht angezeigt.
Du kannst Tags in unterstützten Operationen verwenden, um die für eine Anfrage berücksichtigten Dokumente zu filtern. Eine Anwendung könnte beispielsweise eine Gruppe von Dokumenten als Finanzdokumente taggen und eine Frage auf Dokumente mit diesem Tag beschränken.
Anhänge sind von Sammlungsdokumenten getrennt.
Das Hinzufügen eines Anhangs zu einer Konversation fügt diese Datei nicht zur Sammlung hinzu. Der Anhang kann dennoch Kontext zu einer generierten Antwort beitragen, zusammen mit Sammlungsinhalten und dem Chat-Verlauf.
Verwende Anhang-Endpunkte, wenn deine Anwendung temporäre oder konversationsspezifische Inhalte benötigt, ohne sie dauerhaft zu einer Sammlung hinzuzufügen.
Inferenzantworten können Attributionsinformationen enthalten, die generierte Ausgaben mit unterstützenden Quellinhalten verknüpfen.
Attributionsdaten können Informationen enthalten wie:
Die API stellt diese Informationen als Daten bereit. Deine Anwendung bestimmt, wie sie diese präsentiert.
Eine Anwendung kann beispielsweise zurückgegebene Koordinaten verwenden, um ein Erlebnis mit hervorgehobenen Quellen zu erstellen, das die Stelle angibt, die eine generierte Antwort unterstützt.
API-Operationen verwenden die Berechtigungen, die für die authentifizierte Identität verfügbar sind.
Eine Anfrage kann fehlschlagen, wenn die authentifizierte Identität keinen Zugriff auf die angeforderte Sammlung, das Dokument oder die Operation hat.
Bei der Fehlerbehebung:
Die X-Request-ID kennzeichnet die Anfrage über Dienste der Knowledgebase hinweg und kann dem Support helfen, eine fehlgeschlagene Anfrage zu untersuchen.
Nutze die Python-Demo, wenn du funktionierende Beispiele möchtest, die diese Konzepte in einer Anwendung demonstrieren.
Erste Schritte mit der Python-Demo der Knowledgebase
Nutze die API-Referenz, wenn du bereit bist, eine bestimmte Operation zu implementieren.
