Condividi tramite

Funzione ai_parse_document

Si applica a:segno di spunta sì Databricks SQL segno di spunta sì Databricks Runtime

Important

Questa funzionalità è disponibile in anteprima pubblica e conforme a HIPAA.

Durante l'anteprima:

La ai_parse_document() funzione richiama un modello di intelligenza artificiale generativa all'avanguardia dalle API del modello di Databricks Foundation per estrarre contenuto strutturato da documenti non strutturati.

Requirements

Important

Il modello che alimenta questa funzione viene reso disponibile usando le API Mosaic AI Model Serving Foundation Model. Vedere Licenze e condizioni per sviluppatori di modelli applicabili per informazioni sui modelli disponibili in Databricks e le licenze e i criteri che regolano l'uso di tali modelli.

Se i modelli emergono in futuro che offrono prestazioni migliori in base ai benchmark interni di Databricks, Databricks potrebbe modificare i modelli e aggiornare la documentazione.

Sicurezza dei dati

I dati del documento vengono elaborati all'interno del perimetro di sicurezza di Databricks. Databricks non archivia i parametri passati nelle ai_parse_document function chiamate, ma mantiene i dettagli dell'esecuzione dei metadati, ad esempio la versione di Databricks Runtime usata.

Formati di file di input supportati

I file di dati di input devono essere archiviati come dati BLOB in byte, ovvero una colonna di tipo binario in una tabella DataFrame o Delta. Se i documenti di origine vengono archiviati in un volume del catalogo Unity, è possibile generare la colonna di tipo binario usando il lettore di formato Spark binaryFile .

Sono supportati i formati di file seguenti:

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

Syntax

ai_parse_document(content)

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

Arguments

  • content BINARY: espressione che rappresenta i dati della matrice di byte di input.
  • version: versione dello schema di output, supportata: "2.0".
  • 'imageOutputPath': facoltativo. Salvare le immagini delle pagine di cui è stato eseguito il rendering in un volume di Catalogo Unity per applicazioni RAG di riferimento o multimodali.
  • 'descriptionElementTypes': descrizioni generate dall'intelligenza artificiale. Solo le descrizioni per figures sono supportate per la versione 2.0, quindi '*' producono 'figure' lo stesso comportamento.
    • '' (stringa vuota): non vengono generate descrizioni. In questo modo si riducono le risorse di calcolo necessarie e i costi per i documenti con un numero elevato di cifre.
    • 'figure': genera descrizioni solo per le figure. Supporta solo le descrizioni generate dall'intelligenza artificiale.
    • '*' (impostazione predefinita): genera descrizioni per tutti i tipi di elemento supportati.

Returns

La ai_parse_document funzione estrae i metadati del layout contestuale dal documento, ad esempio page_number, header, footer. Estrae anche il contenuto del documento, ad esempio i paragrafi di testo. Per la versione 2.0, le tabelle sono rappresentate in HTML. L'output è del tipo VARIANT.

Important

Lo schema di output della funzione viene versionato usando un formato major.minor. Databricks potrebbe aggiornare la versione supportata o predefinita per riflettere rappresentazioni migliorate in base alla ricerca in corso.

  • Gli aggiornamenti delle versioni secondarie sono compatibili con le versioni precedenti e potrebbero introdurre solo nuovi campi.
  • Gli aggiornamenti delle versioni principali possono includere modifiche di rilievo, ad esempio aggiunte di campi, rimozioni o ridenominazione.

Di seguito è riportato lo schema di output:

Annotazioni

A partire dal 22 settembre 2025, lo schema di output è nella versione "2.0" ed è stato aggiornato per includere:

  • descriptions per le descrizioni delle figure generate dall'intelligenza artificiale.
  • bbox per le coordinate del rettangolo di delimitazione.

Per eseguire la migrazione dei carichi di lavoro esistenti per usare lo schema aggiornato, vedere Eseguire la migrazione dei carichi di lavoro allo schema aggiornato.

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

Eseguire la migrazione dei carichi di lavoro allo schema aggiornato

I passaggi descritti in questa sezione descrivono come eseguire la migrazione dei carichi di lavoro creati prima del 22 settembre 2025 per usare lo schema di output aggiornato.

  1. Nella richiesta SQL specificare una versione specifica dello schema usando il version parametro .
SELECT
ai_parse_document(
  content,
  map('version', '2.0')
) AS parsed
FROM READ_FILES('/path/to/documents', format => 'binaryFile');
  1. Modificare il codice per leggere il contenuto dalla elements matrice anziché dalla pages matrice.
  2. Rivalutare i metadati. Ad esempio, se si usano page metadati come intestazioni e piè di pagina, dovrai sviluppare un approccio alternativo per estrarre queste informazioni da elements.
  3. Convalidare la logica aggiornata con documenti di esempio prima di eseguire la migrazione del carico di lavoro completo.
  4. È consigliabile abilitare la persistenza delle descrizioni delle figure o delle immagini se sono rilevanti per il caso d'uso.
  5. Controllare le autorizzazioni. Ad esempio, se si prevede di usare la persistenza delle immagini, assicurarsi di avere le autorizzazioni corrette configurate per il volume del catalogo Unity di destinazione.

Examples

In questa sezione vengono forniti esempi per l'uso di ai_parse_document.

Per gli scenari di elaborazione incrementale con ai_parse_document, vedere questo esempio di aggregazioni di asset di Databricks

Nell'esempio seguente viene ai_parse_document usato per estrarre elementi di testo e concatenare tutto il contenuto di testo. Da qui usa ai_query con il modello Claude Sonnet 4 per estrarre informazioni strutturate specifiche, ad esempio nome fornitore, data, numero di fattura e articoli acquistati.

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;

Nell'esempio seguente, viene utilizzato ai_parse_document per estrarre i layout di documento come output VARIANT per un singolo file, specificando,

  • Dove salvare le immagini di cui è stato eseguito il rendering.
  • Fissa una versione dello schema di output.
  • Abilita le descrizioni generate dall'intelligenza artificiale per le figure.
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');

L'esempio seguente usa ai_parse_document per estrarre layout di documento come output VARIANT per i file in un volume del catalogo 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)

Nell'esempio seguente viene usato per separare ai_parse_document ogni campo di primo livello dell'output. Ad esempio, document.pages, document.elements, error_statuse metadata in singole colonne.

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 dell'interfaccia di debug

Il notebook seguente fornisce un'interfaccia di debug visivo per l'analisi dell'output della funzione ai_parse_document. Esegue il rendering dei documenti analizzati con sovrapposizioni interattive di rettangoli delimitatori, consentendo di ispezionare il contenuto estratto da ogni regione dei documenti.

Notebook dell'interfaccia di debug

Ottieni il notebook

Limitazioni

  • Anche se Databricks lavora continuamente per migliorare tutte le sue funzionalità, i llms sono una tecnologia emergente e possono generare errori.
  • La ai_parse_document funzione può richiedere tempo per estrarre il contenuto del documento mantenendo al tempo stesso informazioni strutturali, in particolare per i documenti che contengono contenuti altamente densi o contenuti con risoluzione scarsa. In alcuni casi, la funzione può richiedere un po' di tempo per eseguire o ignorare il contenuto. Databricks funziona continuamente per migliorare la latenza.
  • Vedere Formati di file di input supportati. Databricks accoglie commenti e suggerimenti su quali formati aggiuntivi sono più importanti per l'organizzazione.
  • La personalizzazione del modello che supporta ai_parse_document o l'uso di un modello fornito dal cliente per ai_parse_document non è supportata.
  • Il modello sottostante potrebbe non funzionare in modo ottimale quando si gestiscono immagini usando testo di alfabeti non latini, ad esempio giapponese o coreano.
  • I documenti con firme digitali potrebbero non essere elaborati in modo accurato.
  • Last updated on