分析文件 API 回應

發行項
03/08/2024

此內容適用於：v4.0 （預覽）v3.1 （GA）v3.0 （GA）

在本文中，讓我們檢查回應中 AnalyzeDocument 傳回的不同物件，以及如何在應用程式中使用檔分析 API 回應。

分析文件要求

文件智慧 API 會分析影像、PDF 和其他文件檔，以擷取及偵測各種內容、版面配置、樣式和語意元素。分析作業是非同步 API。提交文件會傳回 Operation-Location 標頭，其中包含要輪詢完成的 URL。當分析要求成功完成時，回應會包含模型資料擷取中所述的元素。

回應元素

內容元素是從文件擷取的基本文字元素。
版面配置元素會將內容元素分組成結構化單位。
樣式元素描述內容元素的字型和語言。
語意元素會將意義指派給指定的內容元素。

所有內容元素都會根據頁面進行分組，並依頁碼 (1 索引) 指定。元素也會依讀取順序排序，以將語意上連續元素排列在一起，即使其跨行或資料行界限也一樣。當段落和其他版面配置元素之間的讀取順序模棱兩可時，服務通常會以從左至右、從上到下的順序傳回內容。

注意

目前，文件智慧不支援跨頁面界限的讀取順序。選取標記不會放置在周圍單字內。

最上層內容屬性包含讀取順序中所有內容元素的串連。所有元素都會透過這個內容字串內的範圍，以讀取器順序指定其位置。某些元素的內容不一定是連續的。

分析回應

每個 API 的分析回應都會傳回不同的物件。 API 回應包含適用元件模型中的元素。

回應內容	描述	API
頁面	從輸入文件的每個頁面辨識到的文字、行和範圍。	讀取、版面配置、一般文件、預先建置和自訂模型
段落	辨識為段落的內容。	讀取、版面配置、一般文件、預先建置和自訂模型
樣式	識別到的文字元素屬性。	讀取、版面配置、一般文件、預先建置和自訂模型
語言	識別到的語言與所擷取文字的每個範圍相關聯	參閱
表	從文件中識別及擷取到的表格式內容。資料表與預先定型版面配置模型所識別到的資料表相關。標示為資料表的內容會擷取為文件物件中的結構化欄位。	版面配置、一般文件、發票和自訂模型
數位	從文件中識別和擷取的圖表（圖表、影像）提供視覺表示法，有助於瞭解複雜的資訊。	版面配置模型
部分	識別並擷取自檔的階層式文件結構。附加相對應的元素（段落、表格、圖表）的區段或子區段。	版面配置模型
keyValuePairs	預先定型模型所辨識到的機碼值組。索引鍵是文件中具有相關聯值的文字範圍。	一般文件和發票模型
文件	辨識到的欄位會在文件清單內的 `fields` 字典中傳回	預先建置的模型、自定義模型。

如需關於每個 API 所傳回物件的詳細資訊，請參閱模型資料擷取。

元素屬性

跨越

範圍會以整體讀取順序指定每個元素的邏輯位置，而每個範圍都會將字元位移和長度指定到最上層內容字串屬性。根據預設，字元位移和長度會以使用者感知字元 (也稱為 grapheme clusters 或文字元素) 的單位傳回。若要容納使用不同字元單位的不同開發環境，使用者也可以指定 stringIndexIndex 查詢參數，以傳回 Unicode 字碼指標 (Python 3) 或 UTF16 程式碼單位 (JAVA、JavaScript、.NET)。如需詳細資訊，請參閱multilingual/emoji support。

Screenshot of detected span example.

周框區域

周框區域描述檔案中每個元素的視覺位置。當元素不是以視覺方式連續或跨頁（數據表）時，大部分元素的位置會透過周框區域的數位來描述。每個區域都會指定頁碼 (以 1 索引) 和周框多邊形。周框多邊形會描述為一連串的點，從左側相對於元素的自然方向順時針排列。針對四邊形，繪圖點是左上角、右上角、右下角和左下角。每個點都代表其 x，y 座標在單位屬性所指定的頁面單位中。一般而言，影像的測量單位是像素，而 PDF 則使用英吋。

Screenshot of detected bounding regions example.

注意

目前，文件智慧只會傳回 4 頂點四邊形做為周框多邊形。未來版本可能會傳回不同的點數來描述更複雜的圖形，例如曲線或非矩形影像。周框區域只會套用至轉譯的檔案，如果檔案未轉譯，則不會傳回周框區域。目前不會轉譯 docx/xlsx/pptx/html 格式的檔案。

內容元素

Word

單字是由字元序列所組成的內容元素。使用文件智慧時，單字會定義為相鄰字元序列，且空白字元會將單字彼此分隔。對於未在單字之間使用空格分隔符號的語言，每個字元都會以個別單字的形式傳回，即使其不代表語意單字單位也一樣。

Screenshot of detected words example.

選取標記

選取項目標記是代表視覺字符的內容元素，表示選取項目的狀態。核取方塊是選取項目標記的常見形式。不過，它們也會透過單選按鈕或可視化表單中的Boxed單元格來表示。可以選取或取消選取選取選取標記的狀態，以不同的視覺表示來表示狀態。

Screenshot of detected selection marks example.

版面配置元素

線條

行是以視覺空間分隔的連續內容元素排序序列，或是緊接在文字之間沒有空格分隔符號的語言連續內容元素排序序列。在相同水平平面 (列)，但以多個視覺空間分隔的內容元素最常分割成多行。雖然此功能有時會將語意上連續的內容分割成不同的行，但其可讓文字內容的標記法分割成多個資料行或儲存格。會以垂直方向偵測到垂直寫入中的行。

Screenshot of detected lines example.

段落

段落是構成邏輯單元的已排序行序列。一般而言，行會共用行之間的一般對齊和間距。段落通常會透過縮排、新增間距或項目符號/編號來進行分隔。您只能將內容指派給單一段落。選取段落也可以與檔中的功能角色相關聯。目前支援的角色包括頁首、頁尾、頁碼、標題、區段標題和註腳。

Screenshot of detected paragraphs example.

頁

頁面是一組內容，通常會對應至紙張的一面。轉譯的頁面是透過指定單位的寬度和高度加以區分。一般而言，影像會使用像素，而 PDF 則使用英吋。 angle 屬性描述可旋轉之頁面的整體文字角度。

注意

對於 Excel 之類的試算表，每個工作表都會對應至頁面。對於 PowerPoint 之類的簡報，每個投影片都會對應至頁面。對於沒有未轉譯 HTML 或 Word 文件之類網頁原生概念的檔案格式，檔案的主要內容會被視為單一頁面。

Table

資料表會將內容組織成格線配置中的一組儲存格。數據列和數據行可以透過網格線、色彩帶狀或更大的間距，以可視化方式分隔。資料表儲存格的位置是透過其資料列和資料行索引加以指定。單元格可以跨越多個數據列和數據行。

根據儲存格的位置和樣式，數據格可以分類為一般內容、數據列標頭、數據行標頭、存根標頭或描述：

資料列標頭儲存格通常是資料列中第一個儲存格，會描述資料列中的其他儲存格。
資料行標頭儲存格通常是資料行中第一個儲存格，會描述資料行中的其他儲存格。
數據列或數據列可以包含多個標題單元格來描述階層式內容。
虛設常式標頭儲存格通常是第一個資料列和第一個資料行位置中的儲存格。它可以是空的，或描述相同數據列/數據行中標頭單元格中的值。
描述儲存格通常會出現在資料表的最上層或底部區域，描述整體資料表內容。不過，它有時會出現在數據表中間，以將數據表分成數個區段。一般而言，描述儲存格跨越單一資料列中的多個儲存格。
資料表標題會指定說明資料表的內容。數據表可以進一步具有相關聯的標題和一組腳注。不同於描述儲存格，標題通常會位於格線配置之外。表格腳註會標註數據表內的內容，通常以腳註符號標示，通常位於表格方格下方。

版面配置表格與從表格式資料擷取到的文件欄位不同。版面配置表格會從文件中的表格式視覺內容擷取，而不需要考慮內容的語意。事實上，某些版面配置數據表是專為視覺版面配置所設計，而且不一定包含結構化數據。從具有不同視覺版面配置的文件擷取結構化資料的方法 (例如收據的已項目化詳細資料)，通常需要大量的後置處理。請務必將資料列或資料行標頭對應至具有標準化欄位名稱的結構化欄位。根據文件類型，使用預建模型或定型自訂模型來擷取這類結構化內容。所產生的資訊會公開為文件欄位。這類定型的模型也可以處理表格式資料，而不需要標頭和非表格式形式的結構化資料，例如履歷的工作體驗區段。

Layout table

數位

檔中的圖表（圖表、影像）在補充和增強文字內容方面扮演了重要角色，提供視覺表示法，有助於瞭解複雜的資訊。 Layout 模型偵測到的圖表物件具有索引鍵屬性，例如 boundingRegions （檔頁面上的圖表空間位置，包括大綱圖界限的頁碼和多邊形座標）， spans （詳細數據與圖表相關的文字範圍，指定檔文字內的位移和長度。此連接有助於將圖形與其相關的文字內容產生關聯， elements （與或描述該圖相關之檔內的文字元素或段落的標識符），如果有 caption 的話。

{
    "figures": [
      {
        "boundingRegions": [],
        "spans": [],
        "elements": [
          "/paragraphs/15",
          ...
        ],
        "caption": {
          "content": "Here is a figure with some text",
          "boundingRegions": [],
          "spans": [],
          "elements": [
            "/paragraphs/15"
          ]
        }
      }
    ]
}

區段

階層式文件結構分析對於組織、理解及處理廣泛的文件至關重要。這種方法對於語意分割長文件至關重要，可提升理解度、促進流覽，以及改善資訊擷取。檔產生式 AI 中擷取增強產生（RAG）的出現突顯了階層式文件結構分析的重要性。版面配置模型支持輸出中的區段和子區段，以識別每個區段內區段和對象的關聯性。階層式結構會在每個區段中維護 elements 。

{
    "sections": [
      {
        "spans": [],
        "elements": [
          "/paragraphs/0",
          "/sections/1",
          "/sections/2",
          "/sections/5"
        ]
      },
...
}

表單欄位 (機碼值組)

表單欄位包含欄位標籤 (索引鍵) 和值。欄位標籤通常是描述欄位意義的描述性文字字串。其通常會出現在值的左側，不過也可以出現在值的上方或下方。欄位值包含特定欄位執行個體的內容值。值可以包含單字、選取標記和其他內容元素。對於未填入的表單域，它也可以是空的。特殊類型的表單欄位具有選取項目標記值，其右側有欄位標籤。文件欄位與一般表單欄位概念類似但不同。一般表單欄位中的欄位標籤 (索引鍵) 必須出現在文件中。因此，其通常無法擷取資訊，例如收據中的商家名稱。檔欄位會加上標籤，且不會擷取索引鍵。檔字段只會將擷取的值對應至標示的索引鍵。如需詳細資訊，請參閱文件欄位。

Screenshot of detected key-value pairs example.

樣式元素

樣式

樣式元素描述要套用至文字內容的字型樣式。內容會透過範圍指定至全域內容屬性。目前，唯一偵測到的字型樣式是文字是否為手寫。新增其他樣式時，可以透過多個非衝突樣式物件來描述文字。為了精簡起見，會透過單一樣式物件描述所有共用特定字型樣式的文字 (具有相同信賴度)。

Screenshot of detected style handwritten text example.


{
    "confidence": 1,
    "spans": [
        {
            "offset": 2402,
            "length": 7
        }
    ],
    "isHandwritten": true
}

語言

語言元素描述透過範圍指定至全域內容屬性的內容所偵測到的語言。偵測到的語言是透過 BCP-47 語言標籤來指定，以指出主要語言和選擇性指令碼及區域資訊。例如，英文和繁體中文分別會辨識為「en」和「zh-Hant」。英國英文的區域拼字差異可能會導致文字偵測為 en-GB。語言元素不會在沒有主要語言的情況下涵蓋文字 (例如數字)。

語意元素

注意

這裡討論的語意元素適用於檔智慧預先建置的模型。您的自定義模型可能會傳回不同的數據表示法。例如，自定義模型傳回的日期和時間可能會以不同於標準 ISO 8601 格式的模式來表示。

文件

文件是語意完整的單位。檔案可以包含多個檔，例如 PDF 檔案內的多個稅務窗體，或單一頁面內的多個收據。不過，檔案內文件的順序基本上不會影響其所傳達的資訊。

注意

目前，文件智慧不支援單一頁面上的多個文件。

檔案類型描述共用一組通用語意欄位的文件，由結構化結構描述所代表，與其視覺範本或版面配置無關。例如，類型為「receipt」的所有檔都可以包含商家名稱、交易日期和交易總計，不過餐廳及酒店收據的外觀通常不同。

檔案元素包含所偵測檔案類型之語意架構所指定之欄位中的辨識欄位清單：

檔欄位可以擷取或推斷。如果可解譯，則會透過擷取到的內容來表示擷取到的欄位，並且選擇性地表示其正規化值。
推斷的欄位沒有內容屬性，而且只會透過其值來表示。
數位欄位不包含 content 屬性。內容可以從數位專案的內容串連。
物件欄位確實包含內容屬性，指定代表物件的完整內容，該物件可以是擷取子字段的超集。

檔類型的語意架構會透過包含的欄位來描述。每個欄位結構描述都是透過其標準名稱和實值類型加以指定。欄位實值類型包含基本 (例如字串)、複合 (例如位址)，以及結構化 (例如陣列、物件) 類型。欄位實值類型也會指定執行以將偵測到的內容轉換成正規化標記法的語意正規化。正規化可以相依地區設定。

基本型別

欄位實值型別	描述	正規化標記法	範例 (欄位內容 - > 值)
string	純文字	與內容相同	商家名稱："Contoso" → "Contoso"
date	Date	ISO 8601 - YYYY-MM-DD	發票日期："5/7/2022" → "2022-05-07"
time	Time	ISO 8601 - hh:mm:ss	交易時間："9:45 PM" → "21:45:00"
電話號碼	電話號碼	E.164 - +{CountryCode}{SubscriberNumber}	公司電話號碼："(800) 555-7676" → "+18005557676"
countryRegion	國家/地區	ISO 3166-1 alpha-3	國家/地區："United States" → "USA"
selectionMark	Is selected	"signed" 或 "unsigned"	AcceptEula：☑ → "selected"
簽章	Is signed	與內容相同	LendeeSignature：{signature} → "signed"
數值	浮點數	浮點數	數量："1.20" → 1.2
整數	整數	64 位元帶正負號的數字	計數："123" → 123
boolean	布林值	true/false	IsStatutoryEmployee：☑ → true

複合類型

貨幣：貨幣金額，並有選擇性的貨幣單位。值，例如：InvoiceTotal: $123.45
```
{
    "amount": 123.45,
    "currencySymbol": "$"
}
```

位址：剖析的位址。例如：ShipToAddress: 123 Main St., Redmond, WA 98052

{
"poBox": "PO Box 12",
"houseNumber": "123",
"streetName": "Main St.",
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"countryRegion": "USA",
"streetAddress": "123 Main St."
}

結構化類型

陣列：相同類型的欄位清單

"Items": {
    "type": "array",
    "valueArray": [

    ]
}

物件：可能不同類型的子欄位具名清單

"InvoiceTotal": {
  "type": "currency",
  "valueCurrency": {
      "currencySymbol": "$",
      "amount": 110
  },
  "content": "$110.00",
  "boundingRegions": [
      {
          "pageNumber": 1,
          "polygon": [
              7.3842,
              7.465,
              7.9181,
              7.465,
              7.9181,
              7.6089,
              7.3842,
              7.6089
          ]
      }
  ],
  "confidence": 0.945,
  "spans": [
      {
          "offset": 806,
          "length": 7
      }
  ]
}

下一步

嘗試使用 Document Intelligence Studio 處理您自己的表單和檔。
完成 Document Intelligence 快速入門，並開始以您選擇的開發語言來建立文件處理應用程式。

共用方式為