ai_parse_document függvény

A következőkre vonatkozik: Databricks SQL Databricks Runtime

A ai_parse_document() függvény a databricks által felügyelt, korszerű kutatási technikákat használja a strukturálatlan dokumentumok strukturált tartalmának elemzéséhez.

A keresési és lekérési használati esetek kimenetének ai_parse_document előkészítéséhez használja ai_prep_search a függvényt.

Ha egy vizualizáció felhasználói felületét ai_parse_documentszeretné ellenőrizni és iterálni az eredményeken, tekintse meg a Dokumentum elemzése című témakört.

Adatbiztonság

A dokumentumadatok feldolgozása a Databricks biztonsági peremhálózatán belül történik. A Databricks nem tárolja azokat a paramétereket, amelyek az AI függvényhívásokba kerülnek, de megőrzi a metaadat-futtatási részleteket, például a használt Databricks Runtime verziót.

Requirements

A függvényt bekapcsoló modell a Model Serving Foundation modell API-kkal érhető el. A Databricksben elérhető modellekről, valamint a modellek használatát szabályozó licencekről és szabályzatokról az Alkalmazandó modellfeltételek című témakörben olvashat.

Ha a Databricks belső teljesítménymutatóinak megfelelően jobb teljesítményt nyújtó modellek jelennek meg a jövőben, a Databricks megváltoztathatja a modelleket, és frissítheti a dokumentációt.

• Ez a függvény csak bizonyos régiókban érhető el, lásd az AI-függvények rendelkezésre állását.
  • A ai_parse_document funkció a Fokozott biztonság és megfelelőség bővítményrel rendelkező munkaterületek számára is elérhető.
• Databricks Runtime 17.3 vagy újabb.
• Kiszolgáló nélküli számítás használata esetén a következőkre is szükség van:
  • A kiszolgáló nélküli környezet verziószámának 3 vagy újabb értékre kell állítania, mivel ez lehetővé teszi az olyan funkciókat, mint a VARIANT.
  • Python vagy SQL-t kell használnia. További kiszolgáló nélküli funkciók és korlátozások: Kiszolgáló nélküli számítási korlátozások.
• A ai_parse_document függvény Databricks-jegyzetfüzetek, SQL-szerkesztők, Databricks-munkafolyamatok, feladatok vagy Lakeflow-folyamatok használatával érhető el.
• ai_parse_document költségeket a termék részeként kell elszámolni AI_FUNCTIONS . Tekintse meg a futtatások költségeinek ai_parse_document megtekintését egy példa lekérdezéshez.

Támogatott bemeneti fájlformátumok

A bemeneti adatfájlokat blobadatokként kell tárolni bájtokban, ami bináris típusú oszlopot jelent egy DataFrame- vagy Delta-táblában. Ha a forrásdokumentumok unity katalóguskötetben vannak tárolva, a bináris típusú oszlop Spark binaryFile formátumolvasóval hozható létre.

A következő fájlformátumok támogatottak:

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

Syntax

ai_parse_document(content)

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

Arguments

content az egyetlen kötelező argumentum. Az argumentumban map (version, , imageOutputPathdescriptionElementTypesés pageRange) megadott összes beállítás megadása nem kötelező.

• content: A BINARY bemeneti bájttömb adatait képviselő kifejezés.
• version: A kimeneti séma verziója, támogatott: "2.0".
• 'imageOutputPath': A renderelt oldalképeket egy Unity-katalóguskötetbe mentheti referencia- vagy többmódusú RAG-alkalmazásokhoz.
• 'descriptionElementTypes': AI által létrehozott leírások. A 2.0 verzió esetében csak a figures leírások támogatottak, így a '*' és 'figure' ugyanazt a viselkedést eredményezik.
  • '' (üres sztring): Nem jön létre leírás. Ez csökkenti a szükséges számítást és a sok adatot tartalmazó dokumentumok költségeit.
  • 'figure': Csak az ábrák leírását generálja. Csak az AI által létrehozott leírásokat támogatja.
  • '*' (alapértelmezett): Leírások létrehozása az összes támogatott elemtípushoz.
• 'pageRange': A dokumentum lapjainak egy részhalmazára korlátozza az elemzést. Az oldalszámok 1 indexeltek. Az érték a jogkivonatok vesszővel tagolt listája, ahol minden jogkivonat egy lap (például "3") vagy egy befogadó tartomány (például "5-10"). Elemezi például az 1. '1,3,5-10' , a 3. és az 5–10. oldalt. A kijelölt lapoknak az 500 oldalas korláton belül kell maradniuk. Ha pageRange nincs megadva, és a dokumentum meghaladja az 500 oldalt, a függvény azonnal meghiúsul, és nem elemzi az oldalakat.

Returns

A ai_parse_document függvény azonosítja és kinyeri egy dokumentum elrendezési adatait, például oldalszámokat, élőfejeket, táblázatokat és élőlábakat, és strukturált elemként adja vissza őket. Ezután kinyeri az elemek tartalmát, beleértve a szöveges bekezdéseket és a táblázatadatokat. A 2.0-s verzióban a táblák HTML-ben jelennek meg. A kimenet VARIANT típusa.

Az elemek ismertetése

Az elem az elemzett dokumentumban azonosított tartalom különálló egysége. Amikor ai_parse_document feldolgoz egy dokumentumot, az elemek sorozatára bontja a dokumentumot, ahol minden elem egy különálló tartalomblokkot jelöl, például egy szöveges bekezdést, egy táblázatot, egy ábrát vagy egy elrendezésjelölőt, például egy oldalfejet vagy élőlábat.

A kimeneti elements tömb minden eleme a következő mezőket tartalmazza:

• id: Egy 0-alapú index, amely az elem pozícióját jelzi a dokumentumban.
• type: Az elem által képviselt tartalomtípust jelző sztring. A támogatott elemtípusok a következők:
  • text: Szöveg bekezdés vagy általános törzsszöveg.
  • table: Egy táblázat, html formátumban ábrázolt tartalommal.
  • figure: A dokumentumon belüli kép vagy diagram.
  • title: A dokumentum címe.
  • caption: Ábra vagy táblázat felirata.
  • section_header: Egy szakasz kezdetét jelölő címsor vagy alcím.
  • page_header: Az oldal tetején megjelenő fejléc.
  • page_footer: Az oldal alján megjelenő élőláb.
  • page_number: Oldalszám-jelölő.
  • footnote: Lábjegyzet-hivatkozás vagy szöveg.
• content: Az elem kinyert szöveges tartalma. Elemek esetén table a tartalom HTML formátumban van formázva. Elemek esetén figure a tartalom lehet NULL.
• confidence: Megbízhatósági pontszám, amely azt jelzi, hogy az elem mennyire lett megbízhatóan kinyerve a dokumentumból.
• bbox: Határolókeret-koordináták tömbje, amely az elem fizikai helyét jelzi az oldalon. A pixel koordináták a megjelenített oldalkép kimeneteihez viszonyíthatók, nem az eredeti dokumentumméretekhez. Minden határolókeret képpontkoordinátákat és hivatkozásokat page_id tartalmaz.
• description: AI által létrehozott szöveges leírás. A 2.0-s verzióban csak akkor jönnek létre leírások az elemekhez figure , ha engedélyezve van a descriptionElementTypes beállítás.

Important

A függvény kimeneti sémája major.minor formátummal van verziószámozott. Előfordulhat, hogy a Databricks frissíti a támogatott vagy alapértelmezett verziót, hogy a folyamatban lévő kutatások alapján továbbfejlesztett megjelenítéseket tükrözzen.

• Az alverziófrissítések visszamenőlegesen kompatibilisek, és előfordulhat, hogy csak új mezőket vezetnek be.
• A főverzió-frissítések közé tartozhatnak a kompatibilitástörő módosítások, például mezőhozzáadások, eltávolítások vagy átnevezések.

A kimeneti séma a következő:

Megjegyzés:

2025. szeptember 22-étől a kimeneti séma a "2.0" verzión van, és a következőkre lett frissítve:

• descriptions az AI által létrehozott ábraleírásokhoz.
• bbox a határolókeret koordinátáihoz.

Ha a meglévő számítási feladatokat a frissített séma használatára szeretné migrálni, olvassa el a Számítási feladatok migrálása frissített sémába című témakört.

{
  "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, relative to the rendered page image outputs
          {
            "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
  }
}

Számítási feladatok migrálása frissített sémába

Az ebben a szakaszban ismertetett lépések bemutatják, hogyan migrálhatja a 2025. szeptember 22. előtt létrehozott számítási feladatokat a frissített kimeneti séma használatára.

1. Az SQL-kérelemben adjon meg egy adott sémaverziót a version paraméterrel.

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

1. Módosítsa a kódot úgy, hogy a elements tömbből olvassa be a tartalmat a pages tömb helyett.
2. Metaadatok újraértékelése. Ha például a fejlécek és láblécek, mint metaadatokat használta page, akkor alternatív módszert kell kidolgoznia ezen információk kinyerésére a elements.
3. A teljes számítási feladat áttelepítése előtt ellenőrizze a frissített logikát mintadokumentumokkal.
4. Fontolja meg az ábraleírások vagy a képek megőrzésének engedélyezését, ha azok relevánsak a használati eset szempontjából.
5. Ellenőrizze az engedélyeket. Ha például a rendszerképek megőrzését tervezi használni, győződjön meg arról, hogy a megfelelő engedélyekkel rendelkezik a cél Unity Catalog-kötethez.

Examples

Ez a rész példákat mutat be a ai_parse_document használatára.

Ha növekményes feldolgozási forgatókönyveket használ ai_parse_document, tekintse meg ezt a Deklaratív Automation-csomagok példáját

A következő példa egy FILE típusú oszlopot továbbít egy táblából document közvetlenül a ai_parse_document.

SELECT
  document.uri AS path,
  ai_parse_document(
    document,
    map(
      'version', '2.0',
      'imageOutputPath', '/Volumes/catalog/schema/volume/directory/'
    )
  ) AS parsed
FROM my_catalog.my_schema.documents;

Megjegyzés:

A FILE típus a Bétában van.

Az alábbi példa szövegelemek kinyerésére és az összes szöveges tartalom összefűzésére használható ai_parse_document . Innen a Claude Sonnet 4 modellel konkrét ai_query strukturált információkat nyer ki, például a szállító nevét, dátumát, számlaszámát és megvásárolt cikkeit.

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;

Az alábbi példa a ai_parse_document segítségével történő dokumentum elrendezéseinek kinyerésére szolgál egyetlen fájl kimenetekéntVARIANT, és megadja,

• A renderelt képek mentésének helye.
• A kimeneti séma verzióját rögzíti.
• Lehetővé teszi a mesterséges intelligencia által generált leírásokat ábrákhoz.

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

Az alábbi példa a Unity-katalógus kötetében lévő bináris fájlokból származó lapok egy részhalmazára való elemzést használja pageRange . Az oldalszámok 1 indexeltek, és egyesítheti az egyes oldalakat tartományokkal (például '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');

Az alábbi példa ai_parse_document használ dokumentumelrendezések kibontására VARIANT kimenetként a Unity Catalog kötetében lévő fájlok számára.

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)

Az alábbi példa ai_parse_documentLakeflow Connect for SharePoint használatával elemzi a dokumentumokat közvetlenül egy SharePoint dokumentumtárból.

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;

To_json() használata a PySpark collect() használatával

ai_parse_document olyan típust VARIANT ad vissza, amelyet a PySpark (vagy más, a VARIANT-t nem támogató API-k) nem gyűjthetnek közvetlenül. Ha további feldolgozás céljából szeretné összegyűjteni az elemzési eredményeket Python, használja az SQL to_json() a VARIANT JSON-sztringgé alakításához, majd elemezje json.loads() 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.

Az alábbi példa a kimenet egyes felső szintű mezőinek elkülönítését használja ai_parse_document . Például, document.pages, document.elements, error_status, és metadata külön oszlopokba.

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)

Validáld és debug a parsing eredményeket

A kimenet validálásához és iterálásához ai_parse_documenthasználja a Dokumentum Parsing UI-t. A forrásdokumentumot a parzírozott kimenettel együtt jeleníti meg, lehetővé téve, hogy megvizsgáld, melyik tartalmat nyerték ki a dokumentumok egyes régióiból. Lásd: Dokumentum elemzés.

korlátozások

• A dokumentumok legfeljebb 500 oldalra korlátozódnak, és a korlát túllépése hibákhoz vezet.
• A maximális fájlméretkorlát 100 MB.
• Bár a Databricks folyamatosan dolgozik az összes funkciójának fejlesztésén, az LLM-ek egy új technológia, amely hibákat okozhat.
• A ai_parse_document függvény időt vehet igénybe a dokumentumtartalmak kinyeréséhez a szerkezeti információk megőrzése mellett, különösen olyan dokumentumok esetében, amelyek nagy sűrűségű tartalmat vagy rossz felbontású tartalmat tartalmaznak. Bizonyos esetekben a függvény futtatása eltarthat egy ideig, vagy figyelmen kívül hagyhat tartalmat. A Databricks folyamatosan dolgozik a késés javításán.
• Lásd : Támogatott bemeneti fájlformátumok. A Databricks üdvözli a szervezet számára legfontosabb további formátumokkal kapcsolatos visszajelzéseket.
• Az a testreszabás, amely a ai_parse_document-ot működtető modellre vagy az ügyfél által biztosított ai_parse_document-hoz használt modellre vonatkozik, nem támogatott.
• A mögöttes modell nem feltétlenül teljesít optimálisan, ha nem latin betűs szövegekkel, például japán vagy koreai betűs szövegekkel kezeli a képeket.
• A digitális aláírással rendelkező dokumentumok nem dolgozhatók fel pontosan.

Kapcsolódó függvények

• ai_prep_search függvény
• ai_search függvény
• ai_extract függvény
• ai_classify függvény
• ai_enrich függvény

Kapcsolódó erőforrások

• Intelligens dokumentumfeldolgozás
• Az AI Functions által működtetett dokumentumintelligencia