Utilización de la API de enriquecimiento externo

La característica de enriquecimiento externo no está soportada en la API de análisis.

La característica de enriquecimiento externo le permite anotar documentos con un modelo de su elección. A través de una interfaz de webhook, puede utilizar modelos personalizados o modelos de base avanzada, y otros modelos de terceros para enriquecer los documentos de una colección. Los documentos se enriquecen mediante la aplicación externa y, a continuación, se fusionan con una colección en un proyecto de descubrimiento.

IBM Cloud Pak for Data cuando ejecute xml-ph-0000@deepl.internal en un entorno aislado, debe conectarse a la aplicación externa a través de un proxy de xml-ph-0001@deepl.internal IBM Software Hub Cuando ejecute Discovery en un entorno aislado, debe conectarse a la aplicación externa a través de un proxy de HTTP. Para obtener más información, consulte Configuración de un proxy de HTTP en entornos aislados.

Para utilizar la característica de enriquecimiento externo, haga lo siguiente:

Configure la aplicación externa que puede recibir notificaciones de webhook de Discovery y anotar documentos.

Para ello, debe registrar la app externa como un punto final de webhook en un proyecto utilizando el método create enrichment. Para obtener más información, consulte Crear enriquecimiento en la referencia de API.

Después de configurar el enriquecimiento externo para un proyecto, pasa a estar disponible para todas las colecciones del proyecto. La aplicación externa también recibe un suceso de webhook ping, que notifica que se ha creado un enriquecimiento externo.
Especifique la colección en la que desea aplicar el enriquecimiento externo. Puede utilizar la API para aplicar el enriquecimiento externo a una colección. Para obtener más información, consulte Utilización de la API para gestionar enriquecimientos.

De forma alternativa, en la interfaz de usuario, puede examinar la página Gestionar colecciones y elegir la colección donde desea aplicar el enriquecimiento externo. A continuación, abra el separador Enriquecimientos y aplique el enriquecimiento externo a un campo de la colección.

Cuando los documentos se procesan o cargan en esta colección, Discovery crea un lote de documentos con un batch_id exclusivo. La aplicación externa también recibe un suceso de webhook enrichment.batch.created, que notifica que los lotes están listos para ser extraídos. A continuación, la aplicación externa puede extraer lotes de Discovery para el enriquecimiento externo.

Si la aplicación externa concluye o se reinicia entre medio, puede obtener lo siguiente utilizando el método Listar lotes:
- Lotes notificados que la aplicación de enriquecimiento externa aún no ha extraído.
- Lotes extraídos, pero que la aplicación de enriquecimiento externa aún no ha enviado a Discovery.
Para obtener más información, consulte Listar lotes en la referencia de API.
Especifique el batch_id proporcionado por Discovery en el método pull batches para extraer los documentos de Discovery para el enriquecimiento por parte de la aplicación externa. Para obtener más información, consulte Extraer lotes en la referencia de API.

El método pull batches devuelve un archivo adjunto binario de Discovery. Para obtener más información sobre el archivo adjunto binario, consulte Archivo adjunto binario del método de extracción de lotes.
Especifique el mismo batch_id en el método push batches después de que el enriquecimiento externo anote los documentos en el lote. Para obtener más información, consulte Envío por lotes en la referencia de API.

Los documentos se envían a Discovery como un archivo adjunto binario. Para obtener más información, consulte Archivo adjunto binario en el método de envío por lotes.
Verifique que los documentos se fusionan e indexan en la colección. Los documentos deben contener las anotaciones que aplica la aplicación externa.

Autentificación de la solicitud para la seguridad del webhook

Para autenticar la solicitud del webhook, verifique la señal web JSON (JWT) que se envía con la solicitud. El microservicio del webhook genera automáticamente una JWT y lo envía en la cabecera Authorization con cada llamada de webhook. Es responsabilidad del usuario añadir código al servicio externo que verifica la JWT.

El sistema puede generar un JWT basado en el sample secret que especifique y, en la cabecera Authorization, puede pasar este JWT generado por el sistema a la aplicación externa. Si especifica un valor en header, el microservicio webhook envía ese valor a la aplicación externa en lugar del JWT.

Por ejemplo, si especifica sample secret en el campo Secret del objeto Webhooks en las API Crear colección o actualizar colección, puede añadir código de ejemplo como el siguiente en Node.js:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'sample secret');
} catch(err) {
  // error thrown if token is invalid
}

Modelo de datos del suceso `ping`

A continuación se muestran los parámetros de suceso ping :

suceso de ping
Parámetro	Descripción
`event`	El nombre del suceso es `ping`.
`instance_id`	El ID de instancia de Discovery.
`version`	La versión de la API Discovery en el formato `yyyy-mm-dd`.
`data`	Un objeto con la información del evento: `url`, `events`, y `metadata`. `url` : El punto final del webhook configurado ( URL ). `events` : Una matriz de valores de cadena de eventos. Los eventos de esta matriz se envían al webhook URL. `metadata` : Un objeto con información específica del webhook creado.
`created_at`	La fecha y hora en que se creó el evento.

Modelo de datos del suceso `enrichment.batch.created`

A continuación se muestran los parámetros de suceso enrichment.batch.created :

Enrichment.batch.created
Parámetro	Descripción
`event`	El nombre del suceso es `enrichment.batch.created`.
`instance_id`	El UUID de la instancia de Discovery, que también se conoce como ID de arrendatario.
`version`	La fecha de versión del suceso de webhook en el formato `yyyy-mm-dd`.
`data`	Un objeto con la información específica del suceso: `project_id`, `collection_id`, `enrichment_id` y `batch_id`. `project_id`: el UUID (Universally Unique Identifier) de un proyecto. `collection_id`: el UUID (Universally Unique Identifier) de una colección. `enrichment_id`: el UUID (Universally Unique Identifier) de un enriquecimiento. `batch_id`: el UUID (Universally Unique Identifier) de un lote.
`created_at`	La fecha y hora en que se creó el evento.

Límites de enriquecimiento externo

Límites de enriquecimiento externo
Planifique	Cantidad máxima de enriquecimiento de webhook por colección	Cantidad máxima de enriquecimiento de webhook por arrendatario
Empresa	1	100
Más	1	10
Premium	1	100

Conexión binaria del método de extracción de lotes

El método pull batches devuelve un archivo adjunto binario de Discovery.

El archivo devuelto es un archivo JSON delimitado por nueva línea (NDJSON) comprimido. Este archivo contiene datos estructurados que representan las propiedades del documento. Por ejemplo, el siguiente es un valor JSON incluido en el archivo NDJSON:

{
    "document_id": "3bafc09abfaacd90d66f57181b50d041",
    "location_encoding": "utf-16",
    "language": "en",
    "artifact": "{\"text_positions\":[0,21],\"space_above\":93.07864284515381,\"space_below\":32.53530788421631,\"is_start_of_block\":true,\"image_id\":-1}{\"text_positions\":[22,63],\"space_above\":32.53530788421631,\"space_below\":13.935576438903809,\"is_start_of_block\":true,\"image_id\":-1}{\"parent_document_id\":\"3bafc09abfaacd90d66f57181b50d041\",\"source\":{\"ListId\":\"f0ac1d32-b9e5-41af-b9da-e1e37e965d99\",\"UniqueId\":\"357d7a48-4460-442c-be56-d8bdd40a8c36\",\"ServerRelativeUrl\":\"/Lists/list1/Attachments/1/addattachments.csv\",\"FileNameAsPath\":{\"DecodedUrl\":\"addattachments.csv\"},\"ListItemId\":\"284dcb51-8021-56d0-9213-7f4eb134e083\",\"FileName\":\"addattachments.csv\",\"ServerRelativePath\":{\"DecodedUrl\":\"/Lists/list1/Attachments/1/addattachments.csv\"},\"WebId\":\"ad5bf592-3b4e-4dd1-bd3e-abc0ef179b03\"},\"ingest_datetime\":\"2023-06-26T09:24:02.573Z\",\"application_id\":\"sharepoint\",\"application_sub_type\":\"ListItemAttachmentCollection\"}0.51vanilla ice creamcontamination_tamperingotherchange_of_propertiesI love the ads for the new milk chocolate. Could you tell me the name of the actor in the commercial?{\"metadata\":{\"numPages\":\"54\",\"title\":\"\",\"publicationdate\":\"2010-06-03\"},\"info\":{\"histogram\":{\"mean-char-height\":{},\"mean-char-width\":{},\"number-of-chars\":{}},\"styles\":[]}}1451692800000",
    "features": [
        {
            "type": "field",
            "location": {
                "begin": 0,
                "end": 128
            },
            "properties": {
                "field_name": "multi_nested",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 128,
                "end": 258
            },
            "properties": {
                "field_name": "multi_nested",
                "field_index": 1,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 258,
                "end": 889
            },
            "properties": {
                "field_name": "metadata",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 889,
                "end": 892
            },
            "properties": {
                "field_name": "claim_score",
                "field_index": 0,
                "field_type": "double"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 892,
                "end": 893
            },
            "properties": {
                "field_name": "claim_id",
                "field_index": 0,
                "field_type": "long"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 893,
                "end": 910
            },
            "properties": {
                "field_name": "claim_product",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 910,
                "end": 933
            },
            "properties": {
                "field_name": "label",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 933,
                "end": 938
            },
            "properties": {
                "field_name": "label",
                "field_index": 1,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 938,
                "end": 958
            },
            "properties": {
                "field_name": "label",
                "field_index": 2,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 958,
                "end": 1059
            },
            "properties": {
                "field_name": "body",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 1059,
                "end": 1230
            },
            "properties": {
                "field_name": "nested",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 1230,
                "end": 1243
            },
            "properties": {
                "field_name": "claim_date",
                "field_index": 0,
                "field_type": "date"
            }
        }
    ]
}

A continuación se muestran las propiedades del archivo binario:

Propiedades del archivo binario del método pull
Propiedad	Tipo	Descripción
`document_id`	`string`	El identificador del documento.
`location_encoding`	`string`	El tipo de codificación utilizado para calcular la ubicación de cada característica. Los tipos soportados son: `utf-8`, `utf-16` y `utf-32`. La aplicación de enriquecimiento externo debe calcular la ubicación de cada característica basándose en el `location_encoding` del documento correspondiente de Discovery. La ubicación de las características en una representación de serie de datos varía en función del tipo de codificación del lenguaje de programación que se utiliza para implementar el enriquecimiento externo. Por ejemplo, C++ y Go utilizan UTF-8, Java y JavaScript utilizan UTF-16y Python utiliza UTF-32.
`language`	`string`	El idioma del contenido del documento.
`artifact`	`string`	El paquete de todos los valores de texto.
`features`	`array`	La lista de características de un documento. Para más información, consulte Tipos de funciones.

Conexión binaria en el método de envío por lotes

Después del enriquecimiento externo, los documentos se pueden enviar a Discovery como un archivo adjunto binario en el método push batches.

El archivo debe ser un archivo NDJSON comprimido con datos estructurados que representen las propiedades del documento. Por ejemplo, el siguiente es un archivo NDJSON:

{
  "document_id": "3bafc09abfaacd90d66f57181b50d041",
  "features": [
    {
      "type": "annotation",
      "location": {
        "begin": 958,
        "end": 1000
      },
      "properties": {
        "type": "element_classes",
        "class_name": "expression",
        "confidence": 0.7905777096748352
      }
    },
    {
      "type": "annotation",
      "location": {
        "begin": 1001,
        "end": 1059
      },
      "properties": {
        "type": "element_classes",
        "class_name": "question",
        "confidence": 0.9507029056549072
      }
    },
    {
      "type": "annotation",
      "location": {
        "begin": 1035,
        "end": 1040
      },
      "properties": {
        "type": "entities",
        "entity_type": "JobTitle",
        "entity_text": "actor",
        "confidence": 0.70953685
      }
    },
    {
      "type": "annotation",
      "properties": {
        "type": "document_classes",
        "class_name": "amount.shortage",
        "confidence": 0.43297016620635986
      }
    },
    {
      "type": "notice",
      "properties": {
        "description": "something wrong happened",
      }
    },
    {
      "type": "notice",
      "properties": {
        "description": "something wrong happened again",
        "created": 1689076276402,
      }
    }
  ]
}

A continuación se muestran las propiedades del archivo binario:

Propiedades del archivo binario del método Push
Propiedad	Tipo	Descripción
`document_id`	`string`	El identificador del documento.
`features`	`array`	La lista de características de un documento. Para más información, consulte Tipos de funciones.

Tipos de característica

Una característica type puede ser una de las siguientes en un archivo binario:

Tipos de característica
Característica	Tipo	Descripción
`field`	`string`	Representa un valor de campo específico del documento.
`annotation`	`string`	Representa una anotación específica que puede enriquecer el documento.
`notice`	`string`	Representa cualquier error que pueda producirse en la aplicación externa durante el enriquecimiento de documentos. La información de `notice` se utiliza para generar un mensaje en la interfaz de usuario de Discovery.

A continuación se muestran las otras propiedades del archivo binario:

Otras propiedades del archivo binario
Característica	Tipo	Descripción
`location`	`object`	Información de ubicación para obtener el valor de texto de `artifact` utilizando los valores `begin` y `end`. El valor `begin` es un valor de serie que representa la ubicación inicial del artefacto. El valor `end` es un valor de serie que representa una ubicación final exclusiva en el artefacto. Esta propiedad es nula cuando una característica representa una información de nivel de documento. Por ejemplo, cuando `type=annotation` y `properties.type=document_classes`.
`properties`	`object`	Las propiedades de una característica en el documento. Las propiedades admitidas varían en función de la e `type` a de la función. Para obtener más información, consulte Propiedades de tipo de campo, Propiedades de tipo de anotación y Propiedades de tipo de aviso.

Propiedades de tipo de campo

Para el tipo field, las propiedades siguientes representan un determinado campo del documento que ha convertido Discovery a partir de un archivo original:

Propiedades de tipo de campo
Propiedad	Tipo	Descripción
`field_name`	`string`	El nombre del campo.
`field_index`	`int`	El índice de un valor de campo. Este valor es `0` para un campo de valor único, pero puede ser `> 0` cuando un campo tiene varios valores, como, por ejemplo, para una matriz de valores.
`field_type`	`string` (enumeración: `long`, `double`, `date`, `json`)	El tipo de datos de la función. Este valor determina cómo analizar la representación de texto de la característica en un lenguaje de programación.

Propiedades de tipo de anotación

Para el tipo annotation, las propiedades siguientes representan una anotación que puede enriquecer un documento:

Propiedades de tipo de anotación
Propiedad	Tipo	Descripción
`type`	`string` (enumeración: `entities`, `element_classes`, `document_classes`)	El tipo de anotación enriquecida que representa una característica. Los `entities` se fusionan con entidades de campos enriquecidos. Los `element_classes` se fusionan con clases de elementos de campos enriquecidos. Los `document_classes` se fusionan con las clases del campo de enriquecimiento de nivel de documento.
`confidence`	`double`	Puntuación de confianza opcional por el modelo externo. Está entre `0` y `1`, y es `0` de forma predeterminada.
`entity_type`	`string`	El tipo de entidad que un modelo externo asigna a una cosa. Necesario para el tipo `entities`.
`entity_text`	`string`	El texto representativo de una entidad que la aplicación externa extrae. Necesario para el tipo `entities`.
`class_name`	`string`	El nombre de una clase que la aplicación externa asigna a una cosa. Necesario para el tipo `element_classes` y `document_classes`.

Propiedades de tipo de aviso

Para el tipo notice, las propiedades siguientes representan errores y excepciones que se han producido en la aplicación externa al enriquecer un documento:

Propiedades de tipo de aviso
Propiedad	Tipo	Descripción
`description`	`string`	El mensaje que describe un error que se ha producido durante el enriquecimiento externo.
`created`	`long`	Tiempo de época de Unix en milisegundos cuando se ha producido un error durante el enriquecimiento externo.

Utilización de la API de enriquecimiento externo

Utilización de la API de enriquecimiento externo

Autentificación de la solicitud para la seguridad del webhook

Modelo de datos del suceso ping

Modelo de datos del suceso enrichment.batch.created

Límites de enriquecimiento externo

Conexión binaria del método de extracción de lotes

Conexión binaria en el método de envío por lotes

Tipos de característica

Propiedades de tipo de campo

Propiedades de tipo de anotación

Propiedades de tipo de aviso

Modelo de datos del suceso `ping`

Modelo de datos del suceso `enrichment.batch.created`