ai_parse_document functie

Van toepassing op: Databricks SQL Databricks Runtime

De ai_parse_document() functie roept een geavanceerde AI-model aan van Databricks Foundation Model-API's om gestructureerde inhoud uit ongestructureerde documenten te extraheren.

Requirements

• Een werkruimte in een Amerikaanse regio die ondersteuning biedt voor AI-functies die zijn geoptimaliseerd voor batchdeductie.
  • Als uw werkruimte zich niet in de VS bevindt, maar zich in een regio bevindt die ONDERSTEUNING biedt voor AI-functies die zijn geoptimaliseerd voor batchdeductie, moet routering tussen geografische regio's in uw werkruimte zijn ingeschakeld .
  • Voor klanten in deze regio's is de ai_parse_document functie ook beschikbaar voor werkruimten met de invoegtoepassing Verbeterde beveiliging en naleving, maar werkruimtebeheerders moeten deze inschakelen in de preview-portal.
• Databricks Runtime 17.1 of hoger.
• Als u serverloze berekeningen gebruikt, is ook het volgende vereist:
  • De serverloze omgevingsversie moet zijn ingesteld op 3 of hoger, omdat dit mogelijk maakt functies zoals VARIANT.
  • Moet Python of SQL gebruiken. Zie Serverloze rekenbeperkingen voor aanvullende serverloze functies en beperkingen.
• De ai_parse_document functie is beschikbaar met behulp van Databricks-notebooks, SQL-editor, Databricks-werkstromen, taken of Lakeflow-declaratieve pijplijnen.
• Zie de pagina met prijzen voor bètaproducten voor factureringsgegevens.

Gegevensbeveiliging

Uw documentgegevens worden verwerkt binnen de Databricks-beveiligingsperimeter. Databricks slaat de parameters die worden doorgegeven aan de ai_parse_document function aanroepen niet op, maar behoudt wel details van de uitvoering van metagegevens, zoals de databricks Runtime-versie die wordt gebruikt.

Ondersteunde invoerbestandsindelingen

Uw invoergegevensbestanden moeten worden opgeslagen als blobgegevens in bytes, wat wil zeggen dat een kolom van het binaire type in een DataFrame- of Delta-tabel nodig is. Als de brondocumenten worden opgeslagen in een Unity Catalog-volume, kan de binaire typekolom worden gegenereerd met behulp van Spark-indelingslezer binaryFile.

De volgende bestandsindelingen worden ondersteund:

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

Syntax

ai_parse_document(content)

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

Arguments

• content: Een BINARY expressie die de invoer-bytematrixgegevens vertegenwoordigt.
• version: De versie van het uitvoerschema, ondersteund: '2.0'.
• 'imageOutputPath': optioneel. Sla weergegeven pagina-afbeeldingen op in een Unity Catalog-volume voor referentie- of multimodale RAG-toepassingen.
• 'descriptionElementTypes': door AI gegenereerde beschrijvingen. Alleen beschrijvingen voor figures worden ondersteund voor versie 2.0, dus '*' en 'figure' produceren hetzelfde gedrag.
  • '' (lege tekenreeks): er worden geen beschrijvingen gegenereerd. Dit vermindert de rekenkracht en de kosten voor documenten met veel cijfers.
  • 'figure': Genereer alleen beschrijvingen voor afbeeldingen. Ondersteunt alleen door AI gegenereerde beschrijvingen.
  • '*' (standaard): Beschrijvingen genereren voor alle ondersteunde elementtypen.

Returns

De ai_parse_document functie extraheert de contextuele indelingsmetagegevens uit het document, zoals page_number, headerfooter. Ook wordt de inhoud van het document geëxtraheerd, zoals tekst alinea's. Voor versie 2.0 worden tabellen weergegeven in HTML. De uitvoer is van het VARIANT type.

Hier volgt het uitvoerschema:

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

Workloads overzetten naar een nieuwste schema

In de stappen in deze sectie wordt beschreven hoe u workloads migreert die vóór 22 september 2025 zijn gemaakt om het bijgewerkte uitvoerschema te gebruiken.

1. Geef in uw SQL-aanvraag een specifieke schemaversie op met behulp van de version parameter.

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

1. Wijzig de code om inhoud uit de elements matrix te lezen in plaats van de pages matrix.
2. Metagegevens opnieuw evalueren. Als u page bijvoorbeeld metagegevens zoals kop- en voetteksten gebruikt, moet u een alternatieve benadering ontwikkelen voor het extraheren van deze informatie uit de elements.
3. Valideer uw bijgewerkte logica met voorbeelddocumenten voordat u uw volledige workload migreert.
4. Overweeg om afbeeldingsbeschrijvingen of afbeeldingspersistentie in te schakelen als deze relevant zijn voor uw use-case.
5. Controleer de machtigingen. Als u bijvoorbeeld van plan bent om afbeeldingspersistentie te gebruiken, moet u ervoor zorgen dat u de juiste machtigingen hebt ingesteld voor het target Unity Catalog-volume.

Examples

Deze sectie bevat voorbeelden voor het gebruik van ai_parse_document.

Zie dit ai_parse_document voor scenario's voor incrementele verwerking met behulp van

In het volgende voorbeeld wordt gebruikgemaakt ai_parse_document van het extraheren van tekstelementen en het samenvoegen van alle tekstinhoud. Van daaruit gebruikt ai_query het met het Claude Sonnet 4-model om specifieke gestructureerde informatie op te halen, zoals de naam van de leverancier, de datum, het factuurnummer en de gekochte artikelen.

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;

In het volgende voorbeeld wordt ai_parse_document gebruikt om documentindelingen te extraheren als uitvoer naar VARIANT voor één bestand en opgegeven,

• Waar kunt u weergegeven afbeeldingen opslaan.
• Maakt een uitvoerschemaversie vast.
• Hiermee kunt u door AI gegenereerde beschrijvingen voor afbeeldingen inschakelen.

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

In het volgende voorbeeld gebruikt men ai_parse_document om documentindelingen als VARIANT uitvoer voor bestanden in een Unity Catalog-volume te extraheren.

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)

In het volgende voorbeeld wordt ai_parse_document gebruikt om elk top-level veld van de uitvoer te scheiden. Bijvoorbeeld, document.pages, document.elementsen error_statusmetadata in afzonderlijke kolommen.

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)

Notebook voor foutopsporingsinterface

Het volgende notebook biedt een visuele foutopsporingsinterface voor het analyseren van de uitvoer van de ai_parse_document functie. Hiermee worden geparseerde documenten met interactieve begrenzingsvak-overlay weergegeven, waarmee u kunt controleren welke inhoud uit elk gebied van uw documenten is geëxtraheerd.

Notebook voor foutopsporingsinterface

Notebook krijgen

Beperkingen

• Hoewel Databricks continu werkt om alle functies te verbeteren, zijn LLM's een opkomende technologie en kunnen er fouten optreden.
• Het kan even duren voordat de ai_parse_document functie documentinhoud extraheert terwijl structurele informatie behouden blijft, met name voor documenten die zeer dichte inhoud of inhoud met een slechte resolutie bevatten. In sommige gevallen kan het even duren voordat de functie inhoud uitvoert of negeert. Databricks werkt voortdurend aan het verbeteren van de latentie.
• Zie ondersteunde invoerbestandsindelingen. Databricks verwelkomt feedback over welke aanvullende indelingen het belangrijkst zijn voor uw organisatie.
• Het aanpassen van het model dat ai_parse_document aandrijft of het gebruik van een door de klant geleverd model voor ai_parse_document wordt niet ondersteund.
• Het onderliggende model presteert mogelijk niet optimaal bij het verwerken van afbeeldingen met tekst van niet-Latijnse alfabetten, zoals Japans of Koreaans.
• Documenten met digitale handtekeningen worden mogelijk niet nauwkeurig verwerkt.