ai_parse_document Função

Aplica-se a: Databricks SQL Databricks Runtime

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

Requirements

• Um espaço de trabalho em uma região dos EUA que suporta funções de IA otimizadas para inferência em lote.
  • Se o seu espaço de trabalho não estiver nos EUA, mas estiver em uma região que ofereça suporte a funções de IA otimizadas para inferência em lote, o roteamento entre geografias deverá ser habilitado em seu espaço de trabalho.
  • Para clientes nessas regiões, a ai_parse_document função também está disponível para espaços de trabalho com o complemento Segurança Reforçada e Conformidade, mas os administradores de espaço de trabalho devem habilitá-la no portal de Visualizações.
• Databricks Runtime 17.1 ou superior.
• Se você estiver usando computação sem servidor, o seguinte também é 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 recursos e limitações adicionais sem servidor, consulte Limitações de computação sem servidor.
• A função ai_parse_document está disponível através de notebooks do Databricks, do editor SQL, dos fluxos de trabalho do Databricks, dos trabalhos ou dos Pipelines Declarativos do Lakeflow Spark.
• ai_parse_document os custos são registados como parte do AI_FUNCTIONS produto. Consulte Ver custos para execuções ai_parse_document como exemplo de consulta.

Segurança de dados

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

Formatos de ficheiro de entrada suportados

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

Os seguintes formatos de ficheiro são suportados:

• 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. Salve imagens de página renderizadas em um volume do Catálogo Unity para referência ou aplicações RAG multimodais.
• 'descriptionElementTypes': descrições geradas por IA. Somente descrições para figures são suportadas para a versão 2.0, portanto '*' , e 'figure' produzem o mesmo comportamento.
  • '' (string 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 apenas para figuras. Suporta apenas descrições geradas por IA.
  • '*' (padrão): gera descrições para todos os tipos de elementos suportados.

Returns

A ai_parse_document função extrai os metadados de layout contextual do documento, como page_number, header, footer. 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.

O seguinte é 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 esquema atualizado

As etapas nesta seção descrevem como migrar cargas de trabalho 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 específica do esquema 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 o código para ler o conteúdo da matriz elements em vez do conteúdo da matriz pages.
2. Reavalie os metadados. Por exemplo, se você estiver 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 toda a carga de trabalho.
4. Considere ativar descrições de figuras ou persistência de imagens se elas forem relevantes para o 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 do Catálogo Unity de destino.

Examples

Esta seção fornece exemplos de uso do ai_parse_document.

Para cenários de processamento incremental, usando ai_parse_document, consulte este exemplo de Databricks Asset Bundles

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 ai_parse_document para extrair layouts de documento como saída VARIANT para um único arquivo e especifica,

• Onde salvar imagens renderizadas.
• Define uma versão de um esquema de saída.
• Permite 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 saída VARIANT para arquivos em um volume do 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)

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, error_status, e metadata 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)

Bloco de anotações de interface de depuração

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

Bloco de anotações de interface de depuração

Obter caderno

Limitações

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