텍스트 분류

ai.classify 함수는 텍스트 입력을 정의된 클래스 또는 라벨 집합으로 분류하는 기본 제공 AlloyDB AI 도구입니다. 이 기능을 데이터베이스에 직접 삽입하면 PostgreSQL용 AlloyDB를 통해 복잡한 추출, 변환, 로드(ETL) 파이프라인이나 외부 서비스 통합을 빌드하지 않고도 비정형 데이터를 처리할 수 있습니다.

텍스트 분류 기능은 다음과 같은 이점을 제공합니다.

  • 실시간 분류: SQL을 사용하여 Gemini의 세계 지식을 엔터프라이즈 데이터에 적용합니다.
  • 확장성: AI 함수를 위한 스마트 일괄 처리(AI 함수 가속이라고도 함)를 지원합니다. 이는 AlloyDB AI의 자동 쿼리 실행 최적화 기능으로, 쿼리 실행 중에 백그라운드에서 개별 행별 스칼라 AI 함수 호출을 일괄 처리된 모델 요청으로 투명하게 그룹화합니다. 또한 배열 기반 및 커서 기반 처리를 지원하여 수천 개의 행을 효율적으로 처리합니다.
  • 단순성: 모델 호출 및 데이터 준비를 자동으로 관리하는 상위 수준 추상화를 제공합니다.

AlloyDB AI의 텍스트 분류 함수는 다음을 포함한 여러 사용 사례를 지원합니다.

  • 주제 분류: 사전 정의된 주제 (예: 스포츠, 기술, 금융)를 문서나 기사에 할당합니다.
  • 스팸 감지: 수신 이메일, 댓글 또는 메시지를 스팸으로 식별합니다.
  • 의도 인식: 항공편 예약, 날씨 확인, 음식 주문 등 쿼리 이면에 있는 사용자의 목표를 파악합니다.

시작하기 전에

ai.classify 함수를 사용하기 전에 다음 요구사항을 충족하는지 확인하세요.

  • PostgreSQL 버전: ai.classify 함수는 PostgreSQL 버전 18 이상에서 지원됩니다. 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로 바꿉니다. 지원되는 사전 등록 모델 목록은 지원되는 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 $$;

다음 단계