> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 함수 — 핵심 함수 가이드

> 이 문서는 **[데이터 웨어하우징](/training/06-data-warehousing/overview)** 섹션의 일부입니다.

## 왜 SQL에 AI 함수가 필요한가요?

전통적으로 텍스트 분류, 감정 분석, 정보 추출 같은 작업을 하려면 Python 코드를 작성하고, ML 모델을 별도로 호출해야 했습니다. Databricks의 **AI 함수** 를 사용하면 이 모든 것을 **SQL 쿼리 한 줄** 로 수행할 수 있습니다.

> 💡 AI 함수는 내부적으로 **Model Serving 엔드포인트** 를 호출합니다. Foundation Model API에서 제공하는 LLM(Llama, DBRX 등)이나 외부 모델(OpenAI, Anthropic) 엔드포인트를 사용할 수 있습니다. SQL Warehouse(Pro 또는 Serverless)에서 실행해야 합니다.

***

## ai\_query() — 범용 LLM 호출

가장 유연한 AI 함수로, 자유 형식의 프롬프트를 LLM에 전달하고 응답을 받습니다.

### 기본 문법

```sql theme={null}
ai_query(
    endpoint,           -- Model Serving 엔드포인트 이름
    request,            -- 프롬프트 (문자열 또는 STRUCT)
    returnType,         -- 반환 타입 (기본: STRING)
    failOnError,        -- 에러 시 실패 여부 (기본: true)
    modelParameters     -- 모델 파라미터 (temperature, max_tokens 등)
)
```

### 사용 예시

```sql theme={null}
-- 1. 기본 사용: 텍스트 요약
SELECT
    article_id,
    ai_query(
        'databricks-meta-llama-3-3-70b-instruct',
        CONCAT('다음 기사를 한국어 3줄로 요약해 주세요:\n\n', article_text)
    ) AS summary
FROM news_articles;

-- 2. 구조화된 응답 반환 (JSON → STRUCT)
SELECT
    review_id,
    ai_query(
        'databricks-meta-llama-3-3-70b-instruct',
        CONCAT('다음 리뷰를 분석하여 JSON으로 반환해 주세요: ', review_text),
        returnType => 'STRUCT<sentiment STRING, topics ARRAY<STRING>, score INT>'
    ) AS analysis
FROM customer_reviews;

-- 3. 모델 파라미터 지정
SELECT ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    '데이터 레이크하우스의 장점을 5가지 나열해 주세요.',
    modelParameters => named_struct(
        'temperature', 0.1,           -- 낮을수록 결정적 (0.0~2.0)
        'max_tokens', 500,            -- 최대 응답 토큰 수
        'top_p', 0.9                  -- 확률 기반 토큰 선택 범위
    )
) AS response;

-- 4. 시스템 프롬프트 + 사용자 프롬프트 (Chat 형식)
SELECT ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    named_struct(
        'messages', ARRAY(
            named_struct('role', 'system', 'content', '당신은 전문 데이터 분석가입니다. 한국어로 답변해 주세요.'),
            named_struct('role', 'user', 'content', CONCAT('다음 데이터를 분석해 주세요: ', data_text))
        )
    )
) AS analysis
FROM reports;

-- 5. 배치 처리 시 에러 무시 (일부 실패해도 전체 쿼리 계속)
SELECT
    doc_id,
    ai_query(
        'databricks-meta-llama-3-3-70b-instruct',
        CONCAT('요약: ', content),
        failOnError => false
    ) AS summary
FROM documents;
```

### 사용 가능한 엔드포인트

| 엔드포인트 이름                                 | 모델            | 설명                                |
| ---------------------------------------- | ------------- | --------------------------------- |
| `databricks-meta-llama-3-3-70b-instruct` | Llama 3.3 70B | Meta의 최신 오픈소스 LLM입니다              |
| `databricks-dbrx-instruct`               | DBRX          | Databricks가 만든 오픈소스 LLM입니다        |
| `databricks-gte-large-en`                | GTE Large     | 영어 텍스트 임베딩 모델입니다                  |
| `databricks-bge-large-en`                | BGE Large     | 영어 텍스트 임베딩 모델입니다                  |
| 사용자 지정                                   | 커스텀 모델        | Model Serving에 배포한 사용자 모델입니다      |
| 사용자 지정                                   | 외부 모델         | OpenAI, Anthropic 등의 프록시 엔드포인트입니다 |

> 💡 **Pay-per-token 엔드포인트**: `databricks-` 접두사가 붙은 내장 엔드포인트는 별도 설정 없이 바로 사용할 수 있으며, 사용한 토큰 수에 따라 과금됩니다.

***

## ai\_classify() — 텍스트 분류

텍스트를 미리 정의한 카테고리 중 하나로 분류합니다. 별도의 학습 데이터 없이 LLM의 이해력만으로 분류를 수행합니다.

### 문법

```sql theme={null}
ai_classify(content, labels)
-- content: 분류할 텍스트 (STRING)
-- labels:  카테고리 목록 (ARRAY<STRING>)
```

### 예시

```sql theme={null}
-- 고객 문의 유형 분류
SELECT
    ticket_id,
    subject,
    ai_classify(
        subject || ': ' || body,
        ARRAY('배송문의', '반품/환불', '상품문의', '결제문제', '기타')
    ) AS category
FROM support_tickets;

-- 감정 분석 (긍정/부정/중립)
SELECT
    review_id,
    review_text,
    ai_classify(review_text, ARRAY('긍정', '부정', '중립')) AS sentiment
FROM customer_reviews;

-- 언어 감지
SELECT
    doc_id,
    ai_classify(content, ARRAY('한국어', '영어', '일본어', '중국어')) AS language
FROM documents;

-- 긴급도 분류
SELECT
    alert_id,
    message,
    ai_classify(message, ARRAY('긴급', '높음', '보통', '낮음')) AS priority
FROM system_alerts;
```

***

## ai\_extract() — 정보 추출

텍스트에서 특정 정보를 추출합니다. 정규 표현식으로는 어려운 비정형 텍스트에서도 LLM의 이해력으로 정확하게 추출할 수 있습니다.

### 문법

```sql theme={null}
ai_extract(content, labels)
-- content: 원본 텍스트 (STRING)
-- labels:  추출할 정보 항목 목록 (ARRAY<STRING>)
-- 반환:    STRUCT (각 항목이 필드로 포함)
```

### 예시

```sql theme={null}
-- 이메일에서 핵심 정보 추출
SELECT
    email_id,
    ai_extract(
        email_body,
        ARRAY('발신자이름', '회사명', '요청사항', '긴급여부', '연락처')
    ) AS extracted
FROM inbox_emails;

-- 추출된 STRUCT에서 개별 필드 접근
SELECT
    email_id,
    extracted.발신자이름,
    extracted.회사명,
    extracted.요청사항
FROM (
    SELECT
        email_id,
        ai_extract(email_body, ARRAY('발신자이름', '회사명', '요청사항')) AS extracted
    FROM inbox_emails
);

-- 계약서에서 핵심 조건 추출
SELECT
    contract_id,
    ai_extract(
        contract_text,
        ARRAY('계약금액', '계약기간', '갱신조건', '해지조건', '위약금')
    ) AS terms
FROM contracts;

-- 뉴스에서 구조화된 정보 추출
SELECT
    ai_extract(
        article_text,
        ARRAY('기업명', '인물', '금액', '날짜', '장소', '사건유형')
    ) AS entities
FROM news_articles;
```

***

## ai\_gen() — 텍스트 생성

주어진 컨텍스트를 기반으로 새로운 텍스트를 생성합니다.

### 예시

```sql theme={null}
-- 상품 설명 자동 생성
SELECT
    product_id,
    product_name,
    ai_gen(
        CONCAT('다음 상품의 매력적인 한국어 마케팅 문구를 100자 이내로 작성해 주세요. ',
               '상품명: ', product_name,
               ', 카테고리: ', category,
               ', 주요 특징: ', features)
    ) AS marketing_copy
FROM products;

-- 데이터 기반 인사이트 생성
SELECT
    region,
    total_revenue,
    yoy_growth,
    ai_gen(
        CONCAT('다음 지역 매출 데이터에 대한 분석 코멘트를 한국어 2문장으로 작성해 주세요. ',
               '지역: ', region,
               ', 매출: ', FORMAT_NUMBER(total_revenue, 0), '원',
               ', 전년대비 성장률: ', ROUND(yoy_growth * 100, 1), '%')
    ) AS analyst_comment
FROM regional_sales_summary;

-- 번역
SELECT
    doc_id,
    ai_gen(CONCAT('Translate the following text to Korean:\n\n', english_text)) AS korean_text
FROM english_documents;
```

***

## ai\_parse\_document() — 문서 파싱

PDF, DOCX, PPTX, 이미지 등의 비정형 문서에서 텍스트를 추출합니다.

### 문법

```sql theme={null}
ai_parse_document(
    path,               -- Volume 내 파일 경로 (STRING)
    mode                -- 'text' 또는 'markdown' (추출 형식)
)
```

### 예시

```sql theme={null}
-- PDF에서 텍스트 추출
SELECT ai_parse_document(
    '/Volumes/catalog/schema/contracts/agreement_2025.pdf',
    'text'
) AS parsed_text;

-- Markdown 형식으로 추출 (제목, 표 등 구조 유지)
SELECT ai_parse_document(
    '/Volumes/catalog/schema/reports/quarterly_report.pdf',
    'markdown'
) AS parsed_markdown;

-- Volume의 여러 파일을 일괄 파싱
SELECT
    file_name,
    ai_parse_document(
        CONCAT('/Volumes/catalog/schema/documents/', file_name),
        'markdown'
    ) AS content
FROM (
    SELECT file_name FROM LIST('/Volumes/catalog/schema/documents/')
    WHERE file_name LIKE '%.pdf'
);

-- 파싱 후 AI 분석 연결 (파싱 → 요약 파이프라인)
WITH parsed AS (
    SELECT
        file_name,
        ai_parse_document(
            CONCAT('/Volumes/catalog/schema/docs/', file_name), 'text'
        ) AS content
    FROM document_list
)
SELECT
    file_name,
    ai_query(
        'databricks-meta-llama-3-3-70b-instruct',
        CONCAT('다음 문서를 5줄로 요약해 주세요:\n\n', content)
    ) AS summary,
    ai_classify(content, ARRAY('계약서', '보고서', '제안서', '매뉴얼')) AS doc_type,
    ai_extract(content, ARRAY('작성자', '작성일', '주요키워드')) AS metadata
FROM parsed;
```

### 지원 파일 형식

| 형식         | 확장자                     | 설명                             |
| ---------- | ----------------------- | ------------------------------ |
| PDF        | `.pdf`                  | 텍스트 기반 및 스캔된 PDF 모두 지원합니다      |
| Word       | `.docx`                 | Microsoft Word 문서입니다           |
| PowerPoint | `.pptx`                 | Microsoft PowerPoint 프레젠테이션입니다 |
| 이미지        | `.png`, `.jpg`, `.tiff` | OCR로 텍스트를 추출합니다                |
| HTML       | `.html`                 | 웹 페이지 내용을 추출합니다                |

***

***

## 참고 링크

* [Databricks: ai\_query()](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_query.html)
* [Databricks: ai\_classify()](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_classify.html)
* [Databricks: ai\_extract()](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_extract.html)
* [Databricks: ai\_gen()](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_gen.html)
* [Databricks: ai\_parse\_document()](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_parse_document.html)