Modelle über Document Understanding-API verbrauchen

IXP Unstructured and Complex Documents projects are accessible through the same Document Understanding framework API. IXP projects appear as ProjectType: "IXP" in Discovery and support both tag-based endpoints and extractorId-based endpoints for extraction.

Related documentation:

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

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 – Dokumente digitalisieren
  • Du.Classification.Api – Dokumente klassifizieren
  • 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=<APP_SECRET>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

Antwort:

{
  "access_token": "eyJh...CRaKrg",
  "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 <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])
Versionierung	Extraktoren/Klassifizierer	Tags (Staging, Produktion)
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 und extrahieren (parallel).
3. Validieren (optional).

Hinweis:

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

Parallele Digitalisierung und Extraktion (nur IXP)

For IXP projects, you can skip polling for the digitization result and immediately start extraction after you submit digitization. The backend runs both operations in parallel. Digitization and IXP extraction proceed concurrently, and the final extraction result is returned only after both complete.

This is an IXP-specific optimization that does not work with Document Understanding Classic or Modern projects, where you must wait for digitization to finish before calling extraction.

The optimized flow:

# 1. Start digitization (fire and forget — do not poll for result).
POST /projects/{projectId}/digitization/start
# → returns { "documentId": "..." }
# 2. Immediately start extraction with the documentId (no need to wait).
POST /projects/{projectId}/{tag}/document-types/{documentTypeId}/extraction/start
# → returns { "operationId": "..." }
# 3. Poll extraction result only — it waits for both digitization and extraction.
GET /projects/{projectId}/{tag}/document-types/{documentTypeId}/extraction/result/{operationId}

Dieser Ablauf eliminiert die Leerlaufzeit zwischen Digitalisierung und Extraktion und reduziert so die Gesamtlatenz.

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=1' \
  -H 'Authorization: Bearer <TOKEN>'

Notieren Sie aus 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=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <TOKEN>'

Schritt 2: Das Dokument digitalisieren

Ä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=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

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

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.
• ExtractorId-basiert – Route über extractorId mit dem Format: gpt_ixp_[version]. Zum Beispiel gpt_ixp_67, wie für Document Understanding Classic- oder Modern-Projekte.

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=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <TOKEN>'

Abfragen, bis status ist Succeeded oder Failed.

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=1' \
  -H 'Authorization: Bearer <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=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

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=1' \
  -H 'Authorization: Bearer <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": { }
  }'

Extraktionsantwortstruktur der Intelligenten Datenextraktion und Verarbeitung (IXP)

API v1 oder v1.1

In v1 und v1.1 werden Feldgruppen der Intelligenten Datenextraktion und Verarbeitung (IXP) FieldType: "Table" in der Antwort zugeordnet, wobei einzelne Felder als Tabellenspalten dienen. Alle Werte werden als Text (string) dargestellt, unabhängig von ihrem ursprünglichen IXP-Datentyp:

{
  "extractionResult": {
    "DocumentId": "...",
    "ResultsDocument": {
      "DocumentTypeId": "00000000-0000-0000-0000-000000000000",
      "DocumentTypeName": "Default",
      "Fields": [
        {
          "FieldId": "Fleet member transaction details",
          "FieldName": "Fleet member transaction details",
          "FieldType": "Table",
          "Values": []
        }
      ],
      "Tables": [
        {
          "FieldId": "Fleet member transaction details",
          "FieldName": "Fleet member transaction details",
          "Values": [
            {
              "Cells": [
                { "FieldId": "Fleet Code", "Value": "FL-7892", "Confidence": 0.95 },
                { "FieldId": "Fuel type", "Value": "Diesel", "Confidence": 0.97 }
              ]
            }
          ]
        }
      ]
    }
  }
}

Wichtige strukturelle Unterschiede zu Document Understanding (v1 oder v1.1):

• Alle Felder gehören zu Feldgruppen, die als Table-Typ in der Antwort erscheinen.
• Selbst Einzelwertfelder werden in eine Tabellenzeilenstruktur eingeschlossen.
• Das Tables-Array enthält die tatsächlichen Zellenwerte.

API v2

In v2, IXP field groups map to FieldType: "FieldGroup" instead of Table. This is an exact mapping of the IXP field group concept. Each field preserves its actual IXP data type, such as Text, Number, Date, MonetaryQuantity, rather than representing everything as strings.

For more details, check Migrating from API v1 to v2 for details.

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

Hauptunterschiede zu v1:

• FieldType: "FieldGroup" ersetzt FieldType: "Table".
• Das Tables-Array wurde entfernt. Feldgruppen werden direkt in Fields zurückgegeben.
• Einzelne Felder behalten ihre IXP-Datentypen bei, anstatt alle vom Typ „string“ zu sein.
• FieldIds verwenden die Punkt-Notation, z. B. Default.Seller.Name.

Struktur der IXP-Ermittlungsantwort

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

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Transcom Invoices - Andras",
  "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, zum Beispiel live, entspricht der Beschriftung „Produktion“ oder „Staging“ in der Benutzeroberfläche der IXP.

Hinweis:

• Keine Prompts erforderlich: Im Gegensatz zum generativen Extraktor/Klassifizierer von DU ist das IXP-Extraktionsschema in der IXP-Projekttaxonomie vordefiniert. Sie übergeben prompts nicht im API-Aufruf.
• 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: GPT-4o bis zu 50 Seiten, Gemini bis zu 500 Seiten pro Aufruf.
• Metering: 1 AI Unit pro Seite (Flex-Plan) oder 0,2 Platform Units pro Seite (Unified Pricing).Fehlgeschlagene Anforderungen verbrauchen keine Einheiten.
• Datenaufbewahrung: Digitalisierung 7 Tage, Extraktion 24 Stunden.