Consumir modelos a través de la API de Document Understanding

Accede a modelos de Extracción y Procesamiento Inteligentes (IXP) creados en nodos de extracción de flujo a través de la API del marco de Document Understanding utilizando puntos finales de extracción basados en etiquetas o en extractorId.

Se puede acceder a los nodos de extracción de Extracción y Procesamiento Inteligentes (IXP) a través de la misma API del marco de Document Understanding. Los nodos de extracción aparecen como ProjectType: "IXP" en Descubrimiento y admiten tanto puntos finales basados en etiquetas como puntos finales basados en extractorId para la extracción.

Documentación relacionada:

• Información general de la API de Document Understanding
• Crear aplicación externa para Document Understanding
• Administrar aplicaciones externas

Nota:

Utiliza la API v2 para consumir los modelos de nodos de extracción y utiliza la última versión de las API públicas de Document Understanding. Los ejemplos de esta página utilizan la API v2 (api-version=2).

Requisitos previos

Antes de llamar a cualquier API de Document Understanding o de Extracción y Procesamiento Inteligentes (IXP), debes tener registrada una aplicación externa en Automation Cloud. Esto proporciona el AppID y el AppSecret que se utilizan para la autenticación de OAuth.

Crear una aplicación externa

1. Ve a Orchestrator a nivel de tenant.

2. Selecciona Gestionar acceso y luego Gestionar cuentas y grupos.

3. En el encabezado Administración de UiPath, selecciona Aplicaciones externas.

4. Selecciona Añadir aplicación.

5. Rellena el nombre de la aplicación, por ejemplo, DU API Client.

6. Selecciona Aplicación confidencial, que es necesaria para obtener un secreto de la aplicación.

7. En Recursos, selecciona Añadir ámbitos:

   • Selecciona Document Understanding en la lista desplegable Recurso.
   • Cambia a la pestaña Ámbitos de la aplicación.
   • Marca los ámbitos que necesitas:
     • Du.Digitization.Api : digitalizar documentos
     • Du.Classification.Api : clasificar documentos
     • Du.Extraction.Api : extraer datos
     • Du.Validation.Api : crear tareas de validación
     • Du.DataDeletion.Api : eliminar datos del documento
   • Selecciona Guardar.

8. Selecciona Añadir para crear el registro.

   Nota:

   La ventana emergente Copiar el secreto de la aplicación inmediatamente se muestra solo una vez y no se puede recuperar. Puedes generar otro más tarde en la pantalla de edición.

El ID de aplicación se muestra siempre en la página Aplicaciones externas.

Obtener un token de acceso

Usa el ID y el secreto de la aplicación para solicitar un token de OAuth a través del flujo de credenciales de cliente:

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'

Respuesta:

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

El token caduca al cabo de 1 hora. Úsalo como Authorization: Bearer <your-access-token> en todas las llamadas a la API posteriores.

Nota:

Si pierdes el secreto de la aplicación, ve a Admin y, luego, a Aplicaciones externas, edita la aplicación y selecciona Generar nuevo en Secreto de la aplicación. Actualiza todas las integraciones con el secreto nuevo.

Principales diferencias

La siguiente tabla muestra las principales diferencias entre los proyectos de Document Understanding y de Extracción y Procesamiento Inteligentes (IXP):

	Document Understanding (clásico o moderno)	IXP (Extracción y Procesamiento Inteligentes)
Tipo de proyecto	Classic o Modern	IXP
Clasificación	Sí	No (solo extracción)
Enrutamiento de la extracción	Por tag + documentTypeId (recomendado) o extractorId	Por tag + documentTypeId o por extractorId (gpt_ixp_[version])
Modelo de extracción	Especializado o generativo	Solo generativo (GPT-4o o Gemini)
Definición del esquema	En el proyecto o a través de solicitudes	Definido en la IU de Extracción y Procesamiento Inteligentes (IXP) (taxonomía)

El flujo de trabajo de Extracción y Procesamiento Inteligentes (IXP)

1. Descubrir el proyecto y las etiquetas.
2. Digitalice el documento y sondee hasta que finalice la digitalización.
3. Extraer y sondear hasta que finalice la extracción.
4. Validar (opcional).

Nota:

No hay un paso de clasificación, ya que Extracción y Procesamiento Inteligentes (IXP) solo gestiona extracciones.

Paso 1: descubrir el Proyecto de Extracción y Procesamiento Inteligentes (IXP)

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

En la respuesta, ten en cuenta el id del proyecto Extracción y Procesamiento Inteligentes (IXP).

Obtener etiquetas (versiones publicadas)

Las etiquetas corresponden a versiones del modelo publicadas y marcadas como Preparación o Producción en la interfaz de usuario de Extracción y Procesamiento Inteligentes (IXP). Cada etiqueta incluye sus extractores y tipos de documentos asociados. Para obtener etiquetas, ejecuta lo siguiente:

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

Obtener tipos de documentos

Para obtener tipos de documentos, ejecuta lo siguiente:

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

Nota:

Después de conocer el ID del proyecto, la etiqueta y el ID del tipo de documento, no es necesario ejecutar las llamadas de descubrimiento en runtime cada vez. Reutiliza estos valores en tu automatización.

Paso 2: digitalizar el documento

Nota:

La digitalización es un paso obligatorio. No se pueden extraer datos de un documento antes de digitalizarlo.

Similar a Document Understanding, carga el archivo para obtener un documentId:

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'

Devuelve { "documentId": "..." }.

Sondeo para el resultado de la digitalización:

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

Sondee hasta que status sea Succeeded y luego inicie la extracción. Para ver los posibles estados y respuestas, consulta Respuestas de sondeo.

Paso 3: extraer

La extracción de Extracción y Procesamiento Inteligentes (IXP) admite los siguientes enfoques de enrutamiento:

• Basado en etiquetas: enruta por tag y documentTypeId. Se recomienda para los flujos de trabajo de producción o de preparación.
• Basado en ExtractorId : enrutar por extractorId utilizando el formato: gpt_ixp_[version]. Por ejemplo, gpt_ixp_67. Esto es lo mismo que para los proyectos de Document Understanding clásico o moderno.

Extracción basada en etiquetas

Utiliza la ruta basada en etiquetas con el documentTypeId de Discovery.

Síncrona (hasta 5 páginas)

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

Asíncrona (multipágina)

Inicio:

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

Devuelve { "operationId": "..." }. Sondeo sobre el resultado:

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

Sondee hasta que status sea Succeeded o Failed. Para ver los posibles estados y respuestas, consulta Respuestas de sondeo.

Extracción basada en ExtractorId

Utiliza los mismos puntos finales basados en extractores que el Document Understanding clásico o moderno. El ExtractorId para Extracción y Procesamiento Inteligentes (IXP) sigue el formato gpt_ixp_[version], que se ve en la respuesta de Discovery. Síncrona (hasta 5 páginas):

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

Asíncrona (multipágina):

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

Devuelve { "operationId": "..." }. Sondeo sobre el resultado:

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

Sondee hasta que status sea Succeeded o Failed. Para ver los posibles estados y respuestas, consulta Respuestas de sondeo.

Paso 4: validar (opcional)

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

Respuestas de sondeo

Las llamadas de digitalización asíncrona del paso 2 y las llamadas de extracción asíncrona del paso 3 devuelven sus resultados a través del sondeo. Cada respuesta de la encuesta contiene un status, que es uno de los siguientes:

• NotStarted : el trabajo se ha creado y está esperando a ser procesado.
• Running : el trabajo se ha recogido y se está procesando.
• Succeeded : el trabajo finalizó correctamente. La respuesta contiene el result.
• Failed : el trabajo finalizó con un error. La respuesta contiene el error.

Siga sondeando mientras el estado sea NotStarted o Running.

Mientras se procesa el trabajo, la respuesta contiene el estado y las marcas de tiempo del trabajo:

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

Cuando el trabajo se realiza correctamente, la respuesta también contiene el result. Para la extracción, el resultado está en result.extractionResult. Para conocer su estructura, consulta Estructura de respuesta de extracción de Extracción y Procesamiento Inteligentes (IXP).

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

Cuando el trabajo falla, la respuesta contiene un objeto error con los siguientes detalles:

• message : la descripción del error.
• severity : la gravedad del fallo, más comúnmente Error.
• code : el código que identifica el tipo de error.
• parameters : información adicional sobre el error, si corresponde.

Para obtener más detalles, consulta Esquemas de respuesta de solicitudes en la guía de la API de Document Understanding.

Estructura de la respuesta de la extracción de Extracción y Procesamiento Inteligentes (IXP)

En la API v2, todos los campos y valores notificados por Extracción y Procesamiento Inteligentes (IXP) utilizan tipos de campo correctos, incluidos grupos de campos y campos secundarios, utilizando una asignación exacta del grupo de campos de Extracción y Procesamiento Inteligentes (IXP) y las definiciones de campos secundarios.

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

Nota:

Recomendamos utilizar la API v2 para el consumo de Extracción y Procesamiento Inteligentes (IXP), debido a la asignación uno a uno entre los grupos de campos y los tipos de campo del proyecto de Extracción y Procesamiento Inteligentes (IXP) y los resultados notificados.

Estructura de la respuesta del descubrimiento de Extracción y Procesamiento Inteligentes (IXP)

Los proyectos de Extracción y Procesamiento Inteligentes (IXP) exponen las versiones a través de etiquetas y projectVersions:

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

El nombre de la etiqueta, por ejemplo, live, se asigna a la etiqueta Producción o Clasificación en la interfaz de usuario de Extracción y Procesamiento Inteligentes (IXP).

Ten en cuenta lo siguiente al llamar a los puntos finales de extracción de Extracción y Procesamiento Inteligentes (IXP):

• Etiqueta = versión del modelo: utiliza la etiqueta que corresponde a la versión de producción o de preparación a la que quieres llamar.
• DocumentTypeId: los proyectos de Extracción y Procesamiento Inteligentes (IXP) suelen utilizar un solo tipo de documento predeterminado (00000000-0000-0000-0000-000000000000).
• Límites de página: para los límites de página y token, consulta Límites de procesamiento de documentos.
• Medición: para obtener más información sobre cómo se cobra la extracción de Extracción y Procesamiento Inteligentes (IXP), consulta Plan de precios Flex de Extracción y Procesamiento Inteligentes (IXP), Unified Pricing y Lógica de medición y carga (Plan Flex).
• Retención de datos: para obtener más información sobre cuánto tiempo se conservan los resultados de digitalización y extracción, consulta la descripción general de la API de Document Understanding.