`ai_parse_document` Funkce

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

Tato ai_parse_document() funkce využívá nejmodernější techniky výzkumu spravované službou Databricks k analýze strukturovaného obsahu z nestrukturovaných dokumentů.

K přípravě výstupu ai_parse_document pro případy použití vyhledávání a načítání použijte ai_prep_search funkci.

Vizuální uživatelské rozhraní pro ověření a iteraci výsledků ai_parse_documentnajdete v tématu Analýza dokumentu.

Requirements

The model powering this function is made available using Model Serving Foundation Model APIs. Informace o modelech dostupných v Databricks a licencích a zásadách, které řídí používání těchto modelů, najdete v příslušných podmínkách modelu .

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.

Tato funkce je dostupná jenom v některých oblastech, viz dostupnost funkce AI.
- Funkce ai_parse_document je dostupná také pro pracovní prostory s doplňkem Rozšířené zabezpečení a dodržování předpisů.
Databricks Runtime 17.3 nebo novější
Pokud používáte bezserverové výpočetní prostředky, je vyžadováno také toto:
- Verze serverless prostředí musí být nastavena na verzi 3 nebo vyšší, protože umožňuje funkce jako VARIANT.
- Musí používat Python nebo SQL. Další bezserverové funkce a omezení najdete v tématu Omezení bezserverového výpočetního prostředí.
Tato ai_parse_document funkce je dostupná pomocí poznámkových bloků Databricks, editoru SQL, pracovních postupů Databricks, úloh nebo deklarativních kanálů Sparku Lakeflow.
ai_parse_document náklady se zaznamenávají jako součást AI_FUNCTIONS produktu. Příklad dotazu najdete v Zobrazení nákladů na ai_parse_document spuštění.

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
TIFF/TIF
DOC/DOCX
PPT/PPTX

Syntax

ai_parse_document(content)

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

Arguments

content je jediný povinný argument. Všechny možnosti předané v argumentu map (version, imageOutputPath, descriptionElementTypesa pageRange) jsou volitelné.

content: Výraz BINARY představující vstupní bajtová pole dat.
version: Verze výstupního schématu, podporovaná: 2.0.
'imageOutputPath': Uložte vykreslené obrázky stránek na svazek 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ů.
'pageRange': Omezuje analýzu na podmnožinu stránek v dokumentu. Čísla stránek jsou 1 indexovaná. Hodnota je čárkami oddělený seznam tokenů, kde každý token je buď jedna stránka (například "3"), nebo inkluzivní rozsah (například "5-10"). Například '1,3,5-10' analyzuje stránky 1, 3 a 5 až 10. Vybrané stránky musí zůstat v limitu 500 stránek. Pokud pageRange je vynechán a dokument přesahuje 500 stránek, funkce okamžitě selže bez analýzy stránek.

Returns

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

Principy elementů

Prvek je samostatná jednotka obsahu identifikovaná v rámci analyzovaného dokumentu. Při ai_parse_document zpracování dokumentu se dokument rozdělí do posloupnosti prvků, kde každý prvek představuje jedinečný blok obsahu, například textový odstavec, tabulku, obrázek nebo značku rozložení, jako je záhlaví nebo zápatí stránky.

Každý prvek ve výstupním elements poli obsahuje následující pole:

id: Index založený na 0 označující pozici elementu v dokumentu.
type: Řetězec označující druh obsahu, který prvek představuje. Podporované typy elementů jsou:
- text: Textový odstavec nebo obecný základní text.
- table: Tabulka s obsahem reprezentovaným ve formátu HTML.
- figure: Obrázek nebo diagram v dokumentu.
- title: Název dokumentu.
- caption: Titulek přidružený k obrázku nebo tabulce.
- section_header: Nadpis nebo podnadpis, který označuje začátek oddílu.
- page_header: Záhlaví, které se zobrazí v horní části stránky.
- page_footer: Zápatí, které se zobrazí v dolní části stránky.
- page_number: Značka čísla stránky.
- footnote: Odkaz na poznámku pod čarou nebo text.
content: Extrahovaný textový obsah prvku. U table elementů je obsah formátován jako HTML. U figure prvků může být NULLobsah .
confidence: Skóre spolehlivosti určující, jak spolehlivě byl prvek extrahován z dokumentu.
bbox: Pole souřadnic ohraničujícího rámečku označující fyzické umístění prvku na stránce. Každý ohraničující rámeček obsahuje souřadnice pixelů a page_id odkaz.
description: Popis textu vygenerovaný AI. Ve verzi 2.0 se popisy generují pouze pro figure prvky, pokud descriptionElementTypes je tato možnost povolená.

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
        "confidence": DOUBLE,      // Confidence score 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
  }
}

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.

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

Upravte svůj kód tak, aby četl obsah z pole elements místo z pole pages.
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.
Před migrací plné úlohy ověřte aktualizovanou logiku pomocí ukázkových dokumentů.
Zvažte povolení popisu obrázku nebo trvalosti obrázků, pokud jsou relevantní pro váš případ použití.
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.

Scénáře přírůstkového zpracování, které se používajíai_parse_document, najdete v tomto příkladu deklarativních balíčků automatizace.

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_docs AS (
  SELECT
    path,
    ai_parse_document(
      content,
      MAP('version', '2.0')
    ) AS parsed_content
  FROM READ_FILES('/Volumes/finance/invoices/', format => 'binaryFile')
)
SELECT
  path,
  ai_extract(
    parsed_content,
    '["invoice_id", "vendor_name", "total_amount"]',
    MAP('instructions', 'These are vendor invoices.')
  ) AS invoice_data
FROM parsed_docs;

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á pageRange k omezení parsování na podmnožinu stránek z binárních souborů ve svazku Katalogu Unity. Čísla stránek jsou 1 indexovaná a můžete kombinovat jednotlivé stránky s rozsahy (například '1,3,5-10').

SELECT
  path,
  ai_parse_document(
    content,
    map('pageRange', '1-500')
  ) AS parsed_doc
FROM READ_FILES('/Volumes/catalog/schema/volume/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 s Lakeflow Connect pro SharePoint k analýze dokumentů přímo z knihovny dokumentů SharePoint.

Important

Lakeflow Connect pro SharePoint je v Beta.

CREATE TABLE documents AS
  SELECT * FROM read_files(
    'https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents',
    databricks.connection => 'my_sharepoint_conn',
    format => 'binaryFile',
    pathGlobFilter => '*.{pdf,docx}',
    schemaEvolutionMode => 'none'
  );

SELECT *, ai_parse_document(content) AS parsed_content
FROM documents;

Použití to_json() s PySpark collect()

ai_parse_document VARIANT vrátí typ, který nelze přímo shromažďovat pomocí PySpark (nebo jiných rozhraní API, která nepodporují variantu). Pokud chcete shromáždit analyzované výsledky do Python pro další zpracování, pomocí příkazu to_json() v SQL převeďte variantu na řetězec JSON a pak ho parsujte pomocí json.loads() v Python:

import json

sql = """
WITH parsed_documents AS (
  SELECT
    path,
    ai_parse_document(
      content,
      map(
        'version', '2.0',
        'imageOutputPath', '/Volumes/catalog/schema/volume/parsed_images/',
        'descriptionElementTypes', '*'
      )
    ) AS parsed
  FROM READ_FILES('/Volumes/catalog/schema/volume/source_docs/*', format => 'binaryFile')
)
SELECT path, to_json(parsed) AS parsed_json FROM parsed_documents
"""
parsed_results = [json.loads(row.parsed_json) for row in spark.sql(sql).collect()]
# Each item in parsed_results is a Python dict with the parsed document structure.

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í

Dokumenty jsou omezeny na maximálně 500 stránek a překročení tohoto limitu způsobí chyby.
Maximální limit velikosti souboru je 100 MB.
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ě.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-06

ai_parse_document Funkce

Requirements

Zabezpečení dat

Podporované formáty vstupních souborů

Syntax

Arguments

Returns

Principy elementů

Migrace úloh na aktualizované schéma

Examples

SQL

Python

Scala

Použití to_json() s PySpark collect()

SQL

Python

Scala

Poznámkový blok rozhraní ladění

Poznámkový blok rozhraní ladění

omezení

Související funkce

Související prostředky

Váš názor

Další materiály

`ai_parse_document` Funkce