分析文件 API 回應

在本文中，我們將檢視作為 AnalyzeDocument 回應的一部分所傳回的不同物件，以及如何在您的應用程式中使用文件分析 API 回應。

分析文件要求

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

回應元素

• 內容元素是從文件擷取的基本文字元素。

• 版面配置元素會將內容元素分組成結構化單位。

• 樣式元素描述內容元素的字型和語言。

• 語意元素會將意義指派給指定的內容元素。

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

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

分析回應

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

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

元素屬性

跨越

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

周框區域

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

內容元素

Word

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

選取標記

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

版面配置元素

線條

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

段落

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

頁

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

Table

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

根據其位置和樣式，儲存格可會分類為一般內容、資料列標頭、資料行標頭、虛設常式標頭或描述：

• 資料列標頭儲存格通常是資料列中第一個儲存格，會描述資料列中的其他儲存格。

• 資料行標頭儲存格通常是資料行中第一個儲存格，會描述資料行中的其他儲存格。

• 資料列或資料行可包含多個標題儲存格來描述階層式內容。

• 虛設常式標頭儲存格通常是第一個資料列和第一個資料行位置中的儲存格。 它可以是空的，或描述相同資料列/資料行中，標頭儲存格中的值。

• 描述儲存格通常會出現在資料表的最上層或底部區域，描述整體資料表內容。 不過，它有時可出現在資料表中間，以將資料表分成幾個區段。 一般而言，描述儲存格跨越單一資料列中的多個儲存格。

• 資料表標題會指定說明資料表的內容。 資料表還可以具有相關聯的標題和一組註腳。 不同於描述儲存格，標題通常會位於格線配置之外。 資料表註腳可標註資料表內的內容，通常以資料表方格下方常見的註腳符號標示。

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

圖形

文件中的圖文框 (圖表、影像) 在補充和增強文字內容上扮演著重要的角色，提供有助於了解複雜資訊的視覺效果表示法。 版面配置模型所偵測到的圖文框物件具有關鍵屬性，例如 boundingRegions (圖文框在文件頁面上的空間位置，包括頁碼和勾勒圖形邊界的多邊形座標)、spans (詳細說明與圖文框相關的文字範圍，指定它們在文件文字中的偏移量和長度。此關係有助於將圖形與其相關文字內容相關聯)、elements (文件中與圖形相關或描述圖形的文字元素或段落的識別碼) 和 caption (如果有的話)。

在初始 Analyze 作業期間指定 output=figures 時，服務會針對可透過 /analyeResults/{resultId}/figures/{figureId} 存取的所有偵測到的圖表產生經過裁切的影像。 FigureId 會包含在每個圖表物件中，並遵循未記載的慣例 {pageNumber}.{figureIndex}，其中 figureIndex 會重設為每頁一個。

{
    "figures": [
      {
        "id": "{figureId}",
        "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"
        ]
      },
...
}

表單欄位 (機碼值組)

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

樣式元素

樣式

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

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

語言

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

語意元素

文件

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

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

文件元素包含所偵測到文件類型的語意結構描述所指定欄位之間的已辨識欄位清單：

• 可以擷取或推斷文件欄位。 如果可解譯，則會透過擷取到的內容來表示擷取到的欄位，並且選擇性地表示其正規化值。

• 推斷的欄位沒有內容屬性，且只會透過其值來表示。

• 陣列欄位不包含內容屬性。 內容可以由陣列元素的內容串連而成。

• 物件欄位確實包含一個內容屬性，該屬性會指定表示物件的完整內容 (該物件可以是擷取的子欄位的超集)。

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

基本類型

複合類型

• 貨幣：貨幣金額，並有選擇性的貨幣單位。 值，例如：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 快速入門，並開始以您選擇的開發語言來建立文件處理應用程式。