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 invoca un modelo de IA generativo de última generación de las API de Databricks Foundation Model para extraer contenido estructurado de documentos no estructurados.

Requisitos

Importante

El modelo que alimenta esta función está disponible mediante las API del modelo de Mosaic AI Serving Foundation. Consulte Licencias y 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.

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 Conjuntos de recursos de Databricks.

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_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;

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 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