Функция ai_parse_document

Область применения: Databricks SQL Databricks Runtime

Функция ai_parse_document() использует методы анализа структурированного содержимого из неструктурированных документов, управляемые Databricks.

Визуальный пользовательский интерфейс для проверки и итерации результатов ai_extractсм. в разделе "Анализ документов".

Требования

Модель, работающая с этой функцией, становится доступной с помощью API модели обслуживания модели. Сведения о моделях, доступных в Databricks, и лицензиях и политиках, которые управляют использованием этих моделей, см. в применимых условиях модели.

Если модели появляются в будущем, которые лучше работают в соответствии с внутренними тестами Databricks, Databricks может изменить модели и обновить документацию.

• Эта функция доступна только в некоторых регионах, см. сведения о доступности функций ИИ.
  • Эта ai_parse_document функция также доступна для рабочих областей с надстройкой повышенной безопасности и соответствия требованиям, но администраторы рабочих областей должны включить ее на портале предварительной версии.
• Databricks Runtime 17.1 или более поздней версии.
• При использовании бессерверных вычислений также требуется следующее:
  • Версия бессерверной среды должна иметь значение 3 или более поздней, так как это обеспечивает такие функции, как VARIANT.
  • Необходимо использовать Python или SQL. Дополнительные бессерверные функции и ограничения см. в разделе об ограничениях бессерверных вычислений.
• Эта ai_parse_document функция доступна с помощью записных книжек Databricks, редактора SQL, рабочих процессов Databricks, заданий или декларативных конвейеров Lakeflow Spark.
• ai_parse_document затраты записываются как часть AI_FUNCTIONS продукта. Пример запроса см. в разделе "Просмотр затрат на ai_parse_document запуски ".

Безопасность данных

Данные документа обрабатываются в периметре безопасности Databricks. Databricks не сохраняет параметры, передаваемые в ai_parse_document function вызовы, но сохраняет сведения о выполнении метаданных, например используемую версию databricks Runtime.

Поддерживаемые форматы входных файлов

Входные файлы данных должны храниться в виде BLOB-данных в виде байт, то есть в столбце двоичного типа таблицы DataFrame или Delta. Если исходные документы хранятся в томе каталога Unity, столбец двоичного типа можно создать с помощью средства чтения формата Spark binaryFile .

Поддерживаются следующие форматы файлов:

• Формат pdf
• JPG / JPEG
• PNG
• DOC/DOCX
• PPT/PPTX

Синтаксис

ai_parse_document(content)

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

Аргументы

• content BINARY: выражение, представляющее входные данные массива байтов.
• version: версия выходной схемы, поддерживаемая: "2.0".
• 'imageOutputPath': необязательный параметр. Сохраните сгенерированные изображения страниц в томе Unity Catalog для справочных или мультимодальных приложений RAG.
• 'descriptionElementTypes': описания, созданные ИИ. Для версии 2.0 поддерживаются только описания figures , поэтому '*' и 'figure' создают такое же поведение.
  • '' (пустая строка): описания не создаются. Это сокращает необходимые вычислительные ресурсы и затраты на документы с большим количеством цифр.
  • 'figure': создайте описания только для фигур. Поддерживает только созданные ИИ описания.
  • '*' (по умолчанию): создание описаний для всех поддерживаемых типов элементов.

Возвраты

Функция ai_parse_document извлекает метаданные контекстного макета из документа, например page_number, header. footer Он также извлекает содержимое документа, например текстовые абзацы. Для версии 2.0 таблицы представлены в HTML. Выходные данные являются типом VARIANT .

Основные сведения о элементах

Элемент представляет собой дискретную единицу содержимого, определяемого в проанализированном документе. При ai_parse_document обработке документа документ разбивается на последовательность элементов, где каждый элемент представляет отдельный блок содержимого, например текстовый абзац, таблицу, фигуру или маркер макета, например верхний или нижний колонтитул страницы.

Каждый элемент в выходном elements массиве содержит следующие поля:

• id: 0-й индекс, указывающий положение элемента в документе.
• type: строка, указывающая тип содержимого, которое представляет элемент. Поддерживаемые типы элементов:
  • text: текстовый абзац или общий текст текста.
  • table: таблица с содержимым, представленным в формате HTML.
  • figure: изображение или схема в документе.
  • title: название документа.
  • caption: подпись, связанная с фигурой или таблицей.
  • section_header: заголовок или подзаголовок, обозначающий начало раздела.
  • page_header: заголовок, который отображается в верхней части страницы.
  • page_footer: нижний колонтитул, который отображается в нижней части страницы.
  • page_number: маркер номера страницы.
  • footnote: ссылка на сноску или текст.
• content: извлеченное текстовое содержимое элемента. Для table элементов содержимое форматируется как HTML. Для figure элементов может быть NULLсодержимое.
• bbox: массив координат ограничивающего прямоугольника, указывающий физическое расположение элемента на странице. Каждое ограничивающее поле включает координаты пикселей и ссылку page_id .
• description: описание текста, созданного СИ. В версии 2.0 описания создаются только для figure элементов, если descriptionElementTypes этот параметр включен.

Ниже приведена схема выходных данных:

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

Перенос рабочих нагрузок в обновленную схему

В этом разделе описано, как перенести рабочие нагрузки, созданные до 22 сентября 2025 г. для использования обновленной выходной схемы.

1. В запросе SQL укажите определенную версию схемы с помощью version параметра.

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

1. Измените код, чтобы считывать содержимое elements из массива вместо массива pages .
2. Переоценка метаданных. Например, если вы использовали page метаданные, такие как верхние и нижние колонтитулы, необходимо разработать альтернативный подход для извлечения этой информации из.elements
3. Проверьте обновленную логику с помощью примеров документов перед переносом всей рабочей нагрузки.
4. Рекомендуется включить описания рисунков или сохраняемость изображений, если они относятся к вашему варианту использования.
5. проверка разрешений; Например, если вы планируете использовать сохраняемость изображений, убедитесь, что у вас есть правильные разрешения, настроенные для целевого тома каталога Unity.

Примеры

В этом разделе приведены примеры использования ai_parse_document.

Сценарии добавочной обработки с использованием ai_parse_documentсм. в этом примере декларативных пакетов автоматизации

В следующем примере используется ai_parse_document для извлечения текстовых элементов и объединения всего текстового содержимого. С этого момента используется ai_query с моделью Claude Sonnet 4 для извлечения определенных структурированных сведений, таких как название поставщика, дата, номер счета и приобретенные товары.

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;

В следующем примере используется ai_parse_document для извлечения макетов документов в качестве VARIANT выходных данных для одного файла и спецификации.

• Где сохранить отрисованные изображения.
• Закрепляет выходную версию схемы.
• Включает ИИ-генерируемые описания для рисунков.

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

В следующем примере используется ai_parse_document для извлечения макетов документов в качестве VARIANT выходных данных для файлов в томе каталога 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)

В следующем примере используется ai_parse_document с Lakeflow Connect для SharePoint для анализа документов непосредственно из библиотеки документов SharePoint.

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;

Использование to_json() с PySpark collect()

ai_parse_document возвращает тип, который не может быть напрямую VARIANT собран PySpark (или другими API, которые не поддерживают VARIANT). Чтобы собрать проанализированные результаты в Python для дальнейшей обработки, используйте to_json() в SQL, чтобы преобразовать VARIANT в строку JSON, а затем проанализировать его с помощью json.loads() в 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.

В следующем примере используется ai_parse_document для разделения каждого поля верхнего уровня выходных данных. Например, , document.pagesи document.elementserror_statusmetadata в отдельные столбцы.

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)

Записная книжка интерфейса отладки

В следующей записной книжке представлена визуальная отладочная среда для анализа вывода функции ai_parse_document. Он отображает распарсенные документы с интерактивными рамками, что позволяет проверить, какое содержимое было извлечено из каждой части ваших документов.

Записная книжка интерфейса отладки

Получите ноутбук

Ограничения

• В то время как Databricks постоянно работает над улучшением всех его возможностей, LLM являются новыми технологиями и могут привести к ошибкам.
• Функция ai_parse_document может занять некоторое время для извлечения содержимого документа при сохранении структурных сведений, особенно для документов, содержащих очень плотное содержимое или содержимое с низким разрешением. В некоторых случаях для выполнения функции может потребоваться некоторое время, или она может игнорировать содержимое. Databricks постоянно работает над улучшением задержки.
• См. поддерживаемые форматы входных файлов. Databricks приветствует отзывы о том, какие дополнительные форматы наиболее важны для вашей организации.
• Настройка модели, которая используется в ai_parse_document, или использование модели, предоставленной клиентом для ai_parse_document, не поддерживается.
• Базовая модель может не работать оптимально при работе с изображениями с текстом из не латинских алфавитов, таких как японский или корейский.
• Документы с цифровыми подписями могут не обрабатываться точно.

Связанные функции

• ai_prep_search функция
• ai_extract функция
• ai_classify функция