Modelle über Document Understanding-API verbrauchen

Unstrukturierte und komplexe Dokumente von IXP sind über dieselbe Document Understanding Framework API zugänglich. IXP-Projekte 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
• Erstellen Sie eine externe Anwendung für Document Understanding
• Verwalten externer Anwendungen

Voraussetzungen

Bevor Sie eine Document Understanding- oder IXP-API aufrufen, benötigen Sie eine externe Anwendung, die in Automation Cloud registriert ist. Dadurch werden AppID und AppSecret für die OAuth-Authentifizierung verwendet.

Erstellen einer externen Anwendung

1. Navigieren Sie zum Orchestrator auf Mandantenebene.
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 den Anwendungsnamen ein, z. B. DU API Client.
6. Wählen Sie Vertrauliche Anwendung aus, die erforderlich ist, um ein App-Geheimnis abzurufen.
7. Wählen Sie unter Ressourcen die Option Scopes hinzufügen:

• Wählen Sie Document Understanding in der Dropdownliste Ressourcen aus.
• Wechseln Sie zur Registerkarte Anwendungs-Scope(s) .
• Aktivieren Sie die Scopes, die Sie benötigen:
  • Du.Digitization.Api – Dokumente digitalisieren
  • Du.Classification.Api – Klassifizieren Sie Dokumente
  • 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 Popup-Fenster App-Geheimnis sofort kopieren wird nur einmal angezeigt und kann nicht wiederhergestellt werden. Sie können später über den Bearbeitungsbildschirm eine neue generieren.

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

Abrufen eines Zugriffstokens

Verwenden Sie die App-ID und das App-Geheimnis, um ein OAuth-Token über den Flow der Client-Anmeldeinformationen 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> für alle nachfolgenden API-Aufrufe.

Hinweis:

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

Wichtigste Unterschiede

In folgender Tabelle werden die wichtigsten Unterschiede zwischen Document Understanding- und IXP-Projekten dargestellt:

	Document Understanding (klassisch oder modern)	IXP
Projekttyp	Classic oder Modern	IXP
Klassifizierung	Ja	Nein (nur Extraktion)
Extraktionsweiterleitung	Von tag + documentTypeId (empfohlen) oder extractorId	Von tag + documentTypeId oder von extractorId (gpt_ixp_[version])
Versionierung	Extraktoren/Klassifizierer	Tags (Staging, Produktion)
Extraktionsmodell	Spezialisiert oder generativ	Nur generativ (GPT-4o, Gemini)
Schemadefinition	Projektintern oder über Prompts	Definiert in IXP UI (Taxonomie)

Der IXP-Workflow

1. Projekt und Tags entdecken.
2. Digitalisieren und Extrahieren (parallel).
3. Validieren (optional).

Hinweis:

Es gibt keinen Klassifizierungsschritt, da IXP nur Extraktionen verarbeitet.

Parallele Digitalisierung und Extraktion (nur IXP)

Bei IXP-Projekten können Sie die Abfrage des Digitalisierungsergebnisses überspringen und die Extraktion sofort nach dem Einreichen der Digitalisierung starten. Das Back-End führt beide Vorgänge parallel aus. Digitalisierung und IXP-Extraktion werden gleichzeitig fortgesetzt, und das endgültige Extraktionsergebnis wird erst zurückgegeben, nachdem beide abgeschlossen sind. Dies ist eine IXP-spezifische Optimierung, die nicht mit klassischen oder modernen Document Understanding-Projekten funktioniert, bei denen Sie warten müssen, bis die Digitalisierung abgeschlossen ist, bevor Sie die Extraktion aufrufen. Der optimierte Fluss:

# 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}

Durch diesen Fluss entfällt die Leerlaufzeit zwischen Digitalisierung und Extraktion, wodurch die Gesamtlatenz reduziert wird.

Schritt 1: Das IXP-Projekt entdecken

# 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>'

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

Tags abrufen (veröffentlichte Versionen)

Tags entsprechen veröffentlichten Modellversionen, die in der IXP-Benutzeroberfläche als Staging oder Produktion gekennzeichnet sind. Jedes Tag enthält die zugehörigen Extraktoren und Dokumenttypen. Führen Sie die folgenden Schritte aus, um Tags abzurufen:

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

Dokumententypen abrufen

Führen Sie die folgenden Schritte aus, um Dokumenttypen abzurufen:

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: Digitalisieren Sie das Dokument

Ähnlich wie bei Document Understanding laden Sie die Datei hoch, um ein 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 folgende Routingansätze:

• Tag-basiert – Route nach tag und documentTypeId. Dies wird für Produktions- oder Staging-Workflows empfohlen.
• ExtraktorID-basiert – Weiterleitung nach extractorId mit folgendem Format: gpt_ixp_[version]. Zum Beispiel gpt_ixp_67), das gleiche wie für klassische oder moderne Document Understanding-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)

Anfang:

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. Abfrage nach Ergebnis:

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

Verwendet die gleichen extraktorbasierten Endpunkte wie Document Understanding (klassisch oder modern). Die ExtraktorID für IXP folgt dem Format gpt_ixp_[version], das in der Erkennungsantwort sichtbar ist. 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": { }
  }'

Struktur der Intelligente Datenextraktion und Verarbeitung (IXP)-Extraktion

API v1 oder v1.1

In v1 und v1.1 werden IXP-Feldgruppen FieldType: "Table" in der Antwort zugeordnet, mit einzelnen Feldern als Tabellenspalten. Alle Werte werden als Text (string) dargestellt, unabhängig von ihrem ursprünglichen Intelligente Datenextraktion und Verarbeitung (IXP)-Typ:

{
  "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 strukturierte Unterschiede von Document Understanding (v1 oder v1.1):

• Alle Felder gehören zu Feldgruppen, die als Typ Table in der Antwort angezeigt werden.
• Selbst Felder mit einem einzigen Wert sind in eine Tabellenzeilenstruktur eingebettet.
• Das Tables -Array enthält die tatsächlichen Zellenwerte.

API v2

In v2 werden IXP-Feldgruppen FieldType: "FieldGroup" anstelle von Table zugeordnet. Dies ist eine genaue Zuordnung des Konzepts der Intelligente Datenextraktion und Verarbeitung (IXP)-Feldgruppe. Jedes Feld behält seinen tatsächlichen Datentyp der Intelligente Datenextraktion und Verarbeitung (IXP) wie Text, Zahl, Datum, Geldmenge bei, anstatt alles als Strings darzustellen. Weitere Informationen finden Sie unter Migrieren von API v1 zu v2 .

{
  "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 wird entfernt. Feldgruppen werden direkt in Fields zurückgegeben.
• Einzelne Felder behalten ihre Datentypen in der Intelligente Datenextraktion und Verarbeitung (IXP) bei, anstatt dass alle Zeichenfolgen sind.
• FeldIDs verwenden die Punktnotation, z. B. Default.Seller.Name).

Struktur der Erkennungsantwort von IXP

IXP-Projekte machen Versionierungen über Tags und projectVersions verfügbar:

{
  "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, z. B. live , ist auf der Benutzeroberfläche von IXP der Beschriftung Produktion oder Staging zugeordnet.

Hinweis:

• Keine Prompts erforderlich: Im Gegensatz zum generativen DU-Extraktor/Klassifizierer ist das IXP-Extraktionsschema in der IXP-Projekt-Taxonomie vordefiniert. Sie übergeben prompts im API-Aufruf nicht.
• Tag = Modellversion: Verwenden Sie das Tag, das der Produktions- oder Staging-Version entspricht, die Sie aufrufen möchten.
• DokumenttypID: 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.
• Messung: 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.