> ## 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 함수

> **핵심 메시지**: "Genie Code의 AI 함수(ai\_parse\_document·ai\_extract·ai\_query)로, 정형 SQL로는 답하지 못하던 '왜'를 비정형 데이터에서 캔다."

> **이 모듈 한눈에**
>
> * **목적** — 정형 SQL로는 다루기 힘든 비정형 데이터(필드리턴 텍스트·8D PDF·AOI 이미지)를 AI 함수로 구조화·분석합니다.
> * **다루는 소스** — `bronze.field_returns`, `bronze.raw_files` 볼륨(8D PDF·AOI 이미지).
> * **생성물** — `silver.parsed_8d_reports`, `gold.quality_8d_structured`, `gold.field_return_insights` 등 AI Ready Data.

### 이 모듈에서 사용하는 Databricks 기능

| 기능 | 설명 | 공식 문서 |
| - | - | - |
| **SQL AI 함수 (Databricks Document Intelligence)** | SQL 한 줄로 LLM을 호출해 비정형 데이터를 정형화하는 내장 AI 함수 브랜드. | [docs](https://docs.databricks.com/en/large-language-models/ai-functions.html) |
| **`ai_query`** | 임의의 서빙 엔드포인트(LLM/Vision)를 SQL에서 직접 호출. 이미지·긴 프롬프트도 처리. | [docs](https://docs.databricks.com/en/sql/language-manual/functions/ai_query.html) |
| **`ai_classify`** | 텍스트를 주어진 레이블 집합으로 분류. | [docs](https://docs.databricks.com/en/large-language-models/ai-functions.html) |
| **`ai_extract`** | 텍스트에서 지정한 항목(엔티티)을 구조화 추출. | [docs](https://docs.databricks.com/en/large-language-models/ai-functions.html) |
| **`ai_gen` / `ai_summarize`** | 생성/요약. 자유형 지시. | [docs](https://docs.databricks.com/en/large-language-models/ai-functions.html) |
| **`ai_parse_document`** | PDF/문서를 텍스트·구조(표/섹션)로 파싱. | [docs](https://docs.databricks.com/en/large-language-models/ai-functions.html) |
| **Agent Bricks Foundation Model API** | 위 AI 함수들이 호출하는 관리형 파운데이션 모델 엔드포인트. Claude·Llama·GTE 등. | [docs](https://docs.databricks.com/en/machine-learning/foundation-models/index.html) |

## 개요

지금까지(모듈 2\~5)는 **정형 데이터**(수율·불량·OEE 수치)를 다뤘습니다. 하지만 현장 지식의 상당 부분은 **비정형**입니다 — 필드 리턴 리포트의 증상 서술, 8D 품질 리포트 PDF, 설비/공정 SOP 문서, AOI 불량 이미지.

이 모듈에서는 SQL **AI 함수**로 비정형을 정형화·분류·추출하여, 대시보드·Genie·RAG가 소비할 수 있는 **AI Ready Data**로 만듭니다.

| 다룰 비정형 | 소스 | AI 함수 |
| - | - | - |
| 필드 리턴 증상/분석 (자연어) | `bronze.field_returns` | `ai_classify`, `ai_extract`, `ai_summarize` |
| 8D 품질 리포트 (PDF) | `bronze.raw_files` 볼륨 | `ai_parse_document` → `ai_extract` |
| AOI 불량 이미지 | `bronze.raw_files` 볼륨 | `ai_query` (Vision LLM) |

> 이 모듈의 산출물(정형화된 인사이트, 파싱된 문서)은 **[모듈 7 Agent Bricks](07-agent-bricks)** 의 Knowledge Assistant 지식 소스가 됩니다.

> **Tip**: AI 함수는 서빙 엔드포인트를 호출하므로 과금됩니다. **항상 `LIMIT`으로 소량 테스트 후** 전체에 적용하세요.

***

## Part 0: 사전 점검 — Foundation Model 엔드포인트 확인

AI 함수는 내부적으로 Foundation Model 서빙 엔드포인트를 호출합니다. 시작 전에 이 워크스페이스에서 해당 엔드포인트를 쓸 수 있는지 짧게 확인합니다.

**1단계 —** 엔드포인트 사용 가능 여부 확인.

```
이 워크스페이스에서 AI 함수가 호출하는 Foundation Model 엔드포인트(예: databricks-claude-sonnet-4, databricks-gte-large-en)가 사용 가능한지, 내가 조회/호출할 권한이 있는지 확인해줘. 사용 가능한 서빙 엔드포인트 목록을 보여줘.
```

> 사용 가능한 엔드포인트가 없거나 권한이 없으면, 아래 실습의 모델 이름을 워크스페이스에서 실제 쓸 수 있는 엔드포인트로 바꾸거나 강사에게 문의하세요.

***

## Part A: 텍스트 AI 함수 — 필드 리턴 분석

`field_returns.failure_symptom`(자연어 증상)과 `analysis_result`(자연어 분석)를 AI로 분류·추출합니다.

> **왜 SQL에서 LLM을 부르나?** AI 함수는 데이터가 이미 있는 테이블 위에서 SQL 한 줄로 LLM을 호출합니다. 별도로 데이터를 추출해 파이썬 파이프라인이나 모델 엔드포인트를 직접 관리하지 않고도, 분류·추출·요약 결과를 곧바로 새 컬럼으로 얻습니다.

### A-1. 데이터 훑어보기

```
@ccm_factory.bronze.field_returns에서 failure_symptom, analysis_result, root_cause_code를
10건만 보여줘. 어떤 자연어 텍스트가 들어있는지 확인하고 싶어.
```

### A-2. `ai_classify` — 증상을 근본원인 카테고리로 분류

`ai_classify`는 텍스트를 **미리 정한 레이블 집합 중 하나로 분류**하는 함수입니다. 여기서는 자연어 증상 텍스트를 근본원인 카테고리로 자동 태깅합니다.

Genie Code에 한 번에 하나씩 덧붙여 요청하면 SQL AI 함수를 생성·실행합니다:

**1단계 —** 최소 분류부터.

```
@ccm_factory.bronze.field_returns의 failure_symptom(한국어 증상 텍스트)을 ai_classify로 분류해줘. 우선 LIMIT 20으로 테스트.
```

**2단계 —** 근본원인 카테고리 지정.

```
근본원인 카테고리는 다음 5개 중 하나로: ALIGNMENT, ACTUATOR, BONDING, CONTAMINATION, SENSOR.
```

**3단계 —** 출력 컬럼·SQL 확인.

```
결과 컬럼은 rma_id, failure_symptom, 기존 root_cause_code, ai_predicted_cause로. 실제 사용할 SQL도 보여줘.
```

생성될 SQL 형태(참고):

```sql theme={null}
SELECT
  rma_id,
  failure_symptom,
  root_cause_code,
  ai_classify(failure_symptom,
    ARRAY('ALIGNMENT','ACTUATOR','BONDING','CONTAMINATION','SENSOR')
  ) AS ai_predicted_cause
FROM ccm_factory.bronze.field_returns
LIMIT 20
```

### A-3. `ai_extract` — 구조화 추출

`ai_extract`는 자유 형식 텍스트에서 **지정한 항목(엔티티)을 뽑아 구조화**하는 함수입니다. 흩어진 서술형 문장을 분석 가능한 필드로 바꿉니다.

**1단계 —** 결합 텍스트에서 추출 시작.

```
field_returns의 failure_symptom과 analysis_result를 결합한 텍스트에서 ai_extract로 항목을 뽑아줘. 우선 LIMIT 20.
```

**2단계 —** 추출 스키마 지정.

```
추출 항목은 3개: symptom(증상), defect_location(불량 부위), suspected_cause(의심 원인).
```

**3단계 —** 출력·SQL.

```
결과를 표로 보여주고 SQL도 알려줘.
```

참고 SQL:

```sql theme={null}
SELECT
  rma_id,
  ai_extract(
    CONCAT(failure_symptom, ' / ', analysis_result),
    ARRAY('symptom', 'defect_location', 'suspected_cause')
  ) AS extracted
FROM ccm_factory.bronze.field_returns
LIMIT 20
```

### A-4. `ai_summarize` — 모델별 리턴 요약

`ai_summarize`는 긴 텍스트를 **지정한 길이로 요약**하는 함수입니다. 여러 건의 증상 서술을 모델별로 묶어 핵심만 압축합니다.

**1단계 —** 모델별 요약 시작.

```
모델(model_code)별로 최근 필드 리턴 증상들을 ai_summarize로 간결하게 요약해줘(요약 길이는 단어 수 인자로 제어). Global_A 고객 모델 위주로 LIMIT 10.
```

**2단계 —** 출력 컬럼 지정.

```
결과는 model_code, return_count, summary 컬럼으로 보여줘.
```

### A-5. 검증 — AI 분류 vs 기존 root\_cause\_code 일치율

**1단계 —** 전체 일치율부터.

```
방금 ai_classify로 예측한 ai_predicted_cause와 기존 root_cause_code의 전체 일치율(%)을 계산해줘.
```

**2단계 —** 혼동행렬·오분류 쌍.

```
이어서 카테고리별 혼동행렬(confusion matrix)과 가장 자주 틀리는 카테고리 쌍도 보여줘.
```

**3단계 —** 원인 추정.

```
불일치가 많으면 원인(레이블 정의 모호 등)도 추정해줘.
```

> 💡 **AI 결과에 도전하기**
>
> * 일치율이 낮은 카테고리는 **레이블 문자열 자체에 정의를 포함**(예: `'ACTUATOR = VCM/OIS 액추에이터 불량'`)해 재실행하면 개선됩니다.
> * 레이블을 단순 코드가 아니라 "코드 = 설명" 형태로 넘겨 모델이 각 카테고리의 의미를 알게 하는 방식입니다.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.