`ai_parse_document`函式

適用於： 勾選為「是」 Databricks SQL Databricks Runtime

Important

此功能已符合公開預覽版及 HIPAA 規範。

預覽期間：

底層語言模型能支援多種語言，但這個 AI 功能是針對英語調整的。
請參閱有限地區可用的功能以了解 AI 功能的區域可用性。

函 ai_parse_document() 式會從 Databricks Foundation 模型 API 叫用最先進的產生式 AI 模型，以從非結構化檔擷取結構化內容。

Requirements

Important

支援此功能的模型是使用 Mosaic 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 Spark 宣告式管線使用。
在 ai_parse_document 裡，成本被記錄為 AI_FUNCTIONS 產品的一部分。如需範例查詢，請參閱檢視執行成本ai_parse_document。

數據安全性

您的文件數據會在 Databricks 安全性周邊內處理。 Databricks 不會儲存傳入 ai_parse_document function 呼叫的參數，但會保留詮釋資料中的執行詳細數據，例如所使用的 Databricks 執行環境版本。

支援的輸入檔案格式

您的輸入資料檔必須儲存為以位元組為單位的 Blob 資料，這表示 DataFrame 或 Delta 資料表中的二進位類型資料行。如果源檔儲存在 Unity 目錄磁碟區中，則可以使用 Spark binaryFile 格式讀取器產生二進位類型數據行。

支援下列檔案格式：

PDF
JPG / JPEG
PNG
文檔/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、header和footer。它還提取文檔的內容，例如文本段落。對於 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 擷取文字元素並串連所有文字內容。從那裡，它與 Claude Sonnet 4 模型一起使用 ai_query 來提取特定的結構化信息，例如供應商名稱、日期、發票號碼和購買的物品。

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 來擷取檔版面配置做為 VARIANT Unity 目錄磁碟區中檔案的輸出。

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。
使用非拉丁字母的文字處理影像時，基礎模型可能無法以最佳方式執行，例如日文或韓文。
具有數位簽名的檔可能無法正確處理。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-28

共用方式為

ai_parse_document函式

Requirements

數據安全性

支援的輸入檔案格式

Syntax

Arguments

Returns

將工作負載移轉至更新的結構描述

Examples

SQL

Python

Scala

SQL

Python

Scala

調試介面筆記本

調試介面筆記本

限制

意見反應

其他資源

`ai_parse_document`函式