AI_CLASSIFY

AI_CLASSIFY() 함수는 텍스트, 이미지 또는 문서를 사용자가 지정한 범주로 분류해요.

출처: Snowflake SQL Reference

본문

지역 가용성 (Region availability)

다음 표는 입력 타입별로 AI_CLASSIFY 함수를 사용할 수 있는 지역을 보여줘요.

데이터 타입	AWS US West 2 (Oregon)	AWS US East 1 (N. Virginia)	AWS Europe Central 1 (Frankfurt)	AWS Europe West 1 (Ireland)	AWS AP Southeast 2 (Sydney)	AWS AP Northeast 1 (Tokyo)	Azure East US 2 (Virginia)	Azure West Europe (Netherlands)	AWS (Cross-Region)
TEXT	✔	✔	✔	✔	✔	✔	✔	✔	✔
IMAGE	✔	✔	✔	✔	✔	✔	✔	✔
DOCUMENT (Preview)	✔

문법

AI_CLASSIFY( <input> , <list_of_categories> [, <config_object> ] [, <return_error_details> ] )

인자

input (필수) — 분류할 문자열, 이미지, 문서 또는 프롬프트 객체예요. 텍스트 분류의 경우 입력 문자열은 대소문자를 구분해요. 대문자 사용에 따라 결과가 달라질 수 있어요.

list_of_categories (필수) — 최소 두 개의 고유 값을 가진 범주 배열이에요. 범주 수는 토큰 창에 의해서만 제한되지만, 실제로는 20개가 넘는 범주는 분류 정확도를 낮출 수 있어요. 범주는 대소문자를 구분해요. 범주는 단순 문자열이거나 같은 타입의 SQL 객체일 수 있어요. 객체를 사용하면 분류 정확도를 높이기 위해 하나 이상의 범주에 설명을 제공할 수 있어요. 각 범주에 대해 다음을 지정하세요.

label (필수): 범주의 이름.
description (선택): 범주를 25단어 이하로 설명.

참고: 설명은 입력 토큰으로 계산되어 분류 작업의 비용에 영향을 줘요. 자세한 내용은 Snowflake Cortex AI 함수는 토큰 수에 따라 컴퓨팅 비용이 발생합니다… 문서를 참고하세요.

config_object (선택) — 키/값 쌍으로 지정된 구성 설정이에요. 지원되는 키는 다음과 같아요.

task_description: 50단어 이하의 분류 작업 설명. 모델이 분류 작업의 맥락을 이해하고 정확도를 높이는 데 도움이 될 수 있어요.
output_mode: 다중 레이블 분류에는 'multi'로 설정. 기본값은 단일 레이블 분류의 'single'.
examples: 퓨샷 학습(few-shot learning)을 위한 예제 객체 목록. 각 예제는 다음을 포함해야 해요.
- input: 분류할 예제 텍스트.
- labels: 입력에 대한 올바른 범주 목록.
- explanation: 입력이 해당 범주에 매핑되는 이유 설명.
입력이 문서일 때는 output_mode가 'single'이어야 하고 examples는 지원되지 않아요.

return_error_details (선택) — 오류 발생 시 오류 세부 정보를 반환할지 나타내는 BOOLEAN 플래그예요. TRUE로 설정하면 함수는 값과 오류 메시지를 담은 OBJECT를 반환하는데, 함수의 성공/실패 여부에 따라 둘 중 하나는 NULL이에요. 자세한 내용은 Error behavior 참고.

반환

직렬화된 객체를 반환해요. 객체의 labels 필드는 입력이 속하는 범주 목록을 지정하는 배열이에요. 단일 레이블 분류의 경우 labels 배열은 정확히 하나의 요소를 가져요. 다중 레이블 분류의 경우 labels 필드는 여러 요소를 가질 수 있어요.

오류 동작 (Error behavior)

기본적으로 AI_CLASSIFY가 입력을 처리할 수 없으면 함수는 NULL을 반환해요. 쿼리가 여러 행을 처리하면 오류가 있는 행은 NULL을 반환하고 쿼리가 완료되는 것을 막지 않아요.

오류 시 반환 값은 return_error_details 인자에 따라 달라져요. 다음 표는 return_error_details 인자에 따른 반환 값을 보여줘요.

return_error_details	반환 값	설명
FALSE / 전달 안 함	NULL
TRUE	value와 error 필드를 가진 OBJECT	value: 분류 결과를 담은 OBJECT, 오류가 발생했으면 NULL. error: 오류가 발생했으면 오류 메시지를 담은 VARCHAR, 함수가 성공하면 NULL.

AI 함수의 오류 처리에 대한 자세한 내용은 Snowflake Cortex AI Function: Multirow error handling improvements 문서를 참고하세요.

접근 제어 요구사항

사용자는 SNOWFLAKE.CORTEX_USER 데이터베이스 역할을 가진 역할을 사용해야 해요. 이 권한에 대한 자세한 내용은 Cortex LLM 권한을 참고하세요.

사용 노트

최상의 결과를 위해 다음 지침을 따르세요.

입력과 list_of_categories에 영어의 일반 텍스트를 사용하세요.
코드 스니펫, 로그, 비영어 텍스트 같은 비산문(non-prose)을 분류하려 하지 마세요.
텍스트에 오픈 소스가 아닌 코드나 형식(독점 언어·형식 같은) 사용을 피하세요. 기본 언어 모델은 독점 형식으로 학습되지 않았어요.
범주 레이블에 약어, 특수 문자, 전문 용어를 사용하지 마세요.
설명적인 범주를 사용하세요. "Xa4s3"이나 "category 1" 같은 범주 이름 사용을 피하세요.
상호 배타적인 범주를 사용하세요.
입력과 범주 사이의 관계가 불분명하거나 복잡할 때 명확한 작업 설명을 제공하면 정확도를 높일 수 있어요.
레이블 설명을 추가하면 정확도를 높일 수 있어요, 특히 레이블이 모호하거나 특정 선택 기준이 필요할 때. 각 레이블을 다른 레이블과 구분 짓는 것을 명확히 강조하는 설명을 작성하세요.
각 레이블, 설명, 예제는 모든 AI_CLASSIFY 호출의 입력 토큰 수를 늘려 비용에 영향을 줘요.
예제는 정확도 향상에 도움이 될 수 있어요.

참고: AI_CLASSIFY는 응답을 생성하기 위해 입력에 프롬프트를 추가해요. 이는 제공한 텍스트를 넘어 토큰 수를 늘려요.

문서 (Documents)

지원되는 파일 타입: .pdf, .doc, .docx, .xls, .xlsx, .html, .csv, .txt. 다음 한도가 적용돼요.

문서당 최대 100페이지
문서당 최대 200,000 토큰 (평균 문서 기준 약 80페이지)
최대 파일 크기: 22 MB
최대 이미지 크기: 2000 × 2000 px
호출당 최대 100개 범주
영어 전용

예제

다음 예제들은 필수 인자만 사용해 AI_CLASSIFY 함수를 사용해요.

AI_CLASSIFY: 텍스트

다음 예제는 프롬프트를 travel 또는 cooking 두 범주 중 하나로 분류해요:

SELECT AI_CLASSIFY('One day I will see the world', ['travel', 'cooking']);

다음은 위 명령의 출력이에요.

'{
  "labels": ["travel"]
 }';

다음 예제는 다중 레이블 분류를 사용해요:

SELECT AI_CLASSIFY(
  'One day I will see the world and learn to cook my favorite dishes',
  ['travel', 'cooking', 'reading', 'driving'],
  {'output_mode': 'multi'}
);

다음은 위 명령의 출력이에요.

'{
  "labels": ["travel", "cooking"]
 }';

다음 예제는 작업 설명, 레이블 설명, 퓨샷 예제를 전달해요:

SELECT AI_CLASSIFY(
  'One day I will see the world and learn to cook my favorite dishes',
  [
    {'label': 'travel', 'description': 'content related to traveling'},
    {'label': 'cooking'},
    {'label': 'reading'},
    {'label': 'driving'}
  ],
  {
    'task_description': 'Determine topics related to the given text',
    'output_mode': 'multi',
    'examples': [
      {
        'input': 'i love traveling with a good book',
        'labels': ['travel', 'reading'],
        'explanation': 'the text mentions traveling and a good book which relates to reading'
      }
    ]
  });

다음은 위 명령의 출력이에요.

'{
  "labels": ["travel", "cooking"]
}';

다음 예제는 text 열과 그 텍스트의 가능한 범주 열을 포함하는 text_classification_table을 만들어요. AI_CLASSIFY 함수는 테이블의 각 행에 호출되어 text 열의 문자열을 분류해요.

CREATE OR REPLACE TEMPORARY TABLE text_classification_table AS
SELECT 'France' AS input, ['North America', 'Europe', 'Asia'] AS classes
UNION ALL
SELECT 'Singapore', ['North America', 'Europe', 'Asia']
UNION ALL
SELECT 'one day I will see the world', ['travel', 'cooking', 'dancing']
UNION ALL
SELECT 'my lobster bisque is second to none', ['travel', 'cooking', 'dancing'];

SELECT input,
    classes,
    AI_CLASSIFY(input, classes):labels AS classification
FROM text_classification_table;

AI_CLASSIFY: 이미지

단일 파일 입력 사용:

WITH food_pictures AS (
  SELECT
      TO_FILE(file_url) AS img
  FROM DIRECTORY(@file_stage)
)
SELECT
*,
AI_CLASSIFY(img, ['dessert', 'drink', 'main dish', 'side dish']):labels AS classification
FROM food_pictures;

PROMPT()로 구성한 프롬프트 객체 사용:

  WITH food_pictures AS (
  SELECT
      TO_FILE(file_url) AS img
  FROM DIRECTORY(@file_stage)
)
SELECT
*,
AI_CLASSIFY(PROMPT('Please help me classify the food within this image {0}', img),
  ['dessert', 'drink', 'main dish', 'side dish']):labels AS classification
FROM food_pictures;

AI_CLASSIFY: 문서

WITH staged_docs AS (
  SELECT TO_FILE(file_url) AS doc FROM DIRECTORY(@my_doc_stage)
)
SELECT doc, AI_CLASSIFY(doc, ['invoice', 'contract', 'lab_report']):labels AS classification
FROM staged_docs;

다음은 위 명령의 출력이에요.

DOC	CLASSIFICATION
@my_doc_stage/invoice_001.pdf	["invoice"]
@my_doc_stage/contract_2026.pdf	["contract"]
@my_doc_stage/blood_panel_report.pdf	["lab_report"]

제한 사항

Snowflake AI 함수는 다음 종류의 스테이지에 있는 파일로 만든 FILE 객체에는 동작하지 않아요.
- 암호화 모드 TYPE = 'SNOWFLAKE_FULL'인 내부 스테이지
- 고객 측 암호화 모드가 있는 외부 스테이지:
  - TYPE = 'AWS_CSE'
  - TYPE = 'AZURE_CSE'
- 사용자 스테이지
- 테이블 스테이지
- 이중 따옴표로 묶인 이름의 스테이지

참고: AI_CLASSIFY는 CLASSIFY_TEXT의 갱신된 버전이에요. 최신 기능을 사용하려면 AI_CLASSIFY를 사용하세요.

법적 고지

법적 고지는 Snowflake AI and ML을 참고하세요.

더 알아보기 (Learn more)

Snowflake Cortex AI 함수