Usando a API de enriquecimento externo
O recurso de enriquecimento externo não é suportado na API do Analyze
O recurso de enriquecimento externo permite anotar documentos com um modelo de sua escolha. Por meio de uma interface de webhook, é possível usar modelos customizados ou modelos de base avançados e outros modelos de terceiros para enriquecer seus documentos em uma coleta. Os documentos são enriquecidos por seu aplicativo externo e, em seguida, mesclados em uma coleção em um projeto de Descoberta
IBM Cloud Pak for DataIBM Software Hub Ao executar o Discovery em um ambiente com air-gap, você deve se conectar ao aplicativo externo por meio de um proxy HTTP. Para obter mais informações, consulte Configuração do proxy HTTP em ambientes com air-gap.
Para usar o recurso de enriquecimento externo, faça o seguinte:
-
Configure o aplicativo externo que pode receber notificações de webhook do Discovery e anotar documentos.
Para isso, deve-se registrar seu app externo como um terminal de webhook em um projeto usando o método
create enrichment. Para obter mais informações, consulte Criar enriquecimento na referência da APIDepois de configurar o enriquecimento externo para um projeto, ele se torna disponível para todas as coleções no projeto O aplicativo externo também recebe um evento
pingde webhook, que notifica que um enriquecimento externo é criado -
Especifique a coleção na qual você deseja aplicar o enriquecimento externo É possível usar a API para aplicar o enriquecimento externo a uma coleta Para obter mais informações, consulte Usando a API para gerenciar enriquecimentos.
Como alternativa, na interface com o usuário, é possível navegar para a página Gerenciar coleções e escolher a coleção na qual você deseja aplicar o enriquecimento externo Em seguida, abra a guia Enriquecimentos e aplique seu enriquecimento externo a um campo na coleta..
Quando documentos são processados ou transferidos por upload para essa coleção, o Discovery cria um lote de documentos com um
batch_idexclusivo. O aplicativo externo também recebe um eventoenrichment.batch.createdde webhook, que notifica que os lotes estão prontos para serem extraídos Seu aplicativo externo pode então extrair lotes do Discovery para enriquecimento externo.Se o aplicativo externo for encerrado ou reiniciado no meio, será possível obter o seguinte usando o método Listar lotes:
- Lotes notificados que ainda não foram extraídos pelo aplicativo de enriquecimento externo
- Lotes que são extraídos, mas ainda não enviados por push para o Discovery pelo aplicativo de enriquecimento externo.
Para obter mais informações, consulte Listar lotes na referência da API..
-
Especifique o
batch_idfornecido pelo Discovery no métodopull batchespara extrair os documentos do Discovery para enriquecimento por seu aplicativo externo. Para obter mais informações, consulte Lotes de pull na referência da API (interface de programação de aplicativos)O método
pull batchesretorna um anexo de arquivo binário do Discovery. Para obter mais informações sobre o anexo binário, consulte Anexo binário do método de lotes de pull. -
Especifique o mesmo
batch_idno métodopush batchesdepois que seu enriquecimento externo anotar os documentos no lote Para obter mais informações, consulte Push batches na referência de API (interface de programação de aplicativos)Os documentos são enviados para o Discovery como um anexo binário. Para obter mais informações, consulte Anexo binário no método de lotes push.
-
Verifique se os documentos são mesclados e indexados na coleção Os documentos devem conter as anotações que são aplicadas pelo aplicativo externo.
Autenticação da solicitação para segurança do webhook
Para autenticar a solicitação do webhook, verifique o JSON Web Token (JWT) que é enviado com a solicitação. O microserviço de webhook gera automaticamente um JWT e o envia no cabeçalho Authorization com cada chamada de webhook.
É sua responsabilidade incluir um código no serviço externo que verifica o JWT.
O sistema pode gerar um JWT com base no sample secret especificado e, no cabeçalho Authorization, é possível transmitir esse JWT gerado pelo sistema para o aplicativo externo. Se você especificar um valor no header,
o microsserviço webhook enviará esse valor para o aplicativo externo em vez do JWT.
Por exemplo, se você especificar sample secret no campo Secret do objeto Webhooks nas APIs Criar coleção ou atualizar coleção, poderá incluir um código de amostra como o seguinte em 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 dados do evento ping
A seguir estão os parâmetros de evento ping :
| Parâmetro | Descrição |
|---|---|
event |
O nome do evento é ping |
instance_id |
A ID da instância Discovery. |
version |
A versão da API Discovery no formato yyyy-mm-dd. |
data |
Um objeto com as informações do evento:
|
created_at |
A data e a hora em que o evento foi criado. |
Modelo de dados do evento enrichment.batch.created
A seguir estão os parâmetros de evento enrichment.batch.created :
| Parâmetro | Descrição |
|---|---|
event |
O nome do evento é enrichment.batch.created |
instance_id |
O UUID da instância do Discovery, que também é conhecido como o ID do locatário. |
version |
A data da versão do evento de webhook no formato yyyy-mm-dd |
data |
Um objeto com as informações específicas do evento:
|
created_at |
A data e a hora em que o evento foi criado. |
Limites de enriquecimento externos
| Plano | Quantia máxima de enriquecimento de webhook por coleção.. | Quantia máxima de enriquecimento de webhook por locatário |
|---|---|---|
| Enterprise | 1 | 100 |
| Mais | 1 | 22 |
| Premium | 1 | 100 |
Anexo binário do método de pull batches
O método pull batches retorna um arquivo de anexo binário do Discovery.
O arquivo retornado é um arquivo JSON (NDJSON) compactado delimitado por nova linha Este arquivo contém dados estruturados que representam as propriedades do documento Por exemplo, o seguinte é um valor JSON incluído no arquivo 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 seguir estão as propriedades de arquivo binário:
| Propriedade | Tipo | Descrição |
|---|---|---|
document_id |
string |
O identificador do documento. |
location_encoding |
string |
O tipo de codificação usado para calcular o local de cada recurso Os tipos suportados são: utf-8, utf-16 e utf-32. O aplicativo de enriquecimento externo deve calcular o local de cada recurso com
base no location_encoding do documento correspondente do Discovery. O local dos recursos em uma representação em sequência de dados varia dependendo do tipo de codificação da linguagem de programação usada para implementar
o enriquecimento externo. Por exemplo, C++ e Go usam UTF-8, Java e JavaScript usam UTF-16e Python usam UTF-32. |
language |
string |
O idioma do conteúdo do documento |
artifact |
string |
O pacote de todos os valores de texto |
features |
array |
A lista de recursos em um documento.. Para obter mais informações, consulte Tipos de recursos. |
Anexo binário no método de lotes push
Após o enriquecimento externo, os documentos podem ser enviados para o Discovery como um anexo binário no método push batches.
O arquivo deve ser um arquivo NDJSON compactado com dados estruturados que representam as propriedades do documento.. Por exemplo, o seguinte é um arquivo 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 seguir estão as propriedades de arquivo binário:
| Propriedade | Tipo | Descrição |
|---|---|---|
document_id |
string |
O identificador do documento. |
features |
array |
A lista de recursos em um documento.. Para obter mais informações, consulte Tipos de recursos. |
Tipos de recurso:
Um recurso type pode ser um dos seguintes em um arquivo binário:
| Recursos | Tipo | Descrição |
|---|---|---|
field |
string |
Representa um valor de campo específico do documento.. |
annotation |
string |
Representa uma anotação específica que pode enriquecer o documento.. |
notice |
string |
Representa qualquer erro que possa ocorrer no aplicativo externo durante o enriquecimento de documento As informações em notice são usadas para gerar uma mensagem na IU de Descoberta |
A seguir estão as outras propriedades no arquivo binário:
| Recursos | Tipo | Descrição |
|---|---|---|
location |
object |
Informações de local para obter o valor de texto do artifact usando os valores begin e end. O valor begin é um valor de sequência que representa o local de início no artefato. O valor
end é um valor de sequência que representa um local final exclusivo no artefato. Essa propriedade é nula quando um recurso representa informações de nível de documento. Por exemplo, quando type=annotation e
properties.type=document_classes. |
properties |
object |
As propriedades de um recurso no documento As propriedades compatíveis variam de acordo com o type do recurso. Para obter mais informações, consulte Propriedades de tipo de campo, Propriedades de tipo de notação e Propriedades de tipo de aviso. |
Propriedades do tipo de campo.
Para o tipo field, as propriedades a seguir representam um determinado campo do documento que foi convertido pela Descoberta de um arquivo original:
| Propriedade | Tipo | Descrição |
|---|---|---|
field_name |
string |
O nome do campo. |
field_index |
int |
O índice de um valor de campo. Esse valor é 0 para um campo com valor único, mas pode ser > 0 quando um campo tem diversos valores, como para uma matriz de valores. |
field_type |
string (enum: long, double, date, json) |
O tipo de dados do recurso. Esse valor determina como analisar a representação de texto do recurso em uma linguagem de programação |
Propriedades do tipo de anotação..
Para o tipo annotation, as seguintes propriedades representam uma anotação que pode enriquecer um documento:
| Propriedade | Tipo | Descrição |
|---|---|---|
type |
string (enumeração: entities, element_classes, document_classes) |
O tipo de anotação enriquecida que um recurso representa Os entities são mesclados com entidades de campos enriquecidos Os element_classes são mesclados para classes de elementos de campos enriquecidos Os document_classes são mesclados para classes de campo de enriquecimento de nível de documento |
confidence |
double |
A pontuação de confiança opcional pelo modelo externo Ele está entre 0 e 1 e é 0 por padrão |
entity_type |
string |
O tipo de entidade que um modelo externo designa a uma coisa Necessário para o tipo entities |
entity_text |
string |
O texto representativo de uma entidade que o aplicativo externo extrai Necessário para o tipo entities |
class_name |
string |
O nome de uma classe que o aplicativo externo designa a uma coisa Necessário para o tipo element_classes e document_classes.. |
Propriedades do tipo de aviso
Para o tipo notice, as propriedades a seguir representam erros e exceções que ocorreram no aplicativo externo ao enriquecer um documento:
| Propriedade | Tipo | Descrição |
|---|---|---|
description |
string |
A mensagem que descreve um erro que ocorreu durante o enriquecimento externo |
created |
long |
Tempo de época do Unix em milissegundos quando ocorreu um erro durante o enriquecimento externo. |