Mengklasifikasikan teks

Fungsi ai.classify adalah alat AlloyDB AI bawaan yang mengategorikan input teks ke dalam serangkaian class atau label yang Anda tentukan. Dengan menyematkan kemampuan ini langsung ke dalam database, AlloyDB untuk PostgreSQL memungkinkan Anda memproses data tidak terstruktur tanpa membangun pipeline Extract, Transform, and Load (ETL) yang kompleks atau integrasi layanan eksternal.

Fungsi klasifikasi teks memberikan manfaat berikut:

  • Klasifikasi real-time: menghadirkan pengetahuan dunia Gemini ke data perusahaan menggunakan SQL.
  • Skalabilitas: mendukung pengelompokan cerdas untuk fungsi AI—juga disebut sebagai akselerasi fungsi AI—yang merupakan fitur pengoptimalan eksekusi kueri otomatis di AlloyDB AI yang secara transparan mengelompokkan panggilan fungsi AI skalar baris demi baris ke dalam permintaan model batch di latar belakang selama eksekusi kueri. Juga mendukung pemrosesan berbasis array dan berbasis kursor untuk menangani ribuan baris secara efisien.
  • Kemudahan: menyediakan abstraksi tingkat tinggi yang mengelola pemanggilan model dan persiapan data secara otomatis.

Fungsi klasifikasi teks AlloyDB AI mendukung beberapa kasus penggunaan, termasuk:

  • Klasifikasi Topik: menetapkan topik yang telah ditentukan (seperti olahraga, teknologi, atau keuangan) ke dokumen atau artikel.
  • Deteksi Spam: mengidentifikasi email, komentar, atau pesan masuk sebagai spam.
  • Pengenalan Intent: menentukan tujuan pengguna di balik kueri, seperti memesan penerbangan, memeriksa cuaca, atau memesan makanan.

Sebelum memulai

Pastikan Anda memenuhi persyaratan berikut sebelum menggunakan fungsi ai.classify:

  • Versi PostgreSQL: Fungsi ai.classify didukung di PostgreSQL versi 18 dan yang lebih baru. Pastikan cluster AlloyDB Anda menjalankan PostgreSQL 18 atau yang lebih baru. Untuk mengetahui informasi selengkapnya, lihat Versi database yang didukung.
  • Versi ekstensi: Pastikan Anda telah menginstal ekstensi google_ml_integration versi terbaru (versi 1.6.1 atau yang lebih tinggi) dengan fungsi Pratinjau diaktifkan.

Mengaktifkan ekstensi

Pastikan Anda telah menginstal ekstensi google_ml_integration versi terbaru (versi 1.6.1 atau yang lebih baru) dengan fungsi Pratinjau diaktifkan.

Untuk mengaktifkan flag google_ml_integration.enable_ai_query_engine dan google_ml_integration.enable_preview_ai_functions di AlloyDB, gunakan perintah SET. Flag ini mengontrol akses ke mesin kueri AI dan fungsi AI pratinjau seperti ai.classify.

  1. Pastikan ekstensi google_ml_integration Anda adalah versi 1.6.1 atau yang lebih tinggi. Untuk memverifikasi versi, jalankan perintah berikut:

    SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

  2. Aktifkan flag untuk sesi saat ini atau untuk seluruh database. Untuk mengaktifkan flag untuk sesi Anda saat ini, jalankan perintah berikut:

    SET google_ml_integration.enable_ai_query_engine = 'on';
SET google_ml_integration.enable_preview_ai_functions = 'on';

    Perubahan ini tidak memerlukan mulai ulang database. Nilai default flag ini adalah off.

Membuat tabel contoh

Untuk mengikuti contoh fungsi classify dalam dokumen ini, buat tabel dan isi dengan contoh ulasan produk berikut.

CREATE TABLE IF NOT EXISTS product_reviews (
    id INT PRIMARY KEY,
    review TEXT
);

INSERT INTO product_reviews (id, review) VALUES
(1, 'Fantastic, would buy again!'),
(2, 'Broken on arrival.'),
(3, 'Mediocre, not worth the price.');

Mengklasifikasikan satu string

Untuk mengategorikan satu input teks, gunakan versi skalar ai.classify. Untuk dokumentasi API yang mendetail, lihat referensi ai.classify.

SELECT ai.classify(
  input => 'TEXT_CONTENT',
  categories => ARRAY['CATEGORY1', 'CATEGORY2', 'CATEGORY3'],
  examples => 'EXAMPLES', -- Optional
  output_mode => 'OUTPUT_MODE', -- Optional. Can be 'single' or 'multi'.
  model_id => 'MODEL_ID' -- Optional. The default value is gemini-3.5-flash-lite.
);

Mengklasifikasikan teks ke dalam kategori yang saling eksklusif

Contoh berikut menunjukkan kasus penggunaan dasar untuk mengklasifikasikan satu bagian teks ke dalam salah satu dari beberapa kategori yang saling eksklusif:

SELECT ai.classify(
  input => 'This is a sales report for Q1.',
  categories => ARRAY['Report', 'Invoice', 'Memo']
);

Berikut adalah contoh output:

Report

Mengklasifikasikan topik multi-label

Contoh berikut mengklasifikasikan judul berita ke dalam beberapa topik dengan menetapkan output_mode ke 'multi' dan dengan memberikan deskripsi kategori:

SELECT ai.classify(
  input => 'The government announced new regulations on AI development, citing both economic opportunities and potential security risks.',
  categories => ARRAY[
    ARRAY['politics', 'Questions about politics'],
    ARRAY['technology', 'Questions about technology'],
    ARRAY['security', 'Questions about security']
  ],
  output_mode => 'multi'
);

Berikut adalah contoh output:

politics,technology,security

Menggunakan kategori dengan deskripsi

Contoh berikut menunjukkan cara yang direkomendasikan untuk memberikan kategori menggunakan format array 2D dengan label dan deskripsi agar lebih jelas:

SELECT ai.classify(
  input => 'The patient reported mild fever and headache.',
  categories => ARRAY[
    ARRAY['urgent', 'Requires immediate medical attention'],
    ARRAY['non-urgent', 'Routine check-up or minor symptoms'],
    ARRAY['query', 'A question about services or appointments']
  ]
);

Berikut adalah contoh output:

non-urgent

Memberikan contoh few-shot

Contoh berikut menunjukkan cara memandu klasifikasi model dengan memberikan contoh input dan output yang diharapkan:

SELECT ai.classify(
  input => 'Is this item returnable after 90 days?',
  categories => ARRAY[
    ARRAY['policy', 'Questions about return, warranty, or other policies'],
    ARRAY['shipping', 'Questions about order shipment and delivery'],
    ARRAY['payment', 'Questions about payment methods or issues'],
    ARRAY['other', 'Any other type of question']
  ],
  examples => '[
    {"input": "When will my order arrive?", "output": "shipping"},
    {"input": "What is the warranty on this?", "output": "policy"},
    {"input": "My discount code isn''t working.", "output": "payment"}
  ]'
);

Berikut adalah contoh output:

policy

Menggunakan ID model tertentu

Contoh berikut menunjukkan cara menggunakan versi atau jenis model tertentu dengan merujuk pada ID-nya:

SELECT ai.classify(
  input => 'This new song is a banger!',
  categories => ARRAY[
    ARRAY['positive', 'Expresses approval or enjoyment'],
    ARRAY['negative', 'Expresses disapproval or dislike']
  ],
  model_id => 'MODEL_ID'
);

Berikut adalah contoh output:

positive

Ganti MODEL_ID dengan ID model yang telah didaftarkan sebelumnya yang didukung atau model kustom yang Anda daftarkan. Untuk mengetahui daftar model yang telah didaftarkan dan didukung, lihat Model AI yang didukung. Untuk mengetahui petunjuk cara mendaftarkan endpoint model lainnya, lihat Mendaftarkan dan memanggil model AI jarak jauh menggunakan pengelolaan endpoint model.

Mengklasifikasikan dalam batch

Saat mengklasifikasikan set data besar di beberapa baris, Anda dapat mengoptimalkan performa menggunakan pengelompokan cerdas untuk fungsi AI atau dengan menggunakan versi berbasis array dari ai.classify.

Pengelompokan cerdas

Untuk mempercepat kueri yang menjalankan ai.classify skalar di beberapa baris tanpa menulis kueri agregasi array yang kompleks, aktifkan pengelompokan cerdas untuk fungsi AI dengan menetapkan flag database google_ml_integration.enable_ai_function_acceleration ke on:

SET google_ml_integration.enable_ai_function_acceleration = 'on';

Jika flag ini diaktifkan, AlloyDB akan otomatis mengelompokkan panggilan ai.classify skalar individual ke dalam batch cerdas di latar belakang.

SELECT
  id,
  ai.classify(
    input => review,
    categories => ARRAY['positive', 'neutral', 'negative']
  ) AS sentiment
FROM product_reviews
ORDER BY id;

Pengelompokan berbasis array

Untuk kontrol eksplisit atas pemrosesan batch pada set data yang lebih besar, gunakan versi ai.classify berbasis array untuk memproses beberapa input sekaligus dengan meneruskan array input SQL. Untuk dokumentasi API yang mendetail, lihat referensi ai.classify.

SELECT ai.classify(
  inputs => TEXT[],
  categories => TEXT[][],
  examples => TEXT, -- Optional.
  output_mode => VARCHAR, -- Optional. The default value is single.
  batch_size => INT, -- Optional. The default value is 10.
  model_id => VARCHAR(100) -- Optional. The default value is gemini-3.5-flash-lite.
);

Contoh berikut mengklasifikasikan beberapa ulasan sekaligus:

SELECT unnest(
  ai.classify(
    inputs => ARRAY(SELECT review FROM product_reviews ORDER BY id),
    categories => ARRAY[
      ARRAY['positive', 'Good sentiment'],
      ARRAY['neutral',  'Neither good nor bad sentiment'],
      ARRAY['negative', 'Bad sentiment']
    ],
    batch_size => 5
  )
) AS sentiment;

Berikut adalah contoh output:

 sentiment
-----------
 positive
 negative
 negative

Mengklasifikasikan menggunakan kursor

Fungsi berbasis kursor memproses set data besar secara efisien dengan memungkinkan sistem melakukan streaming data melalui model AI dalam batch yang dapat dikelola tanpa mengharuskan semua data dimuat ke dalam memori sekaligus. Untuk informasi selengkapnya, lihat referensi ai.classify.

Tanda tangan fungsi untuk ai.classify versi berbasis kursor adalah sebagai berikut:

CREATE OR REPLACE FUNCTION ai.classify(
    input_cursor REFCURSOR,
    categories TEXT[][],
    examples TEXT DEFAULT NULL,
    output_mode VARCHAR DEFAULT NULL,
    batch_size INT DEFAULT NULL,
    model_id VARCHAR(100) DEFAULT NULL)
  RETURNS REFCURSOR

Contoh berikut menunjukkan cara menggunakan kursor untuk memberikan input ke ai.classify:

DO $$
DECLARE
  cur REFCURSOR;
  result_cur REFCURSOR;
  input_val TEXT;
  sentiment TEXT;
BEGIN
  OPEN cur FOR SELECT review FROM product_reviews ORDER BY id;

  result_cur := ai.classify(
    input_cursor => cur,
    categories => ARRAY[
      ARRAY['positive', 'Good sentiment'],
      ARRAY['neutral',  'Neither good nor bad sentiment'],
      ARRAY['negative', 'Bad sentiment']
    ],
    batch_size => 20
  );

  LOOP
    FETCH result_cur INTO input_val, sentiment;
    EXIT WHEN NOT FOUND;
    RAISE NOTICE 'Sentiment: %', sentiment;
  END LOOP;

  CLOSE result_cur;
  CLOSE cur;
END $$;

Langkah berikutnya