文件解析

文件解析運用最先進的研究技術,從多種文件類型中萃取並視覺化結構化資料,包括但不限於 PDF、圖片、Word 文件(DOC/DOCX)及 PowerPoint 檔案(PPT/PPTX)。 它設計用來處理複雜的版面,如表格、圖表,以及文字與圖片混合的內容。

文件解析可透過 Agent Bricks 介面、 SQL、 REST API 及 非同步 API (測試版)進行。

在介面中建立一個文件解析代理程式

Requirements

使用文件解析來解析你的文件並視覺化其結構。

  1. 轉到代理圖標。在您的工作區左側導覽面板中選擇代理程式。
  2. 點擊 建立代理>文件解析。
  3. 選擇你的來源文件。 你可以選擇上傳檔案,或從現有的 Unity 目錄中選擇一個檔案。 支援格式包括:PDF、圖片、DOC/DOCX 及 PPT/PPTX。
  4. 點擊 解析文件。

解析你的文件可能需要幾分鐘。 完成後,文件解析會顯示左側的原始文件,右側顯示解析後的文件。 你可以選擇以 格式化 文字或 原始 JSON 來查看解析後的文件。

文件解析介面,顯示原始文件與解析後的文件並排呈現

流程與查詢結果

若要查看 ai_parse_document 查詢並在更多文件上執行,請點擊 「使用代理」 ,並選擇從 SQL 編輯器或筆記本執行查詢。 你可以編輯查詢,以指向存放文件的磁碟區或資料表。

要準備解析輸出以供檢索(RAG),請使用 ai_prep_search 下游版本(Beta)。

在 SQL 中解析文件

在 SQL 中呼叫 ai_parse_document 以大規模剖析文件:

SELECT
  ai_parse_document(
    content,
    map('version', '2.0')
  ) AS parsed
FROM READ_FILES('/Volumes/my_catalog/my_schema/my_documents', format => 'binaryFile');

請參考 SQL 參考資料 ai_parse_document 。

使用 REST API 解析文件

使用 REST API 來解析應用程式、服務和自動化工作流程的文件。 參考 REST API 文件 。

ai_parse_document REST API 請求每份文件限制為 100 頁。

REST API 請求的預設速率上限 ai_parse_document 是每個工作區每分鐘 250 個請求。 請聯絡您的 Databricks 帳戶團隊申請更高的限額。

ai_parse_document 從 Unity Catalog 磁碟區讀取輸入。 以下範例是將本地 PDF 上傳到帶有 Files API 的磁碟區,然後解析它。

首先,將文件上傳到一個磁碟區:

curl -X PUT "$DATABRICKS_HOST/api/2.0/fs/files/Volumes/my_catalog/my_schema/my_volume/invoice.pdf?overwrite=true" \
     -H "Authorization: Bearer $DATABRICKS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary @invoice.pdf

然後將已上傳文件的磁碟區路徑作為 content 傳遞,以剖析該文件:

curl -X POST "$DATABRICKS_HOST/api/2.0/ai-functions/ai-parse-document" \
     -H "Authorization: Bearer $DATABRICKS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
  "content": "/Volumes/my_catalog/my_schema/my_volume/invoice.pdf"
}'

使用非同步 API 進行文件解析(Beta)

在批次處理方面,Databricks 建議在 Lakeflow Jobs 中使用 AI 函數任務 。 若要在作業中剖析文件,請使用AI Functionai_parse_document任務,該任務會執行以下工作:

  • 在背景執行處理,並將結果寫入 Unity 目錄資料表,讓您不必提交批次、檢查其狀態或下載輸出檔案。
  • 僅處理自上次執行以來新增或變更的文件。
  • 顯示每次執行的進度,以及成功與失敗的輸入數量。

當你想將處理整合到現有應用程式或外部 Orchestrator 中,並自行管理提交與結果時,請改用 AI Functions 非同步 API(Beta)。

Important

這項功能位於 測試版 (Beta) 中。 要使用它,工作區管理員必須從 預覽 頁面啟用 AI Functions 非同步 API。 請參閱 管理 Azure Databricks 預覽。

關於請求與回應欄位,以及取消與列入批次的請求,請參見 非同步 API 參考。

輸入目錄或檔案

批 ai_parse_document 次的輸入為下列之一:

  • Unity Catalog 磁碟區中的一個目錄。 批次會解析目錄中及其子目錄中的每個檔案,因此只將要解析的文件放進去。 API 會對每個檔案發出一次請求,並以檔案的路徑作為其 custom_id。
  • 磁碟區中的 JSONL 輸入檔,列出要解析的文件。 使用輸入檔案來剖析目錄中的部分文件,或為每份文件指定您自己的 custom_id。

輸入檔案的每一行代表一個請求,一個僅包含以下欄位的 JSON 物件:

Field 描述
custom_id 用來識別請求的字串。 輸出檔案的每一行都包含其請求的 custom_id 值,因此請使用可用來將結果對應回請求的值。
body 要解析的文件檔案,格式為 {"path": "/Volumes/..."},其中 path 是文件檔案的磁碟區路徑。

以下輸入檔案包含兩個請求:

{"custom_id": "invoice-001", "body": {"path": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-001.pdf"}}
{"custom_id": "invoice-002", "body": {"path": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-002.pdf"}}

ai_parse_document 除了文件外,不需要其他參數。 若要設定函數選項,例如 version 或 options,在建立批次時將它們放入 params 的 "params": {"options": {"version": "2.0"}},例如 pageRange。 請以 camelCase 撰寫每個選項名稱,例如使用 imageOutputPath,而非 image_output_path。 這些選項適用於批次中的每一份文件。 關於每個選項的功能,請參閱 AI Parse Document REST API 參考資料。

當你建立批次時,API 會先檢查輸入和 params 。 如果輸入或 params 違反以下任一規則,HTTP 400 下請求將失敗,且不會建立批次:

  • 一個目錄包含 1 到 50,000 個檔案。
    • 若要處理更多文件,請將它們拆分成多個目錄或輸入檔,並為每個目錄或輸入檔各建立一個批次。
  • 輸入檔案以 UTF-8 編碼,每一行都是包含欄位 custom_id 與 body的 JSON 物件。 檔案中沒有空白行。
  • 每個 custom_id 都是非空字串,且沒有兩行具有相同的 custom_id。
  • 每個 body 只有一個金鑰 path。
    • 如果值 path 不是字串,批次仍會被建立,該請求會因錯誤類型 invalid_request而失敗。
  • 一個輸入檔案有 1 到 50,000 行,最多 200 MiB。
  • params 沒有任何 ai_parse_document 不接受的參數。

對於輸入檔案某行的問題,錯誤訊息會提供行號與規則,例如 Batch input line 3 custom_id must be unique。 如果你無法讀取輸入或 A path 命名的磁碟區,或無法寫入該 output_ref磁碟區,則該請求會以 HTTP 403 失敗。

API 在建立批次時會列出目錄或複製輸入檔案。 你之後加入目錄的檔案不屬於批次。

執行批次

使用非同步 API 解析文件的方法如下:

  1. 將文件上傳到 Unity Catalog 磁碟區中的目錄。 如果只解析其中一部分,也可以建立一個輸入檔案來列出它們,然後將其上傳到磁碟區。

  2. 建立一個執行 ai_parse_document的批次。 設定 input_ref 為目錄或輸入檔案,以及 output_ref 輸出 檔案的磁碟區目錄或新檔案路徑。 以下範例解析目錄:

    curl -X POST "$DATABRICKS_HOST/api/2.0/ai-functions/batches" \
         -H "Authorization: Bearer $DATABRICKS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
      "endpoint": "ai_parse_document",
      "input_ref": "/Volumes/my_catalog/my_schema/my_volume/invoices/",
      "output_ref": "/Volumes/my_catalog/my_schema/my_volume/output/"
    }'
    

    回應包含批次 name。 接下來的步驟可以用它來代替 <batch-name>。 預設情況下,一個工作區最多可同時有 20 個未完成批次,且涵蓋所有使用者。 如果已達上限,該請求會以 HTTP 409 失敗。 在另一個批次完成或被取消後,請重新建立該批次。

  3. 檢查批次狀況。 當 status 為 COMPLETED、CANCELLED 或 FAILED 時,批次結束:

    curl -X GET "$DATABRICKS_HOST/api/2.0/ai-functions/batches/<batch-name>" \
         -H "Authorization: Bearer $DATABRICKS_TOKEN"
    

    當輸出檔案準備好時,回應中的 output_ref 會包含其路徑。

  4. 使用檔案 API 下載輸出檔案:

    curl -X GET "$DATABRICKS_HOST/api/2.0/fs/files/Volumes/my_catalog/my_schema/my_volume/output/<batch-name>_output.jsonl" \
         -H "Authorization: Bearer $DATABRICKS_TOKEN" \
         -o output.jsonl
    

輸出檔案

非同步 API 會將 ai_parse_document 批次的輸出檔案寫入 output_ref 的位置:

  • 如果 output_ref 以 / 結尾,或是現有目錄的名稱,API 會將輸出檔案寫入該目錄中的 <batch-name>_output.jsonl。 多個批次可以共用一個輸出目錄。
  • 否則, output_ref 為輸出檔案的路徑。 建立批次時,該檔案不得存在。

輸出檔對應每份文件一行。 每行包含其請求的 custom_id 以及下列其中一個欄位:

  • response:請求的結果。 它的欄位與 AI Parse Document REST API 回應相同。
  • error:若請求失敗,則為錯誤的 type 和 message。 如果批次在請求執行前被取消,則類型為 cancelled。

對於輸入檔案,各行的順序與輸入檔案中的順序相同。 對於目錄,每行的 custom_id 是文件的路徑,行的順序可以是任意的:

{"custom_id": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-001.pdf", "response": {...}}
{"custom_id": "/Volumes/my_catalog/my_schema/my_volume/invoices/invoice-002.pdf", "error": {"type": "request_failed", "message": "..."}}

Limitations

詳見ai_parse_document限制。