ai_classify fungsi

Berlaku untuk: Databricks SQL Databricks Runtime

Fungsi ini ai_classify() mengklasifikasikan konten teks sesuai dengan label kustom yang Anda sediakan. Anda dapat menggunakan nama label sederhana untuk klasifikasi dasar, atau menambahkan deskripsi label dan instruksi untuk meningkatkan akurasi untuk kasus penggunaan seperti perutean dukungan pelanggan, kategorisasi dokumen, dan analisis konten.

Fungsi menerima teks atau VARIANT output dari fungsi AI lainnya seperti ai_parse_document, mengaktifkan alur kerja yang dapat disusupi.

Untuk versi UI yang akan diulang pada ai_classify, lihat Klasifikasi.

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 yang berkinerja lebih baik sesuai dengan tolok ukur internal Azure Databricks, Databricks mungkin mengubah model dan memperbarui dokumentasi.

• Fungsi ini hanya tersedia di beberapa wilayah, lihat Ketersediaan fungsi AI.

• Untuk ruang kerja dengan add-on Keamanan dan Kepatuhan yang Ditingkatkan,

  • Lihat dukungan regional untuk ai_classifystandar kepatuhan yang sesuai.
  • Lihat Mengelola pratinjau Azure Databricks cara mengaktifkannya di ruang kerja Anda.

• Fungsi ini tidak tersedia di gudang SQL Pro atau Klasik.

• Databricks Runtime 18.2 atau lebih tinggi diperlukan.

• Komputasi tanpa server diperlukan untuk buku catatan dan alur kerja Databricks.

• Periksa halaman harga Databricks SQL.

Tip

Databricks merekomendasikan penggunaan versi 2.1 untuk ai_classify. Versi 1.0 adalah antarmuka warisan yang tidak mendukung kemampuan ini dan tidak direkomendasikan untuk beban kerja baru atau produksi.

Versi 2.0 mendukung:

• Deskripsi label untuk akurasi yang ditingkatkan
• Klasifikasi multi-label
• Instruksi global
• Hingga 500 label, dibandingkan dengan 20 dalam versi 1.0
• VARIANT input dari fungsi AI upstream seperti ai_parse_document
• Mengembalikan terstruktur VARIANT dengan informasi kesalahan

Versi 2.1 juga mendukung:

• Skor keyakinan untuk setiap label yang dikembalikan, diaktifkan dengan enableConfidenceScores
• Rasional menjelaskan setiap label yang dikembalikan, diaktifkan dengan enableRationales

Dalam versi 2.1, setiap klasifikasi di response adalah objek per label dengan value kunci alih-alih string label biasa. Perubahan bentuk output ini berlaku untuk semua panggilan versi 2.1, bahkan ketika opsi baru dinonaktifkan. Berpindah dari versi 2.0 ke 2.1 tidak kompatibel dengan output. Perbarui kueri dan kode hilir Anda untuk membaca label dari value kunci alih-alih membacanya secara langsung.

Untuk menyematkan versi secara eksplisit, teruskan options => map('version', '2.1').

Sintaks

Versi 2.1 (disarankan)

ai_classify(content, labels [, options])

Versi 2

ai_classify(content, labels [, options])

Versi 1 (Warisan)

ai_classify(content, labels [, options])

Argumen

Versi 2.1 (disarankan)

• content: Ekspresi VARIANT atau STRING. Menerima:

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

• labels: Ekspresi STRING yang menentukan label klasifikasi. Ini bisa berupa untai (karakter) literal atau ekspresi SQL apa pun yang mengevaluasi ke STRING, termasuk kolom tabel Delta. Label dapat berupa:

  • Label sederhana: Array nama label JSON.

    ["urgent", "not_urgent"]
    

  • Label dengan deskripsi: Nama label pemetaan objek JSON ke deskripsi. Deskripsi label harus 0-1000 karakter.

    {
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets"
    }
    

  Setiap label harus 1-100 karakter. labels harus berisi setidaknya 2 label, dan tidak lebih dari 500 label. Untuk taksonomi yang lebih besar dari 500 label, lihat Klasifikasi dengan 500+ label.

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

  • version: Peralihan versi untuk mendukung migrasi ("1.0", "2.0", atau "2.1"). Default didasarkan pada jenis input, tetapi kembali ke "1.0".
  • instructions: Deskripsi global tentang tugas dan domain untuk meningkatkan kualitas klasifikasi. Harus kurang dari 20.000 karakter.
  • multilabel: Atur ke "true" untuk mengembalikan beberapa label saat beberapa kategori berlaku. Defaultnya adalah "false" (klasifikasi label tunggal).
  • enableConfidenceScores: Atur ke "true" untuk menyertakan confidence_score (0–1) untuk setiap label yang dikembalikan. Memerlukan versi "2.1". Defaultnya adalah "false".
  • enableRationales: Atur ke "true" untuk menyertakan alasan singkat yang menjelaskan setiap label yang dikembalikan, di-grounded dalam teks input. Memerlukan versi "2.1". Defaultnya adalah "false".

Versi 2

• content: Ekspresi VARIANT atau STRING. Menerima:

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

• labels: Ekspresi STRING yang menentukan label klasifikasi. Ini bisa berupa untai (karakter) literal atau ekspresi SQL apa pun yang mengevaluasi ke STRING, termasuk kolom tabel Delta. Label dapat berupa:

  • Label sederhana: Array nama label JSON.

    ["urgent", "not_urgent"]
    

  • Label dengan deskripsi: Nama label pemetaan objek JSON ke deskripsi. Deskripsi label harus 0-1000 karakter.

    {
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets"
    }
    

  Setiap label harus 1-100 karakter. labels harus berisi setidaknya 2 label, dan tidak lebih dari 500 label. Untuk taksonomi yang lebih besar dari 500 label, lihat Klasifikasi dengan 500+ label.

• 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 tentang tugas dan domain untuk meningkatkan kualitas klasifikasi. Harus kurang dari 20.000 karakter.
  • multilabel: Atur ke "true" untuk mengembalikan beberapa label saat beberapa kategori berlaku. Defaultnya adalah "false" (klasifikasi label tunggal).

Versi 1 (Warisan)

• content: Ekspresi STRING yang berisi teks yang akan diklasifikasikan.

• labels: Literal ARRAY<STRING> dengan label klasifikasi output yang diharapkan. Harus berisi setidaknya 2 elemen, dan tidak lebih dari 20 elemen. Setiap label harus 1-50 karakter.

• 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".

Pengembalian

Versi 2.1 (disarankan)

Mengembalikan yang VARIANT berisi:

{
  "response": [{ "value": "label_name", "confidence_score": 0.97, "rationale": "Short justification for the label." }],
  "metadata": {
    "version": "2.1"
  },
  "error_message": null // null on success, or error message on failure
}

Setiap elemen di response adalah objek per label dengan value kunci daripada string label biasa. Ketika enableConfidenceScores adalah "true", setiap objek juga menyertakan confidence_score (0–1). Ketika enableRationales adalah "true", setiap objek juga menyertakan rationale. Ketika kedua opsi diaktifkan, urutan kunci di setiap objek adalah value, confidence_score, lalu rationale.

Bidang response berisi:

• Mode label tunggal (default): Array dengan satu elemen yang berisi label pencocokan terbaik
• Mode multi-label (multilabel: "true"): Array dengan beberapa label saat beberapa kategori berlaku
• Nama label sama persis dengan yang disediakan dalam labels parameter

Mengembalikan jika NULL adalah content atau jika konten tidak dapat diklasifikasikanNULL.

Versi 2

Mengembalikan yang VARIANT berisi:

{
  "response": ["label_name"], // Array with single label (or multiple if multilabel=true)
  "metadata": {
    "version": "2.0"
  },
  "error_message": null // null on success, or error message on failure
}

Bidang response berisi:

• Mode label tunggal (default): Array dengan satu elemen yang berisi label pencocokan terbaik
• Mode multi-label (multilabel: "true"): Array dengan beberapa label saat beberapa kategori berlaku
• Nama label sama persis dengan yang disediakan dalam labels parameter

Mengembalikan jika NULL adalah content atau jika konten tidak dapat diklasifikasikanNULL.

Versi 1 (Warisan)

Mengembalikan STRING. Nilai cocok dengan salah satu string yang disediakan dalam labels argumen.

Mengembalikan jika NULL adalah content atau jika konten tidak dapat diklasifikasikanNULL.

Contoh

Versi 2.1 (disarankan)

Label sederhana - nama label saja

Dalam versi 2.1, setiap klasifikasi adalah objek per label dengan value kunci alih-alih string biasa, bahkan ketika opsi baru dinonaktifkan.

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1')
  );
 {
   "response": [{"value": "urgent"}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Dengan skor keyakinan

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableConfidenceScores', 'true')
  );
 {
   "response": [{"value": "urgent", "confidence_score": 0.97}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Dengan rasional

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableRationales', 'true')
  );
 {
   "response": [{"value": "urgent", "rationale": "A leaked password is a security incident requiring immediate action."}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Dengan skor keyakinan dan rasional (multi-label)

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items"
    }',
    MAP('version', '2.1', 'multilabel', 'true', 'enableConfidenceScores', 'true', 'enableRationales', 'true')
  );
 {
   "response": [
     {"value": "billing_issue", "confidence_score": 0.91, "rationale": "Customer explicitly requests a refund."},
     {"value": "product_defect", "confidence_score": 0.88, "rationale": "Reports the product arrived broken."}
   ],
   "metadata": {
     "version": "2.1"
   },
   "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/support/tickets/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_classify(
      parsed_content,
      '["billing_error", "product_defect", "account_issue", "feature_request"]',
      MAP('version', '2.1', 'instructions', 'Customer support ticket classification.')
    ) AS ticket_category
  FROM parsed_docs;

Klasifikasi batch

> SELECT
    description,
    ai_classify(
      description,
      '["clothing", "shoes", "accessories", "furniture", "electronics"]',
      MAP('version', '2.1')
    ) AS category
  FROM products
  LIMIT 10;

Klasifikasi dengan 500+ label

Untuk mengklasifikasikan dengan lebih dari 500 label, sebaiknya sematkan dokumen dan label Anda, mengambil label k teratas per dokumen, lalu berjalan ai_classify pada subset yang lebih kecil.

Lihat Tutorial: Mengklasifikasikan dokumen dengan 500+ label untuk panduan langkah demi langkah.

Versi 2

Label sederhana - nama label saja

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]'
  );
 {
   "response": ["urgent"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Label dengan deskripsi

> SELECT ai_classify(
    'Customer cannot complete checkout due to payment processing error.',
    '{
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets",
      "feature_request": "Customer suggestions for improvements"
    }'
  );
 {
   "response": ["billing_error"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Label dari Tabel Delta

Berikan label dari tabel Delta dengan mengonversinya menjadi string JSON. Misalnya, diberi tabel label dengan skema news_topics(topic STRING, description STRING), Anda dapat meneruskan label Anda sebagai ai_classify berikut:

SELECT
  ai_classify(
    "Leicester City Wins Premier League Title at 5000-1 Odds",
    l.labels,
    MAP('version', '2.0')
  ) AS classification
FROM (
  SELECT to_json(map_from_entries(collect_list(struct(topic, description)))) AS labels
  FROM news_topics
) l;

Menggunakan instruksi global

> SELECT ai_classify(
    'User reports app crashes on startup after update.',
    '["critical", "high", "medium", "low"]',
    MAP('instructions', 'Classify bug severity based on user impact and frequency.')
  );
 {
   "response": ["critical"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Klasifikasi multi-label

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items",
      "shipping_issue": "Delivery problems"
    }',
    MAP('version', '2.0','multilabel', 'true')
  );
 {
   "response": ["billing_issue", "product_defect"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Versi 1 (Warisan)

> SELECT ai_classify("My password is leaked.", ARRAY("urgent", "not urgent"));
  urgent

> SELECT
    description,
    ai_classify(description, ARRAY('clothing', 'shoes', 'accessories', 'furniture')) AS category
  FROM
    products
  LIMIT 10;

Keterbatasan

Versi 2.1 (disarankan)

Batasan versi 2.1:

• Fungsi ini tidak tersedia di Azure Databricks SQL Classic.

• Fungsi ini tidak dapat digunakan dengan Tampilan.

• Nama label harus masing-masing 1–100 karakter.

• Parameter labels harus berisi antara 2 dan 500 label unik.

• Deskripsi label harus masing-masing 0–1.000 karakter.

• Ukuran konteks total maksimum adalah 128.000 token.

Versi 2

Batasan versi 2:

• Fungsi ini tidak tersedia di Azure Databricks SQL Classic.

• Fungsi ini tidak dapat digunakan dengan Tampilan.

• Nama label harus masing-masing 1–100 karakter.

• Parameter labels harus berisi antara 2 dan 500 label unik.

• Deskripsi label harus masing-masing 0–1.000 karakter.

• Ukuran konteks total maksimum adalah 128.000 token.

Versi 1 (Warisan)

Batasan Versi 1 (Warisan):

• Fungsi ini tidak tersedia di Azure Databricks SQL Classic.

• Fungsi ini tidak dapat digunakan dengan Tampilan.

• Nama label masing-masing harus 1–50 karakter.

• Array labels harus berisi antara 2 dan 20 label.

• Input content harus kurang dari 128.000 token (sekitar 300.000 karakter).

Fungsi terkait

• ai_extract fungsi
• ai_parse_document fungsi