Sdílet prostřednictvím

ai_parse_document Funkce

Platí pro:označeno jako ano Databricks SQL označeno jako ano Databricks Runtime

Important

Tato funkce je ve verzi Public Preview a kompatibilní se standardem HIPAA.

Během náhledu:

Funkce ai_parse_document() vyvolá generativní model AI z API nadace Databricks k extrakci strukturovaného obsahu z nestrukturovaných dokumentů.

Requirements

Important

Model zajišťující tuto funkci je k dispozici pomocí APIs nadace modelového servírování Mosaic AI. Informace o tom, které modely jsou k dispozici v Databricks, a o licencích a zásadách, které řídí používání těchto modelů, najdete v části Příslušné licence a podmínky pro vývojáře modelů.

Pokud se modely objeví v budoucnu, které fungují lépe podle interních srovnávacích testů Databricks, může Databricks změnit modely a aktualizovat dokumentaci.

Zabezpečení dat

Vaše data dokumentu se zpracovávají v rámci hraniční sítě zabezpečení Databricks. Databricks neukládá parametry předávané do ai_parse_document function volání, ale zachovává podrobnosti o spuštění metadat, jako je použitá verze Databricks Runtime.

Podporované formáty vstupních souborů

Vaše vstupní datové soubory musí být uloženy jako data typu blob v bajtech, což znamená, že jde o sloupec binárního typu v tabulce DataFrame nebo Delta. Pokud jsou zdrojové dokumenty uloženy ve svazku katalogu Unity, lze sloupec binárního typu vygenerovat pomocí čtečky formátu Sparku binaryFile .

Podporují se následující formáty souborů:

  • soubor PDF
  • JPG / JPEG
  • formát PNG
  • DOC/DOCX
  • PPT/PPTX

Syntax

ai_parse_document(content)

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

Arguments

  • content: Výraz BINARY představující vstupní bajtová pole dat.
  • version: Verze výstupního schématu, podporovaná: 2.0.
  • 'imageOutputPath': Volitelné. Uložte vykreslené obrázky stránek do svazku katalogu Unity pro referenční nebo multimodální aplikace RAG.
  • 'descriptionElementTypes': Popisy generované AI Pro verzi 2.0 jsou podporovány pouze popisy figures, takže '*' a 'figure' vytváří stejné chování.
    • '' (prázdný řetězec): Nejsou generovány žádné popisy. Tím se sníží potřebné výpočetní prostředky a náklady na dokumenty s velkým množstvím obrázků.
    • 'figure': Generujte pouze popisy pro obrázky. Podporuje pouze popisy generované AI.
    • '*' (výchozí): Vygenerujte popisy pro všechny podporované typy prvků.

Returns

Funkce ai_parse_document extrahuje metadata kontextového rozložení z dokumentu, například page_number, header. footer Extrahuje také obsah dokumentu, jako jsou textové odstavce. Pro verzi 2.0 jsou tabulky reprezentovány ve formátu HTML. Výstup je typu VARIANT .

Important

Výstupní schéma funkce je verzováno pomocí formátu hlavní.podřízená. Databricks může upgradovat podporovanou nebo výchozí verzi tak, aby odrážela vylepšené reprezentace na základě probíhajícího výzkumu.

  • Aktualizace podverzí jsou zpětně kompatibilní a možná zavádějí pouze nové funkce.
  • Upgrady hlavních verzí můžou zahrnovat zásadní změny, jako jsou přidání polí, odebrání nebo přejmenování.

Toto je výstupní schéma:

Poznámka:

Od 22. září 2025 je výstupní schéma ve verzi 2.0 a bylo aktualizováno tak, aby zahrnovalo:

  • descriptions pro AI-vygenerované popisy obrázků.
  • bbox pro souřadnice ohraničujícího rámečku.

Pokud chcete migrovat stávající úlohy tak, aby používaly aktualizované schéma, přečtěte si téma Migrace úloh na aktualizované schéma.

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

Migrace úloh na aktualizované schéma

Kroky v této části popisují migraci úloh vytvořených před 22. zářím 2025 pro použití aktualizovaného výstupního schématu.

  1. V požadavku SQL zadejte pomocí parametru konkrétní verzi schématu version .
SELECT
ai_parse_document(
  content,
  map('version', '2.0')
) AS parsed
FROM READ_FILES('/path/to/documents', format => 'binaryFile');
  1. Upravte svůj kód tak, aby četl obsah z pole elements místo z pole pages.
  2. Znovu vyhodnotit metadata. Pokud jste například používali page metadata, jako jsou záhlaví a zápatí, musíte vyvinout alternativní přístup k extrahování těchto informací z elements.
  3. Před migrací plné úlohy ověřte aktualizovanou logiku pomocí ukázkových dokumentů.
  4. Zvažte povolení popisu obrázku nebo trvalosti obrázků, pokud jsou relevantní pro váš případ použití.
  5. Zkontrolujte oprávnění. Pokud například plánujete používat trvalost obrázků, ujistěte se, že máte nastavená správná oprávnění pro cílový svazek katalogu Unity.

Examples

Tato část obsahuje příklady použití ai_parse_document.

Pro scénáře přírůstkového zpracování s použitím ai_parse_document viz tento příklad sad prostředků Databricks

Následující příklad používá ai_parse_document k extrakci textových prvků a zřetězení veškerého textového obsahu. Odsud používá ai_query s modelem Claude Sonnet 4 k extrakci konkrétních strukturovaných informací, jako je název dodavatele, datum, číslo faktury a zakoupené položky.

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;

Následující příklad používá ai_parse_document k extrahování rozložení dokumentů jako VARIANT výstupu pro jeden soubor a určuje,

  • Kam uložit vykreslené obrázky
  • Připne verzi výstupního schématu.
  • Umožňuje popisy vygenerované AI pro obrázky.
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');

Následující příklad používá ai_parse_document k extrahování rozložení dokumentů jako VARIANT výstupu pro soubory ve svazku katalogu 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)

Následující příklad používá ai_parse_document k oddělení každého pole nejvyšší úrovně výstupu. Například document.pages, document.elements, error_status a metadata do jednotlivých sloupců.

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)

Poznámkový blok rozhraní ladění

Následující poznámkový blok poskytuje vizuální ladicí rozhraní pro analýzu výstupu funkce ai_parse_document. Vykreslí analyzované dokumenty pomocí interaktivních překryvných rámečků, což vám umožní zkontrolovat, jaký obsah se extrahoval z každé oblasti vašich dokumentů.

Poznámkový blok rozhraní ladění

Pořiďte si notebook

omezení

  • I když Databricks neustále pracuje na vylepšení všech svých funkcí, LLMs jsou nově vznikající technologie a můžou vést k chybám.
  • Extrakce ai_parse_document obsahu dokumentu při zachování strukturálních informací může nějakou dobu trvat, zejména u dokumentů, které obsahují vysoce zhuštěný obsah nebo obsah s nízkým rozlišením. V některých případech může spuštění nebo ignorování obsahu nějakou dobu trvat. Databricks neustále pracuje na zlepšení latence.
  • Viz Podporované formáty vstupních souborů. Databricks vítá zpětnou vazbu o tom, které další formáty jsou pro vaši organizaci nejdůležitější.
  • Přizpůsobení modelu, který využívá ai_parse_document nebo používá model ai_parse_document poskytovaný zákazníkem, není podporován.
  • Základní model nemusí při zpracování obrázků pomocí textu jiných než latinských abeced, jako je japonština nebo korejština, optimálně fungovat.
  • Dokumenty s digitálními podpisy nemusí být zpracovány přesně.
  • Last updated on