funktion ai_parse_document

gäller för: Databricks SQL Databricks Runtime

Funktionen ai_parse_document() anropar en toppmodern generativ AI-modell från Api:er för Databricks Foundation-modell för att extrahera strukturerat innehåll från ostrukturerade dokument.

Requirements

• En arbetsyta i en region i USA som stöder AI-funktioner som är optimerade för batchinferens.
  • Om din arbetsyta inte finns i USA, men finns i en region som stöder AI Functions som är optimerad för batchinferens, måste routning mellan geografiska områden aktiveras på din arbetsyta.
  • För kunder i dessa regioner ai_parse_document är funktionen också tillgänglig för arbetsytor med tillägget Förbättrad säkerhet och efterlevnad, men arbetsyteadministratörer måste aktivera den i förhandsgranskningsportalen.
• Databricks Runtime 17.1 eller senare.
• Om du använder serverlös beräkning krävs även följande:
  • Den serverlösa miljöversionen måste vara inställd på 3 eller senare, eftersom detta aktiverar funktioner som VARIANT.
  • Måste använda antingen Python eller SQL. Ytterligare serverlösa funktioner och begränsningar finns i Begränsningar för serverlös beräkning.
• Funktionen ai_parse_document är tillgänglig med Databricks notebook-filer, SQL-redigerare, Databricks-arbetsflöden, jobb eller Lakeflow Deklarativa pipelines.
• Se prissidan för Beta-produkter för faktureringsinformation.

Datasäkerhet

Dina dokumentdata bearbetas inom Databricks säkerhetsperimeter. Databricks lagrar inte de parametrar som skickas till anropen ai_parse_document function , men behåller information om metadatakörning, till exempel den Databricks Runtime-version som används.

Indatafilformat som stöds

Dina indatafiler måste lagras som blobdata i byte, vilket innebär en binär typkolumn i en DataFrame- eller Delta-tabell. Om källdokumenten lagras i en Unity Catalog-volym kan kolumnen för binär typ genereras med spark-formatläsaren binaryFile .

Följande filformat stöds:

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

Syntax

ai_parse_document(content)

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

Arguments

• content: Ett BINARY uttryck som representerar inputdata för bytearray.
• version: Den version av utdataschemat som stöds: "2.0".
• 'imageOutputPath': Valfritt. Spara återgivna sidbilder till en Unity Catalog-volym för referens- eller multimodala RAG-program.
• 'descriptionElementTypes': AI-genererade beskrivningar. Endast beskrivningar för figures stöds för version 2.0, så '*' och 'figure' skapar samma beteende.
  • '' (tom sträng): Inga beskrivningar genereras. Detta minskar den beräkning som behövs och kostnaderna för dokument med massor av siffror.
  • 'figure': Generera endast beskrivningar för siffror. Stöder endast AI-genererade beskrivningar.
  • '*' (standard): Generera beskrivningar för alla elementtyper som stöds.

Returns

Funktionen ai_parse_document extraherar kontextuella layoutmetadata från dokumentet, till exempel page_number, header, footer. Det extraherar också innehållet i dokumentet, till exempel textstycken. För version 2.0 representeras tabellerna i HTML. Utdata är av VARIANT typen .

Följande är utdataschemat:

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

Migrera arbetsbelastningar till uppdaterat schema

Stegen i det här avsnittet beskriver hur du migrerar arbetsbelastningar som skapades före den 22 september 2025 för att använda det uppdaterade utdataschemat.

1. I din SQL-begäran anger du en specifik schemaversion med hjälp av parametern version .

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

1. Ändra koden för att läsa innehåll från matrisen elements i stället för matrisen pages .
2. Utvärdera metadata igen. Om du till exempel använder page metadata som sidhuvuden och sidfötter måste du utveckla en alternativ metod för att extrahera den här informationen från elements.
3. Verifiera den uppdaterade logiken med exempeldokument innan du migrerar din fullständiga arbetsbelastning.
4. Överväg att aktivera bildbeskrivningar eller bildpersistens om de är relevanta för ditt användningsfall.
5. Kontrollera behörigheter. Om du till exempel planerar att använda bildpersistens, kontrollerar du att du har rätt behörigheter konfigurerade för målvolymen för Unity Catalog.

Examples

Det här avsnittet innehåller exempel på hur du använder ai_parse_document.

Information om scenarier för inkrementell bearbetning med hjälp av ai_parse_documentfinns i det här exemplet på Databricks-tillgångspaket

I följande exempel används ai_parse_document för att extrahera textelement och sammanfoga allt textinnehåll. Därifrån används ai_query med Claude Sonnet 4-modellen för att extrahera specifik strukturerad information som leverantörsnamn, datum, fakturanummer och köpta artiklar.

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;

I följande exempel används ai_parse_document för att extrahera dokumentlayouter som VARIANT utdata för en enskild fil och anger,

• Var du kan spara renderade bilder.
• Låser en utdataschemaversion.
• Aktiverar AI-genererade beskrivningar för siffror.

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

I följande exempel används ai_parse_document för att extrahera dokumentlayouter som VARIANT utdata för filer i en Unity Catalog-volym.

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)

I följande exempel används ai_parse_document för att avgränsa varje fält på den översta nivån i utdata. Till exempel document.pages, document.elements, error_statusoch metadata i enskilda kolumner.

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)

Felsökningsgränssnitt för notebook

Följande notebook-fil innehåller ett visuellt felsökningsgränssnitt för analys av funktionens ai_parse_document utdata. Den renderar tolkade dokument med interaktiva överlägg för avgränsningsrutor, så att du kan kontrollera vilket innehåll som extraherades från varje region i dina dokument

Felsökningsgränssnitt för notebook

Hämta anteckningsbok

Begränsningar

• Även om Databricks kontinuerligt fungerar för att förbättra alla dess funktioner, är LLM:er en ny teknik och kan orsaka fel.
• Funktionen ai_parse_document kan ta tid att extrahera dokumentinnehåll samtidigt som strukturell information bevaras, särskilt för dokument som innehåller mycket tätt innehåll eller innehåll med dålig upplösning. I vissa fall kan det ta en stund för funktionen att köra eller ignorera innehåll. Databricks arbetar kontinuerligt för att förbättra svarstiden.
• Se Indatafilformat som stöds. Databricks välkomnar feedback om vilka ytterligare format som är viktigast för din organisation.
• Det går inte att anpassa den modell som driver ai_parse_document eller använder en kundanpassad modell för ai_parse_document .
• Den underliggande modellen kanske inte fungerar optimalt när du hanterar bilder med text i icke-latinska alfabet, till exempel japanska eller koreanska.
• Dokument med digitala signaturer kanske inte bearbetas korrekt.