Consommation de modèles via l'API Document Understanding

Les projets Documents complexes et non structurés IXP sont accessibles via la même API d'infrastructure Document Understanding. Les projets IXP apparaissent comme ProjectType: "IXP" dans la découverte et prennent en charge à la fois les points de terminaison basés sur les balises et les points de terminaison basés sur l'extracteur pour l'extraction. Documentation connexe:

• Présentation de l’API Document Understanding
• Créer une application externe pour Document Understanding
• Gestion d'applications externes

Prérequis

Avant d’appeler une API Document Understanding ou IXP, vous avez besoin d’une application externe enregistrée dans Automation Cloud. Il fournit les AppID et AppSecret utilisés pour l’authentification OAuth.

Créer une application externe

1. Accédez à Orchestrator au niveau du locataire.
2. Sélectionnez Gérer l’accès, puis Gérer les comptes et les groupes.
3. Dans l’en-tête de l’administration UiPath , sélectionnez Applications externes.
4. Sélectionnez Ajouter une application.
5. Renseignez le Nom de l'application, par exemple, DU API Client.
6. Sélectionnez Application confidentielle, ce qui est nécessaire pour obtenir une clé secrète d’application.
7. Sous Ressources, sélectionnez Ajouter des étendues:

• Sélectionnez Document Understanding dans la liste déroulante ressources .
• Basculez vers l'onglet Étendue(s) de l'application .
• Vérifiez les étendues dont vous avez besoin:
  • Du.Digitization.Api — documents numérisés
  • Du.Classification.Api — classer les documents
  • Du.Extraction.Api — extraire des données
  • Du.Validation.Api — créer des tâches de validation
  • Du.DataDeletion.Api — supprimer les données du document
• Sélectionnez Enregistrer.

8. Sélectionnez Ajouter pour créer l'enregistrement.

Remarque :

La fenêtre contextuelle Copier le secret de l’application immédiatement s’affiche une seule fois et ne peut pas être récupérée. Vous pouvez en générer un nouveau ultérieurement à partir de l'écran de modification.

L’ ID d’application est visible à tout moment sur la page Applications externes .

Obtenir un jeton d’accès

Utilisez l’ID d’application et le secret d’application pour demander un jeton OAuth via le flux d’informations d’identification du client:

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'

Réponse :

{
  "access_token": "eyJh...CRaKrg",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

Le jeton expire après 1 heure. Utilisez-le comme Authorization: Bearer <token> pour tous les appels API suivants.

Remarque :

Si vous perdez la clé secrète de l’application, accédez à Admin, puis à Applications externes, modifiez l’application et sélectionnez Générer nouveau sous Clé secrète de l’application. Mettez à jour toutes les intégrations avec la nouvelle clé secrète.

Principales différences

Le tableau suivant présente les principales différences entre les projets Document Understanding et IXP:

	Document Understanding (Classique ou Moderne)	IXP
Type de projet	Classic ou Modern	IXP
Classification	Oui (Yes)	Non (extraction uniquement)
Routage d'extraction	Par tag + documentTypeId (recommandé) ou extractorId	Par tag + documentTypeId ou par extractorId (gpt_ixp_[version])
Contrôle de version	Extracteurs/classifieurs	Balises (Organisation, Production)
Modèle d’extraction	spécialisé ou génératif	Génératif uniquement
Définition du schéma	Dans le projet ou via des invites	Défini dans l'interface utilisateur IXP (taxonomie)

Le workflow IXP

1. Découvrez le projet et les balises.
2. Numérisez et extrayez (en parallèle).
3. Validez (facultatif).

Remarque :

Il n'y a pas d'étape de classification, car IXP gère uniquement les extractions.

Numérisation et extraction parallèles (IXP uniquement)

Pour les projets IXP, vous pouvez ignorer l'interrogation pour le résultat de la numérisation et commencer immédiatement l'extraction après avoir soumis la numérisation. Le backend exécute les deux opérations en parallèle. La numérisation et l'extraction IXP se déroulent simultanément et le résultat final de l'extraction n'est renvoyé qu'une fois les deux terminées. Il s’agit d’une optimisation spécifique à IXP qui ne fonctionne pas avec les projets Document Understanding Classique ou Moderne, où vous devez attendre la fin de la numérisation avant d’appeler l’extraction. Le flux optimisé:

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

Ce flux élimine le temps d’inactivité entre la numérisation et l’extraction, ce qui réduit la latence totale.

Étape 1: découvrir le projet IXP

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

Dans la réponse, notez le id du projet IXP.

Obtenir les balises (versions publiées)

Les balises correspondent aux versions de modèle publiées marquées comme Staging ou Production dans l'interface utilisateur d'IXP. Chaque balise inclut ses extracteurs et ses types de documents associés. Pour obtenir des balises, exécutez ce qui suit:

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

Obtenir les types de documents

Pour obtenir des types de documents, exécutez les opérations suivantes:

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

Étape 2: numériser le document

À l’instar de Document Understanding, téléchargez le fichier pour obtenir une documentId:

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'

Renvoie { "documentId": "..." }.

Étape 3: extraire

L'extraction IXP prend en charge les approches de routage suivantes:

• Basé sur les balises : routage par tag et documentTypeId. Ceci est recommandé pour les workflows de production ou d'organisation.
• Basé sur ExtractorId - Routez par extractorId en utilisant le format: gpt_ixp_[version]. Par exemple, gpt_ixp_67), de la même manière que pour les projets Document Understanding Classique ou Moderne.

Extraction basée sur des balises

Utilise le chemin basé sur une balise avec le documentTypeId de la Découverte.

Synchronisé (jusqu'à 5 pages)

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

Asynchrone (multipages)

Démarrer:

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

Renvoie { "operationId": "..." }. Interrogation pour le résultat:

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

Interroger jusqu'à ce que status soit Succeeded ou Failed.

Extraction basée sur IDExtracteur

Utilise les mêmes points de terminaison basés sur des extracteurs que Document Understanding Classique ou Moderne. The ExtractorId pour IXP suit le format gpt_ixp_[version], qui est visible dans la réponse de découverte. Synchroniser (jusqu'à 5 pages):

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

Asynchrone (multi-pages):

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

Étape 4: Valider (facultatif)

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

Structure de la réponse d'extraction IXP

API v1 ou v1.1

Dans v1 et v1.1, les groupes de champs IXP correspondent à FieldType: "Table" dans la réponse, avec des champs individuels sous forme de colonnes de table. Toutes les valeurs sont représentées sous forme de Text, quel que soit leur type de données IXP d'origine:

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

Principales différences structurées avec Document Understanding (v1 ou v1.1):

• Tous les champs appartiennent à des groupes de champs, qui apparaissent comme Table dans la réponse.
• Mêmes les champs à valeur unique sont encapsulés dans une structure de ligne de tableau.
• Le tableau Tables contient les valeurs réelles des cellules.

API v2

Dans v2, les groupes de champs IXP correspondent à FieldType: "FieldGroup" au lieu de Table. Il s'agit d'une correspondance exacte du concept de groupe de champs IXP. Chaque champ préserve son type de données IXP réel, tel que Texte, Nombre, Date, MonetaryQuantity, plutôt que de tout représenter sous forme de chaînes. Pour plus de détails, consultez la section Migration de l’API v1 vers 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
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Principales différences par rapport à la version v1:

• FieldType: "FieldGroup" remplace FieldType: "Table".
• Le tableau Tables est supprimé. Les groupes de champs sont renvoyés directement dans Fields.
• Les champs individuels préservent leurs types de données IXP au lieu de toutes les chaînes.
• Les ID de champ utilisent la notation pointée, par exemple, Default.Seller.Name).

Structure de la réponse de découverte IXP

Les projets IXP exposent le contrôle de version via des balises et des versions de projet:

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

Le nom de la balise, par exemple live , correspond au libellé Production ou Organisation dans l'interface utilisateur IXP.

Remarque :

• Aucune invite requise: contrairement à l’extracteur/classifieur génératif DU, le schéma d’extraction IXP est prédéfini dans la taxonomie du projet IXP. Vous ne transmettez pas prompts dans l'appel d'API.
• Balise = version du modèle: utilisez la balise qui correspond à la version Production ou Organisation que vous souhaitez appeler.
• IDTypeDocument: les projets IXP utilisent généralement un seul type de document par défaut (00000000-0000-0000-0000-000000000000).
• Limites de pages: GPT-4o jusqu'à 50 pages, Gemini jusqu'à 500 pages par appel.
• Mesure: 1 AI Unit par page (plan Flex) ou 0,2 Platform Units par page (Unified Pricing). Les demandes échouées ne consomment pas d’unités.
• Rétention des données: numérisation 7 jours, extraction 24 heures.