ai_parse_document-Funktion

Gilt für: Databricks SQL Databricks Runtime

Die ai_parse_document() Funktion ruft ein hochmodernes generatives KI-Modell aus Databricks Foundation Model-APIs auf, um strukturierte Inhalte aus unstrukturierten Dokumenten zu extrahieren.

Requirements

• Ein Arbeitsbereich in einer US-Region, der KI-Funktionen unterstützt, die für die Batch-Ableitung optimiert sind.
  • Wenn sich Ihr Arbeitsbereich nicht in den USA befindet, sich aber in einer Region befindet, die KI-Funktionen unterstützt, die für die Batch-Ableitung optimiert sind, muss das geografieübergreifende Routing in Ihrem Arbeitsbereich aktiviert sein.
  • Für Kunden in diesen Regionen ist die ai_parse_document Funktion auch für Arbeitsbereiche mit dem Add-On "Erweiterte Sicherheit und Compliance" verfügbar, aber Arbeitsbereichsadministratoren müssen sie im Vorschauportal aktivieren.
• Databricks Runtime 17.1 oder höher.
• Wenn Sie serverlose Berechnung verwenden, ist auch Folgendes erforderlich:
  • Die serverlose Umgebungsversionsnummer muss auf 3 oder höher festgelegt werden, da dies Funktionen wie VARIANT ermöglicht.
  • Muss Python oder SQL verwenden. Weitere serverlose Features und Einschränkungen finden Sie unter Serverless Compute-Einschränkungen.
• Die ai_parse_document Funktion ist mit Databricks-Notizbüchern, SQL-Editor, Databricks-Workflows, Aufträgen oder Lakeflow Spark Declarative Pipelines verfügbar.
• ai_parse_document Die Kosten werden als Teil des AI_FUNCTIONS Produkts erfasst. Siehe die Kostenanzeige für ai_parse_document Ausführungen bei einer Beispielabfrage.

Datensicherheit

Ihre Dokumentdaten werden innerhalb des Databricks-Sicherheitsperimeters verarbeitet. Databricks speichert nicht die Parameter, die an die ai_parse_document function Aufrufe übergeben werden, behält jedoch Metadatenausführungsdetails bei, z. B. die verwendete Databricks-Runtime-Version.

Unterstützte Eingabedateiformate

Ihre Eingabedateien müssen als BLOB-Daten in Bytes gespeichert werden, nämlich in einer Binärspalte innerhalb einer DataFrame- oder einer Delta-Tabelle. Wenn die Quelldokumente in einem Unity-Katalogvolume gespeichert sind, kann die Binärtypspalte mithilfe des Spark-Formatlesers binaryFile generiert werden.

Die folgenden Dateiformate werden unterstützt:

• PDF
• JPG / JPEG
• PNG
• DOC/DOCX
• PPT/PPTX

Syntax

ai_parse_document(content)

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

Arguments

• content: Ein BINARY Ausdruck, der die Eingabe-Byte-Array-Daten darstellt.
• version: Die unterstützte Version des Ausgabeschemas ist: "2.0".
• 'imageOutputPath':Wahlfrei. Speichern Sie gerenderte Seitenbilder in einem Unity Catalog-Volume für Referenzzwecke oder multimodale RAG-Anwendungen.
• 'descriptionElementTypes': KI-generierte Beschreibungen. Es werden nur Beschreibungen für Version 2.0 unterstützt, sodass figures und '*' dasselbe Verhalten erzeugen.
  • '' (leere Zeichenfolge): Es werden keine Beschreibungen generiert. Dies reduziert die berechnungsbedarfen und Kosten für Dokumente mit vielen Zahlen.
  • 'figure': Generieren Sie beschreibungen nur für Zahlen. Unterstützt nur KI-generierte Beschreibungen.
  • '*' (Standard): Generieren Sie Beschreibungen für alle unterstützten Elementtypen.

Returns

Die ai_parse_document-Funktion extrahiert die Kontextlayout-Metadaten aus dem Dokument, wie page_number, header und footer. Außerdem extrahiert er den Inhalt des Dokuments, z. B. Textabsätze. Für Version 2.0 werden Tabellen in HTML dargestellt. Die Ausgabe ist vom Typ VARIANT.

Es folgt das Ausgabeschema:

{
  "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
    }
  }
}

Migrieren von Arbeitslasten zum aktualisierten Schema

In den Schritten in diesem Abschnitt wird beschrieben, wie Arbeitslasten migriert werden, die vor dem 22. September 2025 erstellt wurden, um das aktualisierte Ausgabeschema zu verwenden.

1. Geben Sie in Ihrer SQL-Anforderung eine bestimmte Schemaversion mithilfe des version Parameters an.

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

1. Ändern Sie Den Code so, dass Inhalte aus dem elements Array anstelle des pages Arrays gelesen werden.
2. Metadaten erneut auswerten. Wenn Sie page beispielsweise Metadaten wie Kopf- und Fußzeilen verwenden, müssen Sie einen alternativen Ansatz entwickeln, um diese Informationen aus dem elements zu extrahieren.
3. Überprüfen Sie Ihre aktualisierte Logik mit Beispieldokumenten, bevor Sie Ihre vollständige Workload migrieren.
4. Erwägen Sie die Aktivierung von Abbildungsbeschreibungen oder Bildpersistenz, wenn sie für Ihren Anwendungsfall relevant sind.
5. Prüfen Sie die Berechtigungen. Wenn Sie beispielsweise die Imagepersistenz verwenden möchten, stellen Sie sicher, dass Sie über die richtigen Berechtigungen für das Unity-Katalog-Zielvolume verfügen.

Examples

Dieser Abschnitt enthält Beispiele für die Verwendung ai_parse_document.

Für Szenarien der inkrementellen Verarbeitung mit ai_parse_document siehe dieses Beispiel für Databricks Asset Bundles

Im folgenden Beispiel werden Textelemente extrahiert und sämtliche Textinhalte mit ai_parse_document verkettet. Von dort aus verwendet ai_query es mit dem Claude Sonnet 4-Modell, um bestimmte strukturierte Informationen wie Lieferantenname, Datum, Rechnungsnummer und gekaufte Artikel zu extrahieren.

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;

Im folgenden Beispiel werden ai_parse_document Dokumentlayouts als VARIANT Ausgabe für eine einzelne Datei extrahiert und angegeben,

• Wo gerenderte Bilder gespeichert werden sollen.
• Legt eine Ausgabeschemaversion fest.
• Ermöglicht KI-generierte Beschreibungen für Zahlen.

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');

Im folgenden Beispiel wird ai_parse_document verwendet, um Dokumentlayouts als VARIANT-Ausgabe für Dateien in einem Unity Catalog-Volume zu extrahieren.

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)

Im folgenden Beispiel wird ai_parse_document verwendet, um jedes Feld der obersten Ebene der Ausgabe zu trennen. Beispiel: document.pages, document.elements, error_status und metadata in einzelne Spalten.

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)

Debuggen eines Schnittstellennotizbuchs

Das folgende Notizbuch stellt eine visuelle Debugschnittstelle zum Analysieren der Ausgabe der ai_parse_document Funktion bereit. Es rendert analysierte Dokumente mit interaktiven Umgebenden Boxüberlagerungen, sodass Sie prüfen können, welche Inhalte aus den einzelnen Regionen Ihrer Dokumente extrahiert wurden.

Debuggen eines Schnittstellennotizbuchs

Notebook abrufen

Einschränkungen

• Während Databricks kontinuierlich daran arbeitet, alle features zu verbessern, sind LLMs eine neue Technologie und können Fehler erzeugen.
• Die ai_parse_document Funktion kann Zeit in Anspruch nehmen, um Dokumentinhalte zu extrahieren und dabei strukturelle Informationen beizubehalten, insbesondere für Dokumente, die hochdichte Inhalte oder Inhalte mit schlechter Auflösung enthalten. In einigen Fällen kann es eine Weile dauern, bis die Funktion ausgeführt wird oder den Inhalt abweisen. Databricks arbeitet kontinuierlich daran, die Latenz zu verbessern.
• Siehe Unterstützte Eingabedateiformate. Databricks begrüßt Feedback darüber, welche zusätzlichen Formate für Ihre Organisation am wichtigsten sind.
• Das Anpassen des Modells, das ai_parse_document antreibt, oder die Verwendung eines vom Kunden bereitgestellten Modells für ai_parse_document wird nicht unterstützt.
• Das zugrunde liegende Modell kann nicht optimal ausgeführt werden, wenn Bilder mit Text von nicht lateinischen Alphabeten wie Japanisch oder Koreanisch behandelt werden.
• Dokumente mit digitalen Signaturen werden möglicherweise nicht korrekt verarbeitet.