教程:构建带有 FILE 类型的文件处理流水线

Important

此功能在 Beta 版中。 要使用它,工作区管理员必须在预览页面开启文件类型。 请参阅 Manage Azure Databricks 预览版。

在本教程中,您将使用 Lakeflow 管道构建一个 medallion 体系,以端到端方式处理非结构化文档。 本示例使用 samples.sec.contracts 示例数据集,即以PDF形式存储在Unity目录卷中的SEC提交法律协议集合。

流水线通过自动加载器将PDF作为托管 FILE 引用导入,用AI函数解析每个文档,将其分类为协议类型,并为每种类型提取结构化字段。

关于类型参考,请参见 FILE 类型。

在本教程中,你将:

结果是一个 medallion 样式的管道:青铜(原始托管 FILE 引用)、白银(已解析和分类的文档)和黄金(每种协议类型提取的字段)。 更多信息请参阅什么是勋章式湖屋架构?。 青铜层是一个 流式表 ,递增式地导入文件,而银色和金色层则是 实体化视图 ,只有在输入发生变化时才会重新计算。

要求

若要完成此教程,必须满足以下要求:

  • 登录启用Unity Catalog的Azure Databricks工作区。
  • 在你的工作区中启用该 FILE 类型。 Workspace 管理员可以在 预览 页面启用。 请参阅 Manage Azure Databricks 预览版。
  • 拥有在模式中创建表和创建管道的权限。
  • 准备一个可以写入的 Unity Catalog 卷。 你将此卷声明为青铜表的 FileSpace,Unity Catalog 将引入的文件作为托管存储复制到其中。
  • 对该管道使用预览频道。
  • 使用无服务器计算,这正是本教程中的增量物化视图所要求的。

samples.sec.contracts该数据集默认在所有工作区中可用。 这个教程会把摄取的 PDF 作为 FILE MANAGED 引用存储:Unity Catalog 会把每个文件复制到你声明为表的 FileSpace 卷中,并随表一起管理,因此删除行后,引用的文件可被垃圾回收,表及其文件保持同步。要将流水线适配到你自己的 PDF,可以把源路径指向包含你文件的卷。 有关其他导入选项,请参阅 以 FILE 类型导入文件。

创建文件处理流水线

该管道文件处理分为三个阶段。

第 1 步。 Bronze:将原始PDF作为托管的文件引用导入

用自动加载器逐步阅读卷中的合同PDF。 使用 format => 'file' 读取文件时,可以为每个文件捕获其引用和元数据,而无需将其字节内容实体化。 将列声明为 FILE MANAGED 会将每个文件复制到表的 FileSpace 中,即你使用 databricks.filespace-preview 表属性设置的卷,因此 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_type,checksum)。 将其与 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 到达卷中,自动加载程序将它们作为托管 FILE 引用引入,ai_parse_document 和 ai_classify 路由每个文档,consulting_agreements 黄金具体化视图呈现提取的字段。

示例笔记本

以下笔记本包含了本教程的完整流程。 这些笔记本是流水线源代码,不是可运行的笔记本。 导入你语言的笔记本,然后在配置流水线时在 源代码 字段指定路径。 请参阅 “配置管道”。

SQL

SQL 文件处理流水线笔记本

获取笔记本

Python

文件处理流水线 Python笔记本

获取笔记本

自己探索吧

该管道将文档分类为五种协议类型,但仅提取 consulting_agreement 的字段。 要扩展它,对剩余的每个类型重复金步,修改 contract_type 过滤器和 ai_extract 模式以匹配该类型相关的字段。 例如:

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

其他资源