ai_parse_document Função

Aplica-se a: Databricks SQL Databricks Runtime

A ai_parse_document() função invoca um modelo de IA gerativo de última geração das APIs de Modelo do Databricks Foundation para extrair conteúdo estruturado de documentos não estruturados.

Requirements

O modelo que alimenta essa função é disponibilizado usando AS APIs de modelo do Mosaic AI Serving Foundation. Consulte os termos de desenvolvedor do modelo aplicável para obter informações sobre quais modelos estão disponíveis no Databricks e as licenças e políticas que regem o uso desses modelos.

Se surgirem modelos no futuro com melhor desempenho de acordo com os parâmetros de comparação internos do Databricks, o Databricks poderá alterar os modelos e atualizar a documentação.

• Um workspace em uma região que dá suporte a ai_parse_document nativamente ou por meio do roteamento entre geografias.
  • A ai_parse_document função também está disponível para espaços de trabalho com o complemento Segurança e Conformidade Aprimorados, mas os administradores do espaço de trabalho devem habilitá-la no portal de Visualizações.
• Databricks Runtime 17.1 ou superior.
• Se você estiver usando a computação sem servidor, o seguinte também será necessário:
  • A versão do ambiente sem servidor deve ser definida como 3 ou superior, pois isso permite recursos como VARIANT.
  • Deve usar Python ou SQL. Para obter recursos e limitações adicionais sem servidor, consulte limitações de computação sem servidor.
• A ai_parse_document função está disponível usando notebooks do Databricks, editor SQL, fluxos de trabalho do Databricks, trabalhos ou Pipelines Declarativos do Lakeflow Spark.
• ai_parse_document os custos são registrados como parte do AI_FUNCTIONS produto. Veja custos de ai_parse_document execuções para uma consulta de exemplo.

Segurança de dados

Os dados do documento são processados dentro do perímetro de segurança do Databricks. O Databricks não armazena os parâmetros passados para as ai_parse_document function chamadas, mas mantém os detalhes da execução de metadados, como a versão do Databricks Runtime usada.

Formatos de arquivo de entrada com suporte

Seus arquivos de dados de entrada devem ser armazenados como dados de blob em bytes, o que significa uma coluna de tipo binário em uma tabela DataFrame ou Delta. Se os documentos de origem forem armazenados em um volume do Catálogo do Unity, a coluna de tipo binário poderá ser gerada usando o leitor de formato Spark binaryFile .

Há suporte para os seguintes formatos de arquivo:

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

Syntax

ai_parse_document(content)

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

Arguments

• content: uma BINARY expressão que representa os dados da matriz de bytes de entrada.
• version: A versão do esquema de saída suportada: "2.0".
• 'imageOutputPath': opcional. Armazene as imagens de páginas renderizadas em um volume do Unity Catalog para aplicativos RAG de referência ou multi-modais.
• 'descriptionElementTypes': descrições geradas por IA. Apenas descrições para figures são suportadas na versão 2.0, portanto, '*' e 'figure' produzem o mesmo comportamento.
  • '' (cadeia de caracteres vazia): nenhuma descrição é gerada. Isso reduz a computação necessária e os custos para documentos com muitos números.
  • 'figure': gere descrições somente para figuras. Só dá suporte a descrições geradas por IA.
  • '*' (padrão): gere descrições para todos os tipos de elemento com suporte.

Returns

A ai_parse_document função extrai os metadados de layout contextual do documento, comopage_number, , header. footer Ele também extrai o conteúdo do documento, como parágrafos de texto. Para a versão 2.0, as tabelas são representadas em HTML. A saída é do tipo VARIANT.

Noções básicas sobre elementos

Um elemento é uma unidade discreta de conteúdo identificada em um documento analisado. Quando ai_parse_document processa um documento, ele divide o documento em uma sequência de elementos, em que cada elemento representa um bloco de conteúdo distinto, como um parágrafo de texto, uma tabela, uma figura ou um marcador de layout, como um cabeçalho de página ou rodapé.

Cada elemento na matriz de saída elements inclui os seguintes campos:

• id: um índice baseado em 0 que indica a posição do elemento dentro do documento.
• type: uma cadeia de caracteres que indica o tipo de conteúdo que o elemento representa. Os tipos de elemento com suporte são:
  • text: um parágrafo de texto ou um texto de corpo geral.
  • table: uma tabela, com conteúdo representado no formato HTML.
  • figure: uma imagem ou diagrama dentro do documento.
  • title: o título do documento.
  • caption: uma legenda associada a uma figura ou tabela.
  • section_header: um título ou subtítulo que indica o início de uma seção.
  • page_header: um cabeçalho que aparece na parte superior de uma página.
  • page_footer: um rodapé que aparece na parte inferior de uma página.
  • page_number: um marcador de número de página.
  • footnote: uma referência ou texto de nota de rodapé.
• content: o conteúdo de texto extraído do elemento. Para table elementos, o conteúdo é formatado como HTML. Para figure elementos, o conteúdo pode ser NULL.
• bbox: uma matriz de coordenadas de caixa delimitadora indicando o local físico do elemento na página. Cada caixa delimitadora inclui coordenadas de pixel e uma page_id referência.
• description: uma descrição de texto gerada por IA. Na versão 2.0, as descrições são geradas apenas para figure elementos quando a opção descriptionElementTypes está habilitada.

Veja a seguir o esquema de saída:

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

Migrar cargas de trabalho para o esquema atualizado

As etapas nesta seção descrevem como migrar cargas de trabalho que foram criadas antes de 22 de setembro de 2025 para usar o esquema de saída atualizado.

1. Em sua solicitação SQL, especifique uma versão de esquema específica usando o version parâmetro.

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

1. Modifique seu código para ler o conteúdo da matriz elements em vez da matriz pages.
2. Reavaliar metadados. Por exemplo, se você estava usando page metadados como cabeçalhos e rodapés, precisará desenvolver uma abordagem alternativa para extrair essas informações do elements.
3. Valide sua lógica atualizada com documentos de exemplo antes de migrar sua carga de trabalho completa.
4. Considere habilitar descrições de figura ou persistência de imagem se elas forem relevantes para seu caso de uso.
5. Verifique as permissões. Por exemplo, se você planeja usar a persistência de imagem, verifique se você tem as permissões corretas configuradas para o volume de catálogo do Unity de destino.

Examples

Esta seção fornece exemplos para usar ai_parse_document.

Para cenários de processamento incremental usando ai_parse_document, consulte este exemplo de Pacotes de Ativos do Databricks

O exemplo a seguir usa ai_parse_document para extrair elementos de texto e concatenar todo o conteúdo de texto. A partir daí, ele usa ai_query com o modelo Claude Sonnet 4 para extrair informações estruturadas específicas, como nome do fornecedor, data, número da fatura e itens comprados.

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;

O exemplo a seguir usa o ai_parse_document para extrair layouts de documento como saída VARIANT para um único arquivo e especifica,

• Onde salvar imagens renderizadas.
• Fixa a versão do esquema de saída.
• Habilita descrições geradas por IA para figuras.

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

O exemplo a seguir usa ai_parse_document para extrair layouts de documentos como a saída VARIANT para arquivos em um volume do Catálogo do 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)

Usando to_json() com o PySpark collect()

ai_parse_document retorna um VARIANT tipo, que não pode ser coletado diretamente pelo PySpark (ou outras APIs que não dão suporte a VARIANT). Para coletar resultados analisados no Python para processamento adicional, use to_json() no SQL para converter o VARIANT em uma cadeia de caracteres JSON e, em seguida, analise-o json.loads() no 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.

O exemplo a seguir usa ai_parse_document para separar cada campo de nível superior da saída. Por exemplo, document.pages, document.elements, e error_statusmetadata em colunas individuais.

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 de interface de debug

O notebook a seguir fornece uma interface de depuração visual para analisar a saída da função ai_parse_document. Ele renderiza documentos analisados com sobreposições interativas de caixa delimitadora, permitindo que você inspecione qual conteúdo foi extraído de cada região de seus documentos

Notebook de interface de debug

Obter laptop

Limitações

• Embora o Databricks funcione continuamente para melhorar todos os seus recursos, as LLMs são uma tecnologia emergente e podem produzir erros.
• A ai_parse_document função pode levar tempo para extrair conteúdo do documento, preservando informações estruturais, especialmente para documentos que contêm conteúdo altamente denso ou conteúdo com resolução ruim. Em alguns casos, a função pode demorar um pouco para ser executada ou ignorar o conteúdo. O Databricks está trabalhando continuamente para melhorar a latência.
• Consulte os formatos de arquivo de entrada com suporte. O Databricks recebe comentários sobre quais formatos adicionais são mais importantes para sua organização.
• Não há suporte para personalizar o modelo que alimenta ai_parse_document ou usar um modelo fornecido pelo cliente para ai_parse_document.
• O modelo subjacente pode não ter um desempenho ideal ao manipular imagens usando texto de alfabetos não latinos, como japonês ou coreano.
• Documentos com assinaturas digitais podem não ser processados com precisão.