`ai_parse_document` 函数

2025-10-23

适用于：勾选“是” Databricks SQL Databricks Runtime

Important

此功能目前以公共预览版提供。

该 ai_parse_document() 函数从 Databricks 基础模型 API 调用最先进的生成 AI 模型，以从非结构化文档中提取结构化内容。

Requirements

Important

支持此函数的模型是使用马赛克 AI 模型服务基础模型 API 提供的。有关 Databricks 上可用的模型以及管理这些模型的使用的许可证和策略的信息，请参阅适用的模型开发人员许可证和条款。

如果将来出现根据 Databricks 的内部基准性能更好的模型，Databricks 可能会更改模型并更新文档。

在美国区域中支持针对批处理推理优化的AI功能的工作区。
- 如果你的工作区不在美国，但位于支持针对批处理推理优化的 AI Functions 的区域，则必须在工作区上启用跨地理位置路由。
- 对于这些区域中的客户，此功能 ai_parse_document 也适用于具有增强安全性和合规性加载项的工作区，但工作区管理员必须在预览门户中启用它。
Databricks Runtime 17.1 或更高版本。
如果使用无服务器计算，则还需要满足以下条件：
- 必须将无服务器环境的版本设置为 3 或更高，因为这会启用诸如 VARIANT 之类的功能。
- 必须使用 Python 或 SQL。有关其他无服务器功能和限制，请参阅无服务器计算限制。
该 ai_parse_document 函数可通过 Databricks 笔记本、SQL 编辑器、Databricks 工作流、作业或 Lakeflow 声明式管道使用。
有关计费详细信息，请参阅 Beta 产品定价页。

数据安全性

文档数据在 Databricks 安全外围内进行处理。 Databricks 不存储传入 ai_parse_document function 调用的参数，但会保留元数据运行详细信息，例如使用的 Databricks Runtime 版本。

支持的输入文件格式

输入数据文件必须以字节为单位存储为 Blob 数据，这意味着 DataFrame 或 Delta 表中的二进制类型列。如果源文档存储在 Unity 目录卷中，则可以使用 Spark binaryFile 格式读取器生成二进制类型列。

支持以下文件格式：

PDF
JPG/JPEG
PNG
DOC/DOCX
PPT/PPTX

Syntax

ai_parse_document(content)

ai_parse_document(content, Map("version" -> "2.0"))

Arguments

content：表示 BINARY 输入字节数组数据的表达式。
version：输出架构的版本，支持：“2.0”。
'imageOutputPath'：可选。将已渲染的页面图像保存到 Unity Catalog 卷中，以便参考或用于多模式 RAG 应用。
'descriptionElementTypes'：AI 生成的说明。版本 2.0 仅支持 figures 的说明，因此 '*' 和 'figure' 会产生相同的行为。
- '' （空字符串）：不生成说明。这减少了具有大量数字的文档所需的计算和成本。
- 'figure'：仅为图表生成说明。仅支持 AI 生成的说明。
- '*' （默认值）：为所有支持的元素类型生成说明。

Returns

该ai_parse_document函数从文档中提取上下文布局元数据，例如page_number， headerfooter 它还提取文档的内容，如文本段落。对于版本 2.0，表以 HTML 表示。输出的类型是VARIANT。

Important

函数输出架构使用 major.minor 格式进行版本控制。 Databricks 可能会升级受支持的或默认版本，以反映基于正在进行的研究改进的表示形式。

次要版本升级向后兼容，可能只会引入新字段。
主要版本升级可能包括重大更改，例如字段添加、删除或重命名。

下面是输出架构：

注释

截至 2025 年 9 月 22 日，输出架构位于版本“2.0”上，并已更新为包括：

descriptions 适用于 AI 生成的图形说明。
bbox 用于边界框坐标。

若要迁移现有工作负载以使用更新的架构，请参阅将工作负载迁移到更新的架构。

{
  "document": {
    "pages": [
      {
        "id": INT,                // 0-based page index
        "image_uri": STRING       // Path to saved page image (if enabled)
      }
    ],
    "elements": [
      {
        "id": INT,                 // 0-based element index
        "type": STRING,            // Supported: text, table, figure, table, title, caption, section_header,
                                   // page_footer, page_header, page_number, footnote
        "content": STRING,         // Text content of the target element
        "bbox": [                  // Bounding box coordinates
          {
            "coord": [ INT ],
            "page_id": INT
          }
        ],
        "description": STRING      // AI-generated description for figures
      }
    ]
  },
  "error_status": [
    {
      "error_message": STRING       // The detailed error message
      "page_id": INT                // 0-based page index
    }
  ],
  "metadata": {
    "id": STRING,
    "version": STRING,              // The version of the output schema
    "file_metadata": {
      "file_path": STRING,
      "file_name": STRING,
      "file_size": LONG,
      "file_modification_time": TIMESTAMP
    }
  }
}

将工作负荷迁移到更新的架构

本节中的步骤介绍如何迁移在 2025 年 9 月 22 日之前创建的工作负荷，以使用更新的输出架构。

在 SQL 请求中，使用 version 参数指定特定的架构版本。

SELECT
ai_parse_document(
  content,
  map('version', '2.0')
) AS parsed
FROM READ_FILES('/path/to/documents', format => 'binaryFile');

修改代码以从 elements 数组而不是 pages 数组中读取内容。
重新评估元数据。例如，如果使用 page 标头和页脚等元数据，则需要开发一种替代方法，以便从中提取 elements此信息。
在迁移完整工作负荷之前，使用示例文档验证更新后的逻辑。
如果它们与用例相关，请考虑启用图形说明或图像持久性。
检查权限。例如，如果计划使用映像持久性，请确保为目标 Unity 目录卷设置了正确的权限。

Examples

本部分提供了使用 ai_parse_document示例。

有关使用 ai_parse_document增量处理场景，请参阅此 Databricks 资产捆绑示例

以下示例用于 ai_parse_document 提取文本元素并连接所有文本内容。从那里，它使用 ai_query 与 Claude Sonnet 4 模型一起，提取特定结构化信息，如供应商名称、日期、发票号和购买商品。

WITH parsed_documents AS (
    SELECT
      path,
      ai_parse_document(
        content,
        map(
          'imageOutputPath', '/Volumes/catalog/schema/volume/parsed_images/',
          'descriptionElementTypes', '*'
        )
      ) AS parsed
    FROM READ_FILES('/Volumes/catalog/schema/volume/source_docs/*.{pdf,jpg,jpeg,png,doc,docx,ppt,pptx}', format => 'binaryFile')
  ),
  parsed_text AS (
    SELECT
      path,
      concat_ws(
        '\n\n',
        transform(
          try_cast(parsed:document:elements AS ARRAY<VARIANT>),
          element -> try_cast(element:content AS STRING)
        )
      ) AS text
    FROM parsed_documents
    WHERE try_cast(parsed:error_status AS STRING) IS NULL
  )
  SELECT
    path,
    text,
    ai_query(
      'databricks-claude-sonnet-4',
      concat(
        'Extract vendor name, date, invoice number, and items purchased from this document. ',
        'Return the result as a JSON object with keys: vendor, date, invoice_number, items (as an array). ',
        text
      ),
      returnType => 'STRING'
    ) AS structured_data
  FROM parsed_text
  WHERE text IS NOT NULL;

以下示例演示如何使用 ai_parse_document 提取文档布局，并将其作为 VARIANT 的单个文件输出，并指定：

保存呈现的图像的位置。
固定输出架构版本。
启用 AI 生成的图像说明。

SELECT
  path,
  ai_parse_document(
    content,
    map(
      'version', '2.0',
      'imageOutputPath', '/Volumes/catalog/schema/volume/directory/',
      'descriptionElementTypes', '*'
    )
  ) as parsed_doc
FROM READ_FILES('/Volumes/data/documents/', format => 'binaryFile');

以下示例使用 ai_parse_document 从 Unity Catalog 卷中的文件提取文档布局作为 VARIANT 输出。

SQL

SELECT
  path,
  ai_parse_document(content)
FROM READ_FILES('/Volumes/path/to/your/directory', format => 'binaryFile');

Python

from pyspark.sql.functions import *


df = spark.read.format("binaryFile") \
  .load("/Volumes/path/to/your/directory") \
  .withColumn(
    "parsed",
    expr("ai_parse_document(content)"))
display(df)

Scala

import org.apache.spark.sql.functions._


val df = spark.read.format("binaryFile")
  .load("/Volumes/path/to/your/directory")
  .withColumn(
    "parsed",
    ai_parse_document($"content"))
display(df)

以下示例用于 ai_parse_document 分隔输出的每个顶级字段。例如，将 document.pages、document.elements、error_status 和 metadata 放入各自的列中。

SQL

WITH corpus AS (
  SELECT
    path,
    ai_parse_document(content) AS parsed
  FROM
    READ_FILES('/Volumes/path/to/source/file.pdf', format => 'binaryFile')
)
SELECT
  path,
  parsed:document:pages,
  parsed:document:elements,
  parsed:error_status,
  parsed:metadata
FROM corpus;

Python

from pyspark.sql.functions import *

df = (
  spark.read.format("binaryFile")
    .load("/Volumes/path/to/source/file.pdf")
    .withColumn("parsed", ai_parse_document(col("content")))
    .select(
      "path",
      expr("parsed:document:pages"),
      expr("parsed:document:elements"),
      expr("parsed:error_status"),
      expr("parsed:metadata")
    )
)
display(df)

Scala


import com.databricks.sql.catalyst.unstructured.DocumentParseResultV2_0
import org.apache.spark.sql.functions._


val df = spark.read.format("binaryFile")
 .load("/Volumes/path/to/source/file.pdf")
 .withColumn(
   "parsed",
   ai_parse_document($"content").cast(DocumentParseResultV2_0.SCHEMA))
 .select(
   $"path",
   $"parsed.*")
display(df)

调试接口笔记本

以下笔记本提供了一个可视化调试界面，用于分析函数的 ai_parse_document 输出。它使用交互式边界框覆盖呈现已分析的文档，使你能够检查从文档的每个区域提取的内容

调试接口笔记本

获取笔记本

限制

虽然 Databricks 持续致力于改进其所有功能，但 LLM 是一种新兴技术，可能会产生错误。
该 ai_parse_document 函数可能需要一段时间来提取文档内容，同时保留结构信息，尤其是对于包含高度密集内容或分辨率不佳内容的文档。在某些情况下，函数可能需要一段时间才能运行或忽略内容。 Databricks 持续工作，以提高延迟。
请参阅支持的输入文件格式。 Databricks 欢迎对组织而言最重要的其他格式的反馈。
不支持为ai_parse_document自定义模型或为ai_parse_document使用客户提供的模型。
使用非拉丁字母表（如日语或朝鲜语）的文本处理图像时，基础模型可能无法以最佳方式执行。
无法准确处理具有数字签名的文档。

反馈

此页面是否有帮助？

通过

ai_parse_document 函数

Requirements

数据安全性

支持的输入文件格式

Syntax

Arguments

Returns

将工作负荷迁移到更新的架构

Examples

SQL

Python

Scala

SQL

Python

Scala

调试接口笔记本

调试接口笔记本

限制

反馈

其他资源

`ai_parse_document` 函数