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

• Um workspace em uma região dos EUA que oferece suporte a funções de IA otimizadas para inferência em lote.
  • Se o workspace não estiver nos EUA, mas estiver em uma região que dê suporte a funções de IA otimizadas para inferência em lotes, o roteamento entre geografias deverá ser habilitado em seu workspace.
  • Para clientes nessas regiões, a ai_parse_document função também está disponível para workspaces com o complemento Segurança e Conformidade Aprimorados, mas os administradores do workspace 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.

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)

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.