다음을 통해 공유

ai_parse_document 함수

적용 대상:확인 표시 '예' Databricks SQL 확인 표시 '예' Databricks Runtime

Important

이 기능은 공개 미리 보기 및 HIPAA 규격에 있습니다.

미리 보기 중:

  • 기본 언어 모델은 여러 언어를 처리할 수 있지만 이 AI 함수는 영어로 조정됩니다.
  • AI Functions의 지역 가용성에 대한 지역별로 제한된 기능을 참조하세요.

이 함수는 ai_parse_document()Databricks Foundation 모델 API 에서 최첨단 생성 AI 모델을 호출하여 구조화되지 않은 문서에서 구조화된 콘텐츠를 추출합니다.

Requirements

Important

이 함수를 구동하는 모델은 Mosaic AI Model Serving Foundation Model API를 사용하여 사용할 수 있습니다. Databricks에서 사용할 수 있는 모델 및 해당 모델의 사용을 제어하는 라이선스 및 정책에 대한 자세한 내용은 해당 모델 개발자 라이선스 및 약관 을 참조하세요.

Databricks의 내부 벤치마크에 따라 더 나은 성능을 제공하는 모델이 미래에 등장할 경우 Databricks는 모델을 변경하고 설명서를 업데이트할 수 있습니다.

데이터 보안

문서 데이터는 Databricks 보안 경계 내에서 처리됩니다. Databricks는 호출에 전달되는 매개 변수를 ai_parse_document function 저장하지 않지만 사용된 Databricks 런타임 버전과 같은 메타데이터 실행 세부 정보를 유지합니다.

지원되는 입력 파일 형식

입력 데이터 파일은 Blob 데이터(바이트)로 저장되어야 합니다. 즉, DataFrame 또는 Delta 테이블의 이진 형식 열을 의미합니다. 원본 문서가 Unity 카탈로그 볼륨에 저장되는 경우 Spark binaryFile 형식 판독기를 사용하여 이진 형식 열을 생성할 수 있습니다.

지원되는 파일 형식은 다음과 같습니다.

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

Syntax

ai_parse_document(content)

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

Arguments

  • content BINARY: 입력 바이트 배열 데이터를 나타내는 식입니다.
  • version: 지원되는 출력 스키마의 버전: "2.0".
  • 'imageOutputPath': 선택 사항입니다. 렌더링된 페이지 이미지를 참조 또는 다중 모달 RAG 애플리케이션을 위해 Unity 카탈로그 볼륨에 저장합니다.
  • 'descriptionElementTypes': AI에서 생성된 설명입니다. 버전 2.0에 대한 figures 설명만 지원되므로 '*''figure' 동일한 동작을 생성합니다.
    • ''(빈 문자열): 설명이 생성되지 않습니다. 이렇게 하면 수치가 많은 문서에 필요한 컴퓨팅 및 비용이 줄어듭니다.
    • 'figure': 그림에 대한 설명만 생성합니다. AI 생성 설명만 지원합니다.
    • '*' (기본값): 지원되는 모든 요소 형식에 대한 설명을 생성합니다.

Returns

이 함수는 ai_parse_document 문서에서 page_number, header, footer와 같은 상황별 레이아웃 메타데이터를 추출합니다. 또한 텍스트 단락과 같은 문서의 내용을 추출합니다. 버전 2.0의 경우 테이블은 HTML로 표시됩니다. 출력은 VARIANT 유형의 형식입니다.

Important

함수 출력 스키마는 major.minor 형식을 사용하여 버전이 지정됩니다. Databricks는 진행 중인 연구에 따라 향상된 표현을 반영하도록 지원되거나 기본 버전을 업그레이드할 수 있습니다.

  • 부 버전 업그레이드는 이전 버전과 호환되며 새 필드만 도입할 수 있습니다.
  • 주 버전 업그레이드에는 필드 추가, 제거 또는 이름 바꾸기와 같은 주요 변경 내용이 포함될 수 있습니다.

다음은 출력 스키마입니다.

비고

2025년 9월 22일 현재 출력 스키마는 버전 "2.0"에 있으며 다음을 포함하도록 업데이트되었습니다.

  • descriptions AI에서 생성된 그림 설명의 경우
  • bbox는 경계 상자 좌표에 사용됩니다.

업데이트된 스키마를 사용하도록 기존 워크로드를 마이그레이션하려면 워크로드를 업데이트된 스키마로 마이그레이션을 참조하세요.

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

워크로드를 업데이트된 스키마로 마이그레이션

이 섹션의 단계에서는 업데이트된 출력 스키마를 사용하기 위해 2025년 9월 22일 이전에 생성된 워크로드를 마이그레이션하는 방법을 설명합니다.

  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 카탈로그 볼륨에 대해 올바른 권한이 설정되어 있는지 확인합니다.

Examples

이 섹션에서는 .를 사용하는 ai_parse_document예제를 제공합니다.

증분 처리 시나리오에 대해 ai_parse_document를 사용하는 경우 Databricks 자산 번들 예제를 참조하세요.

다음 예제에서는 ai_parse_document 텍스트 요소를 추출하고 모든 텍스트 콘텐츠를 연결합니다. 여기에서 Claude Sonnet 4 모델과 함께 사용하여 ai_query 공급업체 이름, 날짜, 송장 번호 및 구매한 항목과 같은 특정 구조화된 정보를 추출합니다.

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;

다음 예제에서는 ai_parse_document 문서 레이아웃을 단일 파일에 대한 출력으로 VARIANT 추출하고

  • 렌더링된 이미지를 저장할 위치입니다.
  • 출력 스키마 버전을 고정합니다.
  • 그림에 대해 AI 생성 설명을 사용하도록 설정합니다.
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');

다음 예제에서는 Unity 카탈로그 볼륨의 파일에 대한 출력으로 ai_parse_document 문서 레이아웃을 추출하는 데 사용합니다VARIANT.

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 . 예를 들어 document.pages, , document.elementserror_status및 metadata 개별 열로 입력합니다.

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 사용하는 것은 지원되지 않습니다.
  • 기본 모델은 일본어 또는 한국어와 같은 라틴어 이외의 알파벳 텍스트를 사용하여 이미지를 처리할 때 최적으로 수행되지 않을 수 있습니다.
  • 디지털 서명이 있는 문서는 정확하게 처리되지 않을 수 있습니다.
  • Last updated on