Consommation de modèles via l'API Document Understanding

Les projets Documents complexes et non structurés d'Extraction et traitement intelligents (IXP) sont accessibles via la même API d'infrastructure Document Understanding. Les projets Extraction et traitement intelligents (IXP) apparaissent en tant que ProjectType: "IXP" dans Découverte et prennent en charge à la fois les points de terminaison basés sur des balises et les points de terminaison basés sur ExtractorId pour l'extraction.

Documentation associée :

• Vue d'ensemble 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 Extraction et traitement intelligents (IXP), vous avez besoin d'une application externe enregistrée dans Automation Cloud. Cela fournit le AppID et AppSecret utilisés pour l'authentification OAuth.

Créer une application externe

1. Naviguez vers 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 Administration UiPath, sélectionnez Applications externes.
4. Sélectionnez Ajouter une application.
5. Remplissez le Nom de l'application, par exemple, DU API Client.
6. Sélectionnez Application confidentielle, qui est requise pour obtenir un secret d'application.
7. Sous Ressources, sélectionnez Ajouter des étendues :

• Sélectionnez Document Understanding dans le menu déroulant Ressources.
• Basculez vers l'onglet Étendue(s) de l'application.
• Vérifiez les étendues dont vous avez besoin :
  • Du.Digitization.Api - numériser les documents
  • Du.Classification.Api - classifier les documents
  • Du.Extraction.Api - extraire les 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 plus tard à partir de l'écran de modification.

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

Obtention d'un jeton d'accès

Utilisez l'ID d'application et le Secret de l'application pour demander un jeton OAuth via le flux d'identifiants 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> sur tous les appels d'API suivants.

Remarque :

Si vous perdez le secret de l'application, accédez à Admin, puis Applications externes, modifiez l'application et sélectionnez Générer nouveau sous Secret d'application. Mettez à jour toutes les intégrations avec le nouveau secret.

Principales différences

La table suivante affiche les principales différences entre les projets Document Understanding et Extraction et traitement intelligents (IXP) :

	Document Understanding (Classique ou Moderne)	IXP
Type de projet	Classic ou Modern	IXP
Classification	Oui (Yes)	Non (extraction uniquement)
Routage de l'extraction	Par tag + documentTypeId (recommandé) ou extractorId	Par tag + documentTypeId ou par extractorId (gpt_ixp_[version])
Contrôle de version	Extracteurs/classifieurs	Balises (Pré-production, Production)
Modèle d’extraction	Spécialisé ou Génératif	Génératif uniquement (GPT-4o, Gemini)
Définition du schéma	Dans le projet ou via des invites	Défini dans l'IU d'Extraction et traitement intelligents (IXP) (taxonomie)

Le workflow Extraction et traitement intelligents (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 Extraction et traitement intelligents (IXP) gère uniquement les extractions.

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

Pour les projets Extraction et traitement intelligents (IXP), vous pouvez ignorer l'interrogation du 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 d'Extraction et traitement intelligents (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 que la numérisation se termine 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 Extraction et traitement intelligents (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>'

À partir de la réponse, notez le id du projet Extraction et traitement intelligents (IXP).

Obtenir des balises (versions publiées)

Les balises correspondent aux versions de modèle publiées marquées comme Pré-production ou Production dans l'interface utilisateur Extraction et traitement intelligents (IXP). Chaque balise inclut ses extracteurs et types de document associés. Pour obtenir des balises, exécutez les éléments suivants :

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

Obtenir des types de document

Pour obtenir des types de document, exécutez les éléments suivants :

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

Semblable à Document Understanding, chargez le fichier pour obtenir un 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 d'Extraction et traitement intelligents (IXP) prend en charge les approches de routage suivantes :

• Basé sur des balises - Routage par tag et documentTypeId. Cela est recommandé pour les workflows de Production ou de Pré-production.
• Basé sur ExtractorId - Routage par extractorId à l'aide du format : gpt_ixp_[version]. Par exemple, gpt_ixp_67), la même chose que pour les projets Document Understanding classiques ou modernes.

Extraction basée sur des balises

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

Synchrone (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 (multi-pages)

Démarrez :

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": "..." }. Interroger pour obtenir 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>'

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

Extraction basée sur ExtractorId

Utilise les mêmes points de terminaison basés sur un extracteur que Document Understanding classique ou moderne. L'ExtractorId pour Extraction et traitement intelligents (IXP) suit le format gpt_ixp_[version], qui est visible dans la réponse de découverte. Synchrone (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 réponse d'extraction d'Extraction et traitement intelligents (IXP)

API v1 ou v1.1

Dans v1 et v1.1, les groupes de champs Extraction et traitement intelligents (IXP) sont mappés à FieldType: "Table" dans la réponse, avec des champs individuels en tant que colonnes de table. Toutes les valeurs sont représentées sous forme de texte (string), quel que soit leur type de données Extraction et traitement intelligents (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 structurelles par rapport à Document Understanding (v1 ou v1.1) :

• Tous les champs appartiennent à des groupes de champs, qui apparaissent en tant que type Table dans la réponse.
• Même les champs à valeur unique sont enveloppés dans une structure de ligne de table.
• L'array Tables contient les valeurs réelles de la cellule.

API v2

Dans la v2, les groupes de champs Extraction et traitement intelligents (IXP) sont mappés vers FieldType: "FieldGroup" au lieu de Table. Il s'agit d'une cartographie exacte du concept de groupe de champs Extraction et traitement intelligents (IXP). Chaque champ préserve son type de données Extraction et traitement intelligents (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, vérifiez 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 v1 :

• FieldType: "FieldGroup" remplace FieldType: "Table".
• L'Array Tables est supprimé. Les groupes de champs sont renvoyés directement dans Fields.
• Les champs individuels préservent leurs types de données Extraction et traitement intelligents (IXP) au lieu d'être tous des chaînes.
• Les ID de champ utilisent la notation par points, par exemple, Default.Seller.Name).

Structure de réponse de découverte d'Extraction et traitement intelligents (IXP)

Les projets Extraction et traitement intelligents (IXP) exposent le contrôle de version via des balises et des projectVersions :

{
  "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 mappe au libellé Production ou Pré-production dans l'interface utilisateur Extraction et traitement intelligents (IXP).

Remarque :

• Aucune invite nécessaire : contrairement à l'extracteur/classifieur DU génératif, le schéma d'extraction d'Extraction et traitement intelligents (IXP) est prédéfini dans la taxonomie du projet Extraction et traitement intelligents (IXP). Vous ne transmettez pas prompts dans l'appel d'API.
• Balise = version du modèle : utilisez la balise qui correspond à la version de production ou de pré-production que vous souhaitez appeler.
• DocumentTypeId : les projets Extraction et traitement intelligents (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.