ai_parse_document fonksiyon

Şunun için geçerlidir: Databricks SQL Databricks Runtime

İşlev, ai_parse_document() yapılandırılmış içeriği yapılandırılmamış belgelerden ayrıştırmak için en son düzey Databricks tarafından yönetilen araştırma tekniklerinden yararlanıyor.

Görsel kullanıcı arabiriminin ai_parse_documentsonuçlarını doğrulamak ve yinelemek için bkz. Belge Ayrıştırma.

Requirements

Bu işlevi güçlendiren model, Model Sunma Temeli Model API'leri kullanılarak kullanılabilir hale getirilir. Databricks'te hangi modellerin kullanılabildiği ve bu modellerin kullanımını yöneten lisanslar ve ilkeler hakkında bilgi için bkz. Geçerli model koşulları .

Gelecekte Databricks'in iç karşılaştırmalarına göre daha iyi performans gösteren modeller ortaya çıkarsa Databricks modelleri değiştirebilir ve belgeleri güncelleştirebilir.

• Bu işlev yalnızca bazı bölgelerde kullanılabilir. Bkz. Yapay zeka işlevi kullanılabilirliği.
  • İşlev ai_parse_document , Gelişmiş Güvenlik ve Uyumluluk eklentisine sahip çalışma alanları için de kullanılabilir.
• Databricks Runtime 17.3 veya üzeri.
• Sunucusuz işlem kullanıyorsanız, aşağıdakiler de gereklidir:
  • Sunucusuz ortam sürümü, gibi VARIANTözellikleri etkinleştirdiği için 3 veya üzeri olarak ayarlanmalıdır.
  • Python veya SQL kullanmalıdır. Sunucusuz ek özellikler ve sınırlamalar için bkz. Sunucusuz işlem sınırlamaları.
• ai_parse_document İşlev Databricks not defterleri, SQL düzenleyicisi, Databricks iş akışları, işler veya Lakeflow Spark Bildirimli İşlem Hatları kullanılarak kullanılabilir.
• ai_parse_document maliyetler ürünün bir parçası AI_FUNCTIONS olarak kaydedilir. ai_parse_document örnek sorgusu için bkz.

Veri güvenliği

Belge verileriniz Databricks güvenlik çevresi içinde işlenir. Databricks çağrılara ai_parse_document function geçirilen parametreleri depolamaz, ancak kullanılan Databricks Runtime sürümü gibi meta veri çalıştırma ayrıntılarını korur.

Desteklenen giriş dosyası biçimleri

Giriş veri dosyalarınızın bayt cinsinden blob verisi olarak depolanması gerekir; başka bir deyişle DataFrame veya Delta tablosunda ikili türdeki bir sütun. Kaynak belgeler bir Unity Kataloğu biriminde depolanıyorsa, ikili tür sütunu Spark binaryFile biçim okuyucusu kullanılarak oluşturulabilir.

Aşağıdaki dosya biçimleri desteklenir:

• 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 tek gerekli bağımsız değişkendir. Bağımsız değişkeninde map (version, imageOutputPath, descriptionElementTypesve pageRange) geçirilen tüm seçenekler isteğe bağlıdır.

• content BINARY: Giriş bayt dizisi verilerini temsil eden bir ifade.
• version: Desteklenen çıkış şemasının sürümü: "2.0".
• 'imageOutputPath': Başvuru veya çok kalıcı RAG uygulamaları için işlenen sayfa görüntülerini Unity Kataloğu birimine kaydedin.
• 'descriptionElementTypes': Yapay zeka tarafından oluşturulan açıklamalar. Yalnızca figures açıklamaları sürüm 2.0'da desteklenir, bu nedenle '*' ve 'figure' aynı davranışı üretir.
  • '' (boş dize): Hiçbir açıklama oluşturulmaz. Bu, çok sayıda rakam içeren belgeler için gereken işlem ve maliyetleri azaltır.
  • 'figure': Yalnızca şekiller için açıklamalar oluşturun. Yalnızca yapay zeka tarafından oluşturulan açıklamaları destekler.
  • '*' (varsayılan): Desteklenen tüm öğe türleri için açıklamalar oluşturun.
• 'pageRange': Ayrıştırma işlemini belgedeki sayfaların bir alt kümesiyle kısıtlar. Sayfa numaraları 1 dizinlidir. Değer, her belirtecin tek bir sayfa (örneğin) "3"veya kapsayıcı bir aralık (örneğin) "5-10"olduğu virgülle ayrılmış bir belirteç listesidir. Örneğin, 1, '1,3,5-10' 3 ve 5 ile 10 arasında sayfaları ayrıştırıyor. Seçili sayfaların 500 sayfa sınırı içinde kalması gerekir. Atlanırsa ve belge 500 sayfayı aşarsa pageRange , işlev hiçbir sayfa ayrıştırmadan hemen başarısız olur.

Returns

ai_parse_document işlevi, belgeden , page_number, headergibi footerbağlamsal düzen meta verilerini ayıklar. Ayrıca, metin paragrafları gibi belgenin içeriğini ayıklar. Sürüm 2.0 için tablolar HTML ile gösterilir. Çıkış VARIANT türündedir.

Öğeleri anlama

Öğe, ayrıştırılmış belge içinde tanımlanan ayrık bir içerik birimidir. Bir belgeyi işlerken ai_parse_document , belgeyi bir öğe dizisine böler; burada her öğe metin paragrafı, tablo, şekil veya sayfa üst bilgisi veya altbilgi gibi bir düzen işaretçisi gibi ayrı bir içerik bloğunu temsil eder.

Çıkış elements dizisindeki her öğe aşağıdaki alanları içerir:

• id: Öğenin belge içindeki konumunu gösteren 0 tabanlı dizin.
• type: Öğesinin temsil ettiği içerik türünü gösteren dize. Desteklenen öğe türleri şunlardır:
  • text: Metin paragrafı veya genel gövde metni.
  • table: İçeriği HTML biçiminde temsil edilen bir tablo.
  • figure: Belge içindeki bir resim veya diyagram.
  • title: Belge başlığı.
  • caption: Şekil veya tabloyla ilişkilendirilmiş resim yazısı.
  • section_header: Bölümün başlangıcını belirten başlık veya alt başlık.
  • page_header: Sayfanın en üstünde görünen üst bilgi.
  • page_footer: Sayfanın en altında görünen alt bilgi.
  • page_number: Sayfa numarası işaretçisi.
  • footnote: Dipnot başvurusu veya metin.
• content: öğesinin ayıklanan metin içeriği. Öğeler için table içerik HTML olarak biçimlendirilir. Öğeler için figure içerik olabilir NULL.
• confidence: Öğenin belgeden ne kadar güvenilir bir şekilde ayıklandığını gösteren güvenilirlik puanı.
• bbox: Öğenin sayfadaki fiziksel konumunu gösteren sınırlayıcı kutu koordinatları dizisi. Her sınırlayıcı kutu piksel koordinatları ve bir page_id başvuru içerir.
• description: Yapay zeka tarafından oluşturulan metin açıklaması. Sürüm 2.0'da, açıklamalar yalnızca seçenek etkinleştirildiğinde figure öğeler için descriptionElementTypes oluşturulur.

Important

İşlev çıkış şeması major.minor biçimi kullanılarak sürümlenmiştir. Databricks, desteklenen veya varsayılan sürümü, devam eden araştırmalara göre geliştirilmiş gösterimleri yansıtacak şekilde yükseltebilir.

• Küçük sürüm yükseltmeleri geriye dönük olarak uyumludur ve sadece yeni alanlar ekleyebilir.
• Ana sürüm yükseltmeleri, alan eklemeleri, kaldırmalar veya yeniden adlandırmalar gibi uyumsuzluktan kaynaklanan değişiklikleri içerebilir.

Çıkış şeması aşağıdadır:

Uyarı

22 Eylül 2025 itibarıyla çıkış şeması "2.0" sürümündedir ve şunları içerecek şekilde güncelleştirilmiştir:

• descriptions yapay zeka tarafından oluşturulan şekil açıklamaları için.
• bbox sınırlandırıcı kutu koordinatları için.

Mevcut iş yüklerinizi güncelleştirilmiş şemayı kullanacak şekilde geçirmek için bkz. İş yüklerini güncelleştirilmiş şemaya geçirme.

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

İş yüklerini güncelleştirilmiş şemaya geçirme

Bu bölümdeki adımlarda, güncelleştirilmiş çıktı şemasını kullanmak için 22 Eylül 2025'den önce oluşturulan iş yüklerinin nasıl geçirildiği açıklanmaktadır.

1. SQL isteğinizde parametresini version kullanarak belirli bir şema sürümü belirtin.

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

1. Kodunuzu elements dizisinden içerik okuyacak şekilde pages dizisi yerine değiştirin.
2. Meta verileri yeniden değerlendirin. Örneğin, üst bilgi ve alt bilgi gibi meta veriler kullanıyorsanız, bu bilgileri page öğesinden ayıklamak için alternatif bir yaklaşım geliştirmeniz gerekir.
3. Tüm iş yükünüzü geçirmeden önce güncelleştirilmiş mantığınızı örnek belgelerle doğrulayın.
4. Kullanım örneğinizle ilgiliyse şekil açıklamalarını veya görüntü kalıcılığını etkinleştirmeyi göz önünde bulundurun.
5. İzinleri denetleyin. Örneğin, görüntü kalıcılığını kullanmayı planlıyorsanız, hedef Unity Kataloğu birimi için doğru izinlere sahip olduğunuzdan emin olun.

Examples

Bu bölümde kullanımına ai_parse_documentyönelik örnekler verilmiştir.

kullanan ai_parse_documentartımlı işleme senaryoları için bu Bildirim temelli Otomasyon Paketleri örneğine bakın

Aşağıdaki örnek, metin öğelerini ayıklamak ve tüm metin içeriğini birleştirmek için kullanır ai_parse_document . Buradan Claude Sonnet 4 modeliyle satıcı adı, tarih, fatura numarası ve satın alınan ürünler gibi belirli yapılandırılmış bilgileri ayıklamak için kullanır ai_query .

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;

Aşağıdaki örnek, belge düzenlerini ai_parse_document kullanarak tek bir dosya için VARIANT çıktısı olarak ayıklamak ve belirtmek için kullanır:

• İşlenen görüntülerin kaydedileceği yer.
• Çıkış şeması sürümünü sabitler.
• Şekiller için yapay zeka tarafından oluşturulan açıklamaları etkinleştirir.

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

Aşağıdaki örnek, Unity Kataloğu birimindeki ikili dosyalardan sayfaların bir alt kümesine ayrıştırma işlemini kısıtlamak için kullanır pageRange . Sayfa numaraları 1 dizinlidir ve tek sayfaları aralıklarla birleştirebilirsiniz (örneğin, '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');

Aşağıdaki örnek, belge düzenlerini bir Unity Kataloğu birimindeki dosyalar için ai_parse_document kullanarak VARIANT çıktısı olarak ayıklar.

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)

Aşağıdaki örnek, belgeleri doğrudan SharePoint belge kitaplığından ayrıştırmak için SharePoint için Lakeflow Connect ile kullanır.

Important

SharePoint için Lakeflow Connect Beta içindedir.

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;

PySpark collect() ile to_json() kullanma

ai_parse_document , PySpark (veya VARIANT'ı desteklemeyen diğer API'ler) tarafından doğrudan toplanamayan bir VARIANT tür döndürür. Daha fazla işlem için ayrıştırılmış sonuçları Python toplamak için SQL'de to_json() kullanarak VARIANT'ı bir JSON dizesine dönüştürün ve ardından Python'de json.loads() ile ayrıştırın:

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.

Aşağıdaki örnek, çıkışın her üst düzey alanını ayırmak için ai_parse_document kullanır. Örneğin, document.pages, document.elements, error_statusve metadata tek tek sütunlar halinde.

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)

Hata ayıklama arabirimi not defteri

Aşağıdaki defter, ai_parse_document işlevinin çıkışını analiz etmek için görsel bir hata ayıklama arabirimi sağlar. Ayrıştırılmış belgeleri etkileşimli sınırlayıcı kutu katmanlarıyla işler ve belgelerinizin her bölgesinden hangi içeriğin ayıklandığını incelemenize olanak sağlar

Hata ayıklama arabirimi not defteri

Dizüstü bilgisayar al

Sınırlama

• Belgeler en fazla 500 sayfayla sınırlıdır ve bu sınırın aşılması hatalara neden olur.
• En fazla 100 MB dosya boyutu sınırı vardır.
• Databricks tüm özelliklerini geliştirmek için sürekli olarak çalışsa da LLM'ler yeni ortaya çıkan bir teknolojidir ve hatalara neden olabilir.
• İşlevin ai_parse_document belge içeriğini ayıklaması zaman alabilir ve özellikle yüksek oranda yoğun içerik içeren veya düşük çözünürlüğe sahip olan belgeler için yapısal bilgileri korur. Bazı durumlarda işlevin çalışması veya içeriği göz ardı etmesi biraz zaman alabilir. Databricks, gecikme süresini geliştirmek için sürekli çalışmaktadır.
• Bkz. Desteklenen giriş dosyası biçimleri. Databricks, kuruluşunuz için hangi ek biçimlerin en önemli olduğu konusunda geri bildirimde bulunur.
• ai_parse_document için modeli özelleştirmek veya ai_parse_document için müşteri tarafından sağlanan bir modeli kullanmak desteklenmez.
• Temel alınan model, Japonca veya Korece gibi Latin alfabesi olmayan metinleri kullanarak görüntüleri işlerken en iyi performansı göstermeyebilir.
• Dijital imzalı belgeler doğru işlenmeyebilir.

İlgili işlevler

• ai_prep_search işlev
• ai_extract işlev
• ai_classify işlev