使用外部增益应用程序接口
在 Analyze API 中不支持外部扩充功能。
外部扩充功能允许您使用所选模型对文档进行注释。 通过 Webhook 界面，您可以使用定制模型或高级基础模型以及其他第三方模型来丰富集合中的文档。 这些文档由外部应用程序扩充，然后合并到 Discovery 项目中的集合。
IBM Cloud Pak for Data 当您在隔离的环境中运行xml-ph-0000@deepl.internal时，必须通过xml-ph-0001@deepl.internal代理连接到外部应用程序。IBM Software Hub 当您在隔离的环境中运行 时，必须通过 代理连接到外部应用程序。Discovery HTTP 更多信息，请参阅 在隔离环境中设置 HTTP 代理。
要使用外部扩充功能，请执行以下操作:
-
设置可从“发现”接收 Webhook 通知并对文档进行注释的外部应用程序。
要执行此操作，必须使用
create enrichment方法将外部应用程序注册为项目上的 Webhook 端点。 有关更多信息，请参阅 API 参考中的 创建扩充项。为项目设置外部扩充项后，它将可供项目中的所有集合使用。 外部应用程序还会接收 Webhook
ping事件，这将通知您已创建外部扩充项。 -
指定要在其中应用外部扩充项的集合。 您可以使用 API 将外部扩充应用于集合。 有关更多信息，请参阅 使用 API 来管理扩充项。
或者，在用户界面上，您可以浏览到“管理集合”页面，并选择要在其中应用外部扩充项的集合。 然后，打开 扩充项 选项卡，并将外部扩充项应用于集合中的字段。
处理文档或将文档上载到此集合时，Discovery 会创建一批具有唯一
batch_id的文档。 外部应用程序还会接收到 Webhookenrichment.batch.created事件，该事件会通知您已准备好拉取批处理。 然后，外部应用程序可以从 Discovery 中拉取批处理以进行外部扩充。如果外部应用程序在其间关闭或重新启动，那么可以使用“列示批处理”方法来获取以下内容:
- 外部扩充应用程序尚未拉取的已通知批处理。
- 已拉取但尚未由外部扩充应用程序推送到 Discovery 的批处理。
有关更多信息，请参阅 API 参考中的 列出批处理。
-
在
pull batches方法中指定 Discovery 提供的batch_id，以从 Discovery 中提取文档以供外部应用程序扩充。 有关更多信息，请参阅 API 参考中的 拉取批处理。pull batches方法从 Discovery 返回二进制文件附件。 有关二进制附件的更多信息，请参阅 来自拉取批处理方法的二进制附件。 -
在外部扩充项对批处理中的文档进行注释后，在
push batches方法中指定相同的batch_id。 有关更多信息，请参阅 API 参考中的 推送批处理。文档将作为二进制附件推送到 Discovery。 有关更多信息，请参阅 推送批处理方法中的二进制附件。
-
验证文档是否已在集合中合并并建立索引。 这些文档必须包含外部应用程序应用的注释。
为网络钩子安全自动识别请求
要认证 Webhook 请求，请验证随请求一起发送的 JSON Web 令牌 (JWT)。 Webhook 微服务会自动生成 JWT，并通过每个 Webhook 调用在 Authorization 头中发送该 JWT。 您负责向用于验证 JWT 的外部服务添加代码。
系统可以根据您指定的 sample secret 生成 JWT，并且在 Authorization 头中，可以将此系统生成的 JWT 传递到外部应用程序。 如果在 header 中指定值，那么 Webhook 微服务会将该值发送到外部应用程序，而不是 JWT。
例如，如果在 创建集合 或 更新集合 API 的 Webhook 对象的 Secret 字段中指定 sample secret，那么可以在 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
}
ping 事件的数据模型
以下是 ping 事件参数:
| 参数 | 描述 |
|---|---|
event |
事件名称为 ping。 |
instance_id |
Discovery 实例ID。 |
version |
Discovery API 版本，格式为 yyyy-mm-dd。 |
data |
一个包含事件信息的对象：
|
created_at |
创建活动的日期和时间。 |
enrichment.batch.created 事件的数据模型
以下是 enrichment.batch.created 事件参数:
| 参数 | 描述 |
|---|---|
event |
事件名称为 enrichment.batch.created。 |
instance_id |
Discovery 实例的 UUID，也称为租户标识。 |
version |
yyyy-mm-dd 格式的 Webhook 事件版本日期。 |
data |
具有特定于事件的信息的对象:
|
created_at |
创建活动的日期和时间。 |
外部扩充限制
| 计划 | 每个集合的最大 Webhook 扩充项数 | 每个租户的最大 Webhook 扩充量 |
|---|---|---|
| 企业 | 1 | 100 |
| 加 | 1 | 10 |
| Premium | 1 | 100 |
来自拉取批处理方法的二进制附件
pull batches 方法从 Discovery 返回二进制附件文件。
返回的文件是压缩的换行符分隔 JSON (NDJSON) 文件。 此文件包含表示文档属性的结构化数据。 例如，以下是 NDJSON 文件中包含的 JSON 值:
{
"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"
}
}
]
}
以下是二进制文件属性:
| 属性 | 类型 | 描述 |
|---|---|---|
document_id |
string |
文档的标识符。 |
location_encoding |
string |
用于计算每个功能部件的位置的编码类型。 受支持的类型包括: utf-8，utf-16 和 utf-32。 外部增补应用程序必须根据来自 Discovery 的相应文档的 location_encoding 计算每个功能部件的位置。 数据的字符串表示中特征的位置因用于实现外部扩充的编程语言的编码类型而异。 例如，C++ 和 Go 使用 UTF-8，Java 和 JavaScript
使用 UTF-16，而 Python 使用 UTF-32。 |
language |
string |
文档的内容语言。 |
artifact |
string |
所有文本值的包。 |
features |
array |
文档中的功能部件列表。 更多信息，请参阅 功能类型。 |
推送批处理方法中的二进制附件
外部扩充后，可以将文档作为 push batches 方法中的二进制附件推送到 Discovery。
该文件必须是具有表示文档属性的结构化数据的压缩 NDJSON 文件。 例如，以下是 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,
}
}
]
}
以下是二进制文件属性:
| 属性 | 类型 | 描述 |
|---|---|---|
document_id |
string |
文档的标识符。 |
features |
array |
文档中的功能部件列表。 更多信息，请参阅 功能类型。 |
功能部件类型
功能部件 type 可以是二进制文件中的下列其中一项:
| 特征 | 类型 | 描述 |
|---|---|---|
field |
string |
表示文档的特定字段值。 |
annotation |
string |
表示可扩充文档的特定注释。 |
notice |
string |
表示文档扩充期间外部应用程序中可能发生的任何错误。 notice 中的信息用于在发现 UI 上生成消息。 |
以下是二进制文件中的其他属性:
| 特征 | 类型 | 描述 |
|---|---|---|
location |
object |
用于通过使用 begin 和 end 值从 artifact 获取文本值的位置信息。 begin 值是表示工件中开始位置的字符串值。 end 值是表示工件中的互斥结束位置的字符串值。 当功能部件表示文档级别信息时，此属性为空。 例如，当 type=annotation 和 properties.type=document_classes 时。 |
properties |
object |
文档中功能部件的属性。 支持的属性因功能的 type 而异。 有关更多信息，请参阅 字段类型属性，注释类型属性 和 通知类型属性。 |
字段类型属性
对于 field 类型，以下属性表示 Discovery 从原始文件转换的文档的特定字段:
| 属性 | 类型 | 描述 |
|---|---|---|
field_name |
string |
字段名称。 |
field_index |
int |
字段值的索引。 对于单值字段，此值为 0，但当字段为多值 (例如，对于值数组) 时，此值可以为 > 0。 |
field_type |
string (枚举: long，double，date 和 json) |
功能的数据类型。 此值确定如何解析编程语言中功能部件的文本表示。 |
注释类型属性
对于 annotation 类型，以下属性表示可扩充文档的注释:
| 属性 | 类型 | 描述 |
|---|---|---|
type |
string (枚举: entities，element_classes 和 document_classes) |
功能部件所表示的扩充注释的类型。 entities 将合并到扩充字段的实体中。 element_classes 将合并到扩充字段的元素类。 document_classes 将合并到文档级别扩充字段的类中。 |
confidence |
double |
外部模型的可选置信度分数。 它介于 0 到 1 之间，缺省情况下为 0。 |
entity_type |
string |
外部模型分配给事物的实体类型。 对于 entities 类型是必需的。 |
entity_text |
string |
外部应用程序抽取的实体的代表文本。 对于 entities 类型是必需的。 |
class_name |
string |
外部应用程序分配给事物的类的名称。 对于 element_classes 和 document_classes 类型是必需的。 |
通知类型属性
对于 notice 类型，以下属性表示在扩充文档时在外部应用程序中发生的错误和异常:
| 属性 | 类型 | 描述 |
|---|---|---|
description |
string |
描述外部扩充期间发生的错误的消息。 |
created |
long |
外部扩充期间发生错误时的 Unix 戳记时间 (以毫秒为单位)。 |