使用外部豐富 API
Analyze API 不支援外部強化特性。
外部強化特性可讓您使用您選擇的模型來註釋文件。 透過 Webhook 介面，您可以使用自訂模型或進階基礎模型，以及其他協力廠商模型來強化集合中的文件。 這些文件由外部應用程式強化，然後合併至「探索」專案中的集合。
IBM Cloud Pak for DataIBM Software Hub 當您在 air-gapped 環境中執行 時，您必須透過 proxy 連線到外部應用程式。Discovery HTTP 如需詳細資訊，請參閱 在空氣封閉環境中設定 HTTP proxy。
如果要使用外部強化特性，請執行下列動作:
-
設定可從「探索」接收 Webhook 通知並註釋文件的外部應用程式。
若要這樣做，您必須使用
create enrichment方法，將外部應用程式登錄為專案上的 Webhook 端點。 如需相關資訊，請參閱 API 參考資料中的 建立強化。設定專案的外部強化之後，專案中的所有集合都可以使用它。 外部應用程式也會接收 Webhook
ping事件，這會通知已建立外部強化。 -
指定您要套用外部強化的集合。 您可以使用 API 將外部強化套用至集合。 如需相關資訊，請參閱 使用 API 來管理強化。
或者，在使用者介面上，您可以瀏覽至 管理集合 頁面，並選擇您要套用外部強化的集合。 然後，開啟 強化 標籤，並將外部強化套用至集合中的欄位。
當處理文件或將文件上傳至此集合時，「探索」會建立具有唯一
batch_id的文件批次。 外部應用程式也會收到 Webhookenrichment.batch.created事件，這會通知批次已備妥可供取回。 然後，您的外部應用程式可以從 Discovery 取回批次，以進行外部強化。如果外部應用程式在之間關閉或重新啟動，您可以使用「列出批次」方法來取得下列項目:
- 外部強化應用程式尚未取回的已通知批次。
- 由外部強化應用程式取回但尚未推送至「探索」的批次。
如需相關資訊，請參閱 API 參考資料中的 列出批次。
-
在
pull batches方法中指定「探索」所提供的batch_id，以從「探索」取回文件，供外部應用程式強化。 如需相關資訊，請參閱 API 參考資料中的 取回批次。pull batches方法會從 Discovery 傳回二進位檔附件。 如需二進位附件的相關資訊，請參閱 來自拉取批次方法的二進位附件。 -
在外部強化註釋批次中的文件之後，請在
push batches方法中指定相同的batch_id。 如需相關資訊，請參閱 API 參考資料中的 推送批次。文件會以二進位附件形式推送至「探索」。 如需相關資訊，請參閱 推送批次方法中的二進位附件。
-
請驗證已在集合中合併及檢索文件。 文件必須包含外部應用程式所套用的註釋。
驗證 Webhook 安全性請求
若要鑑別 Webhook 要求，請驗證隨要求一起傳送的 JSON Web 記號 (JWT)。 Webhook 微服務會自動產生 JWT，並隨每一個 Webhook 呼叫在 Authorization 標頭中傳送它。 您必須負責將程式碼新增至驗證 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，也稱為租戶 ID。 |
version |
yyyy-mm-dd 格式的 Webhook 事件版本日期。 |
data |
具有事件特定資訊的物件:
|
created_at |
事件建立的日期和時間。 |
外部強化限制
| 方案 | 每個集合的 Webhook 強化數量上限 | 每個租戶的 Webhook 強化數量上限 |
|---|---|---|
| 企業 | 1 | 100 |
| 增強 | 1 | 10 |
| 進階 | 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。 外部強化應用程式必須根據「探索」中對應文件的 location_encoding 來計算每一個特性的位置。 資料字串表示法中特性的位置視用於實作外部強化的程式設計語言的編碼類型而有所不同。 例如，C++ 和 Go 使用 UTF-8、Java 和 JavaScript
使用 UTF-16，而 Python 使用 UTF-32。 |
language |
string |
文件的內容語言。 |
artifact |
string |
所有文字值的套件。 |
features |
array |
文件中的特性清單。 如需相關資訊，請參閱 特性類型。 |
推送批次方法中的二進位附件
在外部強化之後，可以在 push batches 方法中以二進位附件形式將文件推送至「探索」。
檔案必須是 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 中的資訊用來在探索使用者介面上產生訊息。 |
以下是二進位檔中的其他內容:
| 配件 | 類型 | 說明 |
|---|---|---|
location |
object |
使用 begin 和 end 值從 artifact 取得文字值的位置資訊。 begin 值是一個字串值，代表構件中的開始位置。 end 值是一個字串值，代表構件中的專用結束位置。 當特性代表文件層次資訊時，此內容是空值。 例如，當 type=annotation 和 properties.type=document_classes。 |
properties |
object |
文件中特性的內容。 支援的屬性依 type 功能而異。 如需相關資訊，請參閱 欄位類型內容、註釋類型內容 及 通知類型內容。 |
欄位類型內容
對於 field 類型，下列內容代表「探索」從原始檔案轉換的文件特定欄位:
| 內容 | 類型 | 說明 |
|---|---|---|
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 新紀元時間 (毫秒)。 |