教學:建立一個帶有 FILE 類型的檔案處理管線

Important

這項功能位於 測試版 (Beta) 中。 要使用它,工作區管理員必須從預覽頁面開啟檔案類型。 請參閱 管理 Azure Databricks 預覽。

在這個教學中,你將用 Lakeflow 管線建立一個 medallion 系統,從頭到尾處理非結構化文件。 此範例使用 samples.sec.contracts 範例資料集,即一組由美國證券交易委員會(SEC)提交的法律協議,以PDF格式儲存在Unity Catalog卷中。

管線會以 Auto Loader 的受管理 FILE 參考資料形式匯入 PDF,使用 AI 函式解析每份文件,將其分類為合約類型,並為每種類型擷取結構化欄位。

關於類型參考,請參見 FILE 類型。

在本教學課程中,您將:

結果是一條獎章式資料管線:銅(原始管理的 FILE 參考)、銀(解析與分類後的文件)、金(依協議類型擷取欄位)。 如需詳細資訊,請參閱獎章湖屋架構的概念。 青銅層是一個 串流資料表 ,會逐步擷取檔案,而銀層和金層則是 實體化的視圖 ,只有當輸入改變時才會重新計算。

要求

您必須滿足下列需求,才能完成本教學課程:

  • 登入啟用Unity Catalog的Azure Databricks工作區。
  • 請為你的工作區啟用該 FILE 類型。 Workspace 管理員可以從 預覽 頁面啟用。 請參閱 管理 Azure Databricks 預覽。
  • 擁有在結構中建立資料表和建立管線的權限。
  • 有一個可以寫入的 Unity Catalog 磁碟區。 你將此卷宣告為青銅表的 FileSpace,Unity Catalog 會將擷取的檔案複製到該卷中作為受控儲存體。
  • 使用 預覽通道 作為此管線的通道。
  • 使用無伺服器運算,這是本教學中增量實體化檢視所需要的。

samples.sec.contracts該資料集預設在所有工作區中皆可取得。 這個教學會把擷取的 PDF 存作 FILE MANAGED 參考資料:Unity Catalog 會把每個檔案複製到你指定為資料表的 FileSpace 的磁碟區,並隨資料表一起管理,所以刪除資料列後,參考檔案就符合垃圾回收條件,資料表和檔案也能保持同步。要將管線調整為使用你自己的 PDF,請將來源路徑指向包含你檔案的磁碟區。 如需其他擷取選項,請參閱 以 FILE 類型擷取檔案。

建立檔案處理流程

流程文件處理分為三個階段。

步驟 1. Bronze:將原始 PDF 作為受管理的檔案參考資料擷取

使用 Auto Loader 從磁碟區以增量方式讀取合約 PDF 檔案。 使用 format => 'file' 讀取檔案時,會擷取每個檔案的參照和中繼資料,而不會將其位元組內容實際具現化。 將欄位宣告為 FILE MANAGED 會將每個檔案複製到 FileSpace 你用 databricks.filespace-preview 資料表屬性設定的資料表 volume 中,這樣 Unity Catalog 就能隨資料表一起管理檔案。

SQL

CREATE OR REFRESH STREAMING TABLE raw_contracts (
  path STRING,
  size BIGINT,
  modification_time TIMESTAMP,
  file FILE MANAGED
)
TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/filespace/')
AS SELECT *
  FROM STREAM read_files(
    '/Volumes/samples/sec/contracts/',
    format => 'file');

Python

from pyspark import pipelines as dp

@dp.table(
  name="raw_contracts",
  schema="path STRING, size BIGINT, modification_time TIMESTAMP, file FILE MANAGED",
  table_properties={"databricks.filespace-preview": "/Volumes/my_catalog/my_schema/filespace/"}
)
def raw_contracts():
  return (
    spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "file")
      .load("/Volumes/samples/sec/contracts/")
  )
  • 適用於大型檔案:大型 PDF 存放在資料表的 FileSpace中,而資料表列僅儲存一個輕量級FILE參考(uri, size, content_typechecksum, )。 將此與 BINARY 型別相比,後者會將位元組內嵌在資料列中。
  • 受管理檔案生命週期:Unity Catalog 會將每個被導入的檔案複製到資料表 FileSpace 中,並以資料表管理:刪除資料列後,參考檔案可進行垃圾回收,因此資料表與檔案保持同步。詳情請參見 FILE MANAGED 與 FILE EXTERNAL。
  • 增量處理:串流資料表在新檔案抵達原始碼時逐步擷取,不重新處理現有檔案。 samples.sec.contracts此範例中的資料集是靜態的,但若有即時來源,每次管線更新都會有新檔案被擷取。 若要一併傳送來源中的變更和刪除,請使用 AUTO CDC 擷取變更摘要。 請參見 使用 AUTO CDC 套用更新和刪除。

步驟 2。 銀色:解析與分類文件

將每個 FILE 函式傳遞到 ai_parse_document 函式 ,將原始 PDF 轉換成包含文件元素、版面中繼資料和文字的結構化 VARIANT 文件。 由於 ai_parse_document 接受欄位 FILE ,它會直接從儲存讀取文件,且不會將位元組載入叢集記憶體。

SQL

CREATE OR REFRESH MATERIALIZED VIEW parsed_contracts AS
  SELECT
    path,
    ai_parse_document(file) AS parsed
  FROM raw_contracts;

Python

@dp.materialized_view(name="parsed_contracts")
def parsed_contracts():
  return (
    spark.read.table("raw_contracts")
      .selectExpr("path", "ai_parse_document(file) AS parsed")
  )

Note

將解析步驟定義為對 raw_contracts 串流表的具體視圖,可讓計算過程更為精進。 每次管線更新都只會對自上次更新以來新增的檔案執行 ai_parse_document,而不是對整個資料表執行。 因為 ai_parse_document 是成本最高的步驟,所以這樣可避免重新解析已處理過的文件。 實體化檢視的增量刷新需要無伺服器運算;在無伺服器模式下運行管線。 請參見 Lakeflow 上的 Spark 宣告式管線。

接著,將解析後的輸出傳給 ai_classify 函式 ,讓每份文件被指派為五種協議類型之一。 有解析錯誤的文件會在分類前被過濾掉。 此範例將 ai_classify 固定為 2.1 版;該版本會以各標籤物件的形式傳回分類,因此請從 value 鍵讀取標籤。

SQL

CREATE OR REFRESH MATERIALIZED VIEW classified_contracts AS
  SELECT
    path,
    parsed,
    ai_classify(
      parsed,
      '["affiliate_agreement", "marketing_agreement", "consulting_agreement", "hosting_agreement", "escrow_agreement"]',
      map('version', '2.1')
    ):response[0].value::STRING AS contract_type
  FROM parsed_contracts
  WHERE is_variant_null(parsed:error_status);

Python

@dp.materialized_view(name="classified_contracts")
def classified_contracts():
  return (
    spark.read.table("parsed_contracts")
      .filter("is_variant_null(parsed:error_status)")
      .selectExpr(
        "path",
        "parsed",
        """ai_classify(
             parsed,
             '["affiliate_agreement", "marketing_agreement", "consulting_agreement", "hosting_agreement", "escrow_agreement"]',
             map('version', '2.1')
           ):response[0].value::STRING AS contract_type""")
  )

提示

為提高分類準確度,請在ai_classify中新增標籤描述和instructions選項。 請參閱 ai_classify 函式。

步驟 3。 Gold:依協議類型擷取欄位

每種協議類型都有其相關的欄位集合。 將已分類的文件篩選為單一類型,將解析後的內容傳遞給ai_extract函式,並搭配你所需欄位的結構描述,然後將回應展平成具型別的資料欄。 此範例將 ai_extract 固定為 2.1 版,其中每個擷取出的欄位都是物件,因此請讀取其 value 鍵的值。

以下範例構建顧問協議的黃金表:

SQL

CREATE OR REFRESH MATERIALIZED VIEW consulting_agreements AS
  WITH extracted AS (
    SELECT
      path,
      ai_extract(
        parsed,
        '["company_name", "consultant_name", "compensation_amount", "effective_date"]',
        map('version', '2.1')
      ) AS fields
    FROM classified_contracts
    WHERE contract_type = 'consulting_agreement'
  )
  SELECT
    path,
    fields:response.company_name.value::STRING AS company_name,
    fields:response.consultant_name.value::STRING AS consultant_name,
    fields:response.compensation_amount.value::STRING AS compensation_amount,
    fields:response.effective_date.value::STRING AS effective_date
  FROM extracted;

Python

@dp.materialized_view(name="consulting_agreements")
def consulting_agreements():
  return (
    spark.read.table("classified_contracts")
      .filter("contract_type = 'consulting_agreement'")
      .selectExpr(
        "path",
        """ai_extract(
             parsed,
             '["company_name", "consultant_name", "compensation_amount", "effective_date"]',
             map('version', '2.1')
           ) AS fields""")
      .selectExpr(
        "path",
        "fields:response.company_name.value::STRING AS company_name",
        "fields:response.consultant_name.value::STRING AS consultant_name",
        "fields:response.compensation_amount.value::STRING AS compensation_amount",
        "fields:response.effective_date.value::STRING AS effective_date")
  )

有了這些語句,你就擁有一個完全增量的流程:當新的合約 PDF 進入卷中時,Auto Loader 會將它們作為管理 FILE 參考資料匯入,ai_parse_document 並 ai_classify 將每份文件路由到對應流程,而 consulting_agreements gold 實體化檢視則顯示已擷取的欄位。

筆記本範例

以下筆記本包含了這個教學的完整流程。 這些筆記本是管線原始碼,不是可執行的筆記本。 匯入你語言的筆記本,然後在設定管線時,在 原始碼 欄位指定其路徑。 請參見 「配置管線」。

SQL

檔案處理流程 SQL 筆記簿

取得 Notebook

Python

檔案處理管線 Python 筆記簿

取得 Notebook

自己探索吧

該管線將文件分類為五種協議類型,但僅針對 consulting_agreement 擷取欄位。 若要擴充此做法,請對其餘每種類型重複執行 gold 步驟,並調整 contract_type 篩選器和 ai_extract 結構描述,使其符合與該類型相關的欄位。 例如:

  • affiliate_agreement: party_1_name, party_2_name, commission_rate, payment_frequency
  • marketing_agreement: party_1_name, party_2_name, effective_date, territory
  • hosting_agreement: provider_name, customer_name, effective_date, term_length
  • escrow_agreement: owner_name, licensee_name, escrow_agent_name, software_name

其他資源