ai_extract fungsi

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

Penting

Fungsionalitas ini sesuai dengan Pratinjau Umum dan HIPAA.

Selama pratinjau:

  • Model bahasa yang mendasar dapat menangani beberapa bahasa, tetapi Fungsi AI ini disetel untuk bahasa Inggris.
  • Lihat Fitur dengan ketersediaan regional terbatas untuk mengetahui ketersediaan regional dari Fungsi AI.

Fungsi ini ai_extract() mengekstrak data terstruktur dari teks dan dokumen sesuai dengan skema yang Anda berikan. Anda dapat menggunakan nama bidang sederhana untuk ekstraksi dasar, atau menentukan skema kompleks dengan objek berlapis, array, validasi jenis, dan deskripsi bidang untuk dokumen bisnis seperti faktur, kontrak, dan pengajuan keuangan.

Fungsi ini menerima teks atau VARIANT output dari fungsi AI lainnya seperti ai_parse_document, memungkinkan alur kerja yang dapat disusupi untuk pemrosesan dokumen end-to-end.

Agar UI visual memvalidasi dan melakukan iterasi pada hasil ai_extract, lihat Ekstraksi Informasi.

Persyaratan

Lisensi Apache 2.0

Model dasar yang mungkin digunakan saat ini dilisensikan di bawah Lisensi Apache 2.0, Hak Cipta © Apache Software Foundation. Pelanggan bertanggung jawab untuk memastikan kepatuhan terhadap lisensi model yang berlaku.

Databricks merekomendasikan untuk meninjau lisensi ini untuk memastikan kepatuhan terhadap persyaratan yang berlaku. Jika model muncul di masa depan yang berkinerja lebih baik sesuai dengan tolok ukur internal Databricks, Databricks mungkin mengubah model (dan daftar lisensi yang berlaku yang disediakan di halaman ini).

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.
  • Fungsi ini tidak tersedia di Azure Databricks SQL Classic.
  • Periksa halaman harga Databricks SQL.
  • Di Databricks Runtime 15.1 ke atas, fungsi ini didukung di notebook Databricks, termasuk notebook yang dijalankan sebagai tugas dalam alur kerja Databricks.
  • Beban kerja inferensi batch memerlukan Databricks Runtime 15.4 ML LTS untuk meningkatkan performa.

Sintaks

Databricks merekomendasikan penggunaan versi 2 dari fungsi ini karena mendukung ekstraksi dan deskripsi bidang berlapis.

ai_extract(
    content VARIANT | STRING,
    schema STRING,
    [options MAP<STRING, STRING>]
) RETURNS VARIANT

Versi 2

ai_extract(
    content VARIANT | STRING,
    schema STRING,
    [options MAP<STRING, STRING>]
) RETURNS VARIANT

Versi 1

ai_extract(
    content STRING,
    labels ARRAY<STRING>,
    [options MAP<STRING, STRING>]
) RETURNS STRUCT

Argumen

  • content: Ekspresi VARIANT atau STRING. Menerima:

    • Teks mentah sebagai STRING
    • VARIANT Diproduksi oleh fungsi AI lain (seperti ai_parse_document)

  • schema: Harfiah STRING yang menentukan skema JSON untuk ekstraksi. Skemanya dapat berupa:

    • Skema sederhana: Array JSON dari nama bidang (diasumsikan sebagai string) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Skema tingkat lanjut: Objek JSON dengan informasi jenis, deskripsi, dan struktur berlapis
      • stringMendukung jenis , , integernumber, boolean, dan enum . Melakukan validasi jenis. Nilai yang tidak valid mengakibatkan kesalahan. Maksimum 500 nilai enum.
      • Mendukung objek berlapis menggunakan "type": "object" dengan "properties"
      • Mendukung array primitif atau objek yang menggunakan "type": "array" dengan "items"
      • Bidang opsional "description" untuk setiap properti untuk memandu kualitas ekstraksi

  • options: Opsi MAP<STRING, STRING> konfigurasi opsional yang berisi:

    • version: Peralihan versi untuk mendukung migrasi ("2.1", "2.0", "1.0"). Default didasarkan pada jenis input.
    • instructions: Deskripsi global tugas dan domain untuk meningkatkan kualitas ekstraksi. Harus kurang dari 20.000 karakter.
    • enableCitations: Ketika true, output untuk setiap bidang dalam skema ekstraksi menyertakan daftar nol atau lebih kutipan, yang menunjukkan dalam dokumen output yang diekstrak.
    • enableConfidenceScores: Ketika true, output untuk setiap bidang dalam skema ekstraksi menyertakan skor keyakinan antara 0 dan 1, menunjukkan seberapa pasti model tentang nilai tersebut. Ambang keyakinan yang sesuai tergantung pada kasus penggunaan spesifik Anda, dan Anda harus memilih cutoff yang selaras dengan toleransi Anda untuk risiko dan kesalahan.

Versi 2

  • content: Ekspresi VARIANT atau STRING. Menerima:

    • Teks mentah sebagai STRING
    • VARIANT Diproduksi oleh fungsi AI lain (seperti ai_parse_document)

  • schema: Harfiah STRING yang menentukan skema JSON untuk ekstraksi. Skemanya dapat berupa:

    • Skema sederhana: Array JSON dari nama bidang (diasumsikan sebagai string) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Skema tingkat lanjut: Objek JSON dengan informasi jenis, deskripsi, dan struktur berlapis
      • stringMendukung jenis , , integernumber, boolean, dan enum . Melakukan validasi jenis. Nilai yang tidak valid mengakibatkan kesalahan. Maksimum 500 nilai enum.
      • Mendukung objek berlapis menggunakan "type": "object" dengan "properties"
      • Mendukung array primitif atau objek yang menggunakan "type": "array" dengan "items"
      • Bidang opsional "description" untuk setiap properti untuk memandu kualitas ekstraksi

  • options: Opsi MAP<STRING, STRING> konfigurasi opsional yang berisi:

    • version: Peralihan versi untuk mendukung migrasi ("1.0" untuk perilaku v1, "2.0" untuk perilaku v2). Default didasarkan pada jenis input, tetapi kembali ke "1.0".
    • instructions: Deskripsi global tugas dan domain untuk meningkatkan kualitas ekstraksi. Harus kurang dari 20.000 karakter.

Versi 1

  • content: Ekspresi STRING yang berisi teks mentah.

  • labels: Sebuah literal ARRAY<STRING>. Setiap elemen adalah jenis entitas yang akan diekstrak.

  • options: Opsi MAP<STRING, STRING> konfigurasi opsional yang berisi:

    • version: Peralihan versi untuk mendukung migrasi ("1.0" untuk perilaku v1, "2.0" untuk perilaku v2). Default didasarkan pada jenis input, tetapi akan kembali ke "1.0".

Pengembalian

Mengembalikan yang VARIANT berisi:

{
  "response": {...},       // Extracted data matching the provided schema. Each leaf is returned as a Field object (see below).
  "error_message": null,   // null on success, or error message on failure
  "metadata": { ... }      // Metadata about the response, including unfurled citation ids.
}

Bidang response berisi data terstruktur yang diekstrak sesuai dengan skema:

  • Nama dan jenis bidang cocok dengan definisi skema
  • Struktur skema dipertahankan dalam respons: objek dan array berlapis menjaga bentuk aslinya. Setiap bidang "skalar" dalam skema ekstraksi memiliki objek output dengan bidang berikut:
    • value: Nilai yang diekstrak, diketik sesuai dengan skema. Null jika bidang tidak dapat diekstrak.
    • citation_ids: Hanya ada ketika enableCitations adalah true. Array ID yang diindeks ke dalam metadata.citations.
    • confidence_score: Hanya ada ketika enableConfidenceScores adalah true. Float antara 0 dan 1.
  • Validasi jenis diberlakukan untuk tipe bilangan bulat, angka, boolean, dan enum
  • Jika contentNULL, hasilnya adalah NULL.

Bidang metadata berisi metadata tentang respons. Ketika enableCitations adalah true, metadata bidang berisi detail tentang setiap ID kutipan di response bidang yang melacak nilai yang diekstrak kembali ke lokasinya dalam input.

Tergantung pada jenis input, kutipan dapat berupa salah satu dari dua jenis:

  • Untuk input teks mentah (STRING), kutipan adalah rentang teks dalam input asli. Setiap objek dalam metadata.citations berisi:
    • id: Bilangan bulat yang cocok dengan entri citation_ids pada bidang.
    • start: Offset karakter berbasis 0 inklusif ke dalam string input.
    • stop: Offset karakter berbasis 0 eksklusif ke dalam string input.
  • Untuk dokumen dan gambar PDF (saat menggunakan ai_extract hilir ), kutipan ai_parse_documentadalah kotak pembatas dalam input asli. Setiap objek dalam metadata.citations berisi:
    • id: Bilangan bulat yang cocok dengan citation_ids entri pada bidang.
    • bbox: Array {coord, page_id} objek, identik dalam bentuk ke element.bbox dalam ai_parse_document output. coord adalah koordinat piksel pada gambar halaman seperti [x0, y0, x1, y1]; page_id indeks halaman berbasis 0.

Versi 2

Mengembalikan yang VARIANT berisi:

{
  "response": { ... },   // Extracted data matching the provided schema
  "error_message": null          // null on success, or error message on failure
}

Bidang response berisi data terstruktur yang diekstrak sesuai dengan skema:

  • Nama dan jenis bidang cocok dengan definisi skema
  • Objek dan array berlapis dipertahankan dalam struktur
  • Bidang mungkin null jika tidak ditemukan
  • Validasi jenis diberlakukan untuk integer, , numberboolean, dan enum jenis

Jika contentNULL, hasilnya adalah NULL.

Versi 1

Mengembalikan di STRUCT mana setiap bidang sesuai dengan jenis entitas yang ditentukan dalam labels. Setiap bidang berisi string yang mewakili entitas yang diekstrak. Jika fungsi menemukan lebih dari satu kandidat untuk jenis entitas apa pun, fungsi hanya mengembalikan satu.

Contoh

Skema sederhana - nama bidang saja

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '["invoice_id", "vendor_name", "total_amount", "invoice_date"]',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":   {"value": "12345"},
     "vendor_name":  {"value": "Acme Corp"},
     "total_amount": {"value": "1250.00"},
     "invoice_date": {"value": "2024-01-15"}
   },
   "error_message": null
 }

Skema tingkat lanjut - dengan jenis dan deskripsi

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":   {"value": "12345"},
     "vendor_name":  {"value": "Acme Corp"},
     "total_amount": {"value": 1250.00},
     "invoice_date": {"value": "2024-01-15"}
   },
   "error_message": null
 }

Objek dan array berlapis

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp
     Line 1: Widget A, qty 10, $50.00 each
     Line 2: Widget B, qty 5, $100.00 each
     Subtotal: $1,000.00, Tax: $80.00, Total: $1,080.00',
    '{
      "invoice_header": {
        "type": "object",
        "properties": {
          "invoice_id": {"type": "string"},
          "vendor_name": {"type": "string"}
        }
      },
      "line_items": {
        "type": "array",
        "description": "List of invoiced products",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "quantity": {"type": "integer"},
            "unit_price": {"type": "number"}
          }
        }
      },
      "totals": {
        "type": "object",
        "properties": {
          "subtotal": {"type": "number"},
          "tax_amount": {"type": "number"},
          "total_amount": {"type": "number"}
        }
      }
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_header": {
       "invoice_id":  {"value": "12345"},
       "vendor_name": {"value": "Acme Corp"}
     },
     "line_items": [
       {"description": {"value": "Widget A"}, "quantity": {"value": 10}, "unit_price": {"value": 50.00}},
       {"description": {"value": "Widget B"}, "quantity": {"value": 5},  "unit_price": {"value": 100.00}}
     ],
     "totals": {
       "subtotal":     {"value": 1000.00},
       "tax_amount":   {"value": 80.00},
       "total_amount": {"value": 1080.00}
     }
   },
   "error_message": null
 }

Komposabilitas dengan ai_parse_document

> 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('version', '2.1', 'instructions', 'These are vendor invoices.')
    ) AS invoice_data
  FROM parsed_docs;

Menggunakan enum

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp, amount: $1,250.00 USD',
    '{
      "invoice_id": {"type": "string"},
      "vendor_name": {"type": "string"},
      "total_amount": {"type": "number"},
      "currency": {
        "type": "enum",
        "labels": ["USD", "EUR", "GBP", "CAD", "AUD"],
        "description": "Currency code"
      },
      "payment_terms": {"type": "string"}
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":     {"value": "12345"},
     "vendor_name":    {"value": "Acme Corp"},
     "total_amount":   {"value": 1250.00},
     "currency":       {"value": "USD"},
     "payment_terms":  {"value": null}
   },
   "error_message": null
 }

Kutipan (input STRING, kutipan SPAN)

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
   options => map(
     'version', '2.1',
     'enableCitations', 'true'
   )
  );
 {
   "response": {
     "invoice_id": {"citation_ids": [0], "value": "12345"},
     "vendor_name": {"citation_ids": [0], "value": "Acme Corp"},
     "total_amount": {"citation_ids": [1], "value": 1250.00},
     "invoice_date": {"citation_ids": [1], "value": "2024-01-15"}
   },
   "metadata": {
     "chunk_type": "span",
     "citations": [
       {"id": 0, "start": 0, "stop": 29},
       {"id": 1, "start": 29, "stop": 60}
     ]
   },
   "error_message": null
 }

Kutipan (VARIAN dari ai_parse_document, kutipan BBOX)

> WITH parsed AS (
    SELECT ai_parse_document(
             content,
             map('imageOutputPath', '/Volumes/main/default/parsed_images/')  // necessary for rendering bboxes
           ) AS doc
    FROM READ_FILES('/Volumes/main/default/invoices/invoice.pdf', format => 'binaryFile')
  )
  SELECT ai_extract(
    doc,
    '{"invoice_id":{"type":"string"}, "total_amount":{"type":"number"}}',
    options => map('version','2.1','enableCitations','true')
  ) AS extracted
  FROM parsed;
{
  "response": {
    "invoice_id":   {"citation_ids": [0], "value": "12345"},
    "total_amount": {"citation_ids": [1], "value": 1250.00}
  },
  "metadata": {
    "chunk_type": "bbox",
    "citations": [
      {"id": 0, "bbox": [{"coord": [120, 80,  240, 110], "page_id": 0}]},
      {"id": 1, "bbox": [{"coord": [400, 500, 560, 530], "page_id": 0}]}
    ],
    "pages": [{"id": 0, "image_uri": "/Volumes/main/default/parsed_images/6077ca79...f8efdb2ed05.jpg"}]
  },
  "error_message": null
}

Skor keyakinan


> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
   options => map(
    'version', '2.1',
    'enableConfidenceScores', 'true'
   )
  );
{
  "response": {
    "invoice_id": {"confidence_score": 0.95, "value": "12345"},
    "vendor_name": {"confidence_score": 0.62, "value": "Acme Corp"},
    "total_amount": {"confidence_score": 1.0, "value": 1250.00},
    "invoice_date": {"confidence_score": 0.99, "value": "2024-01-15"}
  },
  "error_message": null
}

Contoh buku catatan

Notebook berikut menyediakan antarmuka penelusuran kesalahan visual untuk menganalisis output kutipan ai_extract fungsi. Ini menunjukkan cara merender metadata kutipan sebagai cuplikan substring (input STRING) atau overlay kotak pembatas (input VARIAN), dan menggabungkan ai_extract kutipan kembali ke ai_parse_document elemen di SQL sehingga Anda dapat menandai ekstraksi keyakinan rendah untuk tinjauan manual.

Buku catatan penyajian kutipan

Dapatkan buku catatan

Versi 2

Skema sederhana - nama bidang saja

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '["invoice_id", "vendor_name", "total_amount", "invoice_date"]'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": "1250.00",
     "invoice_date": "2024-01-15"
   },
   "error_message": null
 }

Skema tingkat lanjut - dengan jenis dan deskripsi

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": 1250.00,
     "invoice_date": "2024-01-15"
   },
   "error_message": null
 }

Objek dan array berlapis

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp
     Line 1: Widget A, qty 10, $50.00 each
     Line 2: Widget B, qty 5, $100.00 each
     Subtotal: $1,000.00, Tax: $80.00, Total: $1,080.00',
    '{
      "invoice_header": {
        "type": "object",
        "properties": {
          "invoice_id": {"type": "string"},
          "vendor_name": {"type": "string"}
        }
      },
      "line_items": {
        "type": "array",
        "description": "List of invoiced products",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "quantity": {"type": "integer"},
            "unit_price": {"type": "number"}
          }
        }
      },
      "totals": {
        "type": "object",
        "properties": {
          "subtotal": {"type": "number"},
          "tax_amount": {"type": "number"},
          "total_amount": {"type": "number"}
        }
      }
    }'
  );
 {
   "response": {
     "invoice_header": {
       "invoice_id": "12345",
       "vendor_name": "Acme Corp"
     },
     "line_items": [
       {"description": "Widget A", "quantity": 10, "unit_price": 50.00},
       {"description": "Widget B", "quantity": 5, "unit_price": 100.00}
     ],
     "totals": {
       "subtotal": 1000.00,
       "tax_amount": 80.00,
       "total_amount": 1080.00
     }
   },
   "error": null
 }

Komposabilitas dengan ai_parse_document

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

Menggunakan enum

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp, amount: $1,250.00 USD',
    '{
      "invoice_id": {"type": "string"},
      "vendor_name": {"type": "string"},
      "total_amount": {"type": "number"},
      "currency": {
        "type": "enum",
        "labels": ["USD", "EUR", "GBP", "CAD", "AUD"],
        "description": "Currency code"
      },
      "payment_terms": {"type": "string"}
    }'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": 1250.00,
     "currency": "USD",
     "payment_terms": null
   },
   "error": null
 }

Versi 1

> SELECT ai_extract(
    'John Doe lives in New York and works for Acme Corp.',
    array('person', 'location', 'organization')
  );
 {"person": "John Doe", "location": "New York", "organization": "Acme Corp."}

> SELECT ai_extract(
    'Send an email to jane.doe@example.com about the meeting at 10am.',
    array('email', 'time')
  );
 {"email": "jane.doe@example.com", "time": "10am"}

Keterbatasan

  • Fungsi ini tidak tersedia di Azure Databricks SQL Classic.
  • Fungsi ini tidak dapat digunakan dengan tampilan.
  • Skema ini mendukung maksimum 128 bidang.
  • Nama bidang dapat berisi hingga 150 karakter.
  • Skema mendukung hingga tujuh tingkat bersarang untuk bidang berlapis.
  • Bidang Enum mendukung maksimal 500 nilai.
  • Validasi jenis diberlakukan untuk integerjenis , , numberboolean, dan enum . Jika nilai tidak cocok dengan jenis yang ditentukan, fungsi mengembalikan kesalahan.
  • Ukuran konteks total maksimum adalah 128.000 token.

Versi 2

  • Fungsi ini tidak tersedia di Azure Databricks SQL Classic.
  • Fungsi ini tidak dapat digunakan dengan tampilan.
  • Skema ini mendukung maksimum 128 bidang.
  • Nama bidang dapat berisi hingga 150 karakter.
  • Skema mendukung hingga tujuh tingkat bersarang untuk bidang berlapis.
  • Bidang Enum mendukung maksimal 500 nilai.
  • Validasi jenis diberlakukan untuk integerjenis , , numberboolean, dan enum . Jika nilai tidak cocok dengan jenis yang ditentukan, fungsi mengembalikan kesalahan.
  • Ukuran konteks total maksimum adalah 128.000 token.

Versi 1

  • Fungsi ini tidak tersedia di Azure Databricks SQL Classic.
  • Fungsi ini tidak dapat digunakan dengan Tampilan.
  • Jika lebih dari satu kandidat untuk jenis entitas ditemukan dalam konten, hanya satu nilai yang dikembalikan.
  • Last updated on