Compartir vía

ai_parse_document Función

Se aplica a:casilla marcada como Sí Databricks SQL casilla marcada como Sí Databricks Runtime

Importante

Esta funcionalidad está en versión preliminar pública y compatible con HIPAA.

Durante la versión preliminar:

La ai_parse_document() función aprovecha técnicas de investigación administradas por Databricks de última generación para analizar el contenido estructurado de documentos no estructurados.

Para que una interfaz de usuario visual valide e itera en los resultados de ai_extract, vea Análisis de documentos.

Requisitos

El modelo que alimenta esta función está disponible mediante las API de modelo de Model Serving Foundation. Consulte Términos aplicables para desarrolladores de modelos para obtener información sobre qué modelos están disponibles en Databricks y las licencias y directivas que rigen el uso de esos modelos.

Si los modelos surgen en el futuro que funcionan mejor según las pruebas comparativas internas de Databricks, Databricks puede cambiar los modelos y actualizar la documentación.

Seguridad de datos

Los datos del documento se procesan dentro del perímetro de seguridad de Databricks. Databricks no almacena los parámetros que se pasan a las ai_parse_document function llamadas, pero conserva los detalles de ejecución de metadatos, como la versión de Databricks Runtime usada.

Formatos de archivo de entrada admitidos

Los archivos de datos de entrada deben almacenarse como datos de blob en bytes, lo que significa una columna de tipo binario en una tabla dataframe o delta. Si los documentos de origen se almacenan en un volumen de catálogo de Unity, la columna de tipo binario se puede generar mediante el lector de formato Spark binaryFile .

Se admiten los siguientes formatos de archivo:

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

Sintaxis

ai_parse_document(content)

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

Argumentos

  • content BINARY: expresión que representa los datos de la matriz de bytes de entrada.
  • version: la versión del esquema de salida, compatible: "2.0".
  • 'imageOutputPath': opcional. Guarde las imágenes de página renderizadas en un volumen de Catálogo de Unity para las aplicaciones RAG de referencia o multimodal.
  • 'descriptionElementTypes': descripciones generadas por IA. Solo se admiten descripciones para figures la versión 2.0, por lo que '*' y 'figure' producen el mismo comportamiento.
    • '' (cadena vacía): no se generan descripciones. Esto reduce el proceso necesario y los costos de los documentos con una gran cantidad de cifras.
    • 'figure': Generar descripciones solo para figuras. Solo admite descripciones generadas por IA.
    • '*' (valor predeterminado): genere descripciones para todos los tipos de elementos admitidos.

Devoluciones

La ai_parse_document función extrae los metadatos de diseño contextual del documento, como page_number, header, footer. También extrae el contenido del documento, como párrafos de texto. Para la versión 2.0, las tablas se representan en HTML. La salida es de tipo VARIANT.

Descripción de los elementos

Un elemento es una unidad discreta de contenido identificado dentro de un documento analizado. Cuando ai_parse_document procesa un documento, divide el documento en una secuencia de elementos, donde cada elemento representa un bloque de contenido distinto, como un párrafo de texto, una tabla, una figura o un marcador de diseño, como un encabezado de página o pie de página.

Cada elemento de la matriz de salida elements incluye los siguientes campos:

  • id: índice basado en 0 que indica la posición del elemento dentro del documento.
  • type: cadena que indica el tipo de contenido que representa el elemento. Los tipos de elementos admitidos son:
    • text: un párrafo de texto o texto de cuerpo general.
    • table: una tabla, con contenido representado en formato HTML.
    • figure: imagen o diagrama dentro del documento.
    • title: título del documento.
    • caption: un título asociado a una figura o tabla.
    • section_header: encabezado o subpartida que denota el inicio de una sección.
    • page_header: encabezado que aparece en la parte superior de una página.
    • page_footer: pie de página que aparece en la parte inferior de una página.
    • page_number: marcador de número de página.
    • footnote: referencia al pie o texto.
  • content: contenido de texto extraído del elemento. En table el caso de los elementos, el contenido tiene el formato HTML. En el caso figure de los elementos, el contenido puede ser NULL.
  • bbox: matriz de coordenadas de rectángulo delimitador que indica la ubicación física del elemento en la página. Cada rectángulo de selección incluye coordenadas de píxeles y una page_id referencia.
  • description: una descripción de texto generada por IA. En la versión 2.0, las descripciones solo se generan para figure los elementos cuando la descriptionElementTypes opción está habilitada.

Importante

El esquema de salida de la función se versiona mediante un formato major.minor. Databricks puede actualizar la versión admitida o predeterminada para reflejar representaciones mejoradas basadas en investigaciones continuas.

  • Las actualizaciones de versiones secundarias son compatibles con versiones anteriores y solo pueden introducir nuevos campos.
  • Las actualizaciones de versiones principales pueden incluir cambios importantes, como adiciones de campos, eliminaciones o cambios de nombre.

A continuación se muestra el esquema de salida:

Nota:

A partir del 22 de septiembre de 2025, el esquema de salida está en la versión "2.0" y se ha actualizado para incluir:

  • descriptions para descripciones de ilustración generadas por IA.
  • bbox para coordenadas de rectángulo delimitador.

Para migrar las cargas de trabajo existentes para usar el esquema actualizado, consulte Migración de cargas de trabajo al esquema actualizado.

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

Migración de cargas de trabajo al esquema actualizado

Los pasos de esta sección describen cómo migrar las cargas de trabajo creadas antes del 22 de septiembre de 2025 para usar el esquema de salida actualizado.

  1. En la solicitud SQL, especifique una versión de esquema específica mediante el version parámetro .
SELECT
ai_parse_document(
  content,
  map('version', '2.0')
) AS parsed
FROM READ_FILES('/path/to/documents', format => 'binaryFile');
  1. Modifique el código para leer contenido de la elements matriz en lugar de la pages matriz.
  2. Vuelva a evaluar los metadatos. Por ejemplo, si usaba page metadatos como encabezados y pies de página, debe desarrollar un enfoque alternativo para extraer esta información de elements.
  3. Valide la lógica actualizada con documentos de ejemplo antes de migrar la carga de trabajo completa.
  4. Considere la posibilidad de habilitar descripciones de figura o persistencia de imágenes si son relevantes para su caso de uso.
  5. Compruebe los permisos. Por ejemplo, si planea usar la persistencia de imágenes, asegúrese de que tiene los permisos correctos configurados para el volumen de catálogo de Unity de destino.

Ejemplos

En esta sección se proporcionan ejemplos de uso de ai_parse_document.

Para escenarios de procesamiento incremental mediante ai_parse_document, consulte este ejemplo de agrupaciones de automatización declarativa.

En el ejemplo siguiente se usa ai_parse_document para extraer elementos de texto y concatenar todo el contenido de texto. Desde allí se usa ai_query con el modelo Claude Sonnet 4 para extraer información estructurada específica, como el nombre del proveedor, la fecha, el número de factura y los artículos comprados.

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;

En el ejemplo siguiente se usa ai_parse_document para extraer diseños de documento como VARIANT salida para un único archivo y se especifica,

  • Dónde guardar las imágenes representadas.
  • Ancla una versión de esquema de salida.
  • Habilita las descripciones generadas por IA para las 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');

En el ejemplo siguiente se usa ai_parse_document para extraer los diseños de documentos como salida VARIANT para los archivos en un volumen de Unity Catalog.

SQL

SELECT
  path,
  ai_parse_document(content)
FROM READ_FILES('/Volumes/path/to/your/directory', format => 'binaryFile');

Pitón

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)

En el ejemplo siguiente se usa ai_parse_document con Lakeflow Connect para SharePoint para analizar documentos directamente desde una biblioteca de documentos de SharePoint.

Importante

Lakeflow Connect para SharePoint está en Beta.

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;

Uso de to_json() con PySpark collect()

ai_parse_document devuelve un VARIANT tipo, que pySpark no puede recopilar directamente (u otras API que no admiten VARIANT). Para recopilar resultados analizados en Python para su posterior procesamiento, use to_json() en SQL para convertir VARIANT en una cadena JSON y, a continuación, analizarlos con json.loads() en 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.

En el ejemplo siguiente se usa ai_parse_document para separar cada campo de nivel superior de la salida. Por ejemplo, document.pages, document.elements, error_statusy metadata en columnas individuales.

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;

Pitón

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)

Cuaderno de depuración de interfaz

El siguiente cuaderno proporciona una interfaz de depuración visual para analizar la salida de la función ai_parse_document. Representa documentos analizados con superposiciones interactivas de cuadros de límite, lo que le permite inspeccionar qué contenido se extrajo de cada región de los documentos.

Cuaderno de depuración de interfaz

Obtener el cuaderno

Limitaciones

  • Aunque Databricks trabaja continuamente para mejorar todas sus funcionalidades, los grandes modelos de lenguaje son una tecnología emergente y pueden producir errores.
  • La ai_parse_document función puede tardar tiempo en extraer el contenido del documento al tiempo que conserva la información estructural, especialmente para los documentos que contienen contenido altamente denso o contenido con una resolución deficiente. En algunos casos, la función puede tardar un tiempo en ejecutarse o omitir el contenido. Databricks está trabajando continuamente para mejorar la latencia.
  • Consulte Formatos de archivo de entrada admitidos. Databricks da la bienvenida a los comentarios sobre qué formatos adicionales son más importantes para su organización.
  • No se admite ni la personalización del modelo que impulsa ai_parse_document ni utilizar un modelo proporcionado por el cliente para ai_parse_document.
  • Es posible que el modelo subyacente no funcione de forma óptima al controlar imágenes mediante texto de alfabetos no latinos, como japonés o coreano.
  • Es posible que los documentos con firmas digitales no se procesen con precisión.
  • Last updated on