分類文字

ai.classify 函式是內建的 AlloyDB AI 工具,可將文字輸入內容分類為您定義的一組類別或標籤。AlloyDB for PostgreSQL 直接將這項功能嵌入資料庫,讓您處理非結構化資料,不必建構複雜的擷取、轉換和載入 (ETL) 管道,或整合外部服務。

文字分類函式有下列優點:

  • 即時分類:使用 SQL 將 Gemini 的世界知識帶入企業資料。
  • 擴充性:支援 AI 函式的智慧批次處理 (也稱為 AI 函式加速),這是 AlloyDB AI 的自動查詢執行最佳化功能,可在查詢執行期間,在背景將個別、逐列的純量 AI 函式呼叫,透明地分組為批次模型要求。此外,也支援陣列和游標式處理,可有效處理數千個資料列。
  • 簡單:提供高階抽象化,可自動管理模型叫用和資料準備。

AlloyDB AI 的文字分類函式支援多種用途,包括:

  • 主題分類:為文件或文章指派預先定義的主題 (例如體育、科技或財經)。
  • 垃圾訊息偵測:將收到的電子郵件、留言或訊息判定為垃圾訊息。
  • 意圖辨識:判斷使用者查詢背後的目的,例如預訂航班、查詢天氣或訂餐。

事前準備

使用 ai.classify 函式前,請確認您符合下列規定:

  • PostgreSQL 版本:PostgreSQL 18 以上版本支援 ai.classify 函式。確認 AlloyDB 叢集執行的是 PostgreSQL 18 以上版本。詳情請參閱「支援的資料庫版本」。
  • 擴充功能版本:請確認您已安裝最新版本 google_ml_integration 擴充功能 (1.6.1 以上版本),並啟用預覽功能。

啟用擴充功能

請確認您已安裝最新版本的 google_ml_integration 擴充功能 (1.6.1 以上版本),並啟用預覽功能。

如要在 AlloyDB 中啟用 google_ml_integration.enable_ai_query_engine 和 google_ml_integration.enable_preview_ai_functions 旗標,請使用 SET 指令。這些旗標可控管 AI 查詢引擎的存取權,以及 ai.classify 等預先發布版 AI 函式。

  1. 請確認 google_ml_integration 擴充功能為 1.6.1 以上版本。如要確認版本,請執行下列指令:

    SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
    
  2. 為目前工作階段或整個資料庫啟用旗標。如要為目前的工作階段啟用旗標,請執行下列指令:

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

    這項變更不需要重新啟動資料庫。這些旗標的預設值為 off。

建立範例資料表

如要按照本文件中的分類函式範例操作,請建立資料表,並填入下列產品評論範例。

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

分類單一字串

如要分類單一文字輸入,請使用純量版本的 ai.classify。如需詳細的 API 說明文件,請參閱 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.
);

將文字分類至互斥類別

以下範例說明將單一文字分類為多個互斥類別之一的基本用途:

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

輸出範例如下:

Report

分類多標籤主題

以下範例將 output_mode 設為 'multi',並提供類別說明,將新聞標題歸類為多個主題:

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

輸出範例如下:

politics,technology,security

使用含有說明的類別

以下範例示範提供類別的首選方式,使用 2D 陣列格式,並附上標籤和說明,讓內容更清楚:

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

輸出範例如下:

non-urgent

提供少量樣本

以下範例說明如何提供輸入內容和預期輸出內容的範例,引導模型進行分類:

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"}
  ]'
);

輸出範例如下:

policy

使用特定模型 ID

以下範例說明如何透過參照 ID,使用特定模型版本或類型:

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

輸出範例如下:

positive

將 MODEL_ID 替換為支援的預先註冊模型 ID,或您註冊的自訂模型 ID。如需支援的預先註冊模型清單,請參閱「支援的 AI 模型」。如要瞭解如何註冊其他模型端點,請參閱「使用模型端點管理功能註冊及呼叫遠端 AI 模型」。

批次分類

如要分類多個資料列的大型資料集,可以使用 AI 函式的智慧批次處理功能,或使用陣列版本的 ai.classify,藉此提升效能。

智慧批次處理

如要加快在多個資料列中執行純量 ai.classify 的查詢,而不必編寫複雜的陣列匯總查詢,請將 google_ml_integration.enable_ai_function_acceleration 資料庫旗標設為 on,啟用 AI 函式的智慧批次處理功能:

SET google_ml_integration.enable_ai_function_acceleration = 'on';

啟用這個旗標後,AlloyDB 會在背景自動將個別純量 ai.classify 呼叫分組為智慧批次。

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

陣列式批次處理

如要明確控管大型資料集的批次處理,請使用陣列式版本的 ai.classify,透過傳遞輸入內容的 SQL 陣列,一次處理多個輸入內容。如需詳細的 API 說明文件,請參閱 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.
);

以下範例會一次分類多則評論:

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;

輸出範例如下:

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

使用游標分類

游標式函式可讓系統以可管理的分批方式,透過 AI 模型串流資料,不必一次將所有資料載入記憶體,因此能有效率地處理大型資料集。詳情請參閱 ai.classify 參考資料。

ai.classify 的游標版本函式簽章如下:

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

以下範例說明如何使用游標將輸入內容提供給 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 $$;

後續步驟