Funkcja ai_parse_document

Dotyczy: Databricks SQL Databricks Runtime

Funkcja ai_parse_document() wywołuje najnowocześniejszy model generowania sztucznej inteligencji z interfejsów API Databricks Foundation Model, aby wyodrębnić ustrukturyzowaną zawartość z dokumentów niestrukturalnych.

Requirements

• Obszar roboczy w regionie USA, który obsługuje funkcje sztucznej inteligencji zoptymalizowane pod kątem wnioskowania wsadowego.
  • Jeśli obszar roboczy nie znajduje się w Stanach Zjednoczonych, ale znajduje się w regionie obsługującym funkcje sztucznej inteligencji zoptymalizowane pod kątem wnioskowania wsadowego, należy włączyć routing między lokalizacjami geograficznymi w obszarze roboczym.
  • W przypadku klientów w tych regionach funkcja ta dostępna jest również dla obszarów roboczych z dodatkiem Rozszerzone zabezpieczenia i zgodność, ale administratorzy obszarów roboczych muszą ją włączyć w portalu Podglądy.
• Databricks Runtime 17.1 lub nowszy.
• Jeśli używasz bezserwerowych obliczeń, wymagane są również następujące elementy:
  • Wersja środowiska bezserwerowego musi być ustawiona na 3 lub nowszą, ponieważ umożliwia to korzystanie z funkcji takich jak VARIANT.
  • Musi używać języka Python lub SQL. Aby uzyskać dodatkowe funkcje i ograniczenia bezserwerowe, zobacz Ograniczenia obliczeniowe bezserwerowe.
• Funkcja ai_parse_document jest dostępna przy użyciu notesów usługi Databricks, edytora SQL, przepływów pracy usługi Databricks, zadań lub potoków deklaratywnych platformy Spark w usłudze Lakeflow.
• ai_parse_document koszty są zapisane jako część AI_FUNCTIONS produktu. Zobacz Wyświetlanie kosztów przebiegówai_parse_document, aby zapoznać się z przykładowym zapytaniem.

Bezpieczeństwo danych

Dane dokumentu są przetwarzane w ramach strefy bezpieczeństwa Databricks. Usługa Databricks nie przechowuje parametrów przekazywanych do ai_parse_document function wywołań, ale zachowuje szczegóły uruchamiania metadanych, takie jak używana wersja środowiska Databricks Runtime.

Obsługiwane formaty plików wejściowych

Pliki danych wejściowych muszą być przechowywane jako dane blob w formie bajtów, co oznacza kolumnę typu binarnego w DataFrame lub Delta table. Jeśli dokumenty źródłowe są przechowywane w woluminie Unity Catalog, kolumna binarna może być generowana przy użyciu czytnika formatu Spark binaryFile.

Obsługiwane są następujące formaty plików:

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

Syntax

ai_parse_document(content)

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

Arguments

• content BINARY: wyrażenie reprezentujące dane tablicy bajtów wejściowych.
• version: wersja schematu wyjściowego obsługiwana: "2.0".
• 'imageOutputPath': opcjonalne. Zapisz renderowane obrazy stron w woluminie Unity Catalog na potrzeby referencji lub zastosowań w wielomodalnych aplikacjach RAG.
• 'descriptionElementTypes': opisy generowane przez sztuczną inteligencję. Tylko opisy dla figures są obsługiwane w wersji 2.0, więc '*' i 'figure' generują to samo zachowanie.
  • "" (pusty ciąg): nie są generowane opisy. Zmniejsza to zapotrzebowanie na zasoby obliczeniowe i koszty dokumentów z dużą liczbą liczb.
  • 'figure': Generuj tylko opisy dla rysunków. Obsługuje tylko opisy generowane przez sztuczną inteligencję.
  • '*' (ustawienie domyślne): Generuj opisy dla wszystkich obsługiwanych typów elementów.

Returns

Funkcja ai_parse_document wyodrębnia metadane układu kontekstowego z dokumentu, takie jak page_number, header, footer. Wyodrębnia również zawartość dokumentu, taką jak akapity tekstowe. W przypadku wersji 2.0 tabele są reprezentowane w kodzie HTML. Wyjściowe dane są typu VARIANT.

Poniżej przedstawiono schemat danych wyjściowych:

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

Migrowanie obciążeń do zaktualizowanego schematu

W krokach w tej sekcji opisano sposób migrowania obciążeń utworzonych przed 22 września 2025 r. w celu użycia zaktualizowanego schematu wyjściowego.

1. W żądaniu SQL określ określoną wersję schematu przy użyciu parametru version .

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

1. Zmodyfikuj kod, aby odczytywał zawartość z tablicy elements zamiast z tablicy pages.
2. Ponownie oceń metadane. Jeśli na przykład używasz page metadanych, takich jak nagłówki i stopki, musisz opracować alternatywne podejście do wyodrębniania tych informacji z elementu elements.
3. Przed migracją pełnego obciążenia zweryfikuj zaktualizowaną logikę przy użyciu przykładowych dokumentów.
4. Rozważ włączenie opisów rysunków lub trwałości obrazu, jeśli są one istotne dla twojego przypadku użycia.
5. Sprawdź uprawnienia. Jeśli na przykład planujesz używać utrwalania obrazu, upewnij się, że masz odpowiednie uprawnienia skonfigurowane dla docelowego woluminu Unity Catalog.

Examples

Ta sekcja zawiera przykłady użycia elementu ai_parse_document.

W przypadku scenariuszy przetwarzania przyrostowego przy użyciu programu ai_parse_documentzobacz ten przykład pakietów zasobów usługi Databricks

W poniższym przykładzie użyto ai_parse_document metody wyodrębniania elementów tekstowych i łączenia całej zawartości tekstowej. Z tego miejsca korzysta ai_query z modelu Claude Sonnet 4, aby wyodrębnić określone informacje ustrukturyzowane, takie jak nazwa dostawcy, data, numer faktury i zakupione elementy.

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;

W poniższym przykładzie ai_parse_document jest używane do wyodrębniania układów dokumentów, generując dane wyjściowe VARIANT dla pojedynczego pliku i szczegółowo to określa.

• Gdzie zapisać renderowane obrazy.
• Przypina wersję schematu wyjściowego.
• Umożliwia tworzenie opisów generowanych przez sztuczną inteligencję dla liczb.

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

W poniższym przykładzie użyto ai_parse_document do wyodrębniania układów dokumentów jako VARIANT wyników dla plików w woluminie Unity Catalog.

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)

W poniższym przykładzie użyto ai_parse_document do oddzielenia każdego pola najwyższego poziomu wyjścia. Na przykład, document.pages, document.elements, error_status i metadata do osobnych kolumn.

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)

Notatnik interfejsu debugowania

Poniższy notatnik zawiera wizualny interfejs debugowania do analizy danych wyjściowych funkcji ai_parse_document. Renderuje przeanalizowane dokumenty z interaktywnymi nakładkami na ramki ograniczające, co umożliwia sprawdzenie zawartości wyodrębnionej z każdej części dokumentów.

Notatnik interfejsu debugowania

Pobierz laptopa

Ograniczenia

• Chociaż usługa Databricks stale pracuje nad ulepszeniem wszystkich swoich funkcji, LLM-y są rozwijającą się technologią i mogą powodować błędy.
• Funkcja ai_parse_document może zająć trochę czasu na wyodrębnienie zawartości dokumentu przy zachowaniu informacji strukturalnych, zwłaszcza w przypadku dokumentów zawierających wysoce gęstą zawartość lub zawartość o niskiej rozdzielczości. W niektórych przypadkach uruchomienie funkcji może zająć trochę czasu lub może ona zignorować zawartość. Usługa Databricks stale pracuje nad zwiększeniem opóźnienia.
• Zobacz Obsługiwane formaty plików wejściowych. Usługa Databricks z zadowoleniem przyjmuje opinie na temat tego, które dodatkowe formaty są najważniejsze dla Twojej organizacji.
• Dostosowywanie modelu obsługującego ai_parse_document lub używającego modelu ai_parse_document dostarczonego przez klienta nie jest obsługiwane.
• Model bazowy może nie działać optymalnie podczas obsługi obrazów przy użyciu tekstu alfabetów innych niż łacińskie, takich jak japoński lub koreański.
• Dokumenty z podpisami cyfrowymi mogą nie być przetwarzane dokładnie.