fungsi ai_parse_document

Berlaku untuk:Ditandai centang ya Databricks SQL Ditandai centang ya Databricks Runtime

Fungsi ini ai_parse_document() memanfaatkan teknik penelitian terkelola Databricks canggih untuk mengurai konten terstruktur dari dokumen yang tidak terstruktur.

Agar UI visual memvalidasi dan melakukan iterasi pada hasil , lihat ai_parse_document Dokumen.

Requirements

Model yang mendukung fungsi ini tersedia menggunakan MODEL Model Serving Foundation API. Lihat Ketentuan model yang berlaku untuk informasi tentang model mana yang tersedia di Databricks serta lisensi dan kebijakan yang mengatur penggunaan model tersebut.

Jika model muncul di masa depan yang berkinerja lebih baik sesuai dengan tolok ukur internal Databricks, Databricks dapat mengubah model dan memperbarui dokumentasi.

  • Fungsi ini hanya tersedia di beberapa wilayah, lihat Ketersediaan fungsi AI.
  • Databricks Runtime 17.3 atau lebih tinggi.
  • Jika Anda menggunakan komputasi tanpa server, berikut ini juga diperlukan:
    • Versi lingkungan tanpa server harus diatur ke 3 atau lebih tinggi, karena ini memungkinkan fitur seperti VARIANT.
    • Harus menggunakan Python atau SQL. Untuk fitur dan batasan tanpa server tambahan, lihat Batasan komputasi tanpa server.
  • Fungsi ai_parse_document ini tersedia menggunakan notebook Databricks, editor SQL, alur kerja Databricks, pekerjaan, atau Lakeflow Spark Declarative Pipelines.
  • ai_parse_document biaya dicatat sebagai bagian produk AI_FUNCTIONS. Lihat Menampilkan biaya untuk ai_parse_document eksekusi untuk contoh kueri.

Keamanan data

Data dokumen Anda diproses dalam perimeter keamanan Databricks. Databricks tidak menyimpan parameter yang diteruskan ke dalam ai_parse_document function panggilan, tetapi mempertahankan detail eksekusi metadata, seperti versi Runtime Databricks yang digunakan.

Format file input yang didukung

File data input Anda harus disimpan sebagai data blob dalam byte, yang berarti kolom jenis biner dalam tabel DataFrame atau Delta. Jika dokumen sumber disimpan dalam volume Katalog Unity, kolom jenis biner dapat dihasilkan menggunakan pembaca format Spark binaryFile .

Format file berikut didukung:

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

Syntax

ai_parse_document(content)

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

Arguments

content adalah satu-satunya argumen yang diperlukan. Semua opsi yang map diteruskan dalam argumen (version, , imageOutputPathdescriptionElementTypes, dan pageRange) bersifat opsional.

  • content: Sebuah pernyataan BINARY yang mewakili data array byte input.
  • version: Versi skema output, didukung: "2.0".
  • 'imageOutputPath': Simpan gambar halaman yang dirender ke volume Katalog Unity untuk aplikasi RAG referensi atau multi-modal.
  • 'descriptionElementTypes': Deskripsi yang dihasilkan AI. Hanya deskripsi untuk figures yang didukung untuk versi 2.0, jadi '*' dan 'figure' menghasilkan perilaku yang sama.
    • '' (string kosong): Tidak ada deskripsi yang dihasilkan. Ini mengurangi komputasi yang diperlukan dan biaya untuk dokumen dengan banyak angka.
    • 'figure': Hasilkan uraian hanya untuk figura. Hanya mendukung deskripsi yang dihasilkan AI.
    • '*' (default): Hasilkan deskripsi untuk semua jenis elemen yang didukung.
  • 'pageRange': Membatasi penguraian ke subset halaman dalam dokumen. Nomor halaman diindeks 1. Nilainya adalah daftar token yang dipisahkan koma, di mana setiap token adalah satu halaman (misalnya, "3") atau rentang inklusif (misalnya, "5-10"). Misalnya, '1,3,5-10' mengurai halaman 1, 3, dan 5 hingga 10. Halaman yang dipilih harus tetap berada dalam batas 500 halaman. Jika pageRange dihilangkan dan dokumen melebihi 500 halaman, fungsi akan langsung gagal tanpa mengurai halaman apa pun.

Returns

Fungsi ini ai_parse_document mengekstrak metadata tata letak kontekstual dari dokumen, seperti page_number, header, footer. Ini juga mengekstrak konten dokumen, seperti paragraf teks. Untuk versi 2.0, tabel diwakili dalam HTML. Outputnya berjenis VARIANT .

Memahami elemen

Elemen adalah unit konten diskrit yang diidentifikasi dalam dokumen yang diurai. Saat ai_parse_document memproses dokumen, dokumen memecah dokumen menjadi urutan elemen, di mana setiap elemen mewakili blok konten yang berbeda seperti paragraf teks, tabel, gambar, atau penanda tata letak seperti header halaman atau footer.

Setiap elemen dalam array output elements mencakup bidang berikut:

  • id: Indeks berbasis 0 yang menunjukkan posisi elemen dalam dokumen.
  • type: String yang menunjukkan jenis konten yang diwakili elemen. Jenis elemen yang didukung adalah:
    • text: Paragraf teks atau teks isi umum.
    • table: Tabel, dengan konten yang diwakili dalam format HTML.
    • figure: Gambar atau diagram dalam dokumen.
    • title: Judul dokumen.
    • caption: Keterangan yang terkait dengan gambar atau tabel.
    • section_header: Judul atau subjudul yang menunjukkan awal bagian.
    • page_header: Header yang muncul di bagian atas halaman.
    • page_footer: Footer yang muncul di bagian bawah halaman.
    • page_number: Penanda nomor halaman.
    • footnote: Referensi catatan kaki atau teks.
  • content: Konten teks yang diekstrak dari elemen . Untuk table elemen, konten diformat sebagai HTML. Untuk figure elemen, kontennya mungkin NULL.
  • confidence: Skor keyakinan yang menunjukkan seberapa andal elemen diekstrak dari dokumen.
  • bbox: Array koordinat kotak pembatas yang menunjukkan lokasi fisik elemen di halaman. Setiap kotak pembatas mencakup koordinat piksel dan page_id referensi.
  • description: Deskripsi teks yang dihasilkan AI. Di versi 2.0, deskripsi hanya dihasilkan untuk figure elemen saat descriptionElementTypes opsi diaktifkan.

Important

Skema output fungsi diberi versi menggunakan format major.minor. Databricks dapat meningkatkan versi yang didukung atau default untuk mencerminkan representasi yang ditingkatkan berdasarkan penelitian yang sedang berlangsung.

  • Peningkatan versi minor kompatibel dengan versi sebelumnya dan mungkin hanya memperkenalkan elemen baru.
  • Peningkatan versi utama mungkin mencakup perubahan yang dapat menyebabkan ketidakcocokan seperti penambahan bidang, penghapusan, atau penggantian nama.

Berikut ini adalah skema output:

Nota

Mulai 22 September 2025, skema output ada pada versi "2.0" dan telah diperbarui untuk menyertakan:

  • descriptions untuk deskripsi gambar yang dihasilkan AI.
  • bbox untuk koordinat kotak pembatas.

Untuk memigrasikan beban kerja yang ada untuk menggunakan skema yang diperbarui, lihat Memigrasikan beban kerja ke skema yang diperbarui.

{
  "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
        "confidence": DOUBLE,      // Confidence score 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
    }
  }
}

Memigrasikan beban kerja ke skema yang diperbarui

Langkah-langkah di bagian ini menjelaskan cara memigrasikan beban kerja yang dibuat sebelum 22 September 2025 untuk menggunakan skema output yang diperbarui.

  1. Dalam permintaan SQL Anda, tentukan versi skema tertentu menggunakan version parameter .
SELECT
ai_parse_document(
  content,
  map('version', '2.0')
) AS parsed
FROM READ_FILES('/path/to/documents', format => 'binaryFile');
  1. Ubah kode Anda untuk membaca konten dari elements array alih-alih pages array.
  2. Evaluasi ulang metadata. Misalnya, jika Anda menggunakan page metadata seperti header dan footer, Anda perlu mengembangkan pendekatan alternatif untuk mengekstrak informasi ini dari elements.
  3. Validasi logika yang diperbarui dengan dokumen sampel sebelum memigrasikan beban kerja penuh Anda.
  4. Pertimbangkan untuk mengaktifkan deskripsi gambar atau persistensi gambar jika relevan dengan kasus penggunaan Anda.
  5. Periksa izin. Misalnya, jika Anda berencana menggunakan ketahanan gambar, pastikan Anda telah menyiapkan izin yang benar untuk volume Katalog Unity yang menjadi target.

Examples

Bagian ini menyediakan contoh untuk menggunakan ai_parse_document.

Untuk skenario pemrosesan bertahap menggunakan ai_parse_document, lihat contoh Bundel Otomatisasi Deklaratif ini

Contoh berikut menggunakan ai_parse_document untuk mengekstrak elemen teks dan menggabungkan semua konten teks. Dari sana digunakan ai_query dengan model Claude Sonnet 4 untuk mengekstrak informasi terstruktur tertentu seperti nama vendor, tanggal, nomor faktur, dan item yang dibeli.

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;

Contoh berikut menggunakan ai_parse_document untuk mengekstrak tata letak dokumen sebagai VARIANT output untuk satu file dan menentukan,

  • Tempat menyimpan gambar yang dirender.
  • Menyematkan suatu versi skema keluaran.
  • Mengaktifkan deskripsi yang dihasilkan AI untuk gambar.
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');

Contoh berikut menggunakan pageRange untuk membatasi penguraian ke subset halaman dari file biner dalam volume Katalog Unity. Nomor halaman diindeks 1, dan Anda dapat menggabungkan satu halaman dengan rentang (misalnya, '1,3,5-10').

SELECT
  path,
  ai_parse_document(
    content,
    map('pageRange', '1-500')
  ) AS parsed_doc
FROM READ_FILES('/Volumes/catalog/schema/volume/documents/', format => 'binaryFile');

Contoh berikut menggunakan ai_parse_document untuk mengekstrak tata letak dokumen menjadi output VARIANT bagi file dalam volume Katalog 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)

Contoh berikut menggunakan ai_parse_document dengan Lakeflow Connect untuk SharePoint untuk mengurai dokumen langsung dari pustaka dokumen SharePoint.

Important

Lakeflow Connect untuk SharePoint berada di 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;

Menggunakan to_json() dengan PySpark collect()

ai_parse_document VARIANT mengembalikan jenis, yang tidak dapat dikumpulkan langsung oleh PySpark (atau API lain yang tidak mendukung VARIAN). Untuk mengumpulkan hasil yang diurai ke dalam Python untuk pemrosesan lebih lanjut, gunakan to_json() di SQL untuk mengonversi VARIAN ke string JSON, lalu uraikan dengan json.loads() di 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.

Contoh berikut menggunakan ai_parse_document untuk memisahkan setiap bidang tingkat atas output. Misalnya, document.pages, document.elements, error_status, dan metadata ke dalam kolom individual.

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)

Men-debug buku catatan antarmuka

Notebook berikut menyediakan antarmuka debugging visual untuk menganalisis output fungsi ai_parse_document. Ini merender dokumen yang sudah diparsing dengan overlay kotak pembatas interaktif, memungkinkan Anda memeriksa konten apa yang diekstrak dari setiap bagian dari dokumen Anda.

Men-debug buku catatan antarmuka

Dapatkan buku catatan

Batasan

  • Dokumen dibatasi hingga maksimum 500 halaman, melebihi batas ini menghasilkan kesalahan.
  • Ada batas ukuran file maksimum 100 MB.
  • Meskipun Databricks terus bekerja untuk meningkatkan semua fiturnya, LLM adalah teknologi yang muncul dan dapat menghasilkan kesalahan.
  • Fungsi ai_parse_document dapat memakan waktu untuk mengekstrak konten dokumen sambil mempertahankan informasi struktural, terutama untuk dokumen yang mengandung konten yang sangat padat atau konten dengan resolusi buruk. Dalam beberapa kasus, fungsi mungkin memakan waktu cukup lama untuk menjalankan atau mengabaikan konten. Databricks terus berupaya meningkatkan latensi.
  • Lihat Format file input yang didukung. Databricks menerima umpan balik tentang format tambahan mana yang paling penting bagi organisasi Anda.
  • Mengubah model yang menggerakkan ai_parse_document atau menggunakan model ai_parse_document yang disediakan oleh pelanggan tidak didukung.
  • Model yang mendasar mungkin tidak berkinerja optimal saat menangani gambar menggunakan teks alfabet non-Latin, seperti Jepang atau Korea.
  • Dokumen dengan tanda tangan digital mungkin tidak diproses secara akurat.
  • Last updated on