Modelle über Document Understanding-API verbrauchen

Greifen Sie über die API des Document Understanding-Frameworks auf IXP-Modelle zu, die auf Tag-basierten oder ExtractorId-basierten Extraktionsendpunkten basieren.

IXP Extract-Knoten sind über dieselbe Document Understanding Framework API zugänglich. Extraktionsknoten werden in Discovery als ProjectType: "IXP" angezeigt und unterstützen sowohl Tag-basierte Endpunkte als auch ExtractorId-basierte Endpunkte für die Extraktion.

Zugehörige Dokumentation:

• Document Understanding API-Übersicht
• Externe Anwendung für Document Understanding erstellen
• Verwalten externer Anwendungen

Hinweis:

Verwenden Sie API v2, um die Modelle von Extract Knoten zu nutzen, und verwenden Sie die neueste Version der öffentlichen Document Understanding-APIs. Die Beispiele auf dieser Seite verwenden API v2 (api-version=2).

Voraussetzungen

Bevor Sie eine Document Understanding- oder Intelligente Datenextraktion und Verarbeitung (IXP)-API aufrufen, benötigen Sie eine externe Anwendung, die in der Automation Cloud registriert ist. Dies stellt AppID und AppSecret für die OAuth-Authentifizierung bereit.

Erstellen einer externen Anwendung

1. Navigieren Sie auf Mandantenebene zu Orchestrator.

2. Wählen Sie Zugriff verwalten und dann Konten und Gruppen verwalten aus.

3. Wählen Sie im Header der UiPath-Verwaltung die Option Externe Anwendungen aus.

4. Wählen Sie Anwendung hinzufügen aus.

5. Geben Sie Anwendungsname ein, z. B. DU API Client.

6. Wählen Sie Vertrauliche Anwendung aus, was erforderlich ist, um ein App-Secret zu erhalten.

7. Wählen Sie unter Ressourcen die Option Scopes hinzufügen aus:

   • Wählen Sie in der Dropdownliste Ressource die Option Document Understanding aus.
   • Wechseln Sie zur Registerkarte Anwendungs-Scope(s).
   • Aktivieren Sie die benötigten Scopes:
     • Du.Digitization.Api – Digitalisieren von Dokumenten
     • Du.Classification.Api – Klassifizieren von Dokumenten
     • Du.Extraction.Api – Daten extrahieren
     • Du.Validation.Api – Validierungsaufgaben erstellen
     • Du.DataDeletion.Api – Dokumentdaten löschen
   • Wählen Sie Speichern.

8. Klicken Sie auf Hinzufügen , um die Registrierung zu erstellen.

   Hinweis:

   Das Pop-up App-Secret sofort kopieren wird nur einmal angezeigt und kann nicht wiederhergestellt werden. Sie können später über den Bearbeitungsbildschirm eine neue Version generieren.

Die Anwendungs-ID ist jederzeit auf der Seite Externe Anwendungen sichtbar.

Abrufen eines Zugriffstokens

Verwenden Sie die App-ID und das App Secret, um ein OAuth-Token über den Client Credentials Flow anzufordern:

curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<your-client-secret>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

Antwort:

{
  "access_token": "<your-access-token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

Das Token läuft nach 1 Stunde ab. Verwenden Sie es als Authorization: Bearer <your-access-token> bei allen nachfolgenden API-Aufrufen.

Hinweis:

Wenn Sie das App-Secret verlieren, wechseln Sie zu Admin, dann zu Externe Anwendungen, bearbeiten Sie die App und wählen Sie unter App-Secret Neu generieren aus.Aktualisieren Sie alle Integrationen mit dem neuen Secret.

Hauptunterschiede

Die folgende Tabelle zeigt die wichtigsten Unterschiede zwischen Document Understanding-Projekten und IXP-Projekten:

	Document Understanding (Klassisch oder Modern)	IXP
Projekttyp	Classic oder Modern	IXP
Klassifizierung	Ja	Nein (nur Extraktion)
Extraktionsrouting	Mit tag + documentTypeId (empfohlen) oder extractorId	Durch tag + documentTypeId oder durch extractorId (gpt_ixp_[version])
Extraktionsmodell	Spezialisiert oder Generativ	Nur generativ (GPT-4o, Gemini)
Schemadefinition	Im Projekt oder über Prompts	Definiert in der Intelligente Datenextraktion und Verarbeitung (IXP)-Benutzeroberfläche (Taxonomie)

Der Intelligente Datenextraktion und Verarbeitung (IXP)-Workflow

1. Projekt und Tags ermitteln
2. Digitalisieren Sie das Dokument und rufen Sie ab, bis die Digitalisierung abgeschlossen ist.
3. Extrahieren und Abfragen, bis die Extraktion abgeschlossen ist.
4. Validieren (optional).

Hinweis:

Es gibt keinen Klassifizierungsschritt, da Intelligente Datenextraktion und Verarbeitung (IXP) nur Extraktionen verarbeitet.

Schritt 1: Das IXP-Projekt ermitteln

# List all projects - filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Beachten Sie in der Antwort die id des IXP-Projekts.

Tags abrufen (veröffentlichte Versionen)

Tags entsprechen veröffentlichten Modellversionen, die in der Benutzeroberfläche von Intelligente Datenextraktion und Verarbeitung (IXP) als Staging oder Produktion gekennzeichnet sind.Jedes Tag enthält die zugehörigen Extraktoren und Dokumenttypen. Um Tags zu erhalten, führen Sie Folgendes aus:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Dokumenttypen abrufen

Um Dokumenttypen zu erhalten, führen Sie Folgendes aus:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Hinweis:

Nachdem Sie die Projekt-ID, das Tag und die Dokumenttyp-ID kennen, müssen Sie die Erkennungsaufrufe nicht jedes Mal zur Runtime ausführen. Verwenden Sie diese Werte stattdessen in Ihrer Automatisierung wieder.

Schritt 2: Das Dokument digitalisieren

Hinweis:

Digitalisierung ist ein obligatorischer Schritt. Sie können keine Daten aus einem Dokument extrahieren, bevor Sie es digitalisiert haben.

Ähnlich wie bei Document Understanding laden Sie die Datei hoch, um documentId zu erhalten:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

Gibt { "documentId": "..." } zurück.

Abfrage für das Digitalisierungsergebnis:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/result/<documentId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Abfragen, bis status Succeeded ist, und dann die Extraktion starten. Die möglichen Status und Antworten finden Sie unter Abrufantworten.

Schritt 3: Extrahieren

Die IXP-Extraktion unterstützt die folgenden Routing-Ansätze:

• Tag-basiert – Routen nach tag und documentTypeId. Dies wird für Produktions- oder Staging-Workflows empfohlen.
• ExtraktorID-basiert – Weiterleitung nach extractorId mit folgendem Format: gpt_ixp_[version]. Beispiel: gpt_ixp_67. Dies ist dasselbe wie bei klassischen oder modernen Document Understanding-Projekten.

Tag-basierte Extraktion

Verwendet den tagbasierten Pfad mit documentTypeId von Discovery.

Synchron (bis zu 5 Seiten)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asynchron (mehrseitig)

Start:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Gibt { "operationId": "..." } zurück. Nach Ergebnis abfragen:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Abfragen bis status ist Succeeded oder Failed. Die möglichen Status und Antworten finden Sie unter Abrufantworten.

ExtractorId-basierte Extraktion

Es werden dieselben extraktorbasierten Endpunkte wie in Document Understanding Classic oder Modern verwendet.Die ExtractorId für Intelligente Datenextraktion und Verarbeitung (IXP) folgt dem Format gpt_ixp_[version], das Sie in der Erkennungsantwort sehen. Synchron (bis zu 5 Seiten):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asynchron (mehrseitig):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Gibt { "operationId": "..." } zurück. Nach Ergebnis abfragen:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/result/<operationId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Abfragen bis status ist Succeeded oder Failed. Die möglichen Status und Antworten finden Sie unter Abrufantworten.

Schritt 4: Validieren (optional)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'

Abrufantworten

Die asynchronen Digitalisierungsaufrufe in Schritt 2 und die asynchronen Extraktionsaufrufe in Schritt 3 geben ihre Ergebnisse durch Abfragen zurück. Jede Abfrageantwort enthält ein status, das eines der folgenden ist:

• NotStarted - Der Auftrag wurde erstellt und wartet auf die Verarbeitung.
• Running – Der Auftrag wurde aufgenommen und wird verarbeitet.
• Succeeded – Der Auftrag wurde erfolgreich fertiggestellt. Die Antwort enthält result.
• Failed - Der Auftrag wurde mit einem Fehler abgeschlossen. Die Antwort enthält error.

Abfragen fortsetzen, während der Status NotStarted oder Running ist.

Während der Auftrag verarbeitet wird, enthält die Antwort den Status und die Zeitstempel des Auftrags:

{
  "status": "Running",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>"
}

Wenn der Auftrag erfolgreich ist, enthält die Antwort auch result. Für die Extraktion ist das Ergebnis in result.extractionResult. Für ihre Struktur aktivieren Sie die Struktur der Intelligente Datenextraktion und Verarbeitung (IXP)-Extraktion.

{
  "status": "Succeeded",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>",
  "result": {
    "extractionResult": {
      "documentId": "<documentId>"
    }
  }
}

Wenn der Auftrag fehlschlägt, enthält die Antwort ein error -Objekt mit den folgenden Details:

• message – Die Beschreibung des Fehlers.
• severity – Der Schweregrad des Fehlers, meistens Error.
• code – Der Code, der den Fehlertyp identifiziert.
• parameters – Zusätzliche Informationen über den Fehler, falls zutreffend.

Weitere Informationen finden Sie unter Antwortschemas für Anforderungen im Document Understanding API-Handbuch.

Extraktionsantwortstruktur der Intelligenten Datenextraktion und Verarbeitung (IXP)

In API v2 verwenden alle von IXP gemeldeten Felder und Werte korrekte Feldtypen, einschließlich Feldgruppen und untergeordnete Felder, mit einer genauen Zuordnung der Definitionen von IXP-Feldgruppen und untergeordneten Feldern.

{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Hinweis:

Wir empfehlen die Verwendung von API v2 für den Verbrauch durch Intelligente Datenextraktion und Verarbeitung (IXP) aufgrund der 1:1-Zuordnung zwischen den Feldgruppen und Feldtypen des Projekts für Intelligente Datenextraktion und Verarbeitung (IXP) und den gemeldeten Ergebnissen.

Struktur der IXP-Ermittlungsantwort

IXP-Projekte stellen die Versionsverwaltung über Tags und projectVersions bereit:

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Invoices",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}

Der Tag-Name, z. B. live, wird der Beschriftung Produktion oder Staging in der Benutzeroberfläche von IXP zugeordnet.

Berücksichtigen Sie Folgendes beim Aufrufen der Intelligente Datenextraktion und Verarbeitung (IXP)-Extraktionsendpunkte:

• Tag = Modellversion: Verwenden Sie das Tag, das der Produktions- oder Staging-Version entspricht, die Sie aufrufen möchten.
• Dokumenttyp-ID: IXP-Projekte verwenden in der Regel einen einzigen Standarddokumenttyp (00000000-0000-0000-0000-000000000000).
• Seitenlimits: Informationen zu Seiten- und Tokenlimits finden Sie unter Dokumentverarbeitungslimits.
• Messung: Weitere Informationen zur Abrechnung der IXP-Extraktion finden Sie unter IXP Flex Pricing-Plan, Unified Pricing und Mess- und Abrechnungslogik (Flex-Plan).
• Datenaufbewahrung: Weitere Informationen dazu, wie lange Digitalisierungs- und Extraktionsergebnisse aufbewahrt werden, finden Sie in der Document Understanding API-Übersicht.