1. AUC (Area Under the Curve) 의미: 모델이 "사용자가 이 아이템을 좋아할 것인가?"를 예측하는 전체적인 정확도를 나타냅니다. 해석: 1에 가까울수록 모델이 긍정적인 반응(클릭 등)과 부정적인 반응을 아주 잘 구분해낸다는 뜻이에요.
2. UAUC (User-specific AUC) 의미: '개인화' 성능을 측정하는 핵심 지표로, 각 사용자별로 AUC를 계산한 뒤 그 값들을 평균 낸 것입니다. 중요성: 전체 평균만 보는 AUC와 달리, 사용자 한 명 한 명의 고유한 취향을 얼마나 잘 맞췄는지를 보여줍니다. 결과: ARROW는 특히 이 UAUC 지표에서 기존 모델들보다 큰 향상을 보였는데, 이는 ARROW의 추론 방식이 개별 사용자의 복잡한 선호도를 깊이 있게 이해하고 있음을 증명합니다.
3. NDCG (Normalized Discounted Cumulative Gain) 의미: 추천된 리스트의 '순위(Ranking)'가 얼마나 정확한지를 평가합니다. 해석: 사용자가 정말 좋아할 만한 아이템이 추천 리스트의 상단(앞부분)에 위치할수록 점수가 높게 나옵니다. 즉, "좋은 걸 먼저 보여줬는가"를 측정하는 지표예요. 요약하자면,

AUC: "전체적으로 잘 맞췄니?" UAUC: "개개인의 취향을 존중했니?" (ARROW의 강점!) NDCG: "가장 좋아하는 걸 맨 앞에 뒀니?"

: 데이터가 평균을 중심으로 얼마나 흩어져 있는지를 표현하는 개념

각 값과 평균 사이의 거리를 제곱한 후 합산한 값 / 데이터 개수

: 분산은 제곱된 단위다 보니 해석하기 어려운 면이 있어서 제곱근을 씌운 표준 편차를 사용

표준 편차, Standard Deviation

: 분산의 제곱 근

평균, 표준 편차

표본의 평균 : 모집단의 평균을 추정

표준 편차 : 추정의 정확성을 판단

모수와 통계량

추론 통계 : 표본의 특성을 바탕으로 모집단의 특성을 추론하는 과정

모수, Parameter

: 모집단의 특성을 나타내는 수치

통계량, Statistic

: 표본의 특성을 나타내는 수치

추론 통계

: 표본의 통계량으로 모수를 추정하는 과정

모평균 : 모집단의 평균 표본평균 : 표본의 평균

표본을 통한 모집단의 추정

1. 모집단에서 표본을 추춣해 표본의 값을 관찰한다
2. 관찰된 결과가 특정 모집단 아래에서 어느 정도의 확률로 나타날 수 있는지 생각한다.
3. 데이터의 배후에 있는 모집단에 대해 추정한다

" 불확실성을 인정하고 가장 확률이 높은 쪽으로 추정하는 사고방식 "

확률 변수, Random Variable

: 특정 상황에서 발생할 수 있는 결과를 숫자로 표현하는 규칙 ex) 동전 던지기의 경우 앞면을 1, 뒷면을 0으로 표현하면 그게 확률변수가 됨.

이산확률변수, Discrete Random Variable : 동전던지기, 주사위 던지기 처럼 값이 딱딱 떨어지는 경우

연속확률변수, Continous Random Variable : 사람의 키처럼 연속적인 경우

정규분포, Normal Distribution(보통의 분포)

(가우스 분포, Gaussian Distribution)

중심극한정리, CLT, Central Limit Theorem : 모집단의 분포와 관계없이, 이 모집단에서 추출된 표본의 크기가 충분히 크다면 반복적으로 추출된 표본평균의 분포는 정규분포에 가까워진다.

표본의 크기 : 표본에 포함된 data의 수 보통 30개 이상이면 충분히 크다고 판단

표본이 충분히 크다면 그 표본 자체의 분포가 정규분포에 가까워진다는 뜻이 아님.

모집단에서 표본을 여러 번 뽑으면 각 표본마다 평균이 다를 텐데 그 표본평균들의 분포가 정규분포를 따른다는 얘기임.

1. 표본의 크기가 커질수록 수집된 표본의 평균이

2. 중심극한정리에 의해 모평균 u에 가까워 진다는 것임.

-> 이 개념이 바로 추론 통계의 핵심 원리.

중심극한정리

1. 모집단에서 표본을 여러 번 뽑고

2. 그 표본들의 평균을 모으면 평균이 모평균 u이고

3. 표준편차가 시그마/루트n 인 정규분포에 가까워짐.

-> 통계학에서는 표본평균의 표준편차를 부르는 용어가 '표준오차'

표준오차, Standard Error

: 표본평균이 모평균에서 얼마나 떨어져 있는지 간접적으로 보여주는 지표

-> 표본평균의 표준편차니까, 특정 표본의 평균이 모평균에서 얼마나 떠ㅓㄹ어져 있는지를 간접적으로 보여 주는 지표가 됨.

그럼 표본을 하나 뽑았을 ㄹ때 표본평균과 표준 오차를 알면 모평균이 어디쯤 있는지 추정할 수 있음

(문제가 있음) 중심극한정리에서 봤듯 이론적으로 평균의 표준오차는 시그마/루트n 으로 계산됨

But, 모집단은 우리가 모르기 때문에 알고 싶은 대상임.

그래서 보통은 모집단의 표준편차인 시그마 대신, 표본의 표준편차인 s를 사용해서 추정함

표본의 크기가 클수록, 표준편차가 작을수록

표준오차가 작아짐 표준오차가 작다는 건

표본평균이 모평균에 가까이 있을 확률이 높다는 뜻.

? 구체적으로 표본평균이 모평균과 얼마나 가까이 있는지는 어떻게 표현가능한가? -> '신뢰구간' 개념을 배워야함

신뢰구간, Confidence Interval

: 모집단의 값이 포함될 것으로 예상되는 구간을 뜻함 보통 '몇 % 신뢰구간'이라고 이야기함

95% 신뢰구간 : 이 방식으로 구간을 여러 번 구할 때, 그 구간이 모집단의 값을 포함할 확률이 95%이다

평균에 대한 85% 신뢰구간

1. JupyterLab 실행

cd /Users/moon/Desktop/lecture/codeit/data_science
jupyter lab

설명: JupyterLab 실행 (브라우저 자동 열림)

2. 매일 Git 명령어 순서

각 명령어 자세한 설명

git status

현재 상태 확인 (가장 먼저!)

예: On branch main
  Changes not staged for commit:
    modified:   lecture_02.ipynb

git add .

📂 현재 폴더 모든 변경파일 준비

git add lecture_02.ipynb  ← 특정 파일만

git commit -m "Lecture 02 - Data Preprocessing"

📸 변경사항을 스냅샷으로 저장 + 제목

좋은 커밋 메시지:

git commit -m "Lecture 02 - Pandas 데이터 전처리"
git commit -m "Lecture 03 - Matplotlib 시각화 추가"

git push

☁️ 로컬 스냅샷 → GitHub 업로드

처음 한 번만: git push -u origin main

📋 매일 체크리스트

✅ 1. cd /Users/moon/.../data_science
✅ 2. jupyter lab
✅ 3. 새 노트북: lecture_XX.ipynb
✅ 4. 강의 코드 작성 → Ctrl+S
✅ 5. Git 탭 → Terminal:
     git status
     git add .
     git commit -m "Lecture XX - 제목"
     git push
✅ 6. GitHub.com 확인

⚠️ 주의사항

1. .gitignore 덕분에 .DS_Store 등 자동 무시됨
2. data/ 폴더는 강의 데이터셋 → 그대로 유지
3. 매일 커밋 메시지는 "Lecture XX - 주제" 형식 추천

🔄 업데이트 예시

Day 1: git commit -m "Lecture 01 - Introduction"
Day 2: git commit -m "Lecture 02 - Pandas basics"  
Day 3: git commit -m "Lecture 03 - Data visualization"

git add .           → "변경된 파일들을 준비함"
git commit -m " "   → "변경사항을 사진 찍어서 저장함"  
git push            → "내 사진을 GitHub에 업로드함"

git add .

📂 현재 폴더의 모든 변경된 파일을 "준비 목록"에 올림
✅ 1.ipynb, data/ 폴더, .DS_Store 등을 준비

git commit -m "first"

📸 준비된 파일들을 "스냅샷"으로 저장 + 설명 "first" 추가
✅ 6개 파일 변경사항 기록 (해시: 73eba50)

git push

☁️ 내 스냅샷을 GitHub(원격 저장소)로 업로드

2. git push -u origin main 뜻

git push                    → 스냅샷 업로드
-u (set-upstream)           → "앞으로 이 브랜치와 자동 연결"
origin                      → GitHub 저장소 이름
main                        → 브랜치 이름

처음 한 번만 -u 필요! 이후엔 git push만 써도 자동 업로드.

3. 네 git push 결과 해석

오브젝트 나열하는 중: 10, 완료.           → 10개 파일 준비
오브젝트 개수 세는 중: 100% (10/10)       → 10개 모두 확인
Delta compression using up to 12 threads   → M4 Pro 12코어 압축
오브젝트 압축하는 중: 100% (9/9)          → 9개 압축 완료
Total 9 (delta 1), reused 0               → 9개 업로드 (1개 최적화)
remote: Resolving deltas: 100% (1/1)      → GitHub 처리 완료

To https://github.com/moon-gh/data_science.git
   355c861..73eba50  main -> main          → 성공! (73eba50 커밋 업로드)
branch 'main' set up to track 'origin/main' → 자동 연결 완료!

4. GitHub 화면 확인

새로고침하면:

✅ 1.ipynb 업로드됨!
✅ data/burger.csv 등 4개 데이터 파일
✅ 커밋 "first" (73eba50)

5. 앞으로 워크플로우 (매일)

1. 새 노트북: lecture_02.ipynb
2. 코드 작성 → Ctrl+S
3. 3단계:
   git add .
   git commit -m "Lecture 02"
   git push    ← -u는 처음만!

6. 정리

✅ git add .     = 파일 준비
✅ git commit    = 스냅샷 저장  
✅ git push      = GitHub 업로드
✅ -u origin main = 처음 한 번만 (자동 연결)

강의용 Git 완벽 마스터! 이제 매일 노트북 만들고 git push만 하면 GitHub에 자동 업로드돼.

각 명령어와 옵션의 상세 설명 (Git 처음 사용자 기준):

1. rm .DS_Store LICENSE README.md

rm = "Remove" (파일 삭제 명령어)
.DS_Store = macOS가 자동 생성하는 쓰레기 파일
LICENSE = 소프트웨어 라이선스 파일 (강의용엔 불필요)
README.md = 프로젝트 설명 파일 (임시로 삭제)

결과: 로컬 폴더에서 3개 파일 삭제됨

2. cat > .gitignore << EOF ~ EOF

cat > 파일명 = 새 파일에 내용 쓰기
.gitignore = "Git이 무시할 파일 목록"
<< EOF ~ EOF = "여기까지 여러 줄 내용을 파일에 넣기"

.gitignore 각 줄 설명:

# OS (macOS 불필요 파일)
.DS_Store           = macOS Finder가 만드는 숨김 파일
.DS_Store?          = macOS 다른 숨김 파일들

# Jupyter (노트북 임시 파일)
.ipynb_checkpoints/ = Jupyter가 저장할 때 백업 폴더
*.ipynb_checkpoints = 모든 Jupyter 임시 파일 무시

# Python (실행 후 생성 파일)
__pycache__/        = Python 컴파일된 캐시 폴더
*.py[cod]           = .pyc, .pyo 컴파일 파일들
*$py.class          = Java/Python 혼합 클래스 파일

# Environments (가상환경)
.env                = 환경변수 파일 (비밀번호 등 민감정보)
.venv               = Python 가상환경 폴더
env/                = 다른 가상환경 폴더들
venv/               = pip 가상환경 폴더들

.env, .venv 설명:

• .env = API키, 비밀번호 등 민감정보 저장 파일 (GitHub에 절대 올리면 안됨!)
• .venv, venv/ = Python 가상환경 폴더들 (conda 환경과는 다름)

3. git add .gitignore

.gitignore을 "Git 준비 목록"에 추가
"이제부터 이 무시 설정을 추적하자!"

4. git rm --cached .DS_Store LICENSE README.md

git rm = Git에서 파일 삭제
--cached = "로컬 파일은 남기고 Git 추적만 중지"
.DS_Store 등 = 이미 커밋된 불필요 파일들

--cached 핵심:

❌ 일반 git rm: 로컬 + Git 둘 다 삭제
✅ git rm --cached: 로컬은 남기고 Git 추적만 삭제

왜 필요한가?

• 이미 git add . → git commit → git push로 GitHub에 올라간 파일
• 새 .gitignore 설정 후에도 GitHub에는 계속 보임
• git rm --cached로 GitHub에서만 삭제

5. git commit -m "Clean up: ..."

commit = 변경사항을 "스냅샷"으로 저장
-m = 메시지 추가
"Clean up: remove unnecessary files, update gitignore" = 커밋 설명

6. git push

로컬 스냅샷을 GitHub로 업로드

전체 흐름 요약

1. rm 파일들           → 로컬에서 삭제
2. .gitignore 생성     → 앞으로 무시할 파일 설정
3. git add .gitignore  → 무시 설정 파일 저장
4. git rm --cached     → GitHub에서만 불필요 파일 삭제 (로컬은 이미 삭제됨)
5. git commit          → 변경사항 스냅샷 저장  
6. git push            → GitHub에 반영

최종 GitHub 결과:

✅ 1.ipynb (네 노트북)
✅ data/ 폴더
✅ .gitignore (깔끔)
❌ .DS_Store, LICENSE, README.md (삭제됨)

이해했으면 Terminal에서 실행하고 GitHub 결과 알려줘!
강의용 깔끔한 저장소 완성하자 🚀

임베딩 차원 수, 제대로 고르기 — 384 vs 768 vs 1024

“임베딩 차원이 높을수록 무조건 좋을까?” RAG/검색/추천에서 자주 받는 질문을, 숫자·차원·메모리·속도 중심으로 정리했습니다.

TL;DR

• 차원 수(=d) 는 한 문장을 표현하는 벡터 좌표의 길이. 예: SBERT 768차원 → 길이 768의 실수 벡터.

• 차원이 높으면 표현력↑(미세한 의미 구분), 하지만 메모리·연산비용·“허브니스(hubness)” 리스크↑.

• 차원이 낮으면 메모리·속도↑(빠름), 하지만 정보 손실로 성능↓ 가능.

• 실무 기준:

  • 문서 수 적고 속도 여유 → 768~1024
  • 대규모(≥ 수백만)·지연 민감 → 384~512 + 2단계 검색(저차원 1차 후보 + 고차원 재랭크)
  • Elasticsearch 사용 시 dense_vector.dims == 모델 차원 꼭 맞추기.

1) 임베딩 차원이란?

• 한 문장/청크를 d차원 실수 벡터로 매핑한 결과의 길이(d). 예) snunlp/KR-SBERT-... → 768차원
• 이 d는 모델이 학습 중 “의미를 담을 수 있는 용량(표현력)”과 연관.

직관:

• d가 크면 더 많은 “축”으로 의미를 분해해 담을 수 있음 (세밀한 구분).
• d가 작으면 압축이 심해져 서로 다른 의미가 섞일 수 있음(충돌/정보손실).

2) 차원 수가 클수록 생기는 일

장점

• 표현력/세분화↑: 유사하지만 다른 개념을 더 잘 분리(특히 다국어, 도메인 다양, 문맥 복잡).
• 충분한 학습 데이터가 있으면 일반화 성능↑(문장 의미의 다양한 측면을 담을 수 있음).

단점

• 메모리·스토리지↑: N개 문서면 저장량이 ≈ N × d × 4byte(float32) 로 증가.
• 거리 계산 비용↑: ANN/Brute-force 모두 연산량이 d에 선형으로 증가.
• Hubness↑: 고차원에서 특정 벡터가 **과도하게 “가까운 이웃”**으로 자주 등장하는 현상 → 검색 랭킹이 왜곡될 수 있음.
• 데이터가 적을수록 과적합 위험: d가 크면 모델/인덱스가 “잡음”까지 설명하려고 함.

3) 차원 수가 작을수록 생기는 일

장점

• 빠름 & 가벼움: 도커/서버리스/모바일 등에서 유리.
• 대규모 인덱스 운영 비용↓: 메모리/디스크·네트워크 전송량↓, 캐시 효율↑.

단점

• 정보 손실: 문장 의미의 중요한 축이 사라져 정확도/재현율 저하 가능.
• 도메인 다양성이 큰 경우 분리 한계.

4) 언젠가 들어본 그 법칙: “차원(d) vs 데이터 수(n)”

• 이론적으로, 거리(유사도)를 보존하려면 필요한 차원 수가 대략 데이터 수의 로그에 비례(존슨–린덴스트라우스 류의 직관).
• 하지만 학습된 임베딩은 단순 랜덤 투영이 아니기 때문에, 이 법칙은 엄밀한 규칙이라기보단 감각으로만 참고.

실무 감

• n이 아주 크다(≥ 수백만) → d를 너무 크게 잡으면 비용이 눈덩이.
• n이 중간(수만~수십만) → 384~768선에서 “성능 vs 비용”의 엘보(elbow) 지점을 찾아 실험.
• n이 작다(≤ 수천~수만) → 768도 무난. 다만 과적합·허브니스는 체크.

5) 메모리 & 속도, 숫자로 감 잡기

저장량(대략)

• 공식: N × d × 4 bytes (float32 가정)

예) N = 100,000 문서

• d=384 → 100,000 × 384 × 4 = 153,600,000 bytes ≈ 146.5 MB
• d=768 → 100,000 × 768 × 4 = 307,200,000 bytes ≈ 293.0 MB
• d=1024 → 100,000 × 1024 × 4 = 409,600,000 bytes ≈ 390.6 MB

팁:

• float16(2 bytes)나 **양자화(quantization, PQ/OPQ/INT8)**를 쓰면 절반 이하로 줄일 수 있음(검색 정확도 하락과 트레이드오프).
• Elasticsearch dense_vector는 내부 구현 제약이 있어 저정밀도 저장/양자화는 보통 FAISS/HNSW 라이브러리가 더 유연함.

연산(대략)

• 코사인/내적 1회 비용 ∝ d.
• KNN(HNSW)도 후보 간 거리 계산량이 d에 비례 → d가 두 배면 대략 연산량도 두 배로 본다(상수항 제외).

6) 언제 차원을 키우고/줄일까 (의사결정 표)

7) Elasticsearch에서의 포인트

• dense_vector의 dims는 임베딩 길이와 반드시 같아야 색인됨.

• Cosine 쓰려면 L2 정규화 권장(정규화 후 dot = cosine).

• 대규모·지연 민감이면 knn_vector + HNSW(근사 KNN) 고려.

• 스코어링 예시(정규화되어 있다면):

  "script": {
    "source": "cosineSimilarity(params.q, 'embedding') + 1.0",
    "params": {"q": [ ... 768 floats ... ]}
  }

• 두 단계 검색:

  1. knn_vector(저차원 or 양자화)로 Top-k 후보
  2. 후보에 대해 고차원 벡터 혹은 Cross-Encoder로 재랭크

8) 차원을 “바꿔보며” 성능-비용 곡선 보기 (실험 프로토콜)

1. 기준 임베딩(예: 768) 만들기
2. PCA로 차원 축소(예: 128/256/384/512)
3. 동일 인덱싱 조건에서 Recall@k / NDCG@k / MRR 측정
4. 엘보 지점(성능 크게 떨어지지 않으면서 비용 낮은 지점)을 채택
5. 필요한 경우 두 단계 검색으로 타협

from sklearn.decomposition import PCA
import numpy as np

base_vecs = ...  # (N, 768)
for d in [128, 256, 384, 512]:
    pca = PCA(n_components=d, random_state=42)
    vecs_d = pca.fit_transform(base_vecs)  # (N, d)
    # 1) 이 vecs_d로 인덱싱
    # 2) 동일한 쿼리셋으로 Recall@10, NDCG@10 측정
    # 3) 비용/성능 비교해 선택

PCA는 “기존 768을 줄였을 때”의 실험용. 실제론 저차원 모델 자체를 쓰는 편이 관리가 쉬움(예: MiniLM 384).

9) 차원과 관련된 자주 하는 실수 체크리스트

• ⛔ 모델 바꿨는데 ES dims 안 바꿈 → 색인 에러

• ⛔ 임베딩 정규화 없이 cosine → 스코어 뒤틀림

• ⛔ 메타데이터 타입 충돌(문서마다 같은 키인데 숫자/문자 섞임) → 색인 실패

• ⛔ Hubness 무시 → 일부 문서가 과도하게 상위에 노출

  • ↳ 완화: 정규화, 차원 축소, 거리 보정(상호근접도/Mutual Proximity) 등

10) 코드 스니펫 모음

(A) 차원 자동 감지 → ES 매핑 자동 설정

from langchain_community.embeddings import HuggingFaceEmbeddings
from elasticsearch import Elasticsearch

model_name = "snunlp/KR-SBERT-V40K-klueNLI-augSTS"
emb = HuggingFaceEmbeddings(model_name=model_name)

probe = emb.embed_query("차원 확인")
dim = len(probe)  # 예: 768

es = Elasticsearch("http://localhost:9200")
index = "my_index"

if es.indices.exists(index=index):
    es.indices.delete(index=index)

es.indices.create(
    index=index,
    mappings={
        "properties": {
            "text": {"type": "text", "analyzer": "nori"},
            "embedding": {"type": "dense_vector", "dims": dim}
        }
    }
)
print("dims =", dim)

(B) L2 정규화 후 색인 (cosine 안정화)

import numpy as np

def l2norm(v):
    v = np.asarray(v, dtype=np.float32)
    n = np.linalg.norm(v)
    return (v / n).tolist() if n else v.tolist()

vecs = [l2norm(v) for v in emb.embed_documents(texts)]
# vecs를 embedding으로 색인하면, dot == cosine

(C) 2단계 검색(개념)

[낮은 차원 / 양자화 인덱스] --Top200--> [고차원 ES/FAISS] --Topk-->
[Cross-Encoder Rerank(Optional)] --Topk-->

11) 추천 선택지(요약)

• 한국어 문단 중심 RAG + 문서 수: 수만~수십만 → 768차원 무난

• 문서 수: 수백만+ & 지연 엄격 → 384~512 + 2단계 검색

• 메모리/비용 제한 → 256~384 + 양자화 고려

• 결과가 마음에 안 들면, 차원만 바꾸지 말고

  • 모델 변경(학습 데이터/도메인 적합성)
  • 청크 전략(분량/오버랩/레이아웃)
  • 리랭킹(크로스인코더)까지 함께 조정

마무리

임베딩 차원은 “성능 vs 비용”의 손잡이입니다. 데이터 크기, 지연 요구사항, 도메인 복잡성을 동시에 보고, 작은 실험으로 엘보 지점을 찾는 게 가장 빠른 길이에요. 필요하면, 현재 쓰는 인덱스 규모/응답 시간 목표 알려주면 권장 차원 + 인덱싱 전략까지 구체적으로 짜 드릴게!

태그: LangChain, SemanticChunker, SentenceTransformer, AttributeError, HuggingFaceEmbeddings

1. 들어가며: 문제 상황 겪기

최근 RAG(Retrieval-Augmented Generation) 파이프라인의 성능을 높이기 위해, LangChain에서 제공하는 SemanticChunker를 도입하는 과정에서 흥미로운 오류를 만났습니다.

의미 기반으로 텍스트를 분할하기 위해 sentence-transformers 라이브러리로 한국어 임베딩 모델을 불러와 SemanticChunker에 전달했는데, 아래와 같은 에러가 발생했습니다.

AttributeError: 'SentenceTransformer' object has no attribute 'embed_documents'

분명 임베딩 모델 객체를 넘겨줬는데, 왜 embed_documents라는 속성이 없다는 오류가 발생했을까요? 이 글에서는 이 문제의 원인을 분석하고, LangChain의 아키텍처를 이해하며 어떻게 해결했는지 그 과정을 공유하고자 합니다.

2. 오류 발생 코드

문제를 일으켰던 코드는 다음과 같습니다. sentence-transformers로 모델을 로드하여 SemanticChunker의 embeddings 인자로 바로 전달했습니다.

from sentence_transformers import SentenceTransformer
from langchain_experimental.text_splitter import SemanticChunker

# 1. sentence-transformers로 임베딩 모델 직접 로드
model_name = "snunlp/KR-SBERT-V40K-klueNLI-augSTS"
embedding_model = SentenceTransformer(model_name)

# 2. SemanticChunker에 그대로 전달
text_splitter = SemanticChunker(
    embeddings=embedding_model, #
    breakpoint_threshold_type="percentile" 
)

# 3. 문서 생성 시도 -> AttributeError 발생!
chunks = text_splitter.create_documents([full_text])

3. 오류의 원인 분석: API 호환성 문제

결론부터 말하면, 이 문제는 **LangChain이 기대하는 '표준 인터페이스'**와 sentence-transformers 라이브러리가 제공하는 객체의 인터페이스가 달라서 발생했습니다.

마치 전기 콘센트와 플러그의 모양이 맞지 않는 것과 같습니다.

**SemanticChunker (콘센트)**는 LangChain 생태계의 부품으로, embed_documents라는 이름의 메소드('세모 모양 플러그')를 가진 임베딩 객체를 받도록 설계되어 있습니다.

**SentenceTransformer 객체 (전자제품)**는 encode라는 메소드('동그란 모양 플러그')를 통해 문장을 임베딩합니다.

SemanticChunker는 embedding_model.embed_documents()를 호출하려고 했지만, 실제 객체에는 embed_documents가 없고 encode만 있으니 AttributeError가 발생한 것입니다.

4. 해결 방법: LangChain 래퍼(Wrapper) 클래스 사용하기

LangChain은 이런 문제를 해결하기 위해 외부 라이브러리를 LangChain 표준에 맞게 감싸주는 래퍼(Wrapper) 클래스를 제공합니다. sentence-transformers를 위한 래퍼가 바로 **HuggingFaceEmbeddings**입니다.

HuggingFaceEmbeddings는 내부에 SentenceTransformer 모델을 품고, 외부에는 LangChain이 알아볼 수 있는 embed_documents 메소드를 노출시켜주는 '모양 변환 어댑터' 역할을 합니다.

수정된 코드

# langchain_community에서 어댑터 역할을 할 래퍼 클래스를 임포트
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_experimental.text_splitter import SemanticChunker

# 1. 사용할 모델 이름 정의
model_name = "snunlp/KR-SBERT-V40K-klueNLI-augSTS"

# 2. SentenceTransformer 대신 HuggingFaceEmbeddings 래퍼 사용
# 이제 embedding_model은 LangChain 표준을 따르는 객체가 됩니다.
embedding_model = HuggingFaceEmbeddings(model_name=model_name)

# 3. SemanticChunker에 호환되는 객체 전달
text_splitter = SemanticChunker(
    embeddings=embedding_model,
    breakpoint_threshold_type="percentile" 
)

# 4. 정상적으로 실행됨!
chunks = text_splitter.create_documents([full_text])

print("성공적으로 청킹 완료!")

5. 결론 및 핵심 요약

이번 오류 해결 과정을 통해 다음과 같은 중요한 점을 배울 수 있었습니다.

LangChain과 같은 프레임워크는 단순히 기능의 집합이 아니라, 정해진 '약속(Interface)'에 따라 각 부품이 유기적으로 연결되는 시스템이다.

외부 라이브러리를 LangChain과 연동할 때는, 해당 라이브러리를 직접 사용하기보다 LangChain이 제공하는 래퍼 클래스가 있는지 먼저 확인하는 습관을 들이는 것이 좋습니다. 이 래퍼들이 바로 서로 다른 모양의 플러그와 콘센트를 연결해주는 고마운 '어댑터'이기 때문입니다.

혹시 저와 같은 AttributeError를 만나신 분들께 이 글이 도움이 되기를 바랍니다.

model="elements"

• PDF내 요소 단위(제목, 본문, 리스트, 표 등)로 잘게 나눠 각각을 별도 Document로 돌려줌.
• model = "single" : PDF전체를 하나의 Document로 변환
• model = "paged" : 페이지 단위로 Document로 변환

strategy="hi_res"

• 고정밀(high-resolution)파이프라인을 사용

• 내부적으로 unstructured라이브러리의 레이아웃감지(딥러닝/컴퓨터비전) + OCR(스캔된 PDF,이미지)을 활용하여 제목/본문/표/리스트 등 블록 수준 구조를 인식.

• 장점 : 표/리스트/섹션 헤더처럼 문서 구조를 더 정확히 파악

• 단점 : 느림, 메모리/의존성 요구 높음.

• 결과적으로 정보 검색(rag)이나 질의응답에서 "문단/표/리스트"등 의미 단위로 청크가 나뉘어 성능이 좋아지는 경우가 많음.

• strategy="fast" : fast: 텍스트 추출 위주(레이아웃 인식은 약함), 빠름

• ocr_only : 무조건 OCR(스캔 위주 문서에 유용, 일반 PDF엔 불리)

documents = loader.load()

• 실제로 PDF를 읽어 List[Document]를 반환.
• model="elements" 이므로 각 요소마다 Document한 개
  • doc.page_content : 해당 블록의 텍스트
  • doc.metadata : source(파일 경로), page_number, category, 등등
• 스캔본/그림만 있는 PDF도 hi_res 덕분에 OCR로 텍스트를 최대한 뽑아냄

• 파이썬 객체를 직렬화(serialize)/ 역직렬화(deserialize) 하는 표준 모듈을 불러옵니다.
• 직렬화 = 메모리 속 객체를 바이트(byte) 형태로 변환해 파일 등에 저장할 수 있게 만드는 것.

# 결과를 pickle 파일로 저장
with open('chunks_baseline.pkl', 'wb') as f:

• 'chunks_baseline.pkl'이라는 파일을 쓰기 모드로(binary) 엽니다.

  • 'wb': write + binary (피클은 텍스트가 아니라 바이너리라서 b 필수)

• with ... as f: 컨텍스트 매니저: 블록이 끝나면 자동으로 파일을 닫아줍니다(에러가 나도 안전하게 닫힘).

    pickle.dump(chunks, f)

• 메모리에 있는 chunks 객체를 피클 형식으로 파일 f에 저장합니다.

• chunks는 미리 만들어져 있어야 합니다(없으면 NameError).

• 프로토콜은 기본값(파이썬 버전에 따라 달라짐)이 사용됩니다. 더 빠르고 작은 최신 포맷을 원하면:

  pickle.dump(chunks, f, protocol=pickle.HIGHEST_PROTOCOL)

print("✅ 'chunks_baseline.pkl' 파일로 저장 완료!")

• 저장이 끝났음을 콘솔에 출력.

추가 팁

불러오는 방법(역직렬화)

import pickle

with open('chunks_baseline.pkl', 'rb') as f:
    chunks_loaded = pickle.load(f)

print(type(chunks_loaded), len(chunks_loaded) if hasattr(chunks_loaded, '__len__') else 'no len')

경로/위치

• 파일은 현재 작업 디렉토리에 저장됩니다. 위치가 헷갈리면:

  import os
  print(os.getcwd())

보안 주의

• 신뢰할 수 없는 소스에서 받은 .pkl을 pickle.load로 열지 마세요. 임의 코드가 실행될 수 있습니다.

용량이 큰 경우 압축 저장

import gzip, pickle
with gzip.open('chunks_baseline.pkl.gz', 'wb') as f:
    pickle.dump(chunks, f, protocol=pickle.HIGHEST_PROTOCOL)

with gzip.open('chunks_baseline.pkl.gz', 'rb') as f:
    chunks_loaded = pickle.load(f)

호환성

• 피클은 파이썬 전용 포맷입니다(다른 언어와 호환 X, 사람이 읽기 어려움).
• 교차 언어/사람 가독성이 필요하면 JSON/CSV 등을 검토하세요(단, 복잡한 파이썬 객체는 JSON으로 바로 저장하기 어려울 수 있음).

## docker run 명령어 상세 설명

우선 전체 명령어는 다음과 같습니다.

docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.10.2

이 명령어를 구성 요소별로 나누어 보면 이렇습니다.

• docker run

  • 가장 기본이 되는 명령어로, Docker에게 "새로운 컨테이너를 하나 만들고 실행해 줘"라고 지시하는 역할을 합니다.

• -d 또는 --detach

  • **"Detached mode"**의 약자입니다. 이 옵션을 사용하면 컨테이너가 백그라운드에서 실행됩니다. 만약 이 옵션을 빼면, 현재 사용 중인 터미널 창이 컨테이너의 로그를 계속 출력하게 되고, 터미널을 닫으면 컨테이너도 함께 종료됩니다. 개발 서버처럼 계속 켜둬야 하는 경우 필수적인 옵션입니다.

• --name elasticsearch

  • 실행되는 컨테이너에 "elasticsearch"라는 고유한 이름을 붙여줍니다. 이름을 지정해두면 나중에 docker stop elasticsearch나 docker logs elasticsearch처럼 이름으로 컨테이너를 제어하기가 매우 편리해집니다.

• -p 9200:9200

  • "Port forwarding" (포트 포워딩) 설정입니다. 콜론(:)을 기준으로 **[내 컴퓨터의 포트]:[컨테이너 내부의 포트]**를 의미합니다.
  • Elasticsearch 컨테이너는 기본적으로 내부 9200번 포트를 사용해 외부와 통신(REST API)합니다. 이 옵션은 내 컴퓨터(호스트 PC)의 9200번 포트로 들어오는 요청을 컨테이너 내부의 9200번 포트로 전달하라는 의미입니다. 그래서 우리가 http://localhost:9200으로 접속할 수 있는 것입니다.

• -p 9300:9300

  • 위와 같은 포트 포워딩 설정입니다. 9300번 포트는 Elasticsearch 노드(컴퓨터)들끼리 서로 통신할 때 사용하는 내부 통신용 포트입니다. 지금은 노드가 하나뿐이라 사용하지는 않지만, 표준 설정에 포함되어 있습니다.

• -e "..." 또는 --env "..."

  • **"Environment variable" (환경 변수)**를 설정하는 옵션입니다. 컨테이너 내부에서 실행되는 애플리케이션(여기서는 Elasticsearch)의 설정을 Docker 명령어로 직접 지정할 수 있게 해줍니다.
  • "discovery.type=single-node": Elasticsearch에게 "너는 다른 노드를 찾을 필요 없이 혼자(단일 노드) 실행될 거야"라고 알려주는 설정입니다. 이걸 설정하지 않으면 Elasticsearch가 클러스터를 구성하기 위해 다른 노드를 찾으려고 시도하다가 오류를 낼 수 있습니다.
  • "xpack.security.enabled=false": Elasticsearch 8.x 버전부터 기본으로 활성화된 보안 기능(사용자 인증 등)을 비활성화하는 설정입니다. 개발 환경에서는 보안 기능이 없어야 번거로운 인증 절차 없이 바로 접속하고 테스트할 수 있어 편리합니다.

• docker.elastic.co/elasticsearch/elasticsearch:8.10.2

  • 실행할 Docker 이미지의 전체 이름입니다.
  • docker.elastic.co/elasticsearch/elasticsearch는 이미지의 이름이고, :8.10.2는 **버전 태그(tag)**입니다. 버전을 명시해주면 항상 동일한 환경에서 컨테이너를 실행할 수 있어 안정적인 개발이 가능합니다.

레시피(Dockerfile)를 보고, 재료(--no-cache)를 아끼지 말고, 처음부터 정직하게 요리(build)해줘.

docker-compose : docker-compose.yml이라는 설계도를 읽어서 여러 Docker 컨테이너를 한 번에 관리

build : 이미지를 만드는 명령어 docker-compose.yml 파일에서 build: . 이라고 지정된 서비스(elasticsearch)를 찾아, 그 서비스의 레시피인 Dockerfile을 보고 이미지를 만듬

—no-cache : Cache를 사용하지 말라는 옵션 Docker는 빌드 속도를 높이기 위해 이전에 만들었던 중간 과정들을 ‘캐시’로 저장해둠. 하지만 가끔 이 캐시 때문에 변경사항이 적용되지 않는 문제가 생기는데, —no-cache 옵션을 붙이면 이전에 기억해 둔 것들을 모두 무시하고, Dockerfile의 모든 단계를 처음부터 끝까지 깨끗하게 다시 실행함.

docker-compose up -d

설계도(Docker-compose.yml)를 보고, 만들어진 이미지들을 사용해서 건물(컨테이너)을 짓고, 백그라운드에서 조용히 운영(-d)시작해줘

up : 컨테이너(Container)를 생성하고 실행 build 명령어로 만들어 둔 이미지를 가져다가 실제 작동하는 프로그램인 컨테이너를 만듬.

-d : 'detached'모드 이 옵션을 붙이면 터미널에서 컨테이너의 실행 로그가 계속 보이지 않고, 백그라운드에서 조용히 실해됨.

🚀 기본 작업 흐름

프로젝트 시작

# 원격 저장소 클론
git clone https://github.com/username/repository.git

# 디렉토리 이동
cd repository-name

새 브랜치 생성 및 작업

# 새 브랜치 생성 + 전환
git checkout -b branch-name

# 또는 (Git 2.23+)
git switch -c branch-name

작업 저장 및 업로드

# 변경사항 추가
git add .

# 커밋
git commit -m "커밋 메시지"

# 원격 저장소에 푸시
git push origin branch-name

🔄 동기화 (Merge 후 필수!)

4단계 동기화

git checkout main                 # main 브랜치로 전환
git pull origin main             # 최신 main 가져오기
git checkout study/01-project-setup  # 작업 브랜치로 복귀
git pull origin main             # 작업 브랜치도 최신화

📋 상태 확인

현재 상태 확인

git status                       # 현재 변경사항 확인
git branch                       # 로컬 브랜치 목록
git branch -r                    # 원격 브랜치 목록
git log --oneline -5             # 최근 5개 커밋 확인

변경사항 확인

git diff                         # 현재 변경사항 확인
git diff --staged                # 스테이지된 변경사항 확인
git log --oneline --graph        # 커밋 그래프 확인

🌿 브랜치 관리

브랜치 생성/전환

git checkout -b new-branch       # 새 브랜치 생성 + 전환
git checkout existing-branch     # 기존 브랜치로 전환
git switch branch-name           # 브랜치 전환 (Git 2.23+)

브랜치 삭제

git branch -d branch-name        # 로컬 브랜치 삭제
git push origin -d branch-name   # 원격 브랜치 삭제

💾 커밋 관련

기본 커밋

git add .                        # 모든 변경사항 스테이지
git add filename                 # 특정 파일만 스테이지
git commit -m "메시지"           # 커밋
git commit -am "메시지"          # 추가 + 커밋 (신규 파일 제외)

커밋 수정

git commit --amend -m "새 메시지"  # 마지막 커밋 메시지 수정
git reset HEAD~1                 # 마지막 커밋 취소 (변경사항 유지)
git reset --hard HEAD~1          # 마지막 커밋 완전 삭제

📤 원격 저장소

푸시/풀

git push origin branch-name      # 브랜치 푸시
git push origin main             # main 브랜치 푸시
git pull origin main             # main 브랜치 풀
git fetch origin                 # 정보만 가져오기 (머지 안함)

원격 저장소 관리

git remote -v                    # 원격 저장소 목록
git remote add origin url        # 원격 저장소 추가

🔍 검색 및 이력

로그 확인

git log                          # 전체 커밋 로그
git log --oneline                # 한 줄로 요약
git log --oneline -10            # 최근 10개만
git log --graph --all            # 그래프로 모든 브랜치

파일 추적

git log filename                 # 특정 파일 변경 이력
git blame filename               # 각 줄의 작성자 확인
git show commit-hash             # 특정 커밋 상세 정보

🛠️ 우리 프로젝트 전용 명령어

Phase 작업 시작

cd /Users/moon/Desktop/study-insupanda
git status
git checkout main
git pull origin main
git checkout study/01-project-setup
git pull origin main

Phase 작업 완료

git add .
git commit -m "docs: Phase X.Y [작업내용] 완료"
git push origin study/01-project-setup

새로운 개별 브랜치 (Phase 1.3부터)

git checkout main
git pull origin main
git checkout -b phase1-3-env-config
# 작업 진행
git add .
git commit -m "docs: Phase 1.3 환경설정 파일 분석 완료"
git push origin phase1-3-env-config

📝 커밋 메시지 템플릿

제목 형식

# 학습 프로젝트용
git commit -m "docs: Phase X.Y [작업내용] 완료"
git commit -m "study: [학습내용] 정리 완료"
git commit -m "analysis: [분석내용] 완료"

# 일반 프로젝트용
git commit -m "feat: 새로운 기능 추가"
git commit -m "fix: 버그 수정"
git commit -m "refactor: 코드 리팩토링"

⚠️ 문제 해결

충돌 해결

# 충돌 발생 시
git status                       # 충돌 파일 확인
# 파일 수동 편집 후
git add .
git commit -m "resolve: merge conflict 해결"

실수했을 때

git reset HEAD filename          # 스테이지 취소
git checkout -- filename        # 파일 변경사항 취소
git reflog                       # 참조 로그 확인 (복구용)

강제 동기화 (주의!)

git fetch origin
git reset --hard origin/main     # 로컬을 원격과 완전 동일하게

🎯 자주 사용하는 조합 명령어

작업 시작할 때

git status && git pull origin main

작업 완료할 때

git add . && git commit -m "메시지" && git push origin branch-name

브랜치 정리할 때

git branch -d old-branch && git push origin -d old-branch

💡 유용한 별칭 설정

별칭 등록

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm commit
git config --global alias.ps push
git config --global alias.pl pull
git config --global alias.lg "log --oneline --graph"

별칭 사용

git st              # git status
git co main         # git checkout main
git cm "메시지"      # git commit -m "메시지"
git lg              # 예쁜 로그

🚨 비상시 명령어

작업 임시 저장

git stash                        # 현재 작업 임시 저장
git stash pop                    # 임시 저장된 작업 복구
git stash list                   # 저장된 작업 목록

브랜치 복구

git reflog                       # 모든 참조 로그 확인
git checkout -b 브랜치명 커밋해시  # 특정 지점에서 브랜치 생성

📱 GitHub CLI (선택사항)

PR 생성 (CLI)

gh pr create --title "제목" --body "내용"
gh pr list                       # PR 목록
gh pr view                       # PR 상세 보기

🔥 실전 시나리오별 명령어

시나리오 1: 새로운 Phase 시작

git checkout main
git pull origin main
git checkout -b phase2-1-config

시나리오 2: 작업 중 main 업데이트됨

git stash                        # 현재 작업 임시 저장
git checkout main
git pull origin main
git checkout my-branch
git pull origin main             # 최신 main 반영
git stash pop                    # 작업 복구

시나리오 3: PR 머지 후 정리

git checkout main
git pull origin main
git branch -d merged-branch      # 로컬 브랜치 삭제
git push origin -d merged-branch # 원격 브랜치 삭제

📋 체크리스트

작업 시작 전

• git status 현재 상태 확인
• git pull origin main 최신 상태 동기화
• 올바른 브랜치에 있는지 확인

작업 완료 후

• git add . 변경사항 스테이지
• 의미있는 커밋 메시지 작성
• git push origin branch-name 푸시
• GitHub에서 PR 생성

PR 머지 후

• 로컬 동기화 4단계 실행
• 불필요한 브랜치 삭제
• 다음 작업 브랜치 생성

💡 TIP: 이 치트시트를 즐겨찾기하고 필요할 때마다 참고하세요!

📋 목차

1. Git 기본 개념
2. 브랜치와 워크플로우
3. Pull Request (PR)
4. Merge의 이해
5. PR vs Merge 차이점
6. 커밋 메시지 작성 규칙
7. Git 명령어 실무 활용
8. 실제 워크플로우 예시

Git 기본 개념

Git이란?

• 버전 관리 시스템: 코드의 변화를 추적하고 관리
• 분산 저장소: 로컬과 원격(GitHub)에 각각 저장
• 협업 도구: 여러 사람이 동시에 작업 가능

핵심 용어

브랜치와 워크플로우

브랜치란?

main:           A ← B ← C (안정된 버전)
                    ↘
feature:            D ← E ← F (새로운 작업)

브랜치 전략의 장점

• ✅ 안전성: main 브랜치 보호
• ✅ 병렬 작업: 동시에 여러 기능 개발
• ✅ 롤백 용이: 문제 시 특정 브랜치만 제거

WBS 기반 브랜치 전략

# Phase별 브랜치 생성
git checkout -b study/01-project-setup    # Phase 1 전체
git checkout -b phase1-3-env-config       # 개별 작업

Pull Request (PR)

PR이란?

• 정의: "내 변경사항을 검토해서 main에 반영해달라"는 요청
• 목적: 코드 리뷰, 품질 관리, 협업
• 상태: 아직 main에 반영되지 않은 제안 상태

PR 생성 과정

# 1. 작업 완료
git add .
git commit -m "Phase 1.1-1.2: 분석 완료"
git push origin study/01-project-setup

# 2. GitHub에서 PR 생성
# Compare & pull request 버튼 클릭

PR 작성 표준 형식

## 📋 작업 내용
- 구체적인 작업 1
- 구체적인 작업 2

## 🔍 변경 사항
- 추가된 파일
- 수정된 부분

## 📚 학습 성과
- 핵심 학습 내용 1
- 핵심 학습 내용 2

## 📈 진행 상황
- Phase X: Y% 완료
- 전체 프로젝트: Z% 완료

Merge의 이해

Merge란?

• 정의: 브랜치의 변경사항을 main에 실제로 반영하는 작업
• 결과: main 브랜치에 새로운 커밋 추가
• 의미: 공식적인 완료 표시

Merge 과정 시각화

# Merge 전
main:           A ← B ← C
feature:            ↘ D ← E

# Merge 후  
main:           A ← B ← C ← M (merge commit)
                        ↗ ↗
feature:            D ← E

Merge 방법 3가지

1. Create a merge commit (기본)

main:     A ← B ← C ← M (merge commit)
                   ↗ ↗
feature:       D ← E

• 머지 기록 보존
• 브랜치 히스토리 유지

2. Squash and merge ⭐ (추천)

main:     A ← B ← C ← S (압축된 하나의 커밋)
feature:       D ← E (원본 유지)

• 여러 커밋을 하나로 합침
• 깔끔한 히스토리

3. Rebase and merge

main:     A ← B ← C ← D' ← E' (선형 배치)

• 선형적 히스토리
• 고급 사용법

PR vs Merge 차이점

핵심 차이점

기록 보존

# 둘 다 영구 보존됨!
GitHub → Pull requests → Closed     # PR 기록
GitHub → Commits                    # Merge 기록

제3자가 보는 정보

• PR: 상세한 작업 과정, 토론, 리뷰 내용
• Commit: 간결한 변경사항, 실제 코드 diff

커밋 메시지 작성 규칙

표준 커밋 타입

feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정/추가
style: 코드 포맷팅
refactor: 코드 리팩토링
test: 테스트 추가/수정
chore: 기타 작업

학습 프로젝트용 타입

docs: 문서 분석/작성
study: 학습 내용 정리
analysis: 코드/구조 분석
review: 검토 및 정리

제목 작성 규칙

# 좋은 예시
docs: Phase 1.1-1.2 프로젝트 설정 분석 완료
study: RAG 시스템 아키텍처 학습 정리

# 나쁜 예시
Update files                    # 너무 모호
Fix stuff                      # 구체적이지 않음
WIP                           # 완료되지 않은 상태

내용 작성 규칙

# PR 내용 (상세함)
## 📋 작업 내용
## 🔍 변경 사항
## 📚 학습 성과
## 📈 진행 상황

# Merge 내용 (간결함)
간단한 요약

- 핵심 작업 1
- 핵심 작업 2
- 주요 결과

Git 명령어 실무 활용

기본 워크플로우

# 1. 프로젝트 클론
git clone https://github.com/username/repository.git

# 2. 새 브랜치 생성 및 전환
git checkout -b feature/new-branch

# 3. 작업 후 커밋
git add .
git commit -m "feat: 새로운 기능 추가"

# 4. 원격 저장소에 푸시
git push origin feature/new-branch

동기화 명령어 (중요!)

# Merge 후 로컬 동기화
git checkout main              # main 브랜치로 전환
git pull origin main          # 최신 내용 가져오기
git checkout feature-branch   # 작업 브랜치로 복귀
git pull origin main          # 작업 브랜치도 최신화

브랜치 관리

# 브랜치 목록 확인
git branch                    # 로컬 브랜치
git branch -r                 # 원격 브랜치

# 브랜치 삭제
git branch -d branch-name     # 로컬 브랜치 삭제
git push origin -d branch-name # 원격 브랜치 삭제

# 브랜치 상태 확인
git status                    # 현재 상태
git log --oneline -5          # 최근 5개 커밋

실제 워크플로우 예시

시나리오: Phase 1.3 작업 시작

1단계: 환경 준비

cd /Users/moon/Desktop/study-insupanda
git status                    # 현재 상태 확인

2단계: 최신 상태로 동기화

git checkout main
git pull origin main
git checkout study/01-project-setup
git pull origin main

3단계: Phase 1.3 작업

# 파일 분석 및 학습
# 문서 작성

4단계: 커밋 및 푸시

git add .
git commit -m "docs: Phase 1.3 환경설정 파일 분석 완료"
git push origin study/01-project-setup

5단계: PR 생성

# GitHub에서 PR 생성
제목: docs: Phase 1.3 환경설정 파일 분석 완료

내용:
## 📋 작업 내용
- .env 파일 구조 분석
- .gitignore 설정 분석
- Docker 관련 파일 탐색

## 🔍 변경 사항
- README.md 업데이트
- 환경설정 분석 문서 추가

## 📚 학습 성과
- 환경변수 관리 방식 이해
- Git 무시 패턴 학습

## 📈 진행 상황
- Phase 1: 100% 완료 (3/3)
- 전체 WBS: 10% 완료 (3/30)

6단계: Merge 실행

Commit message: docs: Phase 1.3 환경설정 파일 분석 완료

Extended description:
환경설정 파일 구조 및 역할 분석

- .env: 환경변수 관리 방식 파악
- .gitignore: 버전 관리 제외 패턴 학습
- Phase 1 완료: 프로젝트 설정 전체 이해

브랜치 전략 비교

전략 1: Phase별 브랜치

study/01-project-setup     → Phase 1 전체 (1.1, 1.2, 1.3)
study/02-config-utils      → Phase 2 전체
study/03-database          → Phase 3 전체

장점: 관련 작업 묶음, 관리 단순 단점: PR이 커질 수 있음

전략 2: 작업별 브랜치

phase1-1-requirements      → 1.1만
phase1-2-pyproject        → 1.2만  
phase1-3-env-config       → 1.3만

장점: 작은 PR, 빠른 리뷰 단점: 브랜치 관리 복잡

전략 3: 하이브리드 (추천)

# 첫 작업은 통합, 이후 개별
study/01-project-setup     → 1.1 + 1.2 (이미 완료)
phase1-3-env-config        → 1.3 개별
phase2-1-config-folder     → 2.1 개별

문제 상황별 해결법

1. Merge 충돌 발생

# 충돌 해결 후
git add .
git commit -m "resolve: merge conflict 해결"
git push origin branch-name

2. 잘못된 커밋 수정

# 마지막 커밋 메시지 수정
git commit --amend -m "새로운 커밋 메시지"

# 아직 푸시 안한 경우만 사용!

3. 브랜치 삭제 후 복구

# 삭제된 브랜치 복구
git reflog                          # 참조 로그 확인
git checkout -b 브랜치명 커밋해시     # 특정 커밋에서 브랜치 생성

4. 원격과 로컬 불일치

# 강제 동기화 (주의!)
git fetch origin
git reset --hard origin/main

좋은 Git 습관

✅ Do (해야 할 것)

• 자주 커밋하기 (의미 있는 단위로)
• 명확한 커밋 메시지 작성
• 작업 전 항상 동기화
• 브랜치 이름 규칙적으로 작성
• PR에 충분한 설명 추가

❌ Don't (하지 말 것)

• main 브랜치에 직접 푸시
• 너무 큰 단위로 커밋
• 모호한 커밋 메시지
• 동기화 없이 작업 시작
• 테스트 없이 머지

유용한 Git 설정

글로벌 설정

# 사용자 정보 설정
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 기본 에디터 설정
git config --global core.editor "code --wait"

# 줄바꿈 설정 (Windows)
git config --global core.autocrlf true

유용한 별칭

# 자주 사용하는 명령어 단축
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm commit
git config --global alias.lg "log --oneline --graph --all"

마무리

핵심 기억사항

1. Git은 협업 도구: 혼자 써도 체계적 관리 가능
2. 브랜치 활용: 안전한 작업 환경 제공
3. 명확한 기록: 나중의 나를 위한 친절함
4. 표준 준수: 일관성 있는 패턴 유지

지속적 학습 포인트

• Git 고급 명령어 (rebase, cherry-pick 등)
• GitHub Actions (CI/CD)
• Git 훅 활용
• 대규모 프로젝트 브랜치 전략

참고 자료

• Pro Git Book
• GitHub Docs
• Conventional Commits

이 가이드는 실제 프로젝트 경험을 바탕으로 작성되었습니다. 계속 업데이트하며 사용하세요! 🚀

• ✅ 프로젝트 메타데이터 분석 완료
• ✅ 빌드 설정 이해 완료
• ✅ Poetry 설정 파악 완료

🔍 pyproject.toml 파일 분석

파일 기본 정보

• 위치: 프로젝트 루트 디렉토리
• 크기: 매우 작음 (개발 도구 설정만 포함)
• 특징: Poetry 미사용, 전통적인 pip 기반 프로젝트

파일 내용 구조

[tool.black]
line-length = 120

[tool.isort]
profile = "black"
line_length = 120
src_paths = ["src", "."]

[tool.mypy]
ignore_missing_imports = true

[tool.mypy.simplejson]
ignore_missing_imports = true

🛠️ 각 도구별 역할과 설정

1. Black (코드 포맷터)

• 목적: Python 코드 자동 포맷팅
• 핵심 설정: line-length = 120 (기본 88자 → 120자로 확장)
• 특징: "타협하지 않는 포맷터", 일관성 중시

2. isort (Import 정렬)

• 목적: import 문 자동 정렬 및 그룹화
• 핵심 설정:
  • profile = "black": Black과 호환성 보장
  • line_length = 120: Black과 동일한 줄 길이
  • src_paths = ["src", "."]: 소스 코드 경로 지정

3. mypy (정적 타입 검사)

• 목적: 타입 힌트 검증으로 런타임 오류 예방
• 핵심 설정: ignore_missing_imports = true (타입 스텁 없는 라이브러리 허용)
• 특별 설정: simplejson 모듈 별도 예외 처리

💡 핵심 학습 내용

pyproject.toml의 존재 이유

1. 과거 문제점: 설정 파일 분산 (setup.py, setup.cfg, .flake8, .isort.cfg 등)
2. 해결책: 하나의 파일로 모든 도구 설정 통합
3. 표준화: PEP 518에 의한 Python 커뮤니티 표준

중요한 오해 해결

• ❌ 잘못된 이해: pyproject.toml만 있으면 자동으로 검사됨
• ✅ 올바른 이해: 단순한 설정 파일, 별도 도구 설치 및 실행 필요

실제 동작 과정

1. 도구 설치: pip install black isort mypy
2. 수동 실행: black ., isort ., mypy .
3. 자동화: pre-commit, IDE 설정, CI/CD 파이프라인

🔗 프로젝트 내 연관 파일들

requirements.txt 연관성

black==25.1.0      # 코드 포맷터
isort==6.0.1       # import 정렬
mypy==1.15.0       # 타입 검사
pre-commit==4.2.0  # Git 훅 자동화

.pre-commit-config.yaml 자동화

• Git 커밋 시 자동으로 black, isort, mypy 실행
• pyproject.toml 설정을 읽어서 적용
• 코드 품질 자동 보장

📊 프로젝트 특징 분석

의존성 관리 방식

• Poetry 미사용: 전통적인 pip + requirements.txt 방식
• 점진적 개선: 개발 도구 설정만 pyproject.toml로 통합
• 안정성 우선: 검증된 방식 유지

개발 워크플로우

코드 작성 → mypy 타입 체크 → isort import 정렬 → black 포맷팅 → Git 커밋

팀 협업 장점

• 모든 개발자가 동일한 코드 스타일 사용
• 설정 파일 하나로 일관성 보장
• 새 팀원 온보딩 시간 단축

🎯 주요 학습 포인트

기술적 개념

• TOML 형식: 설정 파일 표준 형식
• 정적 분석: 코드 실행 전 오류 검출
• 코드 포맷팅: 가독성과 일관성 향상
• 타입 힌팅: Python의 점진적 타이핑 시스템

실무 적용 가치

• 코드 리뷰 시간 단축 (스타일 논쟁 제거)
• 버그 예방 (타입 체크로 오류 사전 발견)
• 유지보수성 향상 (일관된 코드 스타일)
• 자동화 지원 (CI/CD 파이프라인 통합)

🚀 다음 단계 준비

Phase 1.3 예고

• 환경설정 파일들 분석 (.env, .gitignore 등)
• Docker 관련 파일 탐색
• 프로젝트 전체 설정 체계 파악

연관 학습 포인트

• Git 워크플로우와 코드 품질 도구 연동
• IDE 설정과 개발 도구 통합
• CI/CD 파이프라인에서의 자동화 적용

📝 WBS 진행 현황

• Phase 1: 프로젝트 설정 및 환경 구성 (2/3 완료)
• 다음 세션: Phase 1.3 - 환경설정 파일들 분석

• 주제: Python 로깅 시스템 구축 및 이해
• 기준 코드: insupanda-rag의 src/config/logger.py
• 학습 방식: 직접 타이핑 + 상세 주석으로 개념 학습
• 완성 결과: 콘솔과 파일에 동시 출력되는 로깅 시스템

🔍 핵심 개념 학습

1. 로깅(Logging)이란?

• 정의: 프로그램 실행 중 발생하는 이벤트들을 기록하는 시스템
• 비유: 프로그램의 "일기장" - 언제 무슨 일이 일어났는지 상세 기록
• 필요성: 디버깅, 모니터링, 분석, 증거 보전

2. 로깅 레벨 5단계

DEBUG < INFO < WARNING < ERROR < CRITICAL

• DEBUG: 개발자용 상세 정보 (가장 자세함)
• INFO: 일반적인 정보 ← 우리 프로젝트에서 사용
• WARNING: 경고 메시지
• ERROR: 에러 발생
• CRITICAL: 치명적 오류 (가장 심각함)

3. 핸들러(Handler) 개념

로그를 "어디에" 보낼지 결정하는 배달원 역할

StreamHandler

• 역할: 콘솔(터미널 화면)에 실시간 출력
• 장점: 즉시 확인 가능, 개발 중 디버깅 용이
• 단점: 프로그램 종료 시 사라짐

FileHandler

• 역할: 파일에 영구 저장
• 장점: 영구 보관, 나중에 분석 가능
• 설정: ("app.log", "a", "utf-8")
  • "app.log": 파일명
  • "a": append 모드 (기존 내용에 추가)
  • "utf-8": 한글 지원 인코딩

💻 실습 과정

1. 프로젝트 구조 확인

insurance-rag-learning/
├── src/
│   ├── config/     ← 여기에 logger.py 생성
│   ├── db/
│   ├── models/
│   └── ...
├── tests/
└── README.md

2. logger.py 핵심 코드

import logging

def setup_logging() -> None:
    logging.basicConfig(
        level=logging.INFO,  # INFO 이상만 기록
        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
        handlers=[
            logging.StreamHandler(),  # 콘솔 출력
            logging.FileHandler("app.log", "a", "utf-8"),  # 파일 저장
        ],
    )

3. 테스트 코드 작성 및 실행

• 파일: test_logging.py
• 테스트 내용:
  • 모든 로깅 레벨 테스트
  • 다양한 모듈별 로깅 테스트
  • 콘솔과 파일 동시 출력 확인

✅ 테스트 결과 분석

성공적인 동작 확인

1. DEBUG 필터링 ✅ - INFO 레벨 설정으로 DEBUG 메시지 차단
2. 로거 이름 구분 ✅ - __main__, database, openai_api 등 모듈별 구분
3. 시간 정확성 ✅ - 밀리초 단위 정확한 타임스탬프
4. 동시 출력 ✅ - 콘솔과 파일에 동일한 내용 기록
5. Append 모드 ✅ - 여러 번 실행해도 로그 누적 저장
6. UTF-8 인코딩 ✅ - 한글 깨짐 없이 완벽 저장

실제 테스트 출력 예시

2025-08-02 01:06:51,021 [INFO] __main__: ℹ️ 프로그램이 정상적으로 시작되었습니다
2025-08-02 01:06:51,021 [WARNING] __main__: ⚠️ 이것은 경고 메시지입니다
2025-08-02 01:06:51,021 [ERROR] __main__: ❌ 에러가 발생했습니다
2025-08-02 01:06:51,021 [INFO] database: 💾 데이터베이스 연결 성공

🆚 기존 insupanda-rag와 비교

공통점 (잘 따라한 부분)

• ✅ 동일한 로깅 레벨 (INFO)
• ✅ 동일한 포맷 구조
• ✅ 동일한 핸들러 조합
• ✅ 동일한 파일 설정

우리 버전의 장점

• 상세한 주석: 각 라인의 목적과 동작 원리 명확히 설명
• 구조화된 코드: setup_logging() 함수로 깔끔하게 정리
• 학습 친화적: 초보자도 이해할 수 있는 상세한 설명

🎯 핵심 학습 포인트

1. 로깅 시스템의 3가지 핵심 기능

1. 콘솔 출력: 실시간 모니터링
2. 파일 저장: 영구 보관 및 분석
3. 레벨 필터링: 필요한 정보만 선별 기록

2. Append 모드의 중요성

• "a" 모드: 기존 로그 보존하며 새 로그 추가
• "w" 모드: 기존 로그 삭제 후 새로 작성 (위험!)
• 실제 증명: 두 번 실행했을 때 모든 로그가 누적 저장됨

3. 로거 이름(%(name)s)의 가치

• 문제 추적: 어느 모듈에서 발생한 로그인지 즉시 식별
• 디버깅 효율성: 에러 발생 시 해당 부분만 집중 분석 가능
• 시스템 모니터링: 각 구성 요소별 상태 개별 확인

🚀 다음 단계 예고

다음 세션에서는 환경 변수와 설정 관리를 다룰 예정입니다:

• Pydantic을 활용한 설정 관리
• 환경변수(.env) 활용법
• 개발/운영 환경 분리 방법

📝 학습 성과

• ✅ 로깅의 핵심 개념 완전 이해
• ✅ Python logging 라이브러리 실습 완료
• ✅ 콘솔/파일 동시 출력 시스템 구축
• ✅ 기존 프로젝트 코드와 비교 분석 완료
• ✅ 실무에서 사용할 수 있는 로깅 시스템 습득

📖 핵심 개념 학습 1️⃣ 환경변수 (Environment Variables)

정의: 운영체제에 저장되는 설정값 목적: 코드와 설정 분리로 보안성 향상 실생활 비유: 집 열쇠를 안전한 서랍에 보관하는 것

보안 레벨별 분류:

🔴 높은 보안: API 키, 비밀번호 → 절대 코드에 쓰지 않음 🟡 중간 보안: 호스트, 포트 → 기본값 제공하되 환경변수로 덮어쓰기 가능

2️⃣ Pydantic & BaseSettings

Pydantic: 데이터 검증 자동화 라이브러리 BaseSettings: 환경변수 자동 매핑 + 타입 검증 동작원리: db_password → DB_PASSWORD 환경변수 자동 찾기

🔬 라이브러리 심화 분석 pathlib

용도: 현대적 파일 경로 처리 핵심 기능: Path(file).parent.parent.resolve() - 프로젝트 루트 찾기 장점: 직관적인 / 연산자 사용

typing

용도: 타입 힌트 제공 Optional[str]: str 또는 None 가능 장점: IDE 자동완성, 타입 에러 사전 발견

pydantic_settings

용도: 환경변수 자동 로딩 + 데이터 검증 BaseSettings 특징:

환경변수 이름 자동 변환 (snake_case → UPPER_CASE) 타입 자동 변환 ("3306" → 3306) .env 파일 자동 로딩

💡 실무 인사이트 타입 선택 가이드라인

str: 호스트명, 비밀번호, 경로 int: 포트번호, 타임아웃, 개수 (숫자 계산 필요) bool: 디버그 모드, 기능 활성화 여부

보안 베스트 프랙티스 python# ✅ 올바른 방식 db_host: str = "localhost" # 공개 정보 → 기본값 제공 db_password: str # 민감 정보 → 기본값 없음 Pydantic 우선순위

환경변수 값 (최우선) .env 파일 값 코드의 기본값 (백업)

세션명: Insurance RAG 학습 지침 (세션2 수정완료판) 진행 방식: AI 가이드 & 멘토링 + 깊이있는 개념 설명 기준 코드: /Users/moon/Desktop/insupanda-rag/ 구조 참조 학습 원칙: 기존 코드 참조 → 개념 설명 → 실습 안내 → 완료 확인

✅ 완료된 학습 내용 1단계: 프로젝트 구조 이해 개념 학습:

RAG(Retrieval-Augmented Generation): 검색 후 답변 생성 기술

도서관 사서처럼 관련 문서를 먼저 찾고 답변 생성 외운 내용보다 실제 문서 참조로 더 정확한 답변 제공

기존 코드 분석: 📁 insupanda-rag/src/ ├── config/ # 설정 관리 (logger.py, settings.py) ├── db/ # 데이터베이스 (schema.py, sql_utils.py)
├── models/ # RAG 핵심 모듈 (임베딩, 검색, 답변생성) ├── modules/ # 메인 비즈니스 로직 (handler.py, user_state.py) ├── options/ # 타입 정의 (enums.py, insu_name.py) ├── prompts/ # AI 프롬프트 템플릿 (.jinja2 파일들) ├── services/ # 비즈니스 서비스 로직 └── util/ # 유틸리티 함수들 2단계: 프로젝트 기본 구조 생성 중요한 배움 - 명령어 효율성:

❌ 잘못된 방식: mkdir -p를 개별적으로 여러 번 사용 ✅ 올바른 방식: mkdir -p src/{config,db,models,modules,options,prompts,services,util} tests

개념 학습:

mkdir -p: parent directories 옵션으로 중간 폴더까지 한 번에 생성 중괄호 {} 문법: 쉘에서 여러 이름을 한 번에 나열하는 방법

실행 명령어: bashcd /Users/moon/Desktop mkdir insurance-rag-learning cd insurance-rag-learning mkdir -p src/{config,db,models,modules,options,prompts,services,util} tests 3단계: Python 패키지 초기화 개념 학습:

Python 패키지: init.py 파일로 폴더를 Python이 인식할 수 있는 패키지로 변환 import 시스템: from src.config import settings 같은 코드 import 가능

기존 코드 참조:

insupanda-rag에 총 7개의 init.py 파일 확인 모든 주요 폴더에 패키지 초기화 파일 존재

실행 명령어: bashtouch src/init.py src/config/init.py src/db/init.py src/models/init.py src/modules/init.py src/options/init.py src/prompts/init.py src/services/init.py src/util/init.py tests/init.py 문제 해결:

불필요한 src/api/ 폴더 발견 및 삭제 rm -rf src/api 명령어로 정리

4단계: 환경변수 설정 파일 (진행 중) 개념 학습:

환경변수: 프로그램 설정값을 코드 외부에 안전하게 저장 보안성: API 키, 비밀번호 등 민감 정보를 코드에 직접 노출하지 않음 유연성: 개발/테스트/운영 환경별로 다른 설정 사용 가능

기존 코드 참조:

src/.test.env 파일 발견 내용: DB_PASSWORD, OPENAI_API_KEY, UPSTAGE_API_KEY 설정

🔧 학습한 주요 기술 개념 Python 관련

Pydantic: 데이터 검증을 쉽게 해주는 라이브러리 (설정값 타입 자동 체크) 환경변수: 운영체제에 저장된 설정값 (민감 정보 별도 보관) 로깅: 프로그램 실행 중 일어나는 일들을 기록 (에러 찾기와 디버깅에 필수)

RAG 관련

임베딩: 텍스트를 숫자 벡터로 변환 (컴퓨터가 의미 이해 가능) 벡터 검색: 의미가 비슷한 문서를 찾는 기술 (키워드 검색보다 똑똑함) 프롬프트 템플릿: AI에게 질문하는 정해진 형식

터미널 명령어

mkdir -p: 폴더 생성 (중간 폴더도 함께 생성) touch: 빈 파일 생성 rm -rf: 폴더와 내용 완전 삭제 find: 파일 검색

📊 생성된 프로젝트 구조 최종 폴더 구조 📁 insurance-rag-learning/ ├── src/ │ ├── init.py │ ├── config/ │ │ └── init.py │ ├── db/ │ │ └── init.py │ ├── models/ │ │ └── init.py │ ├── modules/ │ │ └── init.py │ ├── options/ │ │ └── init.py │ ├── prompts/ │ │ └── init.py │ ├── services/ │ │ └── init.py │ └── util/ │ └── init.py └── tests/ └── init.py 생성된 파일 목록

총 10개의 init.py 파일 기존 insupanda-rag와 정확히 동일한 구조

🎓 중요한 학습 원칙 AI 역할

✅ 개념 설명 + 기존 코드 참조 + 실습 안내 ✅ 모든 기술 용어 초보자용 설명 제공 ❌ 직접 파일 생성이나 코드 작성 금지

학습자 역할

✅ 터미널 명령어 직접 실행 ✅ Cursor에서 파일/코드 직접 작성 ✅ 이해 안되는 개념 즉시 질문

효율성 원칙

명령어 설명 시 가장 효율적인 방법을 먼저 제시 프로 개발자가 사용하는 방식으로 바로 안내 비효율적 방법 → 수정하는 패턴 지양

학습 일자: 2025년 7월 31일
학습 목표: 프로젝트 환경 설정 및 기본 구조 구축

🎯 주요 학습 내용

1. 학습 폴더 생성

개념: 기존 완성 프로젝트와 분리하여 단계별 학습 기록용
실습 명령어:

cd /Users/moon/Desktop
mkdir insurance-rag-learning
cd insurance-rag-learning

2. README.md 작성

개념: 프로젝트 개요 및 15세션 로드맵 기록용
실습 명령어:

touch README.md
# 텍스트 에디터로 15세션 로드맵과 기술스택 작성

3. 프로젝트 구조 설계 ⭐

프로젝트 구조:

insurance-rag-learning/
├── src/                # 메인 소스코드
│   ├── config/        # 설정 파일들
│   ├── models/        # AI 모델 관련
│   ├── services/      # 비즈니스 로직
│   ├── utils/         # 유틸리티 함수들
│   └── api/           # API 엔드포인트
├── tests/             # 테스트 코드
├── docs/              # 문서
└── data/              # 데이터 파일들

4. 효율적인 명령어 사용법 ⭐

기본 방법:

mkdir src
mkdir tests
mkdir docs
mkdir data

효율적인 방법:

# 여러 폴더를 한 번에 생성
mkdir src tests docs data

# 하위 폴더들도 한 번에 생성
mkdir src/config src/models src/services src/utils src/api

고급 방법 - 중괄호 확장:

# -p 옵션으로 상위 폴더가 없어도 자동 생성
mkdir -p src/{config,models,services,utils,api}

# __init__.py 파일들을 한 번에 생성
touch {src,src/config,src/models,src/services,src/utils,src/api,tests}/__init__.py

5. Python 패키지 구조 설정

개념: __init__.py 파일로 Python 패키지 인식시키기
실수 경험: servies → services 오타 발견 및 수정으로 디버깅 스킬 습득

6. 가상환경 설정

개념: 프로젝트별 독립적인 Python 환경 구축
실습 명령어:

# 가상환경 생성
python -m venv venv

# 가상환경 활성화
source venv/bin/activate

# 활성화 확인
which python

🏆 세션 1 성과

• ✅ 학습 폴더 생성: insurance-rag-learning
• ✅ README.md 작성: 15세션 로드맵 수립
• ✅ 프로젝트 구조 설계: Python 패키지 구조 완성
• ✅ 가상환경 설정: 격리된 개발 환경 구축
• ✅ 효율적인 명령어 학습: mkdir, touch 고급 활용법 습득

📝 학습 노트

좋았던 점

• 프로젝트 구조 설명 시 각 폴더 역할을 주석으로 명시
• mkdir 기본 → 효율적 → 고급 방법 단계적 학습
• 실수(오타)를 통한 자연스러운 디버깅 스킴 습득

개선할 점

• 명령어 입력 전 철자 확인 습관 필요

Column name Type Nullable ID INTEGER FALSE PARENT_ID INTEGER TRUE SIZE_OF_COLONY INTEGER FALSE DIFFERENTIATION_DATE DATE FALSE GENOTYPE INTEGER FALSE 최초의 대장균 개체의 PARENT_ID 는 NULL 값입니다.

문제 대장균 개체의 크기를 내름차순으로 정렬했을 때 상위 0% ~ 25% 를 'CRITICAL', 26% ~ 50% 를 'HIGH', 51% ~ 75% 를 'MEDIUM', 76% ~ 100% 를 'LOW' 라고 분류합니다. 대장균 개체의 ID(ID) 와 분류된 이름(COLONY_NAME)을 출력하는 SQL 문을 작성해주세요. 이때 결과는 개체의 ID 에 대해 오름차순 정렬해주세요 . 단, 총 데이터의 수는 4의 배수이며 같은 사이즈의 대장균 개체가 서로 다른 이름으로 분류되는 경우는 없습니다.

예시 예를 들어 ECOLI_DATA 테이블이 다음과 같다면

ID PARENT_ID SIZE_OF_COLONY DIFFERENTIATION_DATE GENOTYPE 1 NULL 10 2019/01/01 5 2 NULL 2 2019/01/01 3 3 1 100 2020/01/01 4 4 2 16 2020/01/01 4 5 2 17 2020/01/01 6 6 4 101 2021/01/01 22 7 6 101 2022/01/01 23 8 6 1 2022/01/01 27 기준에 의해 분류된 대장균들의 ID는 다음과 같습니다.

CRITICAL (상위 0% ~ 25%) : ID 6, ID 7 HIGH (상위 26% ~ 50%) : ID 3, ID 5 MEDIUM (상위 51% ~ 75%) : ID 1, ID 4 LOW (상위 76% ~ 100%) : ID 2, ID 8

따라서 결과를 ID 에 대해 오름차순 정렬하면 다음과 같아야 합니다.

ID COLONY_NAME 1 MEDIUM 2 LOW 3 HIGH 4 MEDIUM 5 HIGH 6 CRITICAL 7 CRITICAL 8 LOW

SELECT 
    ID,
    CASE
        WHEN percentile <= 0.25 THEN 'CRITICAL'
        WHEN percentile <= 0.50 THEN 'HIGH'
        WHEN percentile <= 0.75 THEN 'MEDIUM'
        WHEN percentile <= 100 THEN 'LOW'
    END AS COLONY_NAME
FROM (
        SELECT 
            ID,
            PERCENT_RANK() OVER( ORDER BY size_of_colony DESC ) AS percentile
        FROM ecoli_data
    ) AS ranked
ORDER BY ID;

문제 설명

HR_DEPARTMENT 테이블은 회사의 부서 정보를 담은 테이블입니다. HR_DEPARTMENT 테이블의 구조는 다음과 같으며 DEPT_ID, DEPT_NAME_KR, DEPT_NAME_EN, LOCATION은 각각 부서 ID, 국문 부서명, 영문 부서명, 부서 위치를 의미합니다.

HR_EMPLOYEES 테이블은 회사의 사원 정보를 담은 테이블입니다. HR_EMPLOYEES 테이블의 구조는 다음과 같으며 EMP_NO, EMP_NAME, DEPT_ID, POSITION, EMAIL, COMP_TEL, HIRE_DATE, SAL은 각각 사번, 성명, 부서 ID, 직책, 이메일, 전화번호, 입사일, 연봉을 의미합니다.

문제

HR_DEPARTMENT와 HR_EMPLOYEES 테이블을 이용해 부서별 평균 연봉을 조회하려 합니다. 부서별로 부서 ID, 영문 부서명, 평균 연봉을 조회하는 SQL문을 작성해주세요.

• 평균연봉은 소수점 첫째 자리에서 반올림하고 컬럼명은 AVG_SAL로 해주세요.
• 결과는 부서별 평균 연봉을 기준으로 내림차순 정렬해주세요.

예시

HR_DEPARTMENT 테이블

HR_EMPLOYEES 테이블

출력 예시

SELECT 
    d.DEPT_ID AS DEPT_ID, 
    d.DEPT_NAME_EN AS DEPT_NAME_EN, 
    ROUND(AVG(SAL), 0) AS AVG_SAL
FROM hr_department d
    JOIN hr_employees e ON d.DEPT_ID = e.DEPT_ID
GROUP BY d.DEPT_ID, d.DEPT_NAME_EN
ORDER BY AVG(SAL) DESC;

SELECT 
    e.DEPT_ID AS DEPT_ID, 
    d.DEPT_NAME_EN AS DEPT_NAME_EN, 
    e.AVG_SAL AS AVG_SAL
FROM hr_department d JOIN (
        SELECT 
            dept_id, 
            ROUND(AVG(SAL), 0) AS AVG_SAL
        FROM hr_employees
        GROUP BY dept_id
        ) e ON d.dept_id = e.dept_id
ORDER BY e.avg_sal DESC;