Growth Diary

[OSSCA] 파이토치 문서 한글화 1,2주차

dong_seok — Sat, 2 May 2026 23:24:55 +0900

OSSCA(오픈소스 컨트리뷰션 아카데미)에서 주최하는 멘토링 프로그램에 2지망으로 신청했던 파이토치 문서 한글화 멘티로 선정되었습니다. 오픈소스 경험이 없던터라 실제 오픈소스 프로젝트에 기여해볼 수 있는 좋은 기회라고 판단해서 적극적으로 참여하기로 했습니다. 이 글에서는 1~2주차 과제를 수행하며 배운 점과 실제 기여 과정을 정리합니다.

1. OSSCA 파이토치 한글화 멘토링이란?

OSSCA는 국내 개발자들이 오픈소스 프로젝트에 직접 기여할 수 있도록 멘토와 멘티를 매칭해주는 프로그램입니다. 파이토치 한글화 트랙은 PyTorch 공식 튜토리얼(pytorch/tutorials)을 한국어로 번역하는 PyTorchKorea/tutorials-kr 프로젝트에 기여합니다.

6주간 멘토의 리뷰를 받으며 번역 품질을 높이는 방식으로 진행되며, 오탈자 수정·오번역 개선·용어집 정비 등 다양한 형태의 기여가 가능합니다.

2. 1주차: 번역 원칙 이해와 첫 PR 연습

2.1. 필독 리스트에서 정리한 번역 중요점 3가지

1주차 과제의 첫 번째 단계는 TRANSLATION_GUIDE.md, CONTRIBUTING.md, 번역 모범 사례(javascript.info)를 읽고 핵심을 정리하는 것이었습니다.

세 문서를 읽으며 가장 중요하다고 느낀 점을 세 가지로 추렸습니다.

#	중요 원칙	이유
1	의역·설명 추가 시 원문 의미 변질 금지	직역이 어색해도 원문 의도를 바꾸면 오히려 독자에게 잘못된 정보를 전달한다
2	번역 후 기호 검색으로 문법 오류 검토	RST 문서 특성상 `·`:math:` 등 기호 오류가 빌드 실패로 이어지기 쉽다
3	기여 전 기존 이슈/PR 선행 확인	이미 논의 중이거나 종결된 이슈에 중복 작업을 하면 낭비가 된다

2.2. 연습 레포에서 이슈 생성 및 PR 제출

필독을 마친 뒤, 실전 흐름을 익히기 위해 연습용 레포(jih0-kim/2026-OSSCA-test)에서 3~4줄 분량의 번역 PR을 올렸습니다.

# 로컬 빌드로 번역 결과 확인
python -m venv .venv
source .venv/bin/activate
pip install -r .build/requirements-minimal.txt
make html-noplot
open _build/html/index.html

빌드가 정상적으로 완료된 것을 확인한 뒤 PR을 올렸습니다.

3. 2주차 ①: 오번역 수정

3.1. 발견한 오번역

intermediate_source/autograd_saved_tensors_hooks_tutorial.py 파일을 검토하던 중, gradient를 기울기로 번역한 부분을 발견했습니다. TRANSLATION_GUIDE.md에는 gradient의 공식 번역어가 명확히 변화도로 명시되어 있습니다.

따라서 공식 가이드를 기준으로 수정 후 PR을 작성하였습니다.

수정 전	수정 후	근거
기울기	변화도	TRANSLATION_GUIDE.md: `gradient → 변화도`

아래는 수정 전 원문 코드 일부입니다.

3.2. 수정 과정과 PR

오번역 위치를 파악한 뒤 이슈를 먼저 등록하고, 수정 후 PR을 제출했습니다.

4. 2주차 ②: 용어집에 새 용어 추가

4.1. 추가 배경

번역 작업을 진행하다 보면 용어집에 등재되지 않은 단어가 종종 등장합니다. Subclass도 그 중 하나였습니다. 번역자마다 다르게 옮길 수 있는 단어인 만큼, 공식 용어집에 추가해 일관성을 확보하는 것이 바람직하다고 판단했습니다.

영문	한글	비고
Subclass	상속	신규 추가

4.2. 이슈 → PR 흐름

용어 추가도 코드 수정과 동일하게 이슈 → PR 순서로 진행했습니다. 용어 선정의 근거를 이슈에 먼저 서술해 리뷰어가 맥락을 파악할 수 있도록 했습니다.

다만 이 용어집 추가의 경우, 멘토분들이나 다른 기여자 분들의 검토 및 동의하에 최종적으로 PR이 진행 될 예정이라고하셔서, 의견제시만 했을뿐 용어집에 추가가 되지는 않을 수 있습니다.

5. 1~2주차를 돌아보며 — 오픈소스 기여에서 얻은 것

2주간의 활동을 통해 "좋은 번역 규칙"과 "올바른 오픈소스 기여 프로세스"를 배울 수 있었습니다.

영역	배운 점	적용 방법
번역 품질	번역 가이드 규칙이나 용어집 한 단어 차이가 문서 전체 일관성에 영향	기여 전 TRANSLATION_GUIDE.md 재확인 습관화
프로세스	이슈 선등록 → PR 제출 흐름이 리뷰 효율을 높임	수정이 작더라도 이슈 없이 PR 직행하지 않기
중복 방지	기존 이슈/PR 확인 없이 시작하면 헛수고	키워드 검색으로 선행 논의 유무 먼저 확인

3~4주차에는 더 긴 분량의 번역 개선을 진행할 예정입니다.

참고자료

https://github.com/PyTorchKorea/tutorials-kr/blob/master/TRANSLATION_GUIDE.md

https://github.com/PyTorchKorea/tutorials-kr/blob/master/CONTRIBUTING.md

https://github.com/javascript-tutorial/ko.javascript.info/wiki/%EB%B2%88%EC%97%AD-%EB%AA%A8%EB%B2%94-%EC%82%AC%EB%A1%80

[Claude] Claude code 기초 체험

dong_seok — Sun, 25 Jan 2026 21:49:10 +0900

평소 Claude Code를 터미널에서 실행해 소스 코드 관련 Q&A 용도로만 가볍게 사용해왔습니다. 그러다 최근 Claude Code가 생각보다 훨씬 다양한 기능을 제공한다는 사실을 알게 되었고, 이를 계기로 관련 기능들을 정리하고 직접 활용해보는 시간을 가졌습니다.

1. Claude Code 기본 명령어 정리

본격적인 설정에 앞서 Claude Code의 핵심 명령어를 정리했습니다.

1.1. 터미널 실행 명령어

명령어	기능
claude	Claude Code 실행
claude --dangerously-skip-permissions	Auto Mode로 실행 (권한 확인 생략)

1.2. Claude Code 내부 CLI 명령어

명령어	기능
/ide	IDE 연동 (Diff viewer, 라인 선택)
/model	사용할 모델 선택
@	파일 첨부
shift + tab / alt + m (윈도우)	Plan Mode ↔ Auto Mode 전환
/resume	이전 작업 이어서 진행
/memory	프로젝트/유저 메모리 설정
#	메모리와 유사한 기능 (작동 방식 상이)
/init	Claude.md 파일 생성
/mcp	MCP 서버 목록 확인
/compact	대화 기록 요약 (기존 대화 삭제)
/clear	기존 대화 내역 전체 삭제
/permissions	사용 가능한 도구 권한 설정
/exit	Claude Code 종료 (Ctrl+C 2번이 더 빠름)
/usage	현재 세션과 금주 세션 Claude 사용량 모니터링
/plugins	사용 가능하거나 설치된 플러그인 설정

이제 본격적으로 GitHub MCP 설정 과정을 살펴보겠습니다.

2. 첫 번째 시도: User Scope 플러그인 설치

2.1. 플러그인 설치

Claude Code에서 GitHub 플러그인을 설치하는 것은 간단합니다:

bash

# Claude Code 실행
claude

# 플러그인 설치
/plugin
# Discover 탭에서 github 검색 후 설치
```

### 2.2. 로컬 작업은 성공

처음에는 순조로웠습니다. Claude에게 "Git 저장소를 초기화하고 커밋해줘"라고 요청하니, 로컬 Git 작업은 완벽하게 수행되었습니다:

- ✅ `git init` 실행
- ✅ `.gitignore` 파일 생성
- ✅ 파일 스테이징 및 커밋
- ✅ 브랜치 `main`으로 설정

### 2.3. 문제 발생: 원격 저장소 연동 실패

하지만 "GitHub에 새 저장소를 만들고 Push해줘"라고 요청하자 문제가 발생했습니다:
```
❌ MCP 연결 끊김
❌ Invalid MCP server config for 'github': Missing environment variables: GITHUB_PERSONAL_ACCESS_TOKEN

원인을 분석한 결과, GitHub Personal Access Token이 설정되지 않아서 MCP 서버가 GitHub API와 통신할 수 없었던 것입니다.

3. 문제 진단과 해결 과정

3.1. MCP 서버 상태 확인

bash

claude mcp list
```

실행 결과:
```
plugin:github:github: https://api.githubcopilot.com/mcp/ (HTTP) - ✗ Failed to connect
Status: ✘ not authenticated

3.2. 근본 원인 파악 및 해결 방향 결정

Claude Code의 안내 메시지를 보니 핵심 문제가 명확했습니다:

User Scope 플러그인은 전역 설정(환경변수)을 필요로 함
프로젝트별 .mcp.json 파일로는 User Scope 플러그인 설정 불가
GitHub Personal Access Token 미설정

-> 에러를 해결하지 못해서 표준 MCP 서버를 직접 설정하는 방식으로 방향을 전환했습니다. 플러그인으로 해보고싶었지만, 표준 MCP 서버를 직접 설정해보는 방식해도 해보지 못했기에, 가능한 방법을 먼저 진행해보고 해결하지못한 이슈는 추후에 다시 시도하기로 하였습니다.

4. 해결책: 표준 MCP 서버 직접 설정

4.1. Project Scope로 MCP 서버 설정

플러그인 대신, 프로젝트별로 MCP 서버를 직접 설정하기로 결정했습니다. 이 방식은 여러 프로젝트에서 다른 GitHub 계정을 사용할 수 있다는 장점도 있습니다.

4.2. GitHub Personal Access Token 발급

GitHub 웹사이트 접속: https://github.com/settings/tokens
"Generate new token (classic)" 클릭
필요한 권한 선택:
- ✅ repo (전체 저장소 접근 권한)
- ✅ workflow (GitHub Actions 워크플로우)
- ✅ delete_repo (저장소 삭제, 선택사항)
"Generate token" 클릭
생성된 토큰 복사 (형식: ghp_xxxxxxxxxxxxxxxxxxxxx)

⚠️ 주의: 토큰은 생성 직후에만 확인 가능하므로 안전한 곳에 보관이 필요합니다.

4.3. .mcp.json 파일 생성

프로젝트 루트에 .mcp.json 파일을 직접 생성하고 토큰을 설정합니다:

bash

cd /Users/dongseok/Desktop/workspace/프로젝트명/test

# .mcp.json 파일 생성
cat > .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_여기에_실제_발급받은_토큰_입력"
      }
    }
  }
}

4.4. 보안 설정: .gitignore 업데이트

토큰이 포함된 .mcp.json 파일이 GitHub에 업로드되지 않도록 .gitignore에 추가합니다:

bash

echo ".mcp.json" >> .gitignore

4.5. Claude Code 재시작 및 확인

bash

# Claude Code 재시작
# Ctrl+C로 종료 후
claude

# MCP 서버 상태 확인
claude mcp list
```

이제 결과를 보면:
```
plugin:github:github: ... - ✗ Failed to connect    # 플러그인은 여전히 실패
github: npx ... - ✓ Connected                       # 직접 설정한 MCP 서버 성공!

* 중요한 발견 : 처음에는 플러그인 설정을 수정해서 성공한 줄 알았지만, 실제로는 플러그인은 여전히 실패 상태였고, .mcp.json으로 설정한 별도의 MCP 서버가 작동하고 있었던 것입니다!

4.6. 실패한 플러그인 제거 (선택사항)

혼란을 방지하기 위해 작동하지 않는 플러그인을 제거할 수 있습니다:

bash

/plugin uninstall github
```

제거 후에는 다음과 같이 깔끔하게 하나만 표시됩니다:
```
github: npx -y @modelcontextprotocol/server-github - ✓ Connected
```

5. 시행착오로 배운 핵심 포인트

5.1. Scope 이해하기

Scope설정	위치적용	범위	장점	단점
User Scope	~/.zshrc 환경변수	전역 (모든 프로젝트)	한 번 설정으로 끝	프로젝트별 다른 계정 사용 불가
Project Scope	.mcp.json	프로젝트별	계정/설정 분리 가능	프로젝트마다 설정 필요

5.2. 파일 역할 구분

.claude: 플러그인 활성화 on/off만 관리 (자동 생성되었으나 실제로는 사용되지 않음)
.mcp.json: MCP 서버 설정 및 환경변수 정의 (실제 작동하는 설정)
.env: 환경변수 대안 (선택사항)

참고자료

https://principled-learning-2c9.notion.site/216dc93a597c80f6953ef4d048d55926

[GPU 기초] AI 시대를 지배하는 하드웨어, NVIDIA GPU의 모든 것

dong_seok — Thu, 15 Jan 2026 17:10:10 +0900

최근 AI 기술의 폭발적인 성장과 함께 하드웨어 인프라에 대한 관심이 뜨겁습니다. NVIDIA가 시장을 독점하는 이유와 아키텍처별 진화 과정, 그리고 규제 속에서 등장한 '800 시리즈'의 기술적 디테일을 완벽 정리해 드립니다.

1. AMD vs NVIDIA: 왜 모두가 NVIDIA를 선택할까?

하드웨어 스펙 시트상으로는 AMD도 강력한 경쟁자이지만, AI 실무 현장에서 NVIDIA가 압도적인 이유는 단순한 칩 성능 그 이상에 있습니다.

CUDA 생태계 (The Software Moat): 2006년부터 구축된 CUDA는 모든 AI 프레임워크와 완벽히 호환되며, 전 세계 개발자들이 가장 선호하는 표준입니다.
연산 효율의 차이: NVIDIA는 일찍부터 AI 전용 Tensor Core를 도입하여 행렬 연산 속도를 비약적으로 높였습니다.
상호 연결 기술 (NVLink): 수만 개의 GPU를 하나로 묶어 거대 모델(LLM)을 학습시킬 때 발생하는 데이터 병목 현상을 해결하는 핵심 무기입니다.

2. NVIDIA GPU 아키텍처의 진화와 성능 개발 내역

NVIDIA는 매 세대마다 SM 개수와 주기당 연산량을 늘리며 성능의 한계를 돌파해왔습니다.

아키텍처	대표 모델	SM 개수	주요 특징	AI 연산 성능
Volta	V100	80	최초의 AI 전용 텐서 코어 아키텍처	125 TFLOPS (FP16)
Turing	T4	40	추론용 성능 강화 (2세대 텐서 코어)	65 TFLOPS (FP16)
Ampere	A100	108	TF32 도입, 주기당 연산량 2배 증가	312 TFLOPS (FP16)
Hopper	H100	132	Transformer Engine (FP8 <-> FP16 자동전환), FP8 도입	1.98 PFLOPS (FP8)
Blackwell	B200/ GB200	~600	듀얼 다이 구조, FP4 지원	20 PFLOPS (FP4)
Rubin (2026)	-	-	-	-

Ampere (A100): SM당 주기별 연산 횟수를 256회로 높이고 처음으로 FP8 모드를 도입했습니다.
Hopper (H100): 주기당 연산 512회로 성능을 두 배 높여 처음으로 PFLOPS(Peta FLOPS) 시대에 진입했습니다.
Blackwell (B200): 듀얼 다이 구조와 160개의 SM(Ultra 기준)을 통해 H100 대비 추론 성능을 최대 30배까지 끌어올렸습니다.

3. 핵심 기술 요소 상세 분석: SM과 HBM

3.1. SM (Streaming Multiprocessor)

개념: GPU 내부에서 실제 연산을 수행하는 '핵심 계산 유닛'입니다.
진화: Ampere(A100)는 SM당 연산 처리 능력을 2배(128→256 ops/cycle)로 높였고, Hopper(H100)는 다시 512회로 높였습니다. Blackwell은 SM 개수 자체를 600개까지 늘려 성능을 극대화했습니다.
공식: GPU 전체 성능 = [SM 개수 × 주기당 연산 횟수 × 동작 주파수]의 조합으로 결정됩니다.

3.2. HBM (High Bandwidth Memory)

개념: D램을 수직으로 쌓아 올려 데이터 전송 통로를 극대화한 고대역폭 메모리입니다.
필요성: AI 모델의 파라미터가 거대해짐에 따라, 연산 속도만큼 데이터를 읽어오는 속도가 중요해졌습니다. 이를 위해 GPU 바로 옆에 HBM을 배치하여 병목 현상을 해결합니다. (H100: HBM3 / Blackwell: HBM3e)

4. A100/H100 vs A800/H800: 규제가 만든 기술적 차이

'800' 시리즈는 미국 정부의 대중국 수출 제한 규정에 따라 성능을 인위적으로 조정한 모델입니다.

4.1. 수출 제한의 배경과 기준

I/O 대역폭: 전송 속도 600GB/s 이상 규제
컴퓨팅 파워: 특정 수치 이상의 연산 능력을 갖춘 칩의 수출을 금지함에 따라 성능을 조정한 하위 모델이 등장했습니다.

4.2. A800과 H800의 실제 사양 변화

A800: 연산 성능은 A100과 동일하지만, NVLink 대역폭을 400GB/s로 하향했습니다. 이로 인해 다중 GPU 훈련 시 효율이 약 40% 감소합니다.
H800: 대역폭 조정은 물론, FP64(배정밀도) 연산 성능을 1 TFLOPS 수준으로 제한했습니다. 이는 AI 학습 외에 고성능 과학 계산(HPC)이나 슈퍼컴퓨팅 용도로 활용되는 것을 차단하기 위한 조치입니다.

5. 전문성 향상을 위한 핵심 기술 용어 정리

5.1. 연산 성능 단위 (FLOPS)

FLOPS: 초당 수행 가능한 부동소수점 연산 횟수입니다.
Tflops (Tera): 1초에 1조 번 연산
Pflops (Peta): 1초에 1,000조 번 연산 (H100부터 본격 진입)

5.2. 데이터 정밀도 (Precision)

FP32: 고정밀 과학 계산용.
FP16 / BF16: 현재 AI 학습의 표준 규격.
FP8 / FP4: 최신 아키텍처에서 추론 속도를 극대화하기 위해 도입된 저정밀도 규격입니다. 비트 수가 낮을수록 연산은 빨라지지만 정밀도는 미세하게 조정됩니다.

참고자료

https://www.fibermall.com/ko/blog/nvidia-ai-chip.htm?srsltid=AfmBOooHXlRMceMJt6LPRgRXqmVmTgPhF490iqCD4eo-8bkUt14GSMhB

https://recording-it.tistory.com/122

[정규표현식] 데이터 전처리를 위한 정규표현식

dong_seok — Sun, 13 Jul 2025 18:17:32 +0900

데이터를 파싱하고 정제하는 과정에서 정규표현식을 통해 원하는 내용의 값들만 추출하고, 변경하는 작업을 할 수 있습니다. 파이썬의 re 모듈을 활용한 정규표현식의 개념과 사용 예제에 대해 간략하게 살펴보겠습니다.

1. 정규표현식의 기초 : 패턴을 만드는 규칙

정규표현식은 특정 규칙을 가진 문자열의 집합을 표현하는 데 사용됩니다. 몇 가지 기본 특수 문자(패턴)만 알면 금방 익숙해질 수 있습니다.

. (마침표): 줄바꿈 문자(\n)를 제외한 모든 문자와 매치됩니다.
\d: 숫자를 의미합니다. [0-9]와 같습니다.
\s: 공백 문자(스페이스, 탭, 줄바꿈 등)를 의미합니다.
\w: 알파벳, 숫자, 언더스코어(_)를 포함하는 문자입니다. [a-zA-Z0-9_]와 같습니다.
* (애스터리스크): 바로 앞의 문자가 0번 이상 반복되는 경우와 매치됩니다.
+ (플러스): 바로 앞의 문자가 1번 이상 반복되는 경우와 매치됩니다.
? (물음표): 바로 앞의 문자가 0번 또는 1번 나타나는 경우와 매치됩니다.
[] (대괄호): 괄호 안의 문자 중 하나와 매치됩니다. (예: [abc]는 'a', 'b', 'c' 중 하나)
() (소괄호): 그룹을 만들어 패턴을 묶거나, 매치된 부분을 캡처(추출)하는 데 사용됩니다.

이 외에도 다양한 특수 문자들이 있지만, 이 정도만 알아도 웬만한 패턴은 만들 수 있습니다.

2. re.compile()

정규 표현식 패턴을 미리 컴파일하여 re.Pattern 타입의 객체를 반환합니다. 같은 패턴을 여러 번 사용할 때 성능 상 유리하고, 미리 컴파일하여 재사용할 때 속도에서 이점을 얻을 수 있습니다.

[입력 예시]

import re

# 컴파일된 패턴
TITLE_PATTERN = re.compile(r'^([１２３４５６７８９０\d]+\.\s*)(.*)$')

# 입력 샘플
samples = [
    "1. 파이썬 정규표현식",
    "２. 두 번째 제목입니다.",
    "10. 마지막 제목"
]

for content in samples:
    title_match = TITLE_PATTERN.match(content)
    if title_match:
        # group(1)은 첫 번째 괄호에 매치된 부분, group(2)는 두 번째 괄호에 매치된 부분
        print(f"입력: '{content}'")
        print(f"  - 번호 부분: '{title_match.group(1)}'")
        print(f"  - 제목 부분: '{title_match.group(2)}'\n")

r
- raw string을 의미합니다.
- Python 문자열에서 \는 이스케이프 문자입니다. \d, \s, \. 같은 정규 표현식 특수 문자를 제대로 전달하려면 \\d, \\s, \\.로 써야 하는데 raw string을 사용하면 백슬래시를 그대로 전달할 수 있어 가독성이 좋아지기때문에 사용합니다.
^
- 문자열의 시작을 의미합니다.
([１２３４５６７８９０\d]+\.\s*)
- 첫 번째 캡처 그룹입니다.
- 전각 숫자(1 , 2 ,...)와 반각 숫자(1,2,...)가 1번 이상 반복되고 마침표 문자가 있고 공백 문자가 0번 이상 반복되는 패턴을 찾습니다.
(.*)
- 두 번째 캡처 그룹입니다.
- 줄바꿈 문자를 제외한 모든 문자가 0번 이상 반복되는 패턴, 즉 나머지 모든 텍스트를 의미합니다.
$
- 문자열의 끝을 의미합니다.
re.match()
- 문자열의 처음부터 패턴이 일치하는지 확인합니다. 중간부터 일치하는 경우는 찾아내지 못합니다.
- 매치가 성공하면 match 객체를 리턴하고 매치되지 않을때는 None을 리턴합니다.

[실행 결과]

입력: '1. 파이썬 정규표현식'
  - 번호 부분: '1. '
  - 제목 부분: '파이썬 정규표현식'

입력: '２. 두 번째 제목입니다.'
  - 번호 부분: '２. '
  - 제목 부분: '두 번째 제목입니다.'

입력: '10. 마지막 제목'
  - 번호 부분: '10. '
  - 제목 부분: '마지막 제목'

3. re.split(pattern, string)

정규표현식 패턴에 맞는 부분을 구분자로 하여 문자열을 분리한 뒤, 리스트로 반환합니다.

[입력 예시]

import re

# 입력 샘플 (데이터프레임의 한 열이라고 가정)
row = {'유형1': '건강/상해, 운전자, 종합보험'}

# re.split 사용
types = re.split(r'[/,]', row['유형1'])

# 각 요소를 순회하며 공백 제거 (x.strip() 활용)
cleaned_types = [x.strip() for x in types if x.strip()]

print(f"입력: '{row['유형1']}'")
print(f"분리 및 공백 제거 후: {cleaned_types}")

r'[/,]'
- '/' 또는 ',' 문자를 의미하는 정규표현식입니다. [] 안에 넣으면 'or' 조건으로 작용합니다.
x.strip()
- 각 요소를 순회하면 공백을 제거해서 쉼표 뒤의 공백까지 깔끔하게 제거하였습니다.

[실행 결과]

입력: '건강/상해, 운전자, 종합보험'
분리 및 공백 제거 후: ['건강', '상해', '운전자', '종합보험']

4. re.findall(pattern, string)

패턴과 일치하는 모든 부분을 찾아 리스트로 반환합니다.

[입력 예시]

import re

# 입력 샘플
insurance_period = "보험기간: 10년 (최대 100세 보장)"

# 숫자만 모두 찾기
numbers = re.findall(r'\d+', insurance_period)
print(f"입력: '{insurance_period}'")
print(f"찾아낸 모든 숫자: {numbers}")

# 첫 번째 숫자만 선택하여 문자열로 변환
first_number_str = str(numbers[0])
print(f"첫 번째 숫자(문자열): '{first_number_str}'")

r'\d+'
- 숫자(\d)가 1번 이상 반복되는 패턴을 찾습니다.
numbers[0]
- findall을 통해 반환된 리스트의 첫 번째 요소를 선택합니다.

[실행 결과]

입력: '보험기간: 10년 (최대 100세 보장)'
찾아낸 모든 숫자: ['10', '100']
첫 번째 숫자(문자열): '10'

5. re.search(pattern, string)

문자열 전체를 검색하여 패턴과 일치하는 첫 번째 부분을 Match 객체로 반환하고, 없으면 None을 반환합니다.

[입력 예시]

import re

# 패턴
PATTERN = re.compile(r"(건강심사|간편심사)(?:\(([^)]+)\))?형?")

# 입력 샘플
samples = [
    "상품명: 무배당 건강심사형 보험",
    "이것은 간편심사(325) 상품입니다.",
    "그냥 간편심사 보험"
]

for text in samples:
    match = PATTERN.search(text)
    if match:
        print(f"입력: '{text}'")
        # group(1)은 첫 번째 괄호, group(2)는 두 번째 괄호(괄호 안 내용)
        print(f"  - 심사 유형: '{match.group(1)}'")
        # group(2)는 괄호가 없는 경우 None이 됩니다.
        print(f"  - 괄호 내용: '{match.group(2)}'\n")

(건강심사|간편심사)
- 첫 번째 캡처 그룹입니다.
- "건강심사" 또는 "간편심사" 문자열과 일치합니다.
(?:$([^)]+)$)?
- (?: ... )
  - 캡처하지 않는 그룹으로, 그룹으로 묶어주지만 match.group()으로 결과를 저장(캡처) 하지는 않습니다.
  - 패턴을 하나로 묶어주기만 할 뿐입니다.
- $ , $
  - 실제 괄호 '(' 와 ')' 문자를 찾습니다.
- ([^)]+)
  - 두 번째 캡처 그룹입니다.
  - 닫는 괄호를 제외한 모든 문자가 1번 이상 반복되는 패턴을 찾습니다. 즉, 괄호 안의 내용물을 의미합니다.
- 형?
  - "형" 이라는 글자가 있을 수도 있고 없을 수도 있다는 의미입니다.

[실행 결과]

입력: '상품명: 무배당 건강심사형 보험'
  - 심사 유형: '건강심사'
  - 괄호 내용: 'None'

입력: '이것은 간편심사(325) 상품입니다.'
  - 심사 유형: '간편심사'
  - 괄호 내용: '325'

입력: '그냥 간편심사 보험'
  - 심사 유형: '간편심사'
  - 괄호 내용: 'None'

참고자료

https://wikidocs.net/4308

[DataFrame] 전처리를 위한 DataFrame 함수들

dong_seok — Sat, 12 Jul 2025 12:06:40 +0900

데이터 전처리과정에서 DataFrame을 많이 다루게 돼서 이참에 기본적이고 핵심적인 함수들을 한번 정리하고 가보도록 하겠습니다.

예제 데이터 준비하기

import pandas as pd
import numpy as np

# 예제용 샘플 데이터프레임
df = pd.DataFrame({
    '제품명': ['A-1', 'B-1', 'A-1', 'C-1', 'B-2', 'D-1'],
    '카테고리': ['가전', '가구', '가전', '가전', '가구', '주방'],
    '가격': [100, 150, 100, 120, 180, np.nan],
    '태그': [['신상', '인기'], '할인', ['신상', '인기'], '추천', '할인', np.nan]
}, index=['p1', 'p2', 'p3', 'p4', 'p5', 'p6'])

print("--- 원본 데이터 ---")
print(df)

[실행 결과]

     제품명 카테고리     가격          태그
p1   A-1    가전  100.0  [신상, 인기]
p2   B-1    가구  150.0        할인
p3   A-1    가전  100.0  [신상, 인기]
p4   C-1    가전  120.0        추천
p5   B-2    가구  180.0        할인
p6   D-1    주방    NaN         NaN

1. columns : 열 이름 확인과 변경

데이터프레임의 모든 열 이름을 확인하거나 변경할 때 사용합니다. 어떤 열들이 있는지 확인하고, 필요하다면 이름을 바꿀 수 있습니다.

[사용 예시]

# 현재 열 이름 확인하기
print(df.columns)

# 열 이름 전체를 영어로 변경하기
df_renamed = df.copy() # 원본 데이터는 소중하니까 복사해서 사용해요!
df_renamed.columns = ['Product', 'Category', 'Price', 'Tags']
print("\n--- 열 이름 변경 후 ---")
print(df_renamed.head(2))

[실행 결과]

Index(['제품명', '카테고리', '가격', '태그'], dtype='object')

--- 열 이름 변경 후 ---
    Product Category  Price         Tags
p1     A-1       가전  100.0  [신상, 인기]
p2     B-1       가구  150.0         할인

2. loc : 이름으로 데이터 선택하기

라벨(이름) 기반으로 행과 열을 선택할 수 있습니다. loc[행_라벨, 열_라벨] 형식으로 사용하고 사람이 보고 이해가기 가장 직관적인 방법이라고 할 수 있습니다.

[사용 예시]

# 1) 특정 행 선택하기 (p1 행의 모든 정보)
print(df.loc['p1'])

# 2) 여러 행과 특정 열 선택하기 (p1, p4 행의 제품명, 가격 정보)
print("\n", df.loc[['p1', 'p4'], ['제품명', '가격']])

# 3) 조건에 맞는 행 선택하기 (카테고리가 '가구'인 모든 데이터)
print("\n", df.loc[df['카테고리'] == '가구'])

[실행 결과]

제품명            A-1
카테고리            가전
가격            100.0
태그       [신상, 인기]
Name: p1, dtype: object

      제품명     가격
p1   A-1  100.0
p4   C-1  120.0

     제품명 카테고리     가격   태그
p2   B-1    가구  150.0   할인
p5   B-2    가구  180.0   할인

3. iloc : 위치로 데이터 선택하기

0부터 시작하는 정수 위치(순서)로 데이터를 선택합니다. 코드로 특정 위치의 데이터를 가져올 때 매우 유용합니다.

[사용 예시]

# 1) 첫 번째 행 선택하기 (0번 인덱스)
print(df.iloc[0])

# 2) 여러 행과 열 슬라이싱하기 (0~2번 행, 1~2번 열)
print("\n", df.iloc[0:3, 1:3])

[실행 결과]

제품명            A-1
카테고리            가전
가격            100.0
태그       [신상, 인기]
Name: p1, dtype: object

     카테고리     가격
p1    가전  100.0
p2    가구  150.0
p3    가전  100.0

4. concat : 데이터프레임 합치기

여러개로 나뉜 데이터를 하나로 합칠때 사용합니다.

[사용 예시]

# 추가할 새로운 데이터
new_product = pd.DataFrame({'제품명': ['E-1'], '카테고리': ['생활'], '가격': [80], '태그': ['특가']})

# 기존 데이터프레임(df) 아래에 새로운 데이터(new_product)를 합치기
df_combined = pd.concat([df, new_product], ignore_index=True) # ignore_index=True 로 인덱스를 새로 부여
print(df_combined.tail(3))

[실행 결과]

   제품명 카테고리     가격    태그
4  B-2    가구  180.0    할인
5  D-1    주방    NaN   NaN
6  E-1    생활   80.0    특가

5. drop_duplicates : 중복 데이터 제거하기

중복된 행을 제거합니다. subset으로 특정 열 기준 중복 검사가 가능하고, keep으로 어떤 중복값을 남길지 정할 수 있습니다.

(p1, p3가 모든 데이터가 동일한 중복 행이라고 가정하겠습니다.)

[사용 예시]

# 1) 기본 : 모든 열이 동일한 행 제거 (첫 번째 값 남김)
print(df.drop_duplicates())

# 2) keep='last' : 중복된 값 중 마지막 값 남기기
print("\n", df.drop_duplicates(keep='last'))

# 3) subset=['카테고리'] : '카테고리' 열 기준으로 중복 제거
print("\n", df.drop_duplicates(subset=['카테고리']))

[실행 결과]

// (기본) p3 행이 제거됨
     제품명 카테고리     가격          태그
p1   A-1    가전  100.0  [신상, 인기]
p2   B-1    가구  150.0        할인
p4   C-1    가전  120.0        추천
p5   B-2    가구  180.0        할인
p6   D-1    주방    NaN         NaN

// (keep='last') p1 행이 제거됨
     제품명 카테고리     가격          태그
p2   B-1    가구  150.0        할인
p3   A-1    가전  100.0  [신상, 인기]
p4   C-1    가전  120.0        추천
p5   B-2    가구  180.0        할인
p6   D-1    주방    NaN         NaN

// (subset) 카테고리별로 처음 나타나는 행만 남김
     제품명 카테고리     가격          태그
p1   A-1    가전  100.0  [신상, 인기]
p2   B-1    가구  150.0        할인
p6   D-1    주방    NaN         NaN

6. reset_index : 인덱스 재설정하기

데이터 정제 후 뒤죽박죽인 인덱스를 0부터 시작하는 깔끔한 정수 인덱스로 초기화합니다.

[사용 예시]

# 1) 기본 : 기존 인덱스('p1', 'p2'...)가 'index'라는 새로운 열로 들어감
print(df.reset_index().head(2))

# 2) drop=True : 기존 인덱스를 열로 추가하지 않고 그냥 버림
print("\n", df.reset_index(drop=True).head(2))

[실행 결과]

  index 제품명 카테고리     가격          태그
0    p1   A-1    가전  100.0  [신상, 인기]
1    p2   B-1    가구  150.0        할인

   제품명 카테고리     가격          태그
0   A-1    가전  100.0  [신상, 인기]
1   B-1    가구  150.0        할인

7. insert : 원하는 위치에 열 삽입하기

원하는 위치에 열을 삽입합니다. insert(위치, 열_이름, 데이터) 형식으로 사용합니다.

[사용 예시]

# 1번 위치(두 번째)에 '판매량' 열 삽입하기
df_inserted = df.copy()
sales_data = [50, 30, 80, 120, 40, 10]
df_inserted.insert(1, '판매량', sales_data)
print(df_inserted.head(2))

[실행 결과]

     제품명  판매량 카테고리     가격          태그
p1   A-1   50    가전  100.0  [신상, 인기]
p2   B-1   30    가구  150.0        할인

8. rename : 열 이름 부분 변경하기

columns 속성은 전체 이름을 바꿀 때, rename 속성은 특정 열의 이름만 골라서 바꿀 때 편리합니다.

[사용 예시]

# '제품명' -> '상품명', '가격' -> '판매가'로 변경
df_renamed_part = df.rename(columns={'제품명': '상품명', '가격': '판매가'})
print(df_renamed_part.head(2))

[실행 결과]

     상품명 카테고리     판매가          태그
p1   A-1    가전  100.0  [신상, 인기]
p2   B-1    가구  150.0        할인

9. explode : 리스트 데이터를 행으로 펼치기

하나의 셀에 여러 값이 리스트로 담겨있을 때, 각 값을 개별 행으로 분리해주는 함수입니다.

[사용 예시]

# '태그' 열의 리스트 값을 각각의 행으로 펼치기
df_exploded = df.explode('태그')
print(df_exploded)

[실행 결과]

     제품명 카테고리     가격   태그
p1   A-1    가전  100.0   신상
p1   A-1    가전  100.0   인기
p2   B-1    가구  150.0   할인
p3   A-1    가전  100.0   신상
p3   A-1    가전  100.0   인기
p4   C-1    가전  120.0   추천
p5   B-2    가구  180.0   할인
p6   D-1    주방    NaN  NaN

10. isna/notna : 결측치 확인하기

데이터가 결측치인지 아닌지를 boolean 값으로 반환합니다. 보통 .sum()과 함께 사용하여 결측치 개수를 파악합니다.

[사용 예시]

# isna() : 결측치면 True, 아니면 False
print(df.isna())

# isna().sum() : 열별 결측치 개수 파악
print("\n--- 열별 결측치 개수 ---")
print(df.isna().sum())

[실행 결과]

       제품명   카테고리     가격     태그
p1  False   False  False  False
p2  False   False  False  False
p3  False   False  False  False
p4  False   False  False  False
p5  False   False  False  False
p6  False   False   True   True

--- 열별 결측치 개수 ---
제품명      0
카테고리     0
가격       1
태그       1
dtype: int64

11. fillna : 결측치 채우기

결측치를 특정 값으로 채워 데이터를 깔끔하게 만듭니다.

[사용 예시]

# '가격'의 결측치는 0으로, '태그'의 결측치는 '정보없음'으로 채우기
df_filled = df.copy()
df_filled['가격'] = df_filled['가격'].fillna(0)
df_filled['태그'] = df_filled['태그'].fillna('정보없음')
print(df_filled.tail(1)) # 마지막 행 확인

[실행 결과]

     제품명 카테고리    가격     태그
p6   D-1    주방   0.0  정보없음

12. iterrows : 행 단위로 반복하기

데이터프레임의 행을 하나씩 순회하며 (인덱스, 행 데이터) 쌍을 반환합니다. for 문과 함께 사용하면 각 행의 데이터에 쉽게 접근할 수 있습니다.

[사용 예시]

# 각 행을 순회하며 제품명과 카테고리를 출력
for index, row in df.iterrows():
    product_name = row['제품명']
    category = row['카테고리']
    print(f"인덱스 '{index}' : {product_name} 제품은 {category} 카테고리에 속합니다.")

[실행 결과]

인덱스 'p1' : A-1 제품은 가전 카테고리에 속합니다.
인덱스 'p2' : B-1 제품은 가구 카테고리에 속합니다.
인덱스 'p3' : A-1 제품은 가전 카테고리에 속합니다.
인덱스 'p4' : C-1 제품은 가전 카테고리에 속합니다.
인덱스 'p5' : B-2 제품은 가구 카테고리에 속합니다.
인덱스 'p6' : D-1 제품은 주방 카테고리에 속합니다.

13. list와의 자유로운 변환

Pandas의 열(series)은 파이썬의 list와 쉽게 변환할 수 있어 데이터 활용도를 높여줍니다.

[사용 예시]

# '카테고리' 열을 리스트로 만들기
category_list = df['카테고리'].tolist()
print(category_list)

[실행 결과]

['가전', '가구', '가전', '가전', '가구', '주방']

[네트워크] 외부에서 사내 서버 접근

dong_seok — Sat, 5 Jul 2025 14:09:54 +0900

1. 서버에서 열려있는 포트 확인 방법

1) netstate

가장 일반적인 사용 방법

# 모든 열린 포트 확인
netstat -tuln

# 특정 포트 확인 (예: 8000번)
netstat -tuln | grep :8000

# 프로세스 정보까지 함께 보기
netstat -tulnp

2) ss

최신 방법으로 netstat보다 빠른 방법

# 모든 열린 포트 확인
ss -tuln

# 특정 포트 확인
ss -tuln | grep :8000

# 프로세스 정보 포함
ss -tulnp

2. 결과 해석

1) 0.0.0.0:포트번호

서버가 가진 모든 IP 주소로 접근 가능
서버 자체(localhost), 서버의 사내 IP, 인터넷에서(공인IP가 있고 방화벽이 허용한다면) 접근 가능

2) 127.0.0.1:포트번호

오직 해당 서버 자체에서만 접근 가능
서버에 직접 SSH로 접속해서 "localhost:포트번호" 또는 "127.0.0.1:포트번호"와 같은 형식으로 접근 가능
접근 불가능
- 같은 사내망의 다른 컴퓨터에서도 접근 불가
- 외부 인터넷에서도 접근 불가
- 서버의 실제 IP로도 접근 불가

3) LISTEN

아직 연결되지 않았지만 "열려 있는" 상태
포트를 지정한 도커 컨테이너를 실행하면 해당 포트가 LISTEN 상태로 출력되는걸 볼 수 있음

3. 포트 사용의 두 가지 방식

포트 번호의 범위는 0~65535로 고정입니다. 그 이유는 TCP/UDP 헤더에서 포트 번호를 16비트(2바이트)로 정의하기 때문에 2^16=65536개 (0~655535)라서 물리적으로 한계가 있습니다.

1) 서버 사용

개발자가 명시적으로 바인딩
1~65535 중 아무 포트나 사용 가능 (1024 미만은 root 권한 필요)

2) 클라이언트 사용

시스템이 32768~60999 중 자동 선택
-> "cat /proc/sys/net/ipv4/ip_local_port_range"으로 시스템에서 설정한 포트 자동 할당 범위 확인 가능

4. IP 확인

1) 외부에서 보는 공인 IP

curl ifconfig.me

외부 웹사이이트(ifconfig.me)에서 보는 나의 IP 주소로, 이 서버가 인터넷으로 나갈 때 사용하는 IP 주소를 의미합니다. 실행시 "203.123.45.67"와 같이 공인 IP를 확인할 수 있습니다.

2) 내 서버의 실제 IP

ip route get 8.8.8.8

8.8.8.8(구글 DNS)에 패킷을 보낼 때 어떤 경로로 나가는가?"를 확인함으로써 내 서버의 실제 IP를 의미합니다. 실행시 "8.8.8.8 via 192.168.1.1 dev eth0 src 203.123.45.67"와 같은 결과를 확인할 수 있고, 여기서 src 뒤의 IP가 외부로 나갈 때 사용하는 내 서버의 IP 주소를 의미합니다.

만일 두 IP가 같다면, 내 서버가 공인 IP를 직접 할당 받았다는 것을 의미하며, 외부에서 직접적으로 접근이 가능합니다. 다르다면, 인터넷과 내 서버 사이에 NAT/공유기가 존재한다는 사실을 알 수 있습니다. 이럴경우에 "curl ifconfig.me"로 출력되는 IP 주소는 공유기,회사 게이트웨이 등을 의미합니다.

5. 외부에서 사내 서버 접근하기

현재 외부에서 사내 서버에서 서빙중인 llm을 직접적으로 접근해서 api call을 하는것은 막혀있는 것으로 확인했습니다. 따라서 외부에서 사내 서버에 먼저 접속한 후 그 서버에서 필요한 소스코드를 다운받고 서버내에서 llm을 호출하는 방법을 사용하기로 하였습니다.

claude code 체험

dong_seok — Sun, 15 Jun 2025 18:37:46 +0900

에이전트형 코딩 도구의 양대산맥인 커서와 윈드서프중 어떤걸 사용할지 고민하다가 더 최근에 떠오른 윈드서프를 써보자는 생각이 들어 찾아보던도중 클로드 코드라는 에이전트형 코딩 도구를 접하게 되었습니다. 어쩌다 뜨게 된 것일까 궁금해 찾아보니 윈드서프에서 플랫폼 운영을 위해 클로드 모델에 크게 의존하고 있었는데, 앤트로픽에서 일방적으로 모델 접근 제한을 통보하면서 자연스럽게 이슈가 된 것으로 파악했습니다. 이러한 결정은 경쟁사인 오픈AI의 윈드서프 인수도 한몫 하지 않았을까하는 개인적인 생각입니다. 마침 클로드 프로를 구독하고 있었기에 클로드 코드를 사용해보기로 하였습니다.

기본적으로 npm을 사용하기 때문에 없으신분들은 별도로 설치후 진행해주시면 되겠습니다.

npm install -g @anthropic-ai/claude-code

명령어 실행 후 원하는 프로젝트 프로젝트 이동해줍니다.

cd your-project-directory

claude code를 실행시켜줍니다.

claude

처음 나오는 화면인데 모드를 설정하는 간단한 화면인 것 같습니다.

처음실행시 앤트로픽 계정을 인증해야합니다.

저는 이미 클로드 프로 계정을 보유하고 있었기에 1번을 선택하니 화면이 자연스럽게 이어졌습니다.

승인후 로그인이 완료된 모습입니다.

이후 몇몇 안내문구를 넘기고 클로드 코드 사용 화면을 접할 수 있었습니다.

CLI 기반 AI 코딩 도구이다보니 터미널에서 진행했는데 자연어 명령을 통해 실행되며 <claude "명령"> 형식으로 실행시키는 것으로 확인했습니다. 앞으로 더 다양한 테스트를 통해 클로드 코드를 사용해보도록 하겠습니다.

참고자료

https://digitalbourgeois.tistory.com/813

RAG Caching (/w Langchain & Langgraph)

dong_seok — Sat, 14 Jun 2025 18:24:41 +0900

LangGraph를 활용한 RAG 시스템의 챗봇을 과제로 진행하던 도중, 팀장님의 조언으로 동일한 질문에 대해 캐싱을 사용해 비용과 시간을 효율적으로 사용하라는 말씀을 들었습니다. 이에 따라 캐싱을 사용해 보다 더 효율적인 RAG 시스템을 구축하고자 하였습니다.

1. 문제상황

아래는 사용자의 같은 질문에 대해 소요된 시간과 토큰에 대한 이미지입니다.

첫번째 질문

두번째 질문

보시다시피 같은 질문임에도 똑같은 노드 순환을 반복하며 시간과 토큰이 소모되는 모습입니다.

2. InMemoryCache (/w Langchain)

langchain에서 캐싱을 위한 라이브러리를 제공해주어서 사용해보았습니다.

from langchain.globals import set_llm_cache
from langchain_community.cache import InMemoryCache

class GraphBuilder:
    def __init__(self):
        set_llm_cache(InMemoryCache())
        self.graph = self._create_graph()
        self.tracer = OpikTracer(
            graph=self.graph.get_graph(xray=True), 
            project_name="agiledocs-rag"
        )

위와같은 코드를 사용해 graph를 생성하기전에, InMemoryCache를 생성해주었습니다. 적용전 이미지는 하단과 같습니다.

set_llm_cache(InMemoryCache()) 적용 후의 이미지입니다.

보시면 query_classifier node에서는 0초의 시간이 소모되지만, 다른 노드는 여전히 순환하는 모습을 볼 수 있습니다. 이는 Langchain에서 제공하는 set_llm_cache(InMemoryCache())가 LLM 호출만 캐싱을 수행하기 때문입니다. 그렇다면 검색과 리랭킹을 제외한 다른 부분에서는 캐싱이 이루어져야하지않나? 라는 생각이 들 수 있지만, 멀티턴 대화 구성을 위해 프롬프트에 이전 메시지들인 chat_history가 새롭게 누적되다보니 동적인 프롬프트가 되어서 캐싱이 이루어지지 않는 것 입니다.

3. InMemoryCache (/w LangGraph)

그렇다면 Langchain을 활용한 캐싱이 최선일까? 라는 생각에서 시작해서 LLM을 통해 생성한 답변은 캐싱하지 못하더라도 retrieve, rerank처럼 동일한 역할을 수행하는 정적인 노드에 대해서만 이라도 캐싱을 수행할 수는 없을까? 라는 생각이 들어서 찾아낸 것이 LangGraph에서 새롭게 고안해낸 노드 단위의 캐싱입니다. 아래는 샘플 코드입니다.

from langgraph.cache.memory import InMemoryCache
from langgraph.types import CachePolicy
import hashlib

class Cache:
    def query_classifier_cache_key(self,state : State) -> str:
        """쿼리 분류기용 캐시 키 - 쿼리 내용만 사용"""
        query = state.get("query", "")
        normalized_query = query.strip().lower()
        cache_key = hashlib.md5(normalized_query.encode()).hexdigest()
        return cache_key

workflow.add_node("query_classifier", queryclassifier.classification, cache_policy=CachePolicy(key_func=cache.query_classifier_cache_key))
workflow.compile(cache=InMemoryCache())

캐싱을 하고자하는 노드에 CachePolicy()를 사용해주었고, 인자로 ttl과 key_func를 사용할 수 있습니다. ttl은 캐싱 유효시간을 의미하고 key_func는 캐싱의 키값을 반환하는 함수를 호출합니다.

구체적인 사용 흐름은 다음과 같습니다.

노드 실행전 LangGraph가 key_func를 호출해서 캐시 키 생성
생성된 키로 이전 결과 검색
값이 있으면 노드 실행 skip 후 바로 결과 반환, 없으면 노드 실행후 결과를 캐시에 저장

동일한 쿼리에 대해서는 항상 동일한 캐시 키값을 생성하도록 코드를 작성했기 때문에, 이전에 같은 질문을 했다면 캐싱된 값을 반환하게됩니다. 적용전 이미지는 하단과 같습니다.

적용 후의 이미지입니다.

시간도 토큰도 확실히 절약된 모습을 볼 수 있었습니다. 여기서 Langchain의 캐싱과 다른 모습을 발견할 수 있는데, LangGraph의 캐싱은 일치하는 키값이 있으면 바로 값을 반환하기때문에 노드를 아에 순환도 하지 않습니다. 반면, Langchain의 캐싱은 0초이긴하지만 노드 자체는 순환한다는 점에서 차별점이 있습니다.

그렇다면 노드를 아에 순환도 하지않는데 캐싱으로 반환하는 값이 무엇이길래 응답을 잘 하는 것이지?하고 생각이 들어서 이 부분도 확인해보았습니다. 처음에는 Multi-turn으로 구성하다보니 이전 대화에서 사용한 state가 다음 대화 기록에 사용 돼서 응답이 정상적으로 이루어지는건 아닐까? 하고 의심했었습니다. 그래서 질문 A,B가 있다고할때 A->B->A 순서로 질문을 해서 B의 state를 담은 상태에서 다시 A질문을 해보았습니다. 그런데도 정상 응답이 나오는걸 확인하고, 이전에 어떤 질문을 하던 상관없이 동일한 질문에 해당하는 값을 캐싱으로 반환할때 이전에 생성했던 상태값을 그대로 반환해준다는 것을 알게되었습니다.

마지막으로 아래는 Langchain, Langgraph의 캐싱을 모두 적용시킨 후 캐싱이 됐을 때 모습입니다.

query_classifier node가 나오지 않는 모습을 보아, LangGraph의 캐싱이 Langchain의 캐싱보다 우선수위가 높다는 것을 알 수 있었습니다.

참고자료

https://python.langchain.com/docs/how_to/llm_caching/

https://langchain-ai.github.io/langgraph/concepts/low_level/?_gl=1*puicu9*_gcl_au*MTAwNTc3NjE5MS4xNzQ5NTEzOTg2*_ga*NDg4NDUxMjExLjE3NDk0NTI1NDc.*_ga_47WX3HKKY2*czE3NDk1MTM5ODUkbzUkZzAkdDE3NDk1MTM5ODckajU4JGwwJGgw#node-caching

[LangGraph] LangGraph 기초 복습

dong_seok — Fri, 2 May 2025 22:20:31 +0900

LangGraph의 기본적인 개념에 대해 복습하는 시간을 가져보도록 하겠습니다.

1. LangGraph란?

LangGraph는 LLM 기반 워크플로우에 순환 연산 기능을 추가하여 복잡한 AI 애플리케이션의 흐름을 효과적으로 제어할 수 있는 프레임워크입니다. 노드(Node), 엣지(Edge), 상태(State)라는 세 가지 핵심 요소를 통해 RAG 파이프라인과 같은 복잡한 시스템을 유연하게 구성할 수 있습니다.

- Node, Edge, State 를 통해 LLM을 활용한 워크플로우에 순환 연산 기능을 추가하여 손쉽게 흐름을 제어

- RAG 파이프라인의 세부 단계별 흐름 제어가 가능

- Conditional Edge를 통한 조건부 흐름 제어 가능

- Human-in-th-loop를 통해 필요시 중간에 개입하여 다음 단계 결정이 가능

- Checkpointer 기능으로 과거 실행 과정에 대한 "수정" 및 "리플레이" 기능 제공

2. 핵심 구성 요소

2.1 State (상태)

상태는 노드 간에 정보를 전달하는 데이터 컨테이너입니다.

TypedDict: 일반 파이썬 딕셔너리에 타입힌팅을 추가한 구조
부분 업데이트: 모든 값을 채울 필요 없이 필요한 필드만 업데이트 가능
Overwrite 방식: 새로운 노드에서 동일한 키의 값을 덮어쓰는 방식으로 상태 갱신
Reducer: add_messages나 operator.add와 같은 함수로 자동으로 리스트에 항목 추가
Annotated: 타입 외에 키값에 대한 추가 정보 제공 가능

2.2 Node (노드)

노드는 워크플로우의 개별 단계를 정의하는 함수입니다.

함수로 정의
입력인자 : State
반환 : 대부분 State (Conditional Edge의 경우 다를 수 있음)
add_node("노드이름",함수)로 노드 추가

2.3 Edge (엣지)

엣지는 노드 간의 연결을 정의합니다.

노드에서 노드간의 연결
add_edge("노드이름","노드이름")로 노드 연결

노드에 조건부 엣지를 추가해 분기 수행 가능
add_conditional_edges("노드이름", 조건부 판단 함수, dict 로 다음 단계 결정)

3. 그래프 구성 및 실행

3.1 시작점 지정

set_entry_point("노드이름")
지정한 시작점부터 Graph가 시작

3.2 체크포인터(Checkpointer)

체크포인터는 그래프의 실행 흐름과 상태를 추적하고 저장합니다.

Checkpointer : 각 노드간 실행결과를 추적하기 위한 메모리(대화에 대한 기록과 유사 개념)
체크 포인터를 활용하여 특정 시점(Snapshot)으로 되돌리기 기능도 가능
compile(checkpointer=memory)로 지정하여 그래프 생성

3.3 그래프 실행

RunnableConfig
recursion_limit : 최대 노드 실행 개수를 지정
thread_id : 그래프 실행 아이디를 기록하고, 추후 추적하기 위한 목적으로 활용
invoke(상태,config)로 전달하여 실행

참고자료

https://www.youtube.com/watch?v=W_uwR_yx4-c

[Prompt Engineering] 프롬프트 엔지니어링의 심화 기법들(2)

dong_seok — Thu, 1 May 2025 22:32:35 +0900

언어 모델의 성능이 지속적으로 발전함에 따라, 이를 더 효과적으로 활용하기 위한 프롬프트 엔지니어링 기법도 진화하고 있습니다. 기본적인 프롬프트 기법을 넘어, 최근에는 AI의 추론 능력을 극대화하고 더 정확한 답변을 얻기 위한 심화 기법들이 연구되고 있습니다. 이 글에서는 최신 프롬프트 엔지니어링 심화 기법들을 살펴보고, 이를 활용하는 방법에 대해 알아보겠습니다.

1. Automatic Prompt Engineer (APE): 자동화된 프롬프트 최적화

1) 개념

자동 프롬프트 엔지니어(APE)는 최적의 프롬프트를 자동으로 생성하는 프레임워크
인간의 개입 없이 여러 단계의 평가 과정을 통해 최적의 명령어를 생성하고 선택
언어 모델 자체를 활용하여 더 나은 프롬프트를 발견하는 메타-프롬프팅 접근법

2) 작동 과정: 6단계 프로세스

1단계: 후보 명령어 제안 - 다양한 잠재적 프롬프트 생성
2단계: 점수 매기기 - 각 후보 프롬프트의 효과성 평가
3단계: 낮은 점수 후보 제거 - 성능이 떨어지는 프롬프트 필터링
4단계: 높은 점수 후보 선정 - 상위 성능 프롬프트 식별
5단계: 샘플링 모델 사용 (선택사항) - 다양성 확보를 위한 샘플링
6단계: 최종 후보 선정 - 최적의 프롬프트 결정

3) 주요 성과

APE가 발견한 프롬프트 예시: "Let's work this out in a step by step way to be sure we have the right answer."
이러한 자동 생성 프롬프트가 인간이 설계한 프롬프트보다 특정 작업에서 더 나은 성능을 보이는 경우도 있음
특히 복잡한 추론 작업에서 효과적인 프롬프트 패턴 발견 가능

4) 활용 가치

프롬프트 엔지니어링의 시간과 노력 절감
인간이 생각하지 못한 효과적인 프롬프트 패턴 발견
작업별 최적화된 프롬프트 자동 생성 가능성

2. Active-Prompt: 동적 프롬프트 최적화

1) 개념

LLM이 능동적으로 프롬프트를 생성하고 수정하는 방법
Chain-of-Thought(CoT) 추론의 한계를 극복하기 위한 접근법
다양한 작업에 특화된 예시 프롬프트를 자동으로 개선

2) CoT 기법의 한계 극복

인간이 만든 예시에 의존하는 기존 CoT의 한계 해소
어렵고 모호한 질문에 대해서도 효과적인 예시 자동 생성
사람이 질문-응답 쌍을 수작업으로 만드는 한계 극복

3) 작동 원리

초기 프롬프트에서 시작해 모델이 스스로 더 나은 예시 생성
생성된 예시를 평가하고 가장 효과적인 예시를 선택
선택된 예시를 활용해 최종 프롬프트 구성

4) 효과적인 활용 영역

계속 변화하는 복잡한 도메인의 질문 처리
다양한 유형의 추론 작업에 적응적 프롬프트 생성
도메인 전문성이 필요한 특수 분야 질의응답

3. Directional Stimulus Prompting: 방향성을 가진 자극 프롬프팅

1) 개념

모델의 출력을 원하는 방향으로 유도하는 프레임워크
방향성을 가진 자극을 통해 AI 모델이 특정 목표를 향해 나아가도록 함
힌트를 생성하는 별도의 작은 모델(T5 등)을 활용

2) 작동 방식

입력값에 대한 보조 프롬프트(힌트) 생성
생성된 요약에 특정 키워드나 개념을 포함하도록 유도
원하는 출력 방향으로 모델을 안내하는 자극 제공

3) 적용 사례

요약 작업에서 특정 주제나 관점 강조
대화 응답 생성 시 특정 톤이나 스타일 유도
사고 추론 과정에서 특정 방법론이나 프레임워크 활용 유도

4) 주요 장점

모델 출력의 예측 가능성 향상
사용자 의도에 더 부합하는 결과물 생성
특정 영역에 집중된 고품질 출력 생성 가능

4. ReAct: 추론과 행동의 통합적 접근

1) 개념

Reasoning(추론)과 Action(행동)을 교차적으로 사용하는 프롬프팅 방식
모델이 생각하고, 행동하고, 결과를 관찰하는 순환적 프로세스
외부 지식 소스와의 상호작용을 통합한 문제 해결 프레임워크

2) 핵심 구성 요소

Reasoning(추론)
- 모델의 행동 계획 수립
- 관찰 결과 추적 및 분석
- 다음 단계 전략 수립 및 예외 상황 처리
Action(행동)
- 외부 지식 베이스나 환경과 상호작용
- 정보 검색 및 도구 활용
- 실제 행동 실행 및 결과 관찰

3) 주요 장점

문제 해결 능력 향상
- 순차적 정보 검색 및 활용 가능
- 복잡한 다단계 문제에 체계적 접근
적응력 증가
- 이전 단계의 결과에 기반한 동적 전략 수정
- 예상치 못한 상황에 유연하게 대응
정보 신뢰성 향상
- 외부 검증 가능한 소스 활용
- 추론과 검색의 균형을 통한 정확도 증가

4) 활용 시나리오

복잡한 질문에 대한 사실 기반 답변 생성
외부 도구와 통합된 문제 해결(계산기, 검색 엔진 등)
단계적 의사결정이 필요한 복잡한 작업 수행

5. AI 모델의 추론 능력을 끌어올리는 핵심 전략

1) 단계적 사고 과정 유도

복잡한 문제를 작은 단계로 분해하도록 안내
"Let's break this down step by step"과 같은 지시어 활용
중간 과정과 결론을 명확히 구분하도록 구조화

2) 생각할 시간/여유 제공

모델이 충분히 추론할 수 있는 공간 확보
"Take your time to think about this thoroughly"와 같은 유도 표현 사용
초기 직관적 답변 이후 재고려 및 검증 단계 추가

3) 다양한 시각에서 사고하도록 유도

여러 관점에서 문제를 바라보도록 요청
"Consider this from multiple perspectives"와 같은 프롬프트 활용
대안적 해결책과 접근법을 탐색하도록 장려

참고자료

패스트 캠퍼스 - 국내 공채 1호 프롬프트 엔지니어 강수진의 프롬프트 엔지니어링 A to Z

[Prompt Engineering] 프롬프트 엔지니어링의 심화 기법들(1)

dong_seok — Wed, 30 Apr 2025 22:03:49 +0900

대규모 언어 모델(LLM)의 능력이 발전함에 따라, 더 정교하고 효과적인 프롬프트 엔지니어링 기법들이 등장하고 있습니다. 기본적인 Zero-shot, Few-shot, Chain-of-Thought 프롬프팅을 넘어서, 복잡한 문제 해결과 정확도 향상을 위한 고급 프롬프트 기법들을 알아보겠습니다.

1. Generate Knowledge Prompting (GoT): 지식 기반 추론 강화

1) 개념

언어 모델이 추론 전에 관련 지식을 먼저 생성하도록 하는 방법
답변 생성 전 모델이 스스로 관련 정보를 가져오고 활용하는 방식
할루시네이션(환각) 현상을 완화하기 위한 효과적인 접근법

2) 주요 목적

모델의 환각 현상 감소 및 사실 기반 답변 강화
추가 지식을 통한 추론 능력 향상
오픈 Q-A 테스크 방식을 활용한 자발적 지식 생성

3) 작동 방식: 3단계 프로세스

1단계: 지식 생성
- Few-shot 프롬프팅을 사용해 모델로부터 관련 정보와 사실 생성
- 질문과 관련된 배경 지식, 개념, 원리 등을 명시적으로 끌어냄
2단계: 지식 통합
- 생성된 지식을 프롬프트에 통합
- 지식의 신뢰도 평가 및 관련성 확인
3단계: 답변 생성
- 확보한 지식을 바탕으로 최종 답변 도출
- 근거 기반의 정확한 추론 수행

4) 프롬프트 예시

질문: 식물의 광합성 과정에서 빛 에너지는 어떻게 화학 에너지로 변환되나요?

단계 1: 이 질문에 답하기 위해 필요한 관련 지식을 먼저 정리해보세요.

[지식 생성 공간]
광합성은 식물이 빛 에너지를 이용해 이산화탄소와 물로부터 포도당을 합성하는 과정입니다.
광합성의 주요 단계는 명반응과 암반응으로 나눌 수 있습니다.
명반응은 엽록체의 틸라코이드 막에서 일어나며, 빛 에너지를 흡수해 ATP와 NADPH 형태의 화학 에너지로 변환합니다.
빛 에너지는 광계 I과 광계 II의 엽록소 분자에 의해 포착됩니다.
광계 II에서는 물 분자를 분해해 전자를 방출하고, 이 전자는 전자 전달계를 통해 ATP를 생성합니다.
광계 I에서는 추가 빛 에너지를 흡수하여 NADP+를 NADPH로 환원시킵니다.
암반응(캘빈 회로)에서는 명반응에서 생성된 ATP와 NADPH를 사용하여 이산화탄소를 포도당으로 고정합니다.

단계 2: 위 정보를 바탕으로 질문에 답변해주세요.

[답변 생성 공간]

5) 장점

사실에 기반한 정확도 향상
복잡한 도메인 지식이 필요한 질문에 효과적
모델의 추론 과정이 투명하게 드러남

6) 한계점

지식 생성 단계에서의 오류가 최종 답변에 영향
프롬프트 길이 증가로 인한 토큰 소비 증가
간단한 질문에는 불필요한 오버헤드 발생

2. Prompt Chaining: 복잡한 작업의 단계적 분해

1) 개념

복잡한 작업을 작고 관리하기 쉬운 하위 작업으로 나누는 기법
각 하위 작업을 별도의 프롬프트로 처리하는 연쇄적 접근법
한 프롬프트의 출력이 다음 프롬프트의 입력으로 사용되는 파이프라인 구조

2) 핵심 원리

문제 분해(Decomposition): 복잡한 작업을 독립적인 하위 작업으로 분할
순차적 처리(Sequential Processing): 각 단계를 순서대로 처리하여 최종 결과 도출
피드백 루프(Feedback Loop): 필요시 이전 단계로 돌아가 수정 및 개선 가능

3) 주요 장점

다단계 작업 처리 강화
- 조사, 계획, 작성 등 여러 단계가 필요한 작업에서 고품질 결과 보장
- 각 단계별 최적화된 프롬프트 설계 가능
복잡한 지시사항 관리 개선
- LLM이 한 번에 처리하기 어려운 복잡한 작업을 단계적으로 분해
- 각 단계의 작업 성능을 독립적으로 향상 가능
출력물 검증 및 품질 향상
- 중간 결과를 검증하고 필터링하는 단계 추가 가능
- 최종 출력물의 안전성, 정확성, 관련성 향상
병렬 처리 효율성
- 독립적인 하위 작업을 병렬로 처리해 시간 절약
- 리소스 활용 최적화 가능

4) 구현 예시: 연구 논문 작성 지원

# 단계 1: 주제 분석 및 정의
프롬프트: "인공지능 윤리에 관한 연구 주제를 구체화해 주세요. 주요 연구 질문 3개를 제안하세요."
출력: [연구 질문 리스트]

# 단계 2: 문헌 조사 가이드
프롬프트: "다음 연구 질문에 대한 문헌 조사를 위해 중요한 키워드와 검색 전략을 제안해 주세요: [단계 1 출력]"
출력: [키워드 및 검색 전략]

# 단계 3: 개요 작성
프롬프트: "다음 연구 질문과 키워드를 바탕으로 연구 논문의 상세 개요를 작성해 주세요: [단계 1, 2 출력]"
출력: [논문 개요]

# 단계 4: 각 섹션 작성
프롬프트: "다음 개요의 '방법론' 섹션을 상세히 작성해 주세요: [단계 3 출력]"
출력: [방법론 섹션 내용]

# 단계 5: 검토 및 개선
프롬프트: "다음 '방법론' 섹션을 검토하고 개선점을 제안해 주세요: [단계 4 출력]"
출력: [개선된 방법론 섹션]

5) 활용 영역

복잡한 창작 작업 (에세이, 기사, 소설 등)
다단계 분석 및 의사결정 프로세스
코드 생성 및 디버깅
복잡한 정보 합성 및 요약

6) 구현 시 고려사항

적절한 작업 분해 수준 결정
각 단계 간 정보 전달의 일관성 유지
에러 전파 방지 메커니즘 구축
전체 파이프라인의 효율성과 비용 균형

3. Tree of Thoughts (ToT): 전략적 탐색을 통한 문제 해결

1) 개념

Chain-of-Thought를 확장한 보다 전략적인 문제 해결 프레임워크
여러 가능한 사고 경로를 트리 구조로 탐색하는 접근법
문제 해결 과정에서 다양한 가능성을 탐색하고 평가하여 최적의 해결책 도출

2) CoT와의 차이점

CoT는 선형적(Linear)으로 한 사고 경로만 따라가는 반면, ToT는 다양한 경로를 동시에 탐색
ToT는 중간에 회귀하며 더 유망한 경로를 시도하는 적응적 탐색 방식 채택
문제 해결의 각 단계에서 여러 대안을 평가하고 선택하는 의사결정 트리 구조

3) 4단계 작동 과정

1단계: 생각 분해(Thought Decomposition)
- 문제를 여러 중간 단계로 나누어 구조화
- 각 단계에서 필요한 의사결정 포인트 식별
- 문제 해결을 위한 전략적 계획 수립
2단계: 생각 생성(Thought Generation)
- 각 단계에서 여러 가능한 "생각"(사고 경로) 생성
- 다양한 접근법과 가능성 탐색
- 창의적이고 다각적인 해결책 모색
3단계: 생각 평가(Thought Evaluation)
- 생성된 각 생각의 유망성과 타당성 평가
- 문제 해결 가능성과 효율성 기준으로 점수 부여
- 가장 유망한 사고 경로 식별
4단계: 검색 알고리즘(Search Strategy)
- 깊이 우선 탐색(DFS) 또는 너비 우선 탐색(BFS) 전략 적용
- 가장 유망한 경로를 우선적으로 탐색하는 전략적 접근
- 필요시 백트래킹을 통한 대안 경로 탐색

고급 프롬프트 엔지니어링 기법들은 LLM의 능력을 한 단계 더 끌어올리는 중요한 도구입니다. Generate Knowledge Prompting은 지식 기반 추론을, Prompt Chaining은 복잡한 작업의 단계적 분해를, Tree of Thoughts는 전략적 문제 해결 능력을 강화합니다. 이러한 고급 기법들을 적절히 활용하면 더 정확하고, 신뢰할 수 있으며, 복잡한 작업도 효과적으로 수행할 수 있습니다.

참고자료

패스트 캠퍼스 - 국내 공채 1호 프롬프트 엔지니어 강수진의 프롬프트 엔지니어링 A to Z

[Prompt Engineering] 프롬프트 엔지니어링의 기초 기법들

dong_seok — Tue, 29 Apr 2025 22:16:07 +0900

프롬프트 엔지니어링은 대규모 언어 모델(LLM)의 잠재력을 최대한 활용하기 위한 중요한 기술입니다. 적절한 프롬프트 기법을 사용하면 복잡한 문제 해결, 정확한 정보 검색, 창의적인 콘텐츠 생성 등 다양한 작업에서 더 나은 결과를 얻을 수 있습니다. 이 글에서는 프롬프트 엔지니어링의 기본 기법들을 소개하고, 각 기법의 장단점과 활용 사례를 살펴보겠습니다.

1. Zero-shot Prompting: 기본 중의 기본

1) 개념

언어 모델에게 예제나 시연 없이 직접 작업을 지시하는 방법
모델이 사전 학습 과정에서 습득한 지식을 바탕으로 작업을 수행
가장 단순하고 직관적인 프롬프트 방식

2) 작동 원리

LLM은 대량의 텍스트 데이터로 사전 학습되어 있어 다양한 지식을 내포
명확한 지시만으로도 기본적인 작업을 수행할 수 있음
모델의 파라미터 크기가 클수록 Zero-shot 성능이 향상됨

3) 적용 사례

텍스트 분류: "다음 리뷰가 긍정적인지 부정적인지 분류해주세요."
번역: "다음 문장을 영어로 번역해주세요."
질문 답변: "인공지능의 정의는 무엇인가요?"

4) 한계점

복잡한 추론이 필요한 작업에서는 성능이 제한적
특수 도메인 지식이 필요한 작업에서 부정확할 수 있음
모델이 작업을 정확히 이해하지 못할 경우 관련 없는 답변 생성 가능

2. Few-shot Prompting: 예시를 통한 학습

1) 개념

언어 모델에게 몇 가지 예시를 제공한 후 유사한 패턴의 작업을 요청하는 방법
복잡하거나 특수한 작업에서 Zero-shot의 한계를 극복
"in-context learning"(문맥 내 학습)의 대표적인 형태

2) 작동 원리

입력-출력 쌍의 예시를 통해 모델에게 작업의 패턴을 보여줌
모델이 제공된 예시의 패턴을 파악하고 새로운 입력에 적용
예시의 개수, 품질, 다양성이 성능에 영향을 미침

3) 예시 구성 방법

입력-출력 쌍을 명확하게 구분하여 제시
다양한 케이스를 포함하여 모델의 이해도 향상
실제 문제와 유사한 난이도와 형식의 예시 선택

입력: 이 영화는 정말 재미있었어요!
출력: 긍정

입력: 시간 낭비였습니다.
출력: 부정

입력: 음식은 괜찮았지만 서비스가 아쉬웠어요.
출력: [여기에 답변 생성]

4) 효과적인 활용 영역

특수 형식의 데이터 변환
특정 스타일의 텍스트 생성
복잡한 분류 작업
도메인 특화 작업

5) 한계점

토큰 제한으로 인해 많은 예시를 제공하기 어려움
예시 선택의 편향이 결과에 영향을 미칠 수 있음
예시 준비에 시간과 노력이 필요

3. Chain-of-Thought (CoT)

1) 개념

복잡한 추론 과제에서 중간 사고 과정을 단계별로 보여주는 방법
"Let's solve this step by step"과 같은 사고 유도 문구 활용
복잡한 수학 문제, 논리 퍼즐, 다단계 추론 작업에 효과적

2) 작동 원리

모델에게 문제 해결을 위한 중간 단계를 명시적으로 생성하도록 유도
단계별 추론을 통해 최종 답변의 정확도 향상
모델이 문제를 분해하고 체계적으로 접근하도록 도움

3) Few-shot CoT 예시

문제: 영희는 사과 5개를 가지고 있었습니다. 철수에게 2개를 주고, 민수에게서 3개를 받았습니다. 영희는 사과를 몇 개 가지고 있나요?

풀이:
1. 영희의 초기 사과 개수: 5개
2. 철수에게 준 사과: 2개
3. 영희에게 남은 사과: 5 - 2 = 3개
4. 민수에게서 받은 사과: 3개
5. 영희의 최종 사과 개수: 3 + 3 = 6개
답: 6개

문제: [새로운 문제]
풀이:

4) 효과적인 활용 영역

수학 문제 해결
논리 퍼즐
다단계 계획 수립
복잡한 분석이 필요한 질문

5) 한계점

작은 규모의 모델에서는 효과가 제한적
사고 과정 예시 작성에 전문성이 필요
프롬프트 길이가 길어져 토큰 소비 증가

4. Zero-shot Chain of Thought

1) 개념

CoT의 장점을 유지하면서 예시 작성의 번거로움을 해결하는 방법
"Let's think step by step"과 같은 간단한 지시문만으로 단계적 사고 유도
최소한의 프롬프트로 복잡한 추론 능력 활용

2) 작동 원리

모델에게 단계적 사고를 명시적으로 요청
모델이 스스로 문제 해결 단계를 생성하고 따라가도록 유도
사고 과정의 외재화를 통한 오류 감소

3) 프롬프트 예시

문제: 한 상자에 빨간 공 3개, 파란 공 5개, 녹색 공 2개가 있습니다. 무작위로 공 2개를 동시에 꺼낼 때, 두 공의 색이 서로 다를 확률은?

단계적으로 생각해봅시다.

4) 효과와 활용

간결한 프롬프트로 복잡한 추론 유도
다양한 문제 유형에 범용적으로 적용 가능
최소한의 맥락으로 효율적인 토큰 사용

5) 한계점

일부 복잡한 문제에서는 Few-shot CoT보다 성능이 낮을 수 있음
모델의 기본 능력에 의존하므로 모델 성능에 따라 결과 차이가 큼

5. Self-Consistency

1) 개념

CoT를 확장하여 여러 추론 경로를 생성한 후 가장 일관된 답변 선택
다양한 접근 방식을 통해 단일 추론의 오류 가능성 감소
집단 지성(wisdom of crowds) 원리를 LLM에 적용

2) 작동 과정

동일한 문제에 대해 여러 CoT 추론 경로 생성 (샘플링)
각 경로에서 도출된 답변들을 수집
가장 많이 도출된 답변(다수결)을 최종 결과로 선택

3) 구현 방식

온도(temperature) 설정을 높여 다양한 추론 경로 생성
각 추론에서 도출된 최종 답변 추출 및 집계
가장 빈도가 높은 답변 또는 확률적으로 가장 유력한 답변 선택

4) 효과적인 활용 영역

고난도 수학 문제
불확실성이 높은 추론 작업
정확도가 중요한 의사 결정 시나리오

5) 한계점

여러 추론 경로 생성으로 인한 계산 비용 증가
구현 복잡성이 높아 실용적 적용이 어려울 수 있음
일부 문제에서는 다수결이 항상 최적 답변을 보장하지 않음

6. Generated Knowledge (GoT)

1) 개념

모델이 문제 해결에 필요한 배경 지식을 먼저 생성한 후 추론하는 방법
복잡한 추론 전에 관련 사실, 개념, 원리를 명시적으로 정리
지식 생성과 추론을 분리하여 더 정확한 결과 도출

2) 작동 과정

문제와 관련된 배경 지식, 개념, 원리 생성
생성된 지식을 바탕으로 CoT 추론 수행
필요시 추가 지식 생성과 추론을 반복

3) 프롬프트 구조 예시

문제: [문제 설명]

1. 먼저 이 문제를 해결하는 데 필요한 관련 지식을 정리해봅시다:
[지식 생성 공간]

2. 위 지식을 바탕으로 문제를 단계적으로 해결해봅시다:
[추론 공간]

4) 효과적인 활용 영역

특수 도메인 지식이 필요한 문제
개념 이해가 중요한 교육적 맥락
복잡한 과학/수학 문제
전문 분야의 질문-답변

5) 장점

관련 지식의 명시적 활성화로 정확도 향상
추론 과정의 투명성 증가
지식 부족으로 인한 오류 감소

6) 한계점

생성된 지식의 정확성에 의존
프롬프트 길이와 복잡성 증가
일부 간단한 문제에서는 불필요한 오버헤드 발생

프롬프트 엔지니어링은 LLM의 잠재력을 최대한 활용하기 위한 핵심 기술로, 지속적으로 발전하고 있습니다. 기본 기법들을 이해하고 효과적으로 적용함으로써, 복잡한 문제 해결부터 창의적인 콘텐츠 생성까지 다양한 작업에서 AI의 능력을 크게 향상시킬 수 있습니다. 각 기법의 장단점을 파악하고 상황에 맞게 활용하는 것이 프롬프트 엔지니어링의 핵심입니다.

참고자료

패스트 캠퍼스 - 국내 공채 1호 프롬프트 엔지니어 강수진의 프롬프트 엔지니어링 A to Z

[DeepLearning] 딥러닝 프레임워크 비교 분석

dong_seok — Fri, 25 Apr 2025 23:02:07 +0900

1. 주요 딥러닝 프레임워크 소개

1) TensorFlow

TensorFlow는 구글에서 개발한 오픈 소스 머신러닝 프레임워크로, 대규모 데이터와 복잡한 모델을 효율적으로 처리할 수 있습니다. CPU와 GPU를 모두 지원하며, TensorBoard라는 시각화 도구를 통해 학습 과정을 모니터링할 수 있습니다. 주로 대규모 프로젝트와 연구에서 활용됩니다.

2) PyTorch

PyTorch는 페이스북이 개발한 프레임워크로, 동적 계산 그래프를 특징으로 합니다. 직관적인 API와 사용 편의성으로 연구자들 사이에서 큰 인기를 얻고 있으며, 특히 자연어 처리(NLP)와 컴퓨터 비전 분야에서 널리 사용됩니다.

3) Keras

Keras는 사용자 친화적인 고수준 API로, 여러 백엔드(TensorFlow, Theano, CNTK)를 지원합니다. 직관적인 인터페이스로 초보자도 쉽게 신경망을 구축할 수 있어, 빠른 프로토타이핑과 소규모 연구에 적합합니다. 현재는 TensorFlow에 통합되어 제공됩니다.

4) Scikit-learn

Scikit-learn은 파이썬 기반의 머신러닝 라이브러리로, 다양한 머신러닝 알고리즘을 제공합니다. 데이터 전처리, 분류, 회귀, 군집화 등 다양한 기능을 포함하며, NumPy, SciPy와 통합되어 강력한 데이터 처리 능력을 제공합니다. 교육용과 중소규모 프로젝트에 적합합니다.

2. 프레임워크 특징 비교

1) 성능 및 확장성

TensorFlow: 대규모 데이터셋과 복잡한 모델에 최적화되어 있으며, 분산 학습을 잘 지원합니다.
PyTorch: 동적 계산 그래프로 유연한 모델 구현이 가능하며, 디버깅이 용이합니다.
Keras: 간결한 코드로 빠르게 모델을 구축할 수 있지만, 매우 복잡한 모델에는 제한이 있습니다.
Scikit-learn: 전통적인 머신러닝 알고리즘에 강점을 보이지만, 딥러닝에는 제한적입니다.

2) 사용 편의성

TensorFlow: 다양한 기능을 제공하지만, 상대적으로 학습 곡선이 가파릅니다.
PyTorch: 파이썬 스타일의 직관적인 인터페이스로 빠르게 익힐 수 있습니다.
Keras: 가장 사용자 친화적인 인터페이스를 제공하여 초보자에게 이상적입니다.
Scikit-learn: 일관된 API로 쉽게 다양한 알고리즘을 적용할 수 있습니다.

3) 커뮤니티 및 지원

TensorFlow: 대규모 커뮤니티와 풍부한 문서, 튜토리얼을 보유하고 있습니다.
PyTorch: 급속도로 성장하는 커뮤니티와 활발한 연구 지원을 받고 있습니다.
Keras: TensorFlow의 공식 고수준 API로 통합되어 강력한 지원을 받습니다.
Scikit-learn: 안정적인 커뮤니티와 잘 정리된 문서를 가지고 있습니다.

3. 활용 사례별 최적 프레임워크

1) 연구 및 프로토타이핑

추천: PyTorch, Keras
이유: 동적 계산 그래프(PyTorch)와 빠른 모델 구현(Keras)이 실험과 반복에 적합합니다.

2) 대규모 프로덕션 환경

추천: TensorFlow
이유: TensorFlow Serving, TensorFlow Lite 등 배포 도구와 최적화 기능이 우수합니다.

3) 교육 및 학습

추천: Keras, Scikit-learn
이유: 간결한 문법과 직관적인 인터페이스로 개념 이해에 집중할 수 있습니다.

4) 특정 응용 분야

컴퓨터 비전: PyTorch, TensorFlow
자연어 처리: PyTorch(특히 최신 연구에서), TensorFlow
일반 머신러닝: Scikit-learn

4. 프레임워크 선택 가이드

1) 고려 사항

프로젝트 규모와 복잡성
사용자의 경험 수준
특정 응용 분야의 요구사항
배포 환경 및 운영 요구사항
커뮤니티 지원 및 문서화 수준

2) 선택 시나리오

초보자가 딥러닝을 배우려는 경우: Keras로 시작하여 기본 개념 습득
연구자가 최신 모델을 실험하는 경우: PyTorch의 유연성 활용
기업에서 안정적인 서비스를 개발하는 경우: TensorFlow의 생태계 활용
전통적인 머신러닝 작업이 필요한 경우: Scikit-learn의 다양한 알고리즘 활용

5. 결론

딥러닝 프레임워크는 각각 고유한 강점과 약점을 가지고 있습니다. TensorFlow는 대규모 배포와 프로덕션에, PyTorch는 연구와 실험에, Keras는 빠른 프로토타이핑과 교육에, Scikit-learn은 전통적인 머신러닝 작업에 적합합니다. 프로젝트의 특성과 목표에 맞는 프레임워크를 선택하는 것이 성공적인 머신러닝/딥러닝 개발의 첫 단계입니다.

참고자료

https://wikidocs.net/250786

[Knowledge] 학습 파라미터, 트레이너 종류, GPU 인프라 총정리

dong_seok — Thu, 24 Apr 2025 21:23:07 +0900

최근 학습 과정에서 생겼던 궁금증에 대해 간략하게 정리해보는 시간을 가졌습니다.

1. 학습 파라미터 vs 하이퍼 파라미터

1) 학습 파라미터

학습 파라미터는 모델이 학습 과정에서 스스로 최적화하는 내부 변수들입니다.

정의: 데이터로부터 학습을 통해 자동으로 업데이트되는 모델 내부 변수
예시: 신경망의 가중치(weights), 편향(biases), 임베딩(embeddings)
특징:
- 역전파를 통해 자동으로 조정됨
- 모델의 성능을 직접적으로 결정하는 요소
- 학습이 완료된 후 모델과 함께 저장됨
- 파인튜닝 시 주로 조정되는 대상

대규모 언어 모델(LLM)의 경우, 학습 파라미터는 수십억 개에 달할 수 있으며, 파인튜닝 과정에서는 이 파라미터의 일부 또는 전체를 조정합니다.

2) 하이퍼 파라미터

하이퍼파라미터는 모델의 학습 방식을 제어하는 외부 설정값입니다.

정의: 학습 과정을 제어하기 위해 사람이 사전에 설정하는 변수들
예시:
- 학습률(learning rate)
- 배치 크기(batch size)
- 에폭 수(epochs)
- 정규화 계수(regularization factor)
- 드롭아웃 비율(dropout rate)
- 모델 구조 설정(은닉층 수, 뉴런 수)
특징:
- 모델이 자동으로 학습하지 않으며 개발자가 직접 설정
- 학습 프로세스와 속도, 성능에 큰 영향을 미침
- 최적값을 찾기 위해 그리드 서치(Grid Search), 랜덤 서치(Random Search), 베이지안 최적화(Bayesian Optimization) 등의 방법 사용

3) 실제 코드에서의 구분

# 학습 파라미터 (모델 내부에서 자동으로 학습됨)
# q_proj, k_proj, v_proj, o_proj, gate_proj 등의 가중치
model = FastLanguageModel.get_peft_model(
    model,
    r=128,  # Choose any number > 0 ! Suggested 8, 16, 32, 64, 128
    target_modules=[
        "q_proj",
        "k_proj",
        "v_proj",
        "o_proj",
        "gate_proj",
        "up_proj",
        "down_proj",
        "embed_tokens",
        "lm_head",
    ],  # Add for continual pretraining
    lora_alpha=32,
    lora_dropout=0,  # Supports any, but = 0 is optimized
    bias="none",  # Supports any, but = "none" is optimized
    # [NEW] "unsloth" uses 30% less VRAM, fits 2x larger batch sizes!
    use_gradient_checkpointing="unsloth",  # True or "unsloth" for very long context
    random_state=3407,
    use_rslora=True,  # We support rank stabilized LoRA
    loftq_config=None,  # And LoftQ
)

# 하이퍼파라미터 (개발자가 직접 설정)
args = UnslothTrainingArguments(
    per_device_train_batch_size=2,  # 배치 크기 설정
    gradient_accumulation_steps=8,  # 그래디언트 누적 단계 수
    warmup_steps=10,                # 워밍업 스텝 수
    num_train_epochs=1,             # 학습 에폭 수
    learning_rate=5e-5,             # 학습률
    embedding_learning_rate=1e-5,   # 임베딩 학습률
    fp16=True,                      # 16비트 부동소수점 사용 여부
    bf16=False,                     # bfloat16 사용 여부
    # ... 기타 설정들
)

2. Trainer 종류 및 장단점

1) Hugging Face Trainer

Hugging Face의 기본 트레이너로, 다양한 모델과 데이터셋에 범용적으로 사용할 수 있습니다.

장점:

쉬운 사용법과 포괄적인 문서화
다양한 모델 아키텍처 지원
분산 학습, 혼합 정밀도 학습 등 고급 기능 내장
커스터마이징이 용이한 콜백 시스템

단점:

대규모 LLM 파인튜닝에 최적화되어 있지 않음
메모리 사용량이 다소 높을 수 있음
특수한 학습 기법(PEFT, QLoRA 등)에 대한 직접적인 지원이 부족

2) UnslothTrainer

Unsloth 라이브러리의 트레이너로, 대규모 LLM의 효율적인 파인튜닝에 특화되어 있습니다.

장점:

LLM 파인튜닝에 최적화된 성능
메모리 효율성이 높아 더 큰 배치 크기 사용 가능
FlashAttention, LoRA와 같은 최신 기술 내장
학습 속도가 일반 Trainer보다 빠름 (2-3배 속도 향상)

단점:

범용성이 다소 부족 (주로 LLaMA, Mistral 계열 모델에 최적화)
상대적으로 새로운 라이브러리로 문서화가 덜 완성됨
커스터마이징 옵션이 제한적일 수 있음

3) SFTTrainer

TRL 라이브러리의 일부로, 지시어 튜닝과 같은 지도 학습 파인튜닝에 특화되어 있습니다.

장점:

대화형 AI 모델 학습에 최적화
지시어 형식의 데이터 처리가 간편함
RLHF(Reinforcement Learning from Human Feedback) 파이프라인과 연동 가능
토크나이징 프로세스가 자동화되어 사용이 편리함

단점:

일반적인 분류나 회귀 태스크에는 덜 적합
학습 과정의 세밀한 제어가 다소 제한적
특화된 용도로 인해 범용성이 다소 떨어짐

3. GPU 인스턴스 종류

1) NVIDIA A100

사양:

메모리: 40GB / 80GB 버전 존재
FP32 성능: 최대 19.5 TFLOPS
FP16/BF16 성능: 최대 312 TFLOPS (Tensor Cores)
메모리 대역폭: 1.6 TB/s (HBM2e)

장점:

우수한 가격 대비 성능
충분한 메모리로 대규모 모델 학습 가능
다양한 클라우드 제공업체에서 폭넓게 사용 가능
TensorFloat-32(TF32) 지원으로 학습 속도 향상

단점:

H100보다는 성능이 떨어짐
가격이 여전히 높은 편 (특히 80GB 버전)

적합한 사용 사례:

7B-70B 파라미터 규모의 LLM 파인튜닝
중간 규모의 연구 및 개발 프로젝트

2) NVIDIA H100

사양:

메모리: 80GB
FP32 성능: 최대 67 TFLOPS
FP16/BF16 성능: 최대 1,979 TFLOPS (Tensor Cores)
메모리 대역폭: 3.35 TB/s (HBM3)

장점:

최고 수준의 연산 성능
대규모 모델 학습 및 추론에 뛰어난 성능
향상된 메모리 대역폭으로 병목 현상 감소
Transformer 엔진으로 LLM 학습 최적화

단점:

매우 높은 비용
가용성이 제한적일 수 있음
냉각 요구사항이 더 높음

적합한 사용 사례:

100B+ 파라미터 규모의 대형 LLM 파인튜닝
최고 성능이 필요한 대규모 상업 프로젝트
다중 GPU 환경에서의 분산 학습

3) 기타 주요 GPU 옵션

NVIDIA V100

A100의 이전 세대로, 여전히 많이 사용됨
16GB/32GB 메모리 옵션
비용 효율적인 대안이지만 최신 최적화 부족

NVIDIA T4

저비용 추론 특화 GPU
파인튜닝에는 제한적이나 가벼운 작업에 적합
16GB 메모리로 소규모 모델 파인튜닝 가능

NVIDIA RTX 4090 (소비자용)

성능 대비 가격이 우수함
24GB 메모리로 중소형 모델 파인튜닝 가능
대규모 프로젝트에는 부적합

AMD MI250X

NVIDIA 대안으로 부상 중
LLM 학습 생태계 지원이 상대적으로 부족
특정 워크로드에서 좋은 성능

[Fine-Tuning] Restoring obfuscation LLM 프로젝트 회고

dong_seok — Wed, 23 Apr 2025 22:17:49 +0900

이전 글에서 Unsloth와 엘리스 클라우드 등 기술적인 부분에 대해 설명했다면, 이번에는 DACON 난독화 한글 리뷰 복원 프로젝트를 진행하면서 겪었던 전체적인 경험과 시행착오를 공유하려 합니다.

대회 개요

DACON에서 진행된 이 대회는 의도적으로 난독화된 한글 텍스트를 원래 형태로 복원하는 과제로, 오픈 소스 LLM(Large Language Model)을 활용해 해결하는 것이 핵심이었습니다.

처음에는 같은 경진대회에 참여한 사람이 공유해준 Gemma-2-B-it Full Fint-tuning 모델을 사용하였습니다.

model_name = "mindw96/Gemma-2-2B-it-DACON-LLM"
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

2B 파라미터 규모의 작은 모델이었지만, Full-Fine-tuning이라서그런지 0.75의 정확도로 생각보다 높은 수치를 보여줬습니다. 하지만 저는 단순히 다른 사람의 모델을 추론에만 사용하는 것이 아니라, 직접 파인튜닝 과정을 경험하고 더 높은 정확도를 달성하고 싶다는 마음으로 대회를 진행하였습니다.

도전 과제: 제한된 컴퓨팅 자원

정확도 향상을 위해 2B보다 더 큰 모델로 풀 파인튜닝을 시도했으나, Colab 무료 환경에서는 지속적으로 OOM(Out Of Memory) 에러가 발생했습니다. 이를 해결하기 위해 배치 사이즈 감소와 양자화 등 여러 메모리 최적화 기법을 시도했지만, 기본적인 메모리가 너무 부족한 상황이었습니다.

모델 크기를 낮추어 학습을 시작했지만, 이번에는 학습 시간이 너무 오래 걸리는 문제에 직면했습니다. 결국 제한된 컴퓨팅 자원과 긴 학습 시간이라는 두 가지 문제를 모두 해결해야 했습니다.

해결책: 엘리스 클라우드와 Unsloth 라이브러리

1) 클라우드 환경으로 전환

근본적인 메모리 부족 문제를 해결하기 위해 엘리스 클라우드의 "A100 80GB PCle MIG 3g-40GB" 인스턴스를 활용하기로 했습니다. 대부분의 연구자들이 RunPod와 같은 플랫폼을 사용하는 경우가 많지만, 엘리스 클라우드는 출시된 지 얼마 되지 않았고 이벤트로 대여 비용을 지원해주어 비용 효율적인 선택이었습니다.

2) Unsloth 라이브러리 도입

메모리 사용 효율성과 학습 속도를 개선하기 위해 Unsloth 라이브러리를 활용했습니다. Unsloth는 사전에 통합(integration)된 모델만 지원하므로, Llama-3B 모델을 새롭게 선택하여 학습을 진행했습니다.

from unsloth import FastLanguageModel
import torch

# 모델 및 토크나이저 로드
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Llama-3.2-3B-Instruct-bnb-4bit",
    max_seq_length=2048,
    dtype=None,  # 자동 감지
    load_in_4bit=True,  # 4비트 양자화
)

# LoRA 설정으로 효율적인 파인튜닝
model = FastLanguageModel.get_peft_model(
    model,
    r=128,  # LoRA 랭크
    target_modules=[
        "q_proj", "k_proj", "v_proj", "o_proj", 
        "gate_proj", "up_proj", "down_proj", 
        "embed_tokens", "lm_head"
    ],
    lora_alpha=32,
    use_gradient_checkpointing="unsloth",  # 메모리 효율성
    use_rslora=True,  # 랭크 안정화 LoRA
)

이후에 학습에 적합한 형태로 데이터를 구성해주는 절차를 거쳤습니다.

# 난독화된 입력을 복원하는 작업을 위한 템플릿 정의
restore_prompt = """다음은 난독화 된 입력을 복원하는 작업입니다.

### 난독화 입력:
{}

### 복원된 출력:
{}"""

EOS_TOKEN = tokenizer.eos_token  # 반드시 EOS_TOKEN 추가 (생성 종료를 위해)

def combine_input_output(example):
    # 입력과 출력 정보를 템플릿에 맞게 합치고 EOS_TOKEN을 추가
    example["text"] = (
        restore_prompt.format(example["input"], example["output"]) + EOS_TOKEN
    )
    return example


# 데이터셋에 대해 map 적용
dataset = dataset.map(combine_input_output)

그 후 UnslothTrainer를 활용해 효율적인 학습을 진행했습니다.

trainer = UnslothTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    dataset_num_proc=2,
    args=UnslothTrainingArguments(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=8,
        warmup_steps=10,
        num_train_epochs=1,
        learning_rate=5e-5,
        embedding_learning_rate=1e-5,  # 임베딩 레이어에 더 낮은 학습률 적용
        fp16=not is_bfloat16_supported(),
        bf16=is_bfloat16_supported(),
        logging_steps=1,
        optim="adamw_8bit",
        weight_decay=0.01,
        lr_scheduler_type="linear",
        output_dir="outputs",
    ),
)

# 학습 실행
trainer.train()

결과 및 성과

Unsloth 라이브러리와 4비트 양자화 기법을 활용한 Llama-3.2-3B 모델 학습으로 0.8의 정확도를 달성했습니다. 이는 초기 접근법보다 약 6.7% 향상된 결과입니다.

1) 이 접근법의 주요 이점

메모리 효율성: 4비트 양자화로 메모리 사용량을 크게 줄임
학습 속도 향상: Unsloth의 최적화로 일반적인 방법보다 2-4배 빠른 학습
유연성: LoRA를 통해 모든 주요 모듈을 효율적으로 파인튜닝

기술적 인사이트

1) LoRA를 이용한 효율적인 파인튜닝

LoRA(Low-Rank Adaptation)는 전체 모델을 학습하는 대신 저차원 업데이트를 통해 파라미터를 효율적으로 학습합니다. r=128이라는 비교적 큰 랭크 값을 사용해 모델의 표현력을 극대화했습니다.

target_modules=[
    "q_proj", "k_proj", "v_proj", "o_proj",  # 어텐션 관련
    "gate_proj", "up_proj", "down_proj",     # MLP 관련
    "embed_tokens", "lm_head"                # 임베딩 및 출력
]

이렇게 모든 주요 모듈을 대상으로 함으로써 모델이 난독화 패턴을 더 깊이 이해하고 복원할 수 있었습니다.

2) 4비트 양자화의 효과

처음엔 16비트 형식의 모델을 양자화 하면 메모리 사용량이 줄어드는 대신 정확도가 크게 떨어질것이라고 예상해서 양자화를 선호하지 않았는데, 줄어든 메모리 사용량 대비 성능이 크게 떨어지지않은 것 같아서 양자화가 정확도 손실을 최소화하면서도 큰 모델을 효율적으로 사용하게 해준다는 긍정적인 인식을 얻게 되었습니다.

[Agent] ESG 데이터 조회 Agent 구현

dong_seok — Tue, 22 Apr 2025 22:23:53 +0900

진행중이던 프로젝트에서 디비를 활용한 부분을 제외하고 API호출을 Tool로 구현하고 LangChain의 Tool calling 기능을 활용하여 ESG 데이터를 조회하는 Agent를 구현한 내용에 대해 말씀드리겠습니다.

1. 시스템 아키텍처 개요

1) 구성 요소

ESG 데이터 수집을 위한 yfinance API 활용
LangChain의 Tool calling 기능을 통한 자연어 기반 데이터 조회
ReAct Agent 패턴을 통한 지능형 데이터 분석

2) 주요 흐름

사용자가 자연어로 ESG 데이터 조회 요청
Agent가 의도를 파악하여 적절한 Tool 호출
ESG 데이터를 가져와 분석 및 리포트 생성

2. ESG 데이터 조회 Tool 구현

1) ESG Search Wrapper 클래스

class ESGSearchWrapper(BaseModel):
    """ESG 데이터 검색을 위한 래퍼 클래스."""
    
    model_config = ConfigDict(
        extra="forbid",
        arbitrary_types_allowed=True,
    )

    def get_from_yfinance_sync(self, ticker: str) -> Dict[str, Any]:
        """yfinance API에서 최신 ESG 데이터를 가져옵니다."""
        try:
            ticker = ticker.upper()
            ticker_obj = yf.Ticker(ticker)
            esg_data = ticker_obj.sustainability

            if esg_data is None:
                return {
                    "ticker": ticker,
                    "error": f"{ticker}에 대한 ESG 데이터를 찾을 수 없습니다.",
                }

            # DataFrame을 딕셔너리로 변환
            esg_dict = esg_data.to_dict()
            if not esg_dict:
                return {
                    "ticker": ticker,
                    "error": f"{ticker}에 대한 ESG 데이터를 찾을 수 없습니다.",
                }

            # 첫 번째 열 데이터만 추출
            column_name = list(esg_dict.keys())[0]
            esg_values = esg_dict[column_name]

            # 현재 연도와 월 추가
            now = datetime.datetime.now()

            result = {
                "ticker": ticker,
                "total_esg": esg_values.get("totalEsg"),
                "environment_score": esg_values.get("environmentScore"),
                "social_score": esg_values.get("socialScore"),
                "governance_score": esg_values.get("governanceScore"),
                "rating_year": now.year,
                "rating_month": now.month,
                "records": [],
            }

            return result
        except Exception as e:
            return {
                "ticker": ticker,
                "error": f"yfinance API 호출 중 오류 발생: {str(e)}",
            }

    def get_esg_data_sync(self, ticker: str, force_refresh: bool = False) -> Dict[str, Any]:
        """주어진 티커에 대한 ESG 데이터를 가져옵니다."""
        ticker = ticker.upper()
        return self.get_from_yfinance_sync(ticker)

2) ESG Data Tool 클래스

class ESGDataInput(BaseModel):
    """Input for the ESG Data tool."""
    ticker: str = Field(description="The stock ticker symbol to get ESG data for.")
    force_refresh: bool = Field(
        description="Whether to force refresh data from yfinance.", default=False
    )


class ESGDataTool(BaseTool):
    """Tool for retrieving ESG data for stocks."""
    
    name: str = "esg_data"
    description: str = (
        "Useful when you need to get ESG (Environmental, Social, Governance) "
        "ratings and scores for publicly traded companies. "
        "Input should be a valid stock ticker symbol."
    )
    args_schema: Type[BaseModel] = ESGDataInput
    api_wrapper: ESGSearchWrapper = Field(default_factory=ESGSearchWrapper)

    def _run(
        self,
        ticker: str,
        force_refresh: bool = False,
        run_manager: Optional[CallbackManagerForToolRun] = None,
    ) -> Dict[str, Any]:
        """Use the tool."""
        try:
            result = self.api_wrapper.get_esg_data_sync(
                ticker=ticker,
                force_refresh=force_refresh,
            )
            return result
        except Exception as e:
            return {"error": repr(e)}

3. ReAct Agent 구현

1) ESG 분석 노드

class RetrieveESGNode(Node):
    def __init__(self):
        super().__init__()
        self.system_prompt = """
        You are a professional ESG data analysis agent. Your core mission is to query the ESG data of a particular company requested by the user in the database, and based on this, provide ESG analysis and recommendations.

        Perform the following tasks sequentially:

        1. Data Inquiry and Validation:
        - Inquire the ESG data of the company in the database based on user-provided ticker symbols
        - Check data up-to-date and check missing information
        - Evaluate quality and scope of searched data

        2. ESG Comprehensive Analysis:
        - Analysis of scores and key indicators for each area of the environment (E), society (S), and governance (G)
        - Identify the relative position of the company relative to the ESG average in the industry
        - Identify ESG rating fluctuations and key variables
        - Investigate key ESG issues and controversies

        3. Sustainability Assessment:
        - Analysis of ESG policies, objectives, and practices of the enterprise
        - Evaluate key ESG factors such as climate change response, resource efficiency, human capital management, and board composition
        - Analysis of long-term ESG risks and opportunities

        4. Investment Opinion:
        - Objective investment recommendation based solely on ESG data (buy/hold/sell)
        - Identify strengths, weaknesses, opportunities, and threats from an ESG perspective
        - Potential valuation from a sustainable investment perspective

        5. Create a report:
        - Executive Summary
        - Basic information such as ticker, company name, industry group, date of analysis, etc
        - ESG-based investment strategies and recommendations

        All analyses and responses should be written in Korean, and provide accurate and objective information that will substantially assist investors in making ESG-oriented decisions. Do not include financial data or financial analyses, but only present assessments and recommendations purely from the ESG data and sustainability perspective.
        If you fail to get the data, answer that you can't find the data.
        """
        self.agent = None
        self.tools = [ESGDataTool()]

    def _run(self, state: dict) -> dict:
        if self.agent is None:
            assert state["llm"] is not None, "The State model should include llm"
            llm = state["llm"]
            self.agent = create_react_agent(
                llm,
                self.tools,
                prompt=self.system_prompt,
            )
        result = self.agent.invoke(state)
        self.logger.info(f"   result: \n{result['messages'][-1].content}")
        return Command(
            update={
                "messages": [
                    HumanMessage(
                        content=result["messages"][-1].content,
                        name=self.__class__.__name__.lower().replace("node", ""),
                    )
                ]
            },
            goto="supervisor",
        )

    def _invoke(self, query: str) -> RawResponse:
        agent = self.agent or create_react_agent(
            ChatOpenAI(model=self.DEFAULT_LLM_MODEL),
            self.tools,
            prompt=self.system_prompt,
        )
        result = agent.invoke({"messages": [("human", query)]})
        return RawResponse(answer=result["messages"][-1].content)

4. 구현 시 고려사항

1) 동기/비동기 처리

API 호출을 위한 동기/비동기 메서드 모두 구현
대부분의 경우 동기 메서드를 사용하며, 필요시 비동기 메서드 활용

2) 오류 처리

API 호출 실패, 데이터 없음 등 다양한 예외 상황 처리
사용자 친화적인 오류 메시지 제공

3) 확장성

새로운 ESG 데이터 소스 추가가 용이하도록 설계
다양한 Tool을 추가하여 기능 확장 가능

5. 실제 사용 예시

# Agent 초기화
esg_node = RetrieveESGNode()

# ESG 데이터 조회 요청
response = esg_node._invoke("테슬라의 ESG 데이터를 분석해주세요")
print(response.answer)

이렇게 실행하면 Agent는 하단과 같은 결과를 출력해주는 모습입니다.

느낀점

LangChain의 Tool calling 기능을 활용하면 복잡한 ESG 데이터 조회 및 분석 작업을 자연어 인터페이스로 간단하게 구현할 수 있습니다.

본 구현에서는 yfinance API를 기본 데이터 소스로 사용했지만, 추가적인 ESG 데이터 제공업체의 API를 통합하거나 자체 데이터베이스를 연동하는 방식으로 확장할 수 있습니다. 또한, 다른 금융 데이터를 조회하는 Tool들을 추가하여 종합적인 투자 분석 시스템으로 발전시킬 수 있습니다.

[PR] 실전 Fork & PR

dong_seok — Mon, 21 Apr 2025 22:19:38 +0900

전에 Fork와 PR을 간단하게 코드로 설명하면서 진행했던 글이 있는데, 이번에는 조금 더 심화적으로 협업중 발생한 문제를 해결하면서 PR을 진행하는 과정에 대해 설명하도록 하겠습니다.

현재 장기간 Merge & PR을 하지않아, 원본 레파지토리의 히스토리가 쌓이고 Fork한 원격 레파지토리에서 새롭게 브랜치를 생성해서 커밋이 쌓인 상황입니다. 따라서 히스토리 충돌이 발생하지 않도록, 원본 레파지토리의 코드를 잘 가져와서 병합 후 PR을 요청하는 과정을 다뤄보도록 하겠습니다.

원본 레파지토리의 최신 코드를 가져오기 위해 "git fetch upstream" 명령어를 실행했는데 아래의 에러가 발생하였습니다.

확인해보니 upstream이라는 이름의 원격 저장소가 등록이 되지 않아 발생한 에러였습니다. "git remote -v" 로 확인 가능합니다. 원본 레포지토리를 upstream이라는 이름으로 추가해줍니다.

git remote add upstream https://github.com/원본유저/원본레포.git

이후 다시 git fetch upstream으로 원본 레파지토리의 변경사항을 가져와줍니다.

에러가 발생하지않고 명령어가 잘 작동한 모습인데, 로컬 코드와 히스토리가 변경된게 없어서 뭔가 잘못됐나?라는 생각을 했습니다. 찾아보니 원본 변경사항을 로컬 브랜치에 병합하는 추가 과정이 필요한 것이었습니다.

git checkout dev
git merge upstream/dev

따라서 내가 병합하고자 하는 브랜치로 이동한 후 원격 저장소에서 가져온 브랜치의 코드를 merge 해주면 되는 것 이었습니다. 이로써 1차적으로 원본 저장소의 코드를 로컬 저장소로 병합하였습니다. 이제 제 작업 브랜치로 이동해서 이 병합한 코드를 다시 머지해서 코드에 문제가 없는지 검증을 하였습니다.

git checkout feat/retrieve_docs
git merge dev

위 명령어들을 통해 제 작업 브랜치와 원본 저장소에서 가져오는 코드들이 병합 되다보니 당연히 충돌이 발생했고, 이 부분들을 수동으로 해결해주었습니다. 그리고 다시 실행하려는데 병합중 가상환경에 다운로드 된 패키지 항목이 달라지면서 Import 에러가 발생해 uv에 새롭게 패키지를 추가해주었습니다.

uv pip install 패키지명

이때 만약 uv 가상환경을 pyproject.toml 같은 의존성 파일로 관리하고 있을 경우, uv sync 의 명렁어 사용시 uv pip install로 설치한 패키지는 사라지기 때문에 필요에 따라 의존성 파일 자체에 패키지명을 기입하는 것도 좋은 방법입니다. 병합 후 파일을 실행해 오류없이 작동하는 것을 확인하면, dev 브랜치로 다시 이동해 기존 작업 브랜치의 코드를 다시 병합해 PR전 마지막으로 검토를 진행해줍니다. 이상이 없음이 확인되면 로컬 저장소의 코드를 원격 저장소의 코드로 Push 해줍니다. 그리고 깃허브 페이지로 가보면 저장소 상단에 PR 창이 뜨는데 안뜨길래 뭐가 문젠가 싶어서 직접 PR 생성 창으로 이동해보았습니다.

base와 compare이 동일한 dev 브랜치를 비교하고 있기 때문에 PR을 생성해도 변경사항이 없을 것으로 판단해 PR이 불가능한것으로 보였습니다.

그래서 compare across forks를 클릭해 fork를 한 원본 저장소의 브랜치를 지정하려했는데 이 부분이 잘 안됐습니다. 지정하고 싶은 브랜치명이 안나오길래 원인을 찾고 있었는데 원본 레파지토리의 Fork 목록에 카운팅이 사라진것을 확인했습니다.

그래서 Fork 연결이 끊겼나? 이런 생각이 들어 기존 코드들을 백덥해두고 레파지토리를 새롭게 만들어보았습니다. 기존 레파지토리를 사용해보려했는데 원본 저장소가 private -> public 으로 바뀌면서 혹시나 모를 key 유출을 대비해 새롭게 만들기로 하였습니다.

Push 후 PR 창을 들어가보니 위와같이 PR을 할 수 있는 이벤트가 생겼길래 이를 활용해 PR을 날려주었습니다.

[LLM 평가]LLM 및 RAG 평가 프레임워크 비교 분석

dong_seok — Fri, 18 Apr 2025 21:33:05 +0900

LLM(Large Language Model)과 RAG(Retrieval-Augmented Generation) 시스템의 성능을 평가하는 것은 AI 애플리케이션 개발에서 중요한 과정입니다. 다양한 평가 프레임워크들이 각자 독특한 특징과 접근 방식을 제공합니다. 이 글에서는 주요 평가 프레임워크들을 비교하고 각각의 장단점을 살펴보겠습니다.

1. LLM-as-a-judge

1) 개념

LLM이 평가자 역할을 수행하여 다른 모델이나 시스템의 성능을 평가
인간 평가자 대신 LLM을 활용하여 대규모 평가 가능
프롬프트 엔지니어링을 통해 평가 기준과 방법 설정

2) 장점

인간 평가보다 비용 효율적
일관된 평가 기준 적용 가능
대규모 평가에 적합

3) 한계

LLM 자체의 편향이 평가에 영향을 줄 수 있음
특정 언어나 도메인에 따라 성능 차이 발생

2. 주요 평가 프레임워크

1) RAGAS

특징:
- 가장 널리 사용되는 RAG 평가 프레임워크
- LLM-as-a-judge 기반으로 작동
- Retrieval 정답 데이터(ground truth) 없이도 평가 가능
장점:
- 에이전트의 tool 사용 평가 지원
- SQL 메트릭 및 전통적 NLP 스코어 포함
- 검색 품질 평가에 강점
단점:
- 모든 단락에 대한 연관성 비교로 비용 부담
- 다국어 지원 부족 (한국어 평가 시 성능 저하 가능)

2) DeepEval

특징:
- RAGAS, G-Eval 등 LLM-as-a-judge 메트릭 포함
- AI Safety 관련 평가 메트릭 제공
- CI/CD 통합 지원
장점:
- 다양한 벤치마크 데이터셋 지원
- LLM 평가에 특화된 기능
단점:
- 다국어 지원 부족
- Retrieval 메트릭 부재 (RAG보다 LLM 평가 중심)

3) OpenAI Evals

특징:
- OpenAI에서 직접 개발한 평가 프레임워크
- OpenAI 대시보드에서 바로 사용 가능
장점:
- 간편한 사용법
- LLM 성능 평가에 최적화
단점:
- OpenAI 모델만 사용 가능
- 제한된 커스터마이징 옵션

4) Langsmith

특징:
- Langchain과 원활한 연동
- 모니터링과 테스트 기능 통합
장점:
- 직관적인 대시보드로 평가 결과 시각화
- LLM-as-a-judge 및 커스텀 메트릭 지원
- 개발에서 프로덕션까지 일관된 환경
단점:
- Langchain 생태계에 의존적

5) Trulens

특징:
- Human-in-the-loop 평가에 특화
- AI Safety 중심 메트릭
장점:
- 결과 확인을 위한 대시보드 제공
- 반복적 평가 프로세스 지원
- 관찰 가능성(Observability) 강화
단점:
- 학습 곡선이 있음

6) Huggingface Evaluate

특징:
- 다양한 NLP 메트릭과 데이터셋 제공
- 간편한 사용법
장점:
- 전통적 NLP 평가 메트릭 쉽게 활용 가능
- 빠른 구현과 통합
단점:
- 외부 라이브러리 의존성 높음
- LLM 특화 평가보다는 일반적 NLP 평가에 중점

7) ARES

특징:
- 스탠포드 대학에서 개발
- 평가용 소형 LLM(sLLM) 파인튜닝 접근법
장점:
- LLM-as-a-judge 중 높은 정확도
- Natural Question 데이터셋 기반 평가
단점:
- 높은 연산 요구사항
- 복잡한 설정 과정

8) AutoRAG

특징:
- RAG에 특화된 최적화 프레임워크
- 다양한 메트릭 지원
장점:
- Retrieval 평가 및 최적화 특화
- 한국어, 영어, 일본어 데이터셋 생성 지원
- 평가 대시보드 제공
단점:
- 상대적으로 새로운 프레임워크로 커뮤니티 지원이 적을 수 있음

3. 프레임워크 선택 가이드

1) RAG 시스템 평가

RAGAS나 AutoRAG가 적합
검색 품질과 생성 품질 모두 평가 가능

2) LLM 자체 평가

DeepEval, OpenAI Evals, ARES 고려
응답 품질, 정확성, 안전성 등 다양한 측면 평가

3) 통합 모니터링 및 평가

Langsmith나 Trulens 활용
프로덕션 환경에서의 지속적 모니터링에 적합

LLM과 RAG 평가 프레임워크는 각각 독특한 강점을 가지고 있습니다. 프로젝트의 요구사항, 평가하려는 시스템의 유형, 그리고 필요한 메트릭에 따라 적절한 프레임워크를 선택하는 것이 중요합니다. 대부분의 경우, 하나의 프레임워크만으로는 모든 평가 요구사항을 충족하기 어려울 수 있으므로, 여러 프레임워크를 조합하여 사용하는 것도 효과적인 전략입니다.

참고자료

Fastcampus - RAG 평가와 개선의 모든 것 : 데이터셋 제작부터 agent 평가까지

[RAG Evaluation] RAG 평가의 기초

dong_seok — Thu, 17 Apr 2025 21:45:47 +0900

RAG(Retrieval Augmented Generation) 시스템은 정보 검색(Retrieval)과 텍스트 생성(Generation)이라는 두 가지 핵심 요소로 구성됩니다. 이 시스템의 성능을 효과적으로 평가하기 위해서는 각 요소를 독립적으로, 그리고 전체 시스템을 통합적으로 평가하는 것이 중요합니다. 이 글에서는 RAG 시스템 평가에 사용되는 다양한 방법론과 메트릭에 대해 살펴보겠습니다.

1. RAG 평가의 기본 개념

RAG 시스템은 일반적으로 Retrieval(검색)과 Generation(생성) 부분으로 나누어 평가합니다. 하지만 Retrieval의 성능이 Generation의 성능에 직접적인 영향을 미치기 때문에, 두 요소를 완벽하게 분리해서 평가하는 것은 불가능합니다. 이러한 복잡성을 고려하여 RAG 평가는 크게 두 가지 접근 방식으로 진행됩니다.

정성적 평가: 주관적 판단에 기반한 평가
정량적 평가: 수치화된 메트릭을 통한 객관적 평가

이 두 방식을 적절히 조합하여 RAG 시스템의 성능을 종합적으로 판단할 수 있습니다.

2. 정성적 평가 방법

정성적 평가는 연구자나 도메인 전문가의 주관적 판단에 의해 이루어지는 평가 방식입니다.

1) 장점

도메인 전문가의 지식과 경험을 바탕으로 한 심층적인 평가 가능
맥락과 의미를 고려한 질적 평가 가능
수치화하기 어려운 미묘한 차이나 뉘앙스 포착 가능

2) 단점

평가자의 주관에 따라 결과가 달라질 수 있음
대규모 평가에 시간과 비용이 많이 소요됨
재현성이 낮을 수 있음

3) 적용 분야

Retrieval: Langsmith와 같은 추적 도구를 사용하거나 답변 생성 과정 출력을 통해 검색된 컨텍스트를 직접 확인
Generation: 최종 답변의 적합성, 허위 정보 포함 여부, 컨텍스트와의 일치성 등을 판단

정성적 평가는 특히 도메인 전문가의 판단이 중요한 분야에서 정량적 평가보다 더 신뢰할 만한 결과를 제공할 수 있습니다.

3. 정량적 평가 방법

정량적 평가는 객관적인 수치를 통해 시스템의 성능을 측정하는 방식입니다.

1) 장점

판단을 수치화하여 객관적인 비교 가능
평가 데이터셋 구축이 선행되어야 함
재현성이 높고 대규모 평가에 적합

2) 고려사항

평가 데이터셋의 품질과 다양성이 결과에 큰 영향을 미침
데이터셋 구축 시 "어느 정도의 양이 필요한가"에 대한 고민 필요
정성적 평가와 정량적 평가를 융합한 새로운 메트릭 개발 가능성 존재

3) 적용 분야

Retrieval: Context Precision, Context Recall 등의 메트릭으로 검색 성능 평가
Generation: Faithfulness, Answer Relevancy 등의 지표로 생성 품질 평가
Total Process: Answer Correctness, Answer Semantic Similarity 등으로 전체 파이프라인 평가

4. Ragas 평가 메트릭 상세 분석

Ragas는 RAG 시스템 평가를 위한 주요 메트릭을 제공하는 프레임워크입니다. 각 메트릭은 0~1 사이의 값을 가지며, 높을수록 더 좋은 성능을 의미합니다.

1) Generation 평가 메트릭

Faithfulness (충실도)

목적: 생성된 답변이 얼마나 제공된 컨텍스트에 충실한지 평가
의미: 답변이 컨텍스트에 기반하여 생성되었는지, 아니면 LLM의 사전 지식에 의존했는지 판단
중요성: 컨텍스트가 잘못되었는데도 LLM이 자체 지식으로 올바른 답변을 생성하는 경우도 hallucination으로 간주될 수 있음

Answer Relevancy (답변 관련성)

목적: 생성된 답변이 주어진 질문에 적절히 대응하는지 평가
평가 방식: 생성된 답변을 기반으로 LLM을 통해 역으로 질문을 생성한 후, 이 질문과 실제 질문 간의 코사인 유사도 계산
중요성: 답변이 질문의 의도를 정확히 파악했는지 확인 가능

2) Retrieval 평가 메트릭

Context Precision (컨텍스트 정밀도)

목적: 검색된 컨텍스트 중 질문과 관련된 정보의 비율 측정
고려사항: 검색할 문서 개수에 따라 점수가 달라질 수 있음
중요성: 검색된 정보의 품질과 관련성 평가

Context Recall (컨텍스트 재현율)

목적: 검색된 컨텍스트가 필요한 정보를 얼마나 포함하는지 평가
평가 방식: Ground truth에 포함된 statement 중 검색된 컨텍스트에 포함된 비율 계산
중요성: 답변 생성에 필요한 정보가 누락 없이 포함되었는지 확인

Context Relevancy (컨텍스트 적합성)

목적: 컨텍스트에 관련 없는 내용이 얼마나 포함되었는지 평가
계산 방식: 전체 추출한 컨텍스트 문장 수 중 적합 문장의 비율 계산
고려사항: 컨텍스트 길이에 따라 값이 달라질 수 있음 (길이가 길수록 오류 정보도 많이 포함될 가능성)

3) End-to-End 평가 메트릭

Answer Semantic Similarity (답변 의미적 유사도)

목적: 생성된 답변과 Ground Truth 간의 의미적 유사성 평가
계산 방식: 벡터 임베딩을 통한 유사도 평균 계산
의미: 답변이 정답과 얼마나 의미적으로 가까운지 측정

Answer Correctness (답변 정확도)

목적: 생성된 답변의 사실적 정확성 평가
특징: 단순한 문장 유사성이 아닌 사실적 내용의 정확성 평가
의미: Semantic Similarity와 달리 내용의 정확성에 중점

5. RAG 평가의 실제 적용

RAG 시스템 평가를 실제로 적용할 때 고려해야 할 점들입니다.

1) 통합적 평가의 중요성

Retrieval과 Generation 각각의 평가뿐만 아니라 전체 시스템의 성능 평가 필요
개별 구성 요소의 성능이 좋아도 전체 시스템의 성능이 반드시 우수하다고 볼 수 없음

2) 도메인 특성 고려

특정 도메인에 따라 중요시되는 메트릭이 다를 수 있음
의료, 법률 등 정확성이 중요한 분야에서는 Faithfulness와 Answer Correctness가 더 중요할 수 있음
일반적인 질의응답에서는 Context Relevancy와 Answer Relevancy가 더 중요할 수 있음

3) 평가 데이터셋 구축

다양한 질문 유형과 난이도를 포함한 균형 잡힌 데이터셋 필요
도메인 전문가의 검증을 거친 Ground Truth 구축
정기적인 데이터셋 업데이트로 시스템 발전 추적

4) 정성적 평가와 정량적 평가의 균형

두 평가 방식의 장단점을 상호 보완하는 평가 체계 구축
정량적 메트릭으로 대규모 평가 후, 중요 사례에 대해 정성적 평가 진행
사용자 피드백과 전문가 평가를 함께 고려

RAG 시스템의 평가는 여러가지 벤치마크 데이터셋이 존재하고 다양한 기법이 존재합니다. 그 중 상황에 맞게 알맞은 방법을 선택하고 평가를 진행할 수 있도록 많은 공부가 필요하겠다는 생각이 들었습니다.

참고자료

https://velog.io/@cathx618/RAG-%ED%8F%89%EA%B0%80-%EB%B0%A9%EB%B2%95-%EC%A0%95%EB%A6%AC

[DeepLearning] 딥러닝의 기초와 메모리 최적화 기법 복습

dong_seok — Wed, 16 Apr 2025 22:12:52 +0900

오늘은 복습겸 딥러닝의 기초과 되는 핵심 원리와 기법에 대해 간단하게 얘기하고자 합니다.

1. 딥러닝의 학습 과정

1) 순전파

입력 데이터가 모델의 각 층을 거쳐 예측값을 생성합니다. 이 과정에 각 층의 계산 결과와 상태값이 메모리에 저장됩니다.

2) 손실 계산

모델의 예측값과 실제 정답 간의 차이 즉, 손실을 계산합니다. 이 손실은 모델의 정확도를 측정하는 지표가 됩니다.

3) 역전파

계산된 손실을 기준으로 각 층을 거슬러 올라가며 가중치가 손실에 미치는 영향 즉, 그래디언트를 계산합니다. 이때 순전파에서 저장해둔 상태값들이 활용됩니다.

4) 가중치 업데이트

계산된 그래디언트를 바탕으로 옵티마이저가 모델의 가중치를 조정합니다. 이 과정을 통해 모델은 점점 더 정확한 예측을 할 수 있게 됩니다.

2. 딥러닝의 핵심 구성 요소

1) 레이어(Layer)

레이어 또는 층은 인공 신경망의 기본 구조 단위입니다.

입력 데이터를 받아 특정 연산을 수행
연산 결과를 다음 레이어로 전달
가중치와 활성화 함수를 포함하여 데이터의 특징을 추출하거나 변환

2) 활성화 함수(Activation Function)

신경망에 비선형성을 도입하여 복잡한 패턴 학습 가능
ReLU, Sigmoid, Tanh, LeakyReLU 등 다양한 종류 존재
각 활성화 함수는 고유한 특성과 적합한 사용 사례 보유
기울기 소실 문제 해결을 위한 특수 설계된 활성화 함수들 발전

3) 손실 함수(Loss Function)

모델의 예측과 실제 정답 간의 차이를 수치화 및 학습 목표 정의
회귀 문제: MSE(Mean Squared Error), MAE(Mean Absolute Error)
분류 문제: Cross-Entropy Loss, BCE(Binary Cross-Entropy)
특수 목적: Triplet Loss(유사도 학습), Focal Loss(클래스 불균형)

4) 옵티마이저(Optimizer)

그래디언트를 기반으로 모델 파라미터를 업데이트하는 알고리즘
SGD, Adam, RMSprop, AdamW 등 다양한 알고리즘 존재
학습률 스케줄링을 통한 최적화 성능 향상
모멘텀, 적응적 학습률 등의 기법 활용

5) 그래디언트

그래디언트는 손실 함수의 기울기를 의미합니다.

각 가중치 파라미터가 손실에 미치는 영향을 수치화한 값으로 손실 함수를 파라미터에 대해 미분하여 계산
그래디언트의 방향은 손실이 가장 빠르게 증가하는 방향
옵티마이저는 그래디언트의 반대 방향으로 파라미터를 업데이트
학습률(learning rate)은 파라미터 업데이트 크기를 결정

6) 정규화 기법(Regularization)

Dropout: 학습 중 일부 뉴런을 임의로 비활성화
가중치 감소(Weight Decay): L1/L2 정규화를 통한 모델 복잡도 제한
배치 정규화(Batch Normalization): 내부 공변량 이동 감소
데이터 증강(Data Augmentation): 학습 데이터 다양화

3. 대규모 모델 훈련을 위한 메모리 최적화 기법

딥러닝 모델이 커질수록 메모리 요구량도 증가합니다. 제한된 리소스에서 효율적인 훈련을 위한 주요 기법 몇가지를 정리합니다.

1) KV 캐시(Key-Value Cache)

개념: 이전에 계산한 키(Key)와 값(Value) 결과를 메모리에 저장해 재활용
효과: 동일한 입력 토큰에 대한 중복 계산 방지
적용: 주로 트랜스포머 기반 모델(GPT, BERT 등)의 어텐션 메커니즘에서 사용
이점: 추론 속도 향상 및 계산 비용 절감

2) 그래디언트 체크포인팅(Gradient Checkpointing)

개념: 모든 중간 활성화값 대신 일부 체크포인트만 저장
작동방식: 역전파 시 필요한 중간값을 체크포인트로부터 재계산
트레이드오프: 메모리 사용량 감소 ↔ 계산 시간 증가
적용 사례: 초대형 언어 모델, 고해상도 이미지 처리 모델

3) 기타 메모리 최적화 기법

양자화(Quantization)
- 32비트 부동소수점 → 16비트, 8비트, 4비트로 정밀도 축소
- 모델 크기 및 메모리 사용량 대폭 감소
- 약간의 성능 손실이 발생할 수 있음
모델 병렬화(Model Parallelism)
- 대규모 모델을 여러 GPU/TPU에 분산 배치
- 파이프라인 병렬화: 모델 레이어를 여러 장치에 분할
- 텐서 병렬화: 단일 연산을 여러 장치에서 병렬 처리
혼합 정밀도 훈련(Mixed Precision Training)
- FP32와 FP16을 혼합하여 사용
- 메모리 사용량 감소 및 계산 속도 향상
- 스케일링 기법을 통해 정확도 손실 방지

[Transformer] 인코더와 디코더

dong_seok — Tue, 15 Apr 2025 21:46:06 +0900

1. 인코더

인코더는 입력 텍스트를 이해하고 의미를 추출하는 역할을 합니다. 기본적으로 여러 개의 동일한 층이 반복되는 구조로 되어 있습니다.

1) 인코더의 주요 구성 요소

층 정규화(Layer Normalization): 데이터의 분포를 조정하여 학습을 안정화
멀티 헤드 어텐션(Multi-Head Attention): 입력 시퀀스의 다양한 관계를 파악
피드 포워드 층(Feed Forward Layer): 비선형 변환을 통해 표현력 강화

2) 잔차 연결

잔차 연결은 이미지에 보이는 것처럼 원래 입력값을 각 하위 층의 출력에 더해주는 방식을 말합니다.

그래디언트 소실 문제 해결: 깊은 네트워크에서 학습 신호가 손실되는 문제 방지
학습 안정화: 층이 많아져도 안정적인 학습 가능
정보 보존: 원본 정보가 네트워크를 통과하며 유지됨

2. 디코더

디코더는 인코더가 이해한 정보를 바탕으로 실제 텍스트를 생성하는 역할을 합니다. 인코더와 유사하지만 두 가지 중요한 차이점이 있습니다.

1) 마스크 멀티 헤드 어텐션

일반 적인 멀티 헤드 어텐션과 다르게 앞에 "마스크" 라는 키워드가 붙는데 이게 왜 붙는지 알아보겠습니다.

문제 상황

실제 텍스트 생성 시에는 이전까지 생성한 텍스트만 확인 가능한데, 학습할때 완선된 텍스트를 입력받음
이때 미래에 등장할 단어를 미리 참조하면 안됨

-> 이때 마스크를 사용해 특정 위치에서는 이전 위치의 단어만 볼 수 있도록 제한

2) 크로스 어텐션

디코더의 또 다른 특별한 부분은 인코더의 정보를 활용하는 크로스 어텐션 메커니즘입니다.

작동 방식

쿼리(Q): 디코더 자체의 잠재 상태에서 가져옴
키(K)와 값(V): 인코더의 출력에서 가져옴

-> 크로스 어텐션을 통해 디코더가 생성하는 각 단어가 입력 텍스트의 어떤 부분에 집중해야하는지 알 수 있음

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

[Transformer] 어텐션 연산과 핵심 구성 요소

dong_seok — Mon, 14 Apr 2025 22:32:13 +0900

1. 어텐션 연산

우리는 글을 읽을 때 모든 단어에 동일한 중요도를 부여하지 않습니다. 어떤 단어들은 특별히 주목하고, 다른 단어들은 상대적으로 덜 집중하며 전체 맥락을 파악합니다. 트랜스포머 모델의 핵심인 어텐션 연산은 이러한 인간의 읽기 방식을 모방한 연산입니다.

1) 어텐션이란 무엇인가?

어텐션은 단어들 사이의 관계를 파악하여 문맥을 이해하는 방식으로, 다음과 같은 과정으로 작동합니다:

단어와 단어 사이의 관계를 계산하여 관련성의 깊이를 판단
관련이 깊은 단어는 더 많이, 관련이 적은 단어는 더 적게 맥락에 반영

이 연산은 모델이 문장 내에서 단어 간의 복잡한 관계를 이해하고, 문맥에 따라 단어의 의미를 적절히 해석할 수 있게 합니다.

2. QKV(쿼리, 키, 값) 모델 이해하기

트랜스포머 아키텍처를 개발한 연구진은 정보 검색 분야에서 영감을 받아 쿼리(Query), 키(Key), 값(Value)이라는 개념을 도입했습니다.

1) QKV 모델의 역할

구성 요소 역할 검색 시스템 예시

역할	설명	검색 예시
쿼리(Query)	우리가 찾고자 하는 정보	사용자의 검색어
키(Key)	쿼리와의 관련성을 판단하기 위한 특징	문서의 제목, 저자
값(Value)	실제로 활용하게 될 정보	문서의 본문 내용

이 구조에서 모델은 쿼리와 키의 관련도를 계산한 뒤, 가장 관련이 깊은 키에 연결된 값을 활용합니다. 이를 통해 맥락에 따라 단어의 의미를 다르게 해석할 수 있게 됩니다.

2) 규칙 기반 방법의 한계

어텐션을 구현하기 위한 초기 시도로, 몇 가지 규칙 기반 방법들이 있었습니다:

모든 단어를 동등하게 반영하는 방식
- 문제점: 정보의 우선순위를 표현할 수 없음
거리 기반 가중치 적용
- 가정: "가까운 단어일수록 관련이 깊다"
- 문제점: 문맥과 무관하게 단순 거리만으로 의미 관계를 결정하는 한계

이러한 규칙 기반 방법들의 핵심 문제는 유연성 부족입니다. 예를 들어, "파리"를 "박물관"으로 바꿔도 동일한 계산 결과가 나온다면, 문맥에 따른 의미 변화를 포착할 수 없습니다.

3) 벡터 기반 어텐션의 등장

이러한 한계를 극복하기 위해, 트랜스포머는 토큰의 임베딩 벡터를 활용한 계산 방식을 도입했습니다. 벡터 간 연산을 통해 관련도를 계산하면 문자열이 일치하지 않더라도 의미적으로 유사한 정보를 활용할 수 있습니다. 하지만 이 방식에도 문제가 있었습니다.

쿼리와 키의 임베딩이 동일할 경우, 관련도가 지나치게 높게 계산되어 주변 맥락 반영이 미흡해질 수 있음
직접적인 관련성은 잘 포착하지만, 문법적 관계와 같은 간접적 관련성은 반영하기 어려움

4) 가중치 도입을 통한 문제 해결

트랜스포머는 토큰 임베딩을 변환하는 학습 가능한 가중치를 도입하여 이러한 문제를 해결했습니다:

쿼리-키 임베딩 일치 문제 해결: 서로 다른 가중치 행렬을 통해 동일한 임베딩도 다르게 변환
간접 관계 반영: 가중치 행렬이 단어의 위치, 역할, 문장 구조 등을 학습하여 간접적 관계도 포착

결과적으로, 트랜스포머는 QKV 가중치를 통해 문맥에 따라 단어 간 관계를 유연하게 계산하고 적절히 반영하는 방법을 학습합니다.

5) 스케일 점곱 방식

"Attention is All You Need" 논문에서 처음 소개된 스케일 점곱 어텐션의 연산 과정은 다음과 같습니다.

쿼리와 키를 곱한 후, 임베딩 차원의 제곱근으로 나눔 (분산 증가 방지)
계산된 스코어에 소프트맥스를 적용하여 합이 1이 되는 가중치로 변환
이 가중치와 값을 곱해 최종 출력 계산

3. 멀티 헤드 어텐션

한 번의 어텐션 연산으로는 문장 내 복잡한 관계를 모두 포착하기 어렵습니다. 트랜스포머는 여러 개의 어텐션을 동시에 계산하는 '멀티 헤드 어텐션'을 도입해 이 문제를 해결했습니다.

1) 멀티 헤드 어텐션의 작동 원리

쿼리, 키, 값을 헤드 수만큼 분할하여 각각의 어텐션 연산 수행
각 헤드의 결과를 결합하여 입력과 동일한 형태로 변환
선형층을 통과시켜 최종 결과 생성

이를 통해 모델은 하나의 문장에서 다양한 관계와 패턴을 동시에 파악할 수 있습니다.

4. 트랜스포머의 핵심 구성 요소

1) 층 정규화(Layer Normalization)

딥러닝 모델에서 데이터가 일정한 분포를 유지하도록 만드는 정규화는 학습 안정성과 속도에 중요한 영향을 미칩니다.

(1) 배치 정규화 vs 층 정규화

배치 정규화
- 배치 내 데이터 간 정규화 수행
- 이미지 처리에 주로 사용
- 문제점: 자연어 처리에서는 문장 길이가 다양하여 효과적이지 않음

층 정규화
- 특정 차원에서 정규화 수행
- 각 토큰 임베딩의 평균과 표준편차를 구해 정규화
- 자연어 처리에 적합

(2) 정규화 적용 방식

사후 정규화: 원 트랜스포머 논문 방식 - 어텐션과 피드 포워드 층 이후에 정규화 적용
사전 정규화: 최신 방식 - 먼저 정규화 적용 후 다른 층 통과 (학습 안정성 향상)

2) 피드 포워드 층(Feed-Forward Layer)

트랜스포머에서 피드 포워드 층은 데이터의 특징을 학습하는 완전 연결 층으로, 다음과 같은 역할을 합니다:

멀티 헤드 어텐션이 단어 간 관계를 파악한다면, 피드 포워드 층은 텍스트 전체 맥락 이해 담당
선형 층, 드롭아웃 층, 층 정규화, 활성 함수로 구성
모델이 입력 텍스트의 고수준 특성과 의미를 포착할 수 있도록 함

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

[Text Embedding] 텍스트를 임베딩하는 3단계

dong_seok — Fri, 11 Apr 2025 22:44:49 +0900

딥러닝 모델이 텍스트를 이해하려면 먼저 문자 기반의 텍스트 데이터를 숫자 기반의 벡터로 변환해야 합니다. 이 과정을 임베딩(embedding)이라고 부르며, 보통 다음의 세 가지 단계를 거칩니다.

1. 토큰화 (Tokenization)

텍스트를 모델에 넣기 위해 가장 먼저 해야 할 일은 텍스트를 잘게 나누는 것, 즉 토큰화입니다. 이때 각 토큰에 고유한 숫자 ID를 부여하며, 이 정보를 사전(dict)에 기록합니다.

토큰화 방법은 다양하지만, 크게 다음 두 가지 방식이 있습니다:

큰 단위 토큰화: 예를 들어 단어 단위로 자르는 방식입니다. 의미 보존에 유리하지만, 새로운 단어가 등장했을 때 처리할 수 없는 OOV(Out-Of-Vocabulary) 문제가 발생합니다.
작은 단위 토큰화: 예를 들어 글자 단위로 자르는 방식입니다. OOV 문제는 줄지만, 의미가 잘려 나가 문장의 의미를 제대로 전달하기 어렵습니다.

그래서 최근에는 두 방식의 장점을 적절히 결합한 서브워드(Subword) 토크나이저를 많이 사용합니다. 이 방식은 자주 등장하는 단어는 그대로 유지하고, 드물게 등장하는 단어는 의미 있는 작은 조각으로 분해합니다. 대표적인 예로는 BPE(Byte Pair Encoding), WordPiece, SentencePiece 등이 있습니다.

2. 토큰 임베딩 (Token Embedding)

토큰화된 결과는 단지 정수 ID일 뿐, 단어의 의미를 표현하기엔 부족합니다. 따라서 각 토큰 ID를 다차원 벡터로 바꿔주는 임베딩 과정이 필요합니다. 이때 사용되는 것이 바로 딥러닝 프레임워크의 Embedding 레이어입니다. 파이토치(PyTorch)에서는 다음과 같이 사용할 수 있습니다.

import torch
import torch.nn as nn

embedding_dim = 16
embed_layer = nn.Embedding(len(str2idx), embedding_dim)

input_embeddings = embed_layer(torch.tensor(input_ids))  # (5, 16)
input_embeddings = input_embeddings.unsqueeze(0)  # (1, 5, 16)
input_embeddings.shape

여기서 주의할점은 초기 임베딩 층은 토큰의 의미를 담는 것이 아니라 단순히 입력 토큰 아이디를 임의의 벡터로 변환할 뿐입니다. 임베딩 층이 단어의 의미를 효과적으로 표현하기 위해서는 딥러닝 모델이 학습 데이터로 훈련되어야 합니다. 딥러닝에서는 모델이 특정 작업을 수행하도록 학습하는 과정에서 데이터의 의미를 잘 담은 임베딩을 만드는 방법도 함께 학습합니다. 이것이 바로 딥러닝이 머신러닝과의 차별점 중 하나 입니다.

3. 위치 인코딩

RNN과 트랜스포머의 가장 큰 차이점은 입력 처리 방식에 있습니다. RNN은 입력을 순차적으로 처리하므로 순서 정보가 자연스럽게 유지되지만, 트랜스포머는 모든 입력을 동시에 처리하므로 순서 정보가 소실됩니다. 텍스트에서 순서는 중요한 정보이므로 위치 인코딩을 통해 이를 보완합니다.

초기에는 수식을 통해 위치 정보를 입력했지만, 최근에는 위치에 따른 임베딩 층을 추가해 학습 데이터를 통해 학습하는 방식을 많이 활용합니다.

절대 위치 인코딩은 구현이 간단하지만, 토큰 간의 상대적 위치 정보를 활용하지 못하고 긴 텍스트 추론 시 성능이 저하되는 단점이 있습니다. 이러한 단점을 보완하기 위해 최근에는 상대적 위치 인코딩도 함께 사용합니다.

4. 최종적인 입력 임베딩 생성 과정

최종적으로 모델에 입력되는 임베딩은 다음과 같은 과정을 거칩니다.

1) 텍스트를 토큰화하여 토큰 ID와 위치 ID를 생성합니다.

2) 각 ID를 각각 토큰 임베딩과 위치 임베딩으로 변환합니다.

3) 두 임베딩을 더해 최종 입력 임베딩을 만듭니다.

이 과정을 통해 모델은 단어의 의미뿐 아니라 단어가 문장에서 어떤 위치에 있는지까지 함께 고려할 수 있게 됩니다.

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

[Transformer] RNN과 트랜스포머 아키텍처의 이해

dong_seok — Thu, 10 Apr 2025 20:12:08 +0900

딥러닝 기반 자연어 처리 기술은 최근 몇 년간 혁신적인 발전을 이루었습니다. 이 발전의 중심에는 RNN(순환신경망)에서 트랜스포머 아키텍처로의 패러다임 전환이 있었습니다. 이번 글에서는 두 모델의 특징과 차이점, 그리고 트랜스포머가 어떻게 기존 RNN의 한계를 극복했는지 알아보겠습니다.

1. 순환신경망(RNN)의 구조와 한계

RNN은 시퀀스 데이터를 처리하기 위한 초기 딥러닝 모델로, 텍스트를 순차적으로 하나씩 처리하는 특징을 가집니다.

1) RNN의 작동 방식

텍스트의 각 토큰(단어)을 하나씩 순차적으로 입력
이전 토큰 처리 결과를 다음 토큰 처리에 활용
이런 순환 구조가 시퀀스 데이터 처리에 적합

2) RNN의 한계점

순차적 처리로 인한 비효율

병렬 처리가 불가능해 학습 속도가 느림
긴 시퀀스 처리 시 계산 시간이 크게 증가

장기 의존성 문제

입력이 길어질수록 초기 정보가 희석되는 현상 발생
텍스트의 앞부분과 뒷부분의 관계 파악이 어려움

깊은 네트워크 구성의 어려움

층을 깊게 쌓으면 그래디언트 소실이나 폭발 문제 발생
학습의 불안정성 증가

LSTM이나 GRU와 같은 개선된 RNN 모델들이 등장했지만, 근본적인 한계를 완전히 극복하지는 못했습니다.

2. 트랜스포머 아키텍처

트랜스포머는 2017년 "Attention is All You Need" 논문을 통해 소개된 혁신적인 아키텍처로, RNN의 한계를 극복하기 위해 설계되었습니다.

1) 트랜스포머의 핵심 구성 요소

인코더: 언어를 이해하는 역할

디코더: 언어를 생성하는 역할

2) 트랜스포머의 장점

뛰어난 확장성

더 깊은 모델 구성이 가능하며 학습도 안정적
동일한 블록의 반복적 사용으로 구조 확장이 용이

우수한 효율성

병렬 연산이 가능해 학습 시간이 크게 단축
자원 활용 효율이 높아 대규모 모델 학습 가능

긴 시퀀스 처리 능력

입력 시퀀스가 길어져도 성능 저하가 적음
문서 전체 맥락을 파악하는 능력이 우수

3. 셀프 어텐션

트랜스포머의 가장 중요한 혁신은 순차적 처리 방식을 버리고 '셀프 어텐션' 메커니즘을 도입한 것입니다.

셀프 어텐션의 작동 원리

문장 내 모든 단어 간의 관련성을 동시에 계산
각 단어가 다른 모든 단어와 어떤 관계를 갖는지 학습
관련성에 따라 각 단어의 표현을 조정

이를 통해 문맥을 더 정확하게 이해하고, 장거리 의존성 문제를 효과적으로 해결합니다.

4. 트랜스포머의 처리 과정

트랜스포머는 다음과 같은 단계로 텍스트를 처리합니다.

1) 입력 임베딩

텍스트를 숫자 벡터(임베딩)로 변환

2) 위치 인코딩

순서 정보를 임베딩에 추가

3) 인코더 처리

층 정규화, 멀티 헤드 어텐션, 피드 포워드 층을 통한 처리
입력 텍스트의 의미 이해

4) 디코더 처리

마스크 멀티 헤드 어텐션으로 자기 자신 처리
크로스 어텐션으로 인코더 결과 활용
최종 출력 생성

5. 인코더와 디코더의 주요 차이점

1) 마스크 멀티 헤드 어텐션

디코더에서는 미래 정보를 사용하지 못하도록 마스킹이 적용됩니다.

필요성: 실제 텍스트 생성 시 미래 토큰은 알 수 없기 때문
작동 방식: 현재 위치 이후의 토큰에는 어텐션 점수를 0으로 설정
효과: 자연스러운 텍스트 생성 가능

2) 크로스 어텐션

디코더에서 인코더의 출력을 활용하는 메커니즘입니다.

역할: 인코더가 이해한 입력 정보를 디코더의 생성 과정에 반영
장점: 입력 텍스트의 맥락을 출력 생성에 효과적으로 반영 가능

트랜스포머 아키텍처는 RNN의 한계를 극복하고 자연어 처리 성능을 획기적으로 향상시켰습니다. 특히 셀프 어텐션 메커니즘을 통해 병렬 처리가 가능해지고, 장거리 의존성 문제를 해결했습니다. 이러한 혁신은 BERT, GPT와 같은 강력한 언어 모델의 기반이 되었고, 현대 NLP 기술의 중심에 자리 잡고 있습니다. 다음 포스팅에서는 트랜스포머의 인코더와 디코더를 구성하는 각 Layer에 대해 자세히 알아보고, 멀티 헤드 어텐션, 피드 포워드 네트워크, 층 정규화 등의 구성 요소가 어떻게 작동하는지 심층적으로 살펴보겠습니다.

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

[GitHub] Fork & Pull Request

dong_seok — Wed, 9 Apr 2025 22:08:20 +0900

간단한 프로젝트나 제가 지금까지 진행한 프로젝트에서는 Github에서 프로젝트를 관리할때 각자 기능별 브랜치를 만들고 메인 브랜치에 반영하고 싶으면 로컬에서 commit, merge 를 통해 검증이 되면 그 main 브랜치를 원격 레파지토리에 push해서 병합하는 구조를 사용했었습니다. 그런데 이번에 새로운 프로젝트를 진행하면서 Fork + Pull Request 조합으로 프로젝트를 관리하게 돼서 이 과정에 대해 알아보려고합니다.

1. Fork란 무엇인가?

Fork는 다른 사용자의 GitHub 저장소(Repository)를 내 계정으로 복제하는 기능입니다. 이는 단순한 복사본이 아니라 원본 저장소와의 연결을 유지하면서 독립적으로 작업할 수 있는 공간을 만들어줍니다.

Fork의 주요 목적

오픈소스 프로젝트 기여: 직접적인 쓰기 권한 없이도 프로젝트에 기여할 수 있습니다
독립적인 개발: 기존 코드를 기반으로 새로운 기능을 추가하거나 방향을 전환할 수 있습니다
안전한 실험: 원본 코드에 영향을 주지 않고 다양한 변경사항을 시도해볼 수 있습니다

2. Pull Request란?

Pull Request(PR)는 내가 Fork한 저장소에서 작업한 변경사항을 원본 저장소에 반영해달라고 요청하는 기능입니다. 코드 리뷰와 토론을 거쳐 최종적으로 프로젝트에 병합될 수 있습니다. PR의 장점은 코드 변경사항을 한눈에 비교할 수 있어 리뷰어가 쉽게 검토할 수 있다는 점입니다.

3. Fork & Pull Request 작업 흐름

이제 Fork와 Pull Request를 활용한 전체 작업 흐름을 단계별로 살펴보겠습니다.

1) Fork 하기

먼저 기여하고 싶은 프로젝트의 GitHub 페이지에서 오른쪽 상단의 'Fork' 버튼을 클릭합니다.

Fork가 완료되면 내 GitHub 계정에 동일한 이름의 저장소가 생성됩니다. 이제 이 저장소는 내 소유이며 자유롭게 수정할 수 있습니다.

2) Clone 및 Remote 설정

Fork한 저장소를 로컬 환경으로 가져옵니다.

# 내 Fork한 저장소 복제
git clone https://github.com/내사용자명/저장소이름.git

# 복제된 디렉토리로 이동
cd 저장소이름

이제 로컬 저장소에 원본 저장소를 'upstream'이라는 이름으로 추가합니다. 이는 나중에 원본 저장소의 변경사항을 쉽게 가져오기 위함입니다.

# 원본 저장소를 'upstream'으로 추가
git remote add upstream https://github.com/원본사용자명/저장소이름.git

# 설정된 Remote 확인
git remote -v

출력 결과는 다음과 같을 것입니다:

origin    https://github.com/내사용자명/저장소이름.git (fetch)
origin    https://github.com/내사용자명/저장소이름.git (push)
upstream  https://github.com/원본사용자명/저장소이름.git (fetch)
upstream  https://github.com/원본사용자명/저장소이름.git (push)

3) 브랜치 생성

작업을 시작하기 전에 새로운 브랜치를 만들어 작업합니다. 이는 여러 기능을 동시에 개발하거나 다른 팀원과의 코드 충돌을 방지하는데 도움이 됩니다.

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

# 브랜치 목록 확인
git branch

4) 코드 수정 및 커밋

이제 필요한 변경사항을 작업하고 커밋합니다.

# 파일 수정 후 변경사항 스테이징
git add .

# 변경사항 커밋
git commit -m "[feat] Retrieve docs node"

5) Fork한 저장소에 Push

작업이 완료되면 내 GitHub 계정의 Fork 저장소에 변경사항을 Push합니다.

git push origin feature/new-feature

6) Pull Request 생성

GitHub로 돌아가면 방금 Push한 브랜치에 대한 'Compare & pull request' 버튼이 표시됩니다. 이 버튼을 클릭하여 Pull Request를 생성합니다. PR 생성 페이지에서 PR의 제목과 설명을 작성합니다. 변경사항을 설명하고 필요한 경우 관련 이슈를 언급합니다. 생성된 PR 페이지에서는 변경된 코드를 한눈에 비교해볼 수 있습니다. 이는 코드 리뷰를 진행하는 데 매우 유용합니다.

7) 코드 리뷰 및 병합

PR이 생성되면 프로젝트 관리자나 다른 팀원들이 코드를 리뷰하고 피드백을 제공합니다. 필요한 경우 추가 수정을 진행하고 다시 Push합니다.모든 검토가 완료되면 관리자가 'Merge pull request' 버튼을 클릭하여 변경사항을 원본 저장소에 병합합니다.

8) 동기화 및 정리

PR이 병합된 후에는 로컬 저장소를 원본 저장소와 동기화하고 사용한 브랜치를 정리합니다.

# 메인 브랜치로 전환
git checkout main

# 원본 저장소의 변경사항 가져오기
git pull upstream main

# 로컬 브랜치 삭제
git branch -d feature/new-feature

# Fork 저장소도 업데이트
git push origin main

Fork & Pull Request의 장점

코드 품질 향상: 코드 리뷰 과정을 통해 버그를 사전에 발견하고 코드 품질을 높일 수 있습니다
지식 공유: 팀원들이 서로의 코드를 검토하며 지식을 공유할 수 있습니다
프로젝트 안정성: 직접적인 main 브랜치 수정 없이 변경사항을 검증할 수 있습니다
기여 추적: 누가 어떤 기능을 개발했는지 명확하게 기록됩니다

Fork와 Pull Request는 오픈소스 프로젝트뿐만 아니라 팀 프로젝트에서도 효과적인 협업 방식입니다. 처음에는 기존의 브랜치 방식보다 복잡해 보일 수 있지만, 익숙해지면 더 체계적이고 안전한 개발 환경을 구축할 수 있습니다.

참고자료

https://dusanbaek.tistory.com/97

https://velog.io/@0x45c/Git-Fork-Pull-Request

[DeepLearning] 메모리 효율적인 딥러닝

dong_seok — Tue, 8 Apr 2025 18:40:17 +0900

딥러닝 모델, 특히 대규모 언어 모델(LLM)이 발전함에 따라 모델 크기와 필요한 계산 자원도 크게 증가했습니다. 하지만 모델 성능이 향상됨에 따라 모델의 크기와 요구되는 계산 자원 또한 기하급수적으로 증가하고 있습니다. 수십억에서 수백억 개의 파라미터를 가진 모델을 학습하고 추론하려면, 단순히 고성능 하드웨어만으로는 한계가 있습니다. 메모리 효율성과 연산 최적화 없이는 현실적인 운영이 어려워지기 때문이죠. 이번 글에서는 대규모 딥러닝 모델을 효율적으로 다루기 위한 핵심 기술들을 정리해보겠습니다. 특히 메모리 관점에서 모델을 어떻게 경량화하고 최적화할 수 있는지를 중심으로 다뤄보겠습니다.

1. 데이터 타입에 따른 메모리 사용량

딥러닝 모델은 본질적으로 수많은 파라미터(가중치)를 포함한 거대한 행렬 연산의 집합입니다. 이 파라미터들을 어떤 데이터 타입으로 저장하느냐에 따라 모델의 용량과 성능이 크게 달라집니다.

과거에는 32비트 부동소수점(FP32)이 표준이었지만, 최근에는 메모리와 연산 효율을 고려해 FP16이나 BF16과 같은 16비트 형식이 널리 사용됩니다.

데이터 타입	정밀도	특징
FP32	높음	높은 정밀도와 안정성, 큰 메모리 사용량
FP16	낮음	낮은 정밀도, 메모리 사용량 감소, 오버플로우 위험
BF16	중간	FP16보다 넓은 표현 범위, 학습 안정성이 높음

모델 용량 = 파라미터 수 × 파라미터당 비트 수

예를 들어:

10억 개 파라미터 모델(fp16): 20억B -> 2GB
70억 개 파라미터 모델(fp16): 140억B -> 14GB

2. 양자화: 모델 압축의 핵심 기술

양자화는 더 나아가 모델의 정밀도를 줄이는 대신 크기를 획기적으로 줄이는 방법입니다. 32비트나 16비트가 아닌, 8비트 또는 4비트로 파라미터를 표현함으로써 모델의 메모리 사용량을 1/2에서 최대 1/8까지 절감할 수 있습니다.

주요 양자화 방법

1) 절대 최댓값 기준 양자화 (Absmax Quantization)

전체 데이터의 절대값 최대치를 기준으로 스케일링
단순하지만 이상치에 민감

2) 블록 단위 양자화 (Block-wise Quantization)

K개의 데이터를 하나의 블록으로 묶어 양자화
이상치의 영향을 제한된 범위로 격리 가능

3) 퀀타일(Quantile) 양자화

데이터를 정렬해 균등 분포되도록 스케일링
메모리와 계산량이 증가하지만 정밀도 손실을 최소화 가능

3. GPU 메모리 사용 구조 이해

딥러닝 학습 과정에서 GPU 메모리에는 다음과 같은 항목이 저장됩니다.

모델 파라미터
그레이디언트
옵티마이저 상태
순전파 상태

이 중 순전파 상태는 역전파 시 다시 사용되기 때문에 전체 메모리에서 상당한 부분을 차지하게 됩니다. 특히 모델이 깊거나 배치 크기가 클수록 메모리 부담은 더욱 커집니다. 딥러닝 학습 과정을 간단히 요약하면, 먼저 순전파를 수행하고 그때 계산한 손실로부터 역전파를 수행하고 마지막으로 옵티마이저를 통해 모델을 업데이트합니다. 역전파는 순전파의 결과를 바탕으로 수행하는데, 이때 역전파를 수행하기 위해 저장하고 있는 값들이 순전파 상태값입니다. 그레이디언트는 역전파 결과 생성됩니다.

4. 메모리 효율적인 학습 기법

1) 그레이디언트 누적(Gradient Accumulation)

여러 배치의 그레이디언트를 누적한 후 모델을 한번에 업데이트하는 방식입니다.
장점: 적은 메모리로 큰 배치 효과
단점: 학습 시간이 길어질 수 있음

2) 그레이디언트 체크포인팅(Gradient Checkpointing)

순전파 시 모든 중간 값을 저장하지 않고 일부만 저장한 뒤, 역전파 시 필요할 때 재계산하는 방식입니다.
장점: 메모리 사용량 대폭 감소
단점: 일부 계산 재수행으로 학습 시간 증가

5. 분산 학습 기법

분산학습이란 대규모 모델 학습을 위해 여러 GPU를 활용하는 방법으로 모델 학습 속도를 높이고 1개의 GPU로 학습이 어려운 모델을 다루는 것을 목표로 하고 있습니다.

1) 데이터 병렬화(Data Parallelism)

동일한 모델을 여러 GPU에 복제하고 각각 다른, 데이터를 처리하는 방식입니다.

2) 모델 병렬화 (Model Parallelism)

모델 자체를 분할하여 각 GPU가 서로 다른 파트를 처리합니다. 다시 세분화하면:

파이프라인 병렬화 (Pipeline Parallelism)
→ 모델의 층(layer)을 수직(상하)으로 나누어 각 GPU에 순차적으로 배치
텐서 병렬화 (Tensor Parallelism)
→ 한 층의 연산 자체를 좌우로 나눠 여러 GPU에 병렬 분산시킴

3) ZeRO(Zero Redundancy Optimizer)

데이터 병렬화를 사용하는 경우 동일한 모델을 여러 GPU에 올리기 때문에 중복으로 모델을 저장하면서 메모리 낭비가 발생합니다. 이런 비효율을 해결하기 위해 ZeRO가 개발됐습니다. 하나의 모델을 하나의 GPU에 올리지 않고 마치 모델 병렬화처럼 모델을 나눠 여러 GPU에 올리고 각 GPU에서는 자신의 모델 부분의 연산만 수행하고 그 상태를 저장하면 메모리를 효율적으로 사용하면서 속도도 빠르게 유지할 수 있다는 것이 ZeRO의 컨셉입니다. Accelerate의 DeepSpeed 사용 가이드를 통해 쉽게 적용할 수 있습니다.

대규모 언어 모델의 시대에는 단순히 GPU 성능만 믿고 학습을 진행할 수 없습니다. 한정된 자원 안에서 효율적인 학습과 추론을 수행하려면 데이터 타입 최적화, 양자화, 메모리 절감 기법, 분산 학습 전략 등이 필수적입니다. 적절한 최적화 기법을 조합하면 수천만 원대의 대형 GPU 서버 없이도, 상대적으로 저렴한 환경에서 대형 모델을 실험하고 운영할 수 있습니다.

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

[LLM 평가] LLM 모델 자체 평가

dong_seok — Mon, 7 Apr 2025 17:37:07 +0900

평소 LLM 애플리케이션을 개발하였지만, 의도대로 답변인 나오는지를 눈대중으로만 확인하다가 신뢰성 확보 및 객관적인 지표를 통한 성능 고도화를 위해 LLM의 성능을 평가해야겠다는 생각이 들었고, 이에 LLM의 성능 평가에 대한 내용을 정리해보고자 합니다.

1. LLM 평가 배경

LLM평가는 모델 자체의 전반적인 성능을 객관적으로 측정하고, 이를 통해 실제 환경에서의 효용성을 예측하는 데 초점을 둡니다. 신뢰할 수 있는 평가 체계를 갖추는 것은 LLM 개발과 응용에서 필수적인 과정입니다. 이러한 LLM 평가는 크게 모델 자체를 평가하는 것과 LLM 애플리케이션을 평가하는 두 가지로 구분됩니다. 이번 글에서는 모델 자체 평가에 대해 다뤄보도록 하겠습니다.

1) LLM 평가의 주요 접근법

LLM 평가는 크게 세 가지 관점에서 이루어집니다.

일반적 성능 측정
- 언어를 얼마나 잘 이해하고 자연스럽게 구사할 수 있는지를 평가합니다.
- 문장의 의미 파악, 번역, 독해, 질문-답변 등 다양한 언어 응용 분야에서의 성능을 측정합니다.
도메인 특화 성능 측정
- 법률, 의료, 금융 등 특정 도메인에 대해 파인튜닝된 모델의 성능을 평가합니다.
- 각 분야에 맞게 훈련된 모델이 얼마나 정확한 결과를 도출하는지 측정합니다.
얼라인먼트(Alignment) 성능 측정
- 모델이 편향성, 유해성, 윤리적 이슈에 대해 인간의 보편적 기준에 얼마나 부합하는지를 평가합니다.
- 이는 모델이 사회적, 윤리적 기준을 어느 정도 따르는지에 중점을 둡니다.

2) LLM 평가가 어려운 이유

자세한 설명에 앞서 LLM 평가가 다른 모델에비해 왜 어려운가를 간단하게 설명하고 넘어가겠습니다. 언어 모델의 평가가 어려운 가장 큰 이유는 언어 자체가 지닌 복잡성과 다양성 때문입니다.

언어의 복잡성: 언어는 문맥, 뉘앙스, 함축적 의미를 포함하는 복잡한 시스템입니다.
평가 기준의 다양성: 단순히 정답을 맞히는 것을 넘어 창의성, 유용성, 적절성 등 다양한 측면에서 평가가 필요합니다.
주관성: 특히 창의적 텍스트 생성에서는 '좋은' 결과에 대한 정의가 주관적일 수 있습니다.
일관성: 모델의 성능은 태스크, 도메인, 입력 프롬프트의 형식에 따라 크게 달라질 수 있습니다.

이러한 이유로, LLM 평가에서는 다양한 방법론이 병행되어 사용되며, 그중 대표적인 평가 접근법을 아래와 같이 정리할 수 있습니다.

2. LLM 정량적 평가

정량적 평가는 수치적 지표를 통해 모델의 성능을 객관적으로 측정하는 접근법입니다. 주요 평가 지표는 다음과 같습니다.

1) Accuracy

전체 예측 중 정답으로 판단된 비율입니다. 정형 데이터에 대한 분류 문제에 가장 널리 사용됩니다.

2) F1 Score

Precision(정밀도)과 Recall(재현율)의 조화 평균으로, 데이터 불균형 상황에서 유용합니다.

Precision: 모델이 positive로 예측한 것 중 실제 positive인 비율
Recall: 실제 positive 중 모델이 positive로 예측한 비율

3) BLEU (Bilingual Evaluation Understudy)

기계 번역 품질을 평가하기 위한 지표로, 생성된 문장이 참조 문장과 얼마나 유사한지 측정합니다. 단어 및 구 단위의 정확도에 중점을 둡니다.

4) ROUGE (Recall-Oriented Understudy for Gisting Evaluation)

주로 문서 요약 성능을 평가하며, 참조 요약과 생성 요약 간의 재현율 기반 유사도를 측정합니다.

선택 기준 정리

정형화된 출력 (예: 선택지 문제, 짧은 응답): Accuracy, F1 Score
비정형화된 출력 (예: 자연어 요약, 생성): BLEU, ROUGE

3. 모델 평가 방식에 따른 분류

1) 확률 기반 평가

모델이 각 후보 답변에 대해 부여한 확률값(log-likelihood)을 기반으로 평가하는 방식입니다. 계산이 빠르고 간단하지만, 실제 생성된 응답과는 차이가 있을 수 있습니다.

질문: 콜라독립 815는 코카콜라에서 만들었나요?
확률 결과: {' 아니오': -3.56..., ' 예': -3.57...}

"아니오"가 더 높은 확률값을 가지므로 정답으로 선택됩니다.

2) 생성 기반 평가

확률 기반의 평가는 말그대로 답변에 대한 확률적인 값일 뿐이지, 답변이 정확하게 지문 처럼 출력된 다는 것은 아닙니다. 어떤 경우는 평가에 있어 정확한 워딩이 들어간 결과를 선호 할 수 도 있습니다. 생성 기반 평가는 모델이 실제로 텍스트를 생성하게 한 후, 그 출력을 정답과 비교하는 방식입니다. 이 방법은 실제 사용 시나리오와 더 유사하지만, 평가 시간이 더 오래 걸리고 모델의 출력 형식이 일관되지 않을 수 있다는 단점이 있습니다.

{
"doc_id":10,
"doc":{
"question":"밀가루의 제분 후 인공적인 산화를 시키는 첨가물 중 국내에서 사용할 수 없는 것은?",
"answer":3,
"A":"Chlorine Dioxide",
"B":"Diluted Benzoyl Peroxide",
"C":"Potassium Bromate",
"D":"Ammonium Persulfate",
"Category":"Food Processing",
"Human Accuracy":0.0741
},
"target":"C",
[중략]
"resps":[["C\n해설：국내에서 사용할 수 없는 것은 Potassium Bromate이다"]],
[중략]
"exact_match":0.0
}

평가 로그인데, 모델의 출력을 보면 답변을 제대로 했지만 뒤에 추가적인 설명이 들어가서 답변이 일치하지 않는다고 판단해서 답변이 틀리다고 판단하였습니다. 이럴때는 맨 앞의 정답만 취하도록 정규식 필터링을 취해주면 됩니다. 다만 모델의 출력 형식이 일관되지 않으면 정규식을 작성할때 혼란을 겪을 수 있으니 모델의 출력이 일정할때 쓰면 좋은 방법인 것 같습니다.

추가로, 생성 기반의 평가는 직접 추론을 해서 결과를 가지고 평가를 하기 때문에 단순 확률값을 구하는 계산보다 훨씬 더 많은 리소스를 필요로 하게 됩니다. 따라서 생성 기반의 평가가 확률 기반의 평가 보다 평가 시간이 더 소요됩니다.

4. 정성적 평가

정량적 평가만으로는 모델의 모든 측면을 평가하기 어렵습니다. 정성적 평가는 인간의 판단을 통해 모델의 출력 품질을 더 종합적으로 평가하는 접근법입니다.

1) 인간 평가자 활용

확률 기반의 방법은 모델의 성능을 수치화하는데 유용하지만, 문법적으로 올바른 문장일지라도, 그 의미가 왜곡되거나 맥락에 맞지 않게 나오는 경우가 있기 때문에 생성된 텍스트의 품질을 보장하기 어렵습니다. 또한, 생성 기반의 평가는 생성한 문장을 직접 평가함으로써 더 현실적인 대안으로 보일 수 있지만, 생성된 문장의 품질을 평가하려면 문개 이해, 논리적 일관성, 창의성 등 다양한 요소를 고려해야 하는데, 단순히 필터링 기법이나 데이터 처리로는 평가 방식에 한계가 있습니다. 그렇기에 제일 신뢰 할 수 있는 방법은 사람이 직접 모델의 출력을 검토하는 것입니다. 다음과 같은 측면에서 평가가 이루어질 수 있습니다.

유용성: 모델의 응답이 사용자의 질문이나 요구를 얼마나 잘 해결했는지
정확성: 제공된 정보가 사실과 일치하는지
자연스러움: 응답이 인간이 작성한 것처럼 자연스러운지
맥락 이해: 질문의 맥락을 제대로 파악했는지
윤리성: 응답이 윤리적 기준을 준수하는지

하지만 사람이 직접 모델의 출력을 검토한다는 것은 너무 많은 시간과 비용이 소모된다는 단점이 있습니다. 이러한 한계를 해결하기 위해 등장한 것이 LLM as a Judge 입니다.

2) LLM as a Judge

최근에는 다른 LLM을 평가자로 활용하는 접근법이 주목받고 있습니다. 예를 들어, GPT-4와 같은 고성능 모델이 다른 모델의 출력을 평가하는 방식입니다. 이 방법은 인간 평가자를 동원하는 것보다 비용과 시간을 절약할 수 있고, 평가 결과의 신뢰성을 높일 뿐만 아니라, 인간 평가자가 가질 수 있는 주관적인 편향을 줄이는 데도 큰 도움이 됩니다.

결론

LLM 평가는 단순한 수치 비교를 넘어 다양한 관점과 방법론이 필요한 복잡한 작업입니다. 정량적 평가는 객관적인 비교를 가능하게 하지만, 언어의 복잡성과 창의성을 완전히 포착하지 못할 수 있습니다. 반면, 정성적 평가는 보다 종합적인 평가를 제공하지만, 주관성과 비용 문제가 있습니다. 최적의 LLM 평가 시스템은 이 두 접근법을 균형 있게 결합하여, 모델의 기술적 성능뿐만 아니라 실제 사용 환경에서의 유용성과 적합성까지 종합적으로 고려해야 합니다. 앞으로 LLM 기술이 발전함에 따라, 이러한 평가 방법론 역시 계속해서 진화할 것으로 기대됩니다.

다음에는 이러한 평가 방법론을 직접 적용하고 비교해보는 시간을 가져보겠습니다.

참고자료

https://devocean.sk.com/blog/techBoardDetail.do?ID=166716&boardType=techBlog

https://wikidocs.net/238529

[LLM 서빙] vLLM vs sglang

dong_seok — Fri, 4 Apr 2025 22:52:05 +0900

대규모 언어 모델의 효율적인 서빙을 위해서는 메모리 관리와 병렬 처리 같은 최적화 기술이 필수적입니다. LLM 서빙이란 동일한 연산을 수행하면서도 성능 하락 없이 추론 능력을 향상시키는 방안을 통해 모델 서빙을 수행하는 것을 말합니다. 다양한 프레임워크들이 개발되었지만, 현재 가장 널리 사용되고 자주 언급되는 vLLM과 SGLang에 대해 간단히 설명하고 비교해보는 시간을 가지겠습니다.

1. vLLM

vLLM은 LLM 추론 및 제공을 위한 빠르고 사용하기 쉬운 라이브러리입니다. UC 버클리의 스카이 컴퓨팅 랩에서 개발되었으며, 학계와 산업계의 기여를 통해 커뮤니티 중심 프로젝트로 발전했습니다.

주요 기능

1) 고성능 서빙

PagedAttention 기술을 사용한 메모리 관리와 처리 성능 극대화
대기중인 요청 연속 처리 가능
고처리량을 유지하면서도 낮은 지연 시간 실현 가능
실시간 응용 프로그램에서 강력한 성능을 발휘
CUDA/HIP 그래프를 통한 빠른 모델 실행
최적화된 CUDA 커널과 FlashAttention, FlashInfer 통합

2) 유연한 배포 및 확장성

Hugging Face 같은 다양한 모델 허브에서 모델 가져올 수 있음
Tensor Parallelism, Pipeline Parallelism을 지원하여 여러 GPU에 걸쳐 모델 분산 배포 가능
대규모 데이터 처리와 추론작업에서 탁월한 성능 제공
NVIDIA 및 AMD 환경에서 최적화

3) 다양한 디코딩 알고리즘

병렬 샘플링: 다수의 출력 동시 생성
빔 검색: 최적의 출력 시퀀스 탐색

4) API 호환성

OpenAI API와 호환되는 서버 설정 가능
기존 OpenAI API를 사용하던 애플리케이션을 vLLM으로 대체하거나 보완 가능

5) 최적화 기능

GPTQ, AWQ, FP8 KV Cache와 같은 다양한 양자화 기법 지원
모델의 메모리 사용량을 줄이고, GPU에서 실행 시 성능을 최적화
스트리밍 출력 및 프리픽스 캐싱 지원
Multi-lora 지원

6) 하드웨어 지원

NVIDIA GPU, AMD CPU 및 GPU
Intel CPU, Gaudi® 가속기
IBM Power CPU, TPU
AWS Trainium 및 Inferentia 가속기

2. sglang

SGLang은 대규모 언어 모델과 비전 언어 모델을 위한 빠른 서빙 프레임워크입니다. 백엔드 런타임과 프런트엔드 언어를 공동 설계하여 모델과의 상호 작용을 더 빠르고 제어 가능하게 만듭니다.

주요 기능

1) 빠른 백엔드 런타임

접두사 캐싱, 제로 오버헤드 CPU 스케줄러
연속 배칭, 토큰 어텐션(페이지 어텐션)
추측 디코딩, 텐서 병렬 처리
청크별 사전 채우기, 구조화된 출력
RadixAttention을 통한 효율적인 서비스 제공
FP8/INT4/AWQ/GPTQ 양자화 지원

2) 유연한 프런트엔드 언어

체인 생성 호출: 복잡한 생성 작업의 연결
고급 프롬프팅: 효과적인 프롬프트 전략 지원
제어 흐름: 조건부 및 반복적 프로세스 구현
다중 모달 입력: 텍스트와 이미지 등 다양한 입력 처리
병렬성: 동시 작업 처리
외부 상호 작용: 다른 시스템과의 통합

3) 광범위한 모델 지원

생성 모델: Llama, Gemma, Mistral, QWen, DeepSeek, LLaVA 등
임베딩 모델: e5-mistral, gte, mcdse
보상 모델: Skywork
새로운 모델을 쉽게 통합할 수 있는 확장성

4) 커뮤니티

오픈 소스로 제공
활발한 커뮤니티의 지원
업계에서 점차 채택되는 추세

3. vLLM vs sglang

1) 공통점

PagedAttention 기술	두 프레임워크 모두 메모리 관리 최적화를 위한 PagedAttention 기술 활용
연속 배칭	대기 중인 요청들을 효율적으로 처리하여 처리량 극대화
양자화 지원	GPTQ, AWQ, INT4 등 다양한 양자화 기법 지원으로 모델 경량화
추측 디코딩	생성 속도 향상을 위한 추측 디코딩 메커니즘 지원
텐서 병렬 처리	대규모 모델의 분산 처리를 위한 텐서 병렬화 지원
청크별 사전 채우기	대용량 입력을 효율적으로 처리하기 위한 청크 기반 사전 채우기 지원

2) vLLM 강점

다양한 하드웨어 지원	• NVIDIA GPU, AMD CPU/GPU<br>• Intel CPU, IBM Power CPU<br>• TPU, Gaudi 가속기<br>• AWS Trainium/Inferentia
OpenAI 호환 API	기존 OpenAI API 기반 애플리케이션과의 즉시 호환성 제공
다양한 디코딩 알고리즘	병렬 샘플링, 빔 검색 등 다양한 디코딩 방식 지원
CUDA/HIP 그래프	그래프 기반 최적화로 모델 실행 속도 향상
멀티로라 지원	여러 LoRA 어댑터를 동시에 적용할 수 있는 기능 제공

3) sglang 강점

통합 백엔드-프론트엔드 설계	백엔드 런타임과 프론트엔드 언어의 공동 설계로 일관된 개발 경험
유연한 프로그래밍 모델	• 체인 생성 호출<br>• 고급 프롬프팅<br>• 제어 흐름<br>• 병렬성 관리
다중 모달 입력 처리	텍스트, 이미지 등 다양한 입력 형식의 통합 처리 지원
제로 오버헤드 CPU 스케줄러	CPU 리소스의 효율적 활용을 위한 최적화된 스케줄러
RadixAttention	구조화된 출력 생성을 위한 특화된 어텐션 메커니즘
임베딩 및 보상 모델 지원	• 임베딩 모델: e5-mistral, gte, mcdse<br>• 보상 모델: Skywork

4. 선택 가이드

1) vLLM 선택 시나리오

다양한 하드웨어 환경에서 배포 필요
OpenAI API와의 호환성 중요
최대한의 처리량과 확장성이 우선시되는 경우
멀티-LoRA 적용이 필요한 경우
성숙한 커뮤니티 지원과 광범위한 문서화가 중요한 경우

2) SGLang 선택 시나리오

복잡한 생성 작업의 체인화 필요
고급 프롬프팅 및 제어 흐름 중요
통합된 백엔드-프론트엔드 접근 방식이 선호되는 경우
다중 모달 입력 처리 필요
임베딩 및 보상 모델과의 통합 필요
구조화된 출력 처리 중요

vLLM은 다양한 하드웨어 지원과 성숙한 인프라를 갖춘 범용 서빙 솔루션으로, 대규모 배포와 높은 처리량이 필요한 프로젝트에 적합합니다. 반면 SGLang은 프로그래밍 모델과 사용자 경험에 중점을 둔 통합 접근 방식을 제공하여, 복잡한 LLM 애플리케이션 개발에 더 적합할 수 있습니다. 공식문서마다 적절한 예제와 자세한 설명이 제공되고있으니 활용하면 좋을 것 같습니다.

참고자료

https://docs.vllm.ai/en/latest/

https://docs.sglang.ai/

https://machinelog.tistory.com/entry/vLLM-%EC%9D%B4%EB%9E%80-%EB%AD%98%EA%B9%8C

[Github] 잔디가 심어지지 않는 문제 해결하기

dong_seok — Thu, 3 Apr 2025 23:17:51 +0900

이전에 GitHub와 티스토리 블로그를 연동해서 잔디 심기를 만들어보았고 연동이 잘 된 것을 확인했습니다. 그런데 그 이후 제가 따로 생성한 레포지토리에서 push한 내용이 잔디가 심어지지 않는 현상을 발견했습니다. 오늘은 제가 최근에 겪었던 GitHub 잔디 심기 문제와 그 해결 과정을 공유하려고 합니다.

1. 문제 상황

저는 여러 개의 GitHub 레포지토리에서 작업을 하고 있었습니다. 그런데 이상한 점을 발견했습니다.

레포지토리 A: 코드를 push했더니 GitHub 프로필에 잔디가 잘 심어짐
레포지토리 B: 코드를 push했는데 GitHub 프로필에 잔디가 심어지지 않음

처음에는 레포지토리 설정 문제인가 싶었지만, 둘 다 제가 직접 만든 public 레포지토리였기 때문에 설정 차이는 없었습니다.

2. 원인 분석

문제를 파악하기 위해 먼저 각 레포지토리의 커밋 로그를 확인해보았습니다.

git log

그리고 바로 차이점을 발견했습니다:

잔디가 심어지는 레포지토리의 커밋:

commit f3f623f60ce7f2ba3170694f8c5f320310777841
Author: ehdtjr <dskang207@gmail.com>
Date:   Sat Apr 5 13:42:15 2025 +0900

잔디가 심어지지 않는 레포지토리의 커밋:

commit e1257241f82e16f8f2ef2143ad335f5b185cb2ae
Author: 동석 <dongseok@dongseog-ui-Macmini.local>
Date:   Sat Apr 5 14:06:07 2025 +0900

바로 문제를 파악할 수 있었습니다. 잔디가 심어지지 않는 레포지토리에서는 제 GitHub 계정과 연결된 이메일이 아닌, 컴퓨터의 로컬 사용자 정보를 사용하고 있었던 것입니다!

3. 해결 방법

1) 개별 레파지토리 설정 변경

우선 잔디가 심어지지 않던 레포지토리에서 git config 설정을 변경했습니다.

git config user.name "ehdtjr"
git config user.email "dskang207@gmail.com"

이 명령어는 현재 레포지토리에만 적용되는 설정입니다. 설정 후 새로운 커밋을 push했더니 드디어 잔디가 심어졌습니다!

2) 전역 설정으로 모든 레포지토리에 적용하기

하지만 매번 새 레포지토리마다 설정하는 것은 번거롭습니다. 그래서 전역 설정으로 모든 레포지토리에 동일하게 적용했습니다.

git config --global user.name "ehdtjr"
git config --global user.email "dskang207@gmail.com"

이제 새로 클론하거나 생성하는 모든 레포지토리에서 GitHub 계정과 연결된 정보로 커밋이 생성되어 잔디가 제대로 심어집니다.

4. 느낀점

PC를 바꾼 후부터 레포지토리에 push를 하고 commit log를 살펴보면 아래 이미지처럼 로컬 사용자 정보로 기록이 남았는데, 이것이 GitHub 계정 연결을 하지 않아서 생긴 문제라는 점을 오늘에서야 알게 되었습니다. 평소엔 그냥 "왜 그러지?" 하고 넘어갔는데, 사소한 궁금증도 그냥 넘어가지 말고 이유를 찾아볼 필요가 있다고 다시 한번 생각하게 된 계기가 되었습니다.

결론

GitHub 잔디가 심어지지 않는 문제는 대부분 Git 설정의 user.name과 user.email이 GitHub 계정과 연결되지 않아서 발생합니다. 이 설정을 GitHub 계정과 일치시키면 쉽게 해결할 수 있습니다. 최근에 PC를 바꾸면서 기존 설정들이 사라지다보니 이런 문제가 발생했던것 같습니다. 앞으로 새 컴퓨터에서 개발을 시작할 때는 가장 먼저 git config --global 설정을 하는 것을 잊지 말아야겠습니다!

[ESG 투자] ESG 투자란?

dong_seok — Wed, 2 Apr 2025 23:10:28 +0900

문서 검색 에이전트를 개발하던 중, 재무제표만을 활용하는 기존 솔루션들과의 차별화 필요성을 느껴 ESG 데이터 활용으로 방향을 전환하게 되었습니다. ESG 및 ESG 투자에 대한 기본 개념부터 실제 데이터 확보 방법까지 정리해보았습니다.

1. ESG 투자란 무엇인가?

ESG 투자는 단순한 트렌드가 아닌 현대 투자 전략의 핵심 요소로 자리잡고 있습니다. 환경(Environmental), 사회(Social), 지배구조(Governance) 요소를 고려해 투자 결정을 내리는 이 접근법은 재무적 성과와 사회적 가치를 동시에 추구합니다.

ESG의 세 가지 핵심 요소

환경(E): 탄소 배출량, 에너지 효율성, 폐기물 관리, 자원 사용, 기후변화 대응 등 기업의 환경 영향을 평가
사회(S): 인권, 노동 조건, 다양성과 포용성, 공정한 보상, 제품 안전성 등 기업과 이해관계자 간 관계를 평가
지배구조(G): 이사회 구성, 경영진 보상, 회계 투명성, 윤리적 비즈니스 관행, 주주 권리 등 기업 운영 방식을 평가

2. ESG 투자 지표와 평가

ESG 투자에는 신뢰할 수 있는 데이터와 표준화된 지표가 필수적입니다. MSCI, Sustainalytics, Bloomberg, S&P Global 등의 기관이 주요 평가 지표를 개발하여 제공하고 있습니다.

주요 ESG 평가 지표

환경 지표: 탄소 발자국, 에너지 효율성, 수자원 사용량, 폐기물 관리, 환경 규제 준수
사회 지표: 직원 다양성, 작업장 안전, 인권 정책, 공급망 관리, 지역사회 참여
지배구조 지표: 이사회 독립성, 경영진 보상 구조, 부패 방지 정책, 세금 투명성, 주주 권리

3. ESG 투자의 성공 사례

ESG 원칙을 효과적으로 적용한 기업들의 성공 사례는 ESG 투자의 가치를 입증합니다:

유니레버: '지속가능한 생활 계획'을 통해 환경 영향을 줄이고 사회적 가치를 창출하면서도 재무적 성과 달성
테슬라: 전기차와 청정 에너지 솔루션으로 환경 영향 감소에 기여하며 기업 가치 증대
파타고니아: 환경 보호 중심의 기업 문화와 지속가능한 제품으로 소비자 신뢰와 브랜드 가치 제고

4.ESG 투자의 위험 요소와 관리

ESG 투자에도 주의해야 할 위험 요소가 존재합니다:

그린워싱: 기업이 실제 ESG 개선 노력은 미미하면서 성과를 과장하는 문제
데이터 신뢰성: 표준화가 미흡하고 평가 기관마다 다른 방법론을 사용하는 문제
단기 성과 압박: 장기적 관점이 필요한 ESG 투자와 단기 수익 추구 간의 갈등
지역적 차이: 글로벌 투자에서 지역마다 다른 ESG 기준과 규제

5. ESG 투자를 선택해야 하는 이유

ESG 투자는 다양한 측면에서 매력적인 선택입니다:

재무적 성과 개선: 연구에 따르면 ESG 성과가 우수한 기업이 장기적으로 더 나은 재무 성과를 보이는 경향
위험 관리: 환경 규제, 소송, 평판 손상 등 잠재적 위험을 선제적으로 관리
장기적 가치 창출: 지속가능한 비즈니스 모델을 통한 안정적 성장과 가치 창출
사회적 영향: 환경 보호, 사회 정의, 기업 책임 등 긍정적인 사회적 변화에 기여
투자자 수요 증가: 특히 밀레니얼과 Z세대의 가치 기반 투자 선호도 상승

6. ESG 데이터 확보 방법

ESG 데이터를 확보하기 위해 다양한 방법을 검토한 결과, 많은 데이터 제공 서비스가 유료이거나 별도의 승인이 필요했습니다. MSCI, Sustainalytics, Bloomberg, S&P Global 등은 대부분 유료 서비스를 제공합니다. 그러나 Yahoo Finance에서 무료로 기본적인 ESG 데이터를 확인할 수 있었습니다. 종목 검색 후 Sustainability 항목에서 ESG 종합 점수와 환경(E), 사회(S), 구조(G) 각각의 점수를 확인할 수 있습니다.

모든 종목에 해당하는건 아니지만 종목을 검색하고 Sustainability 항목에 들어가면 하단 이미지처럼 ESG 점수와 각 E,S,G에 대한 점수가 매겨져있습니다. 다른 ESG 요소에 대한 데이터를 추가적으로 가져오고 싶지만 yahhoo Finance에서 지원하는 API에서 무료로 가져올 수 있는 데이터에는 한계가 있는 것 같았습니다.

yfinance 라이브러리를 사용해 ESG 데이터를 쉽게 가져올 수 있습니다.

import yfinance as yf
ticker = yf.Ticker("NVDA")
esg_data = ticker.sustainability
print(esg_data)

이 코드를 실행하면 NVIDIA의 ESG 점수 데이터를 확인할 수 있습니다. 현재는 기본적인 점수 데이터만 확보 가능하지만, 향후 추가 데이터 소스를 발굴하거나 유료 서비스를 검토하여 더 풍부한 ESG 데이터를 확보할 계획입니다.

참고자료

https://creativestudio.kr/3542

https://www.samsungsds.com/kr/insights/esg-global-trends-in-2025.html

https://www.hankyung.com/article/202412201003i

https://www.fidelity.co.kr/insight-and-learning/learn-about-investing/esg-investing/esg-benefits

MCP Client & Server 직접 구현하기

dong_seok — Tue, 1 Apr 2025 23:08:14 +0900

MCP의 원리와 Claude를 이용한 사용방법을 알아보았지만, 더 근본적으로 MCP Client와 Server가 어떻게 만들지고 사용되는지에 대해 더 깊게이해하고 넘어가야 추후에 응용하는데 도움이 될 것 같아. 유튜브에서 MCP Client, Server를 직접 만들어서 Youtube Agent 데모를 구현한 예제가 있길래, 이걸 보면서 Mcp Client와 Server의 생성방법과 작동 원리에 대해 이해하고 넘어가도록 하겠습니다.

1. MCP 서버 생성

먼저 MCP 서버를 만들어줍니다. Server라고 생각하면 어렵게 느껴질 수 있는데, MCP 서버는 생각보다 단순합니다. 일반 함수를 작성하는 것과 크게 다르지 않습니다.

from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("youtube_agent_server")

@mcp.tool()
def get_youtube_transcript(url: str) -> str:
    """ 유튜브 영상 URL에 대한 자막을 가져옵니다."""
    
    # 1. 유튜브 URL에서 비디오 ID를 추출합니다.
    video_id_match = re.search(r"(?:v=|\/)([0-9A-Za-z_-]{11}).*", url)
    if not video_id_match:
        raise ValueError("유효하지 않은 YouTube URL이 제공되었습니다")
    video_id = video_id_match.group(1)
    
    languages = ["ko", "en"]
    # 2. youtube_transcript_api를 사용하여 자막을 가져옵니다.
    try:
        transcript_list = YouTubeTranscriptApi.get_transcript(video_id, languages=languages)
        
        # 3. 자막 목록의 'text' 부분을 하나의 문자열로 결합합니다.
        transcript_text = " ".join([entry["text"] for entry in transcript_list])
        return transcript_text

    except Exception as e:
        raise RuntimeError(f"비디오 ID '{video_id}'에 대한 자막을 찾을 수 없거나 사용할 수 없습니다.{e}")
        
...

우리가 앞서 MCP Server를 "표준화된 모델 컨텍스트 프로토콜을 활용해 특정 기능을 노출하는 경량 프로그램"이라고 정의하였습니다. 그럼 우리가 MCP Server에서 구현해야할 것은 "특정 기능"이는 것입니다. 이 특정 기능을 함수화 해서 만들어두고 "@mcp.tool()" 데코레이터로 표시해두면 됩니다. 이 데코레이터는 함수자체가 mcp client들이 활용 가능한 형태로 자동으로 변환 시켜주는 역할을 합니다.

핵심 포인트

Tool Calling을 통한 Agent를 구현해 보신 분들은 익숙하겠지만 Agent에게 도구를 여러개 Mapping 시켜줬을때 Agent는 어떤 상황에 어떤 도구를 써야할지 판단을 내리기 힘듭니다. 그래서 도구마다 description을 자세히 적어줄 필요가 있습니다. MCP도 마찬가지입니다.

상세한 설명(docstring): LLM이 도구의 목적과 사용법을 정확히 이해하도록 돕습니다.
타입 힌트: 인자와 반환값의 타입을 명시하여 LLM이 더 정확하게 도구를 사용할 수 있게 합니다.

if __name__ == "__main__":
    print("Starting MCP server...")
    mcp.run()

만들고 싶은 도구를 이어서 만들어주고 하단에 mcp.run()으로 mcp server 코드를 마무리합니다.

2. MCP Clinet 연동을 위한 준비

MCP Clinet를 생성하기에 앞서 로컬 MCP 서버를 연동하려면, 서버 실행에 필요한 Python 실행 파일 경로와 MCP 서버 스크립트 경로를 JSON 설정에 입력해야 합니다. 따라서 별도의 json파일을 만들고 하단 Json 파일처럼 작성해줍니다.

{
  "mcpServers": {
    "mcp-test": {
      "command": "/Users/yourname/projects/python_mcp_agent/venv/bin/python",
      "args": [
        "/Users/yourname/projects/python_mcp_agent/2_mcp_server.py"
      ]
    }
  }
}

command에 가상환경의 경로, args에 우리가 생성한 mcp Server의 경로를 작성해줍니다. 경로는 왼쪽 디렉토리 구조에서 우클릭으로 Path를 확인하는게 제일 간편합니다.

3. MCP Client 생성

이제 본격적인 준비가 끝났으니 MCP Clinet를 생성하고 Server와 연동해서 실행해보겠습니다.

from agents.mcp import MCPServerStdio

# MCP 서버 설정
async def setup_mcp_servers():
    servers = []
    
    # mcp.json 파일에서 설정 읽기
    with open('mcp.json', 'r') as f:
        config = json.load(f)
    
    # 구성된 MCP 서버들을 순회
    for server_name, server_config in config.get('mcpServers', {}).items():
        mcp_server = MCPServerStdio(
            params={
                "command": server_config.get("command"),
                "args": server_config.get("args", [])
            },
            cache_tools_list=True
        )
        await mcp_server.connect()
        servers.append(mcp_server)

    return servers

우리가 작성한 json 파일을 가져와서 서버 목록을 확인하고 순회하며 연결합니다.

from agents import Agent, Runner

# 에이전트 설정
async def setup_agent():
    # 서버가 이미 존재하는지 확인하고, 없으면 생성
    mcp_servers = await setup_mcp_servers()
    
    agent = Agent(
        name="Assistant",
        instructions="너는 유튜브 컨텐츠 분석을 도와주는 에이전트야",
        model="gpt-4o-mini",
        mcp_servers=mcp_servers
    )
    return agent,mcp_servers

여기서 사용한 Agent는 OpenaAI Agents SDK로 Openai에서 정식으로 공개한 패키지입니다. Agent를 간단하게 만들고 MCP Server 연동도 쉽게 할 수 있도록 도와줍니다.

# 메시지 처리
async def process_user_message():
    agent,mcp_servers = await setup_agent()
    messages = st.session_state.chat_history

    result = Runner.run_streamed(agent, input=messages)

    response_text = ""
    placeholder = st.empty()

    async for event in result.stream_events():
        # LLM 응답 토큰 스트리밍
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            response_text += event.data.delta or ""
            with placeholder.container():
                with st.chat_message("assistant"):
                    st.markdown(response_text)


        # 도구 이벤트와 메시지 완료 처리
        elif event.type == "run_item_stream_event":
            item = event.item

            if item.type == "tool_call_item":
                tool_name = item.raw_item.name
                st.toast(f"  도구 활용: `{tool_name}`")


    st.session_state.chat_history.append({
        "role": "assistant",
        "content": response_text
    })
    # 명시적 종료 (streamlit에서 비동기 처리 오류 방지)
    for server in mcp_servers:
        await server.__aexit__(None, None, None)

streamlit 기본 설정을 마친뒤 위 코드로 사용자의 입력에 대해 "Runner.run_streamed(agent, input=messages)" 실행하고 결과값을 받아와 화면에 보여주면 됩니다.

만들어져있는 MCP Server를 가져다가 사용하는 것도 좋지만, 어떤 원리로 작동하는지를 코드를 뜯어보면서 살펴보니 확실히 이해하는데 더 도움이 되는 것 같습니다.

참고자료

https://www.youtube.com/watch?v=Rn5HMaWunx4

https://github.com/dabidstudio/python_mcp_agent

[MCP] Github MCP Server 사용하기

dong_seok — Mon, 31 Mar 2025 15:53:57 +0900

이전 포스트에서 Claude에서 MCP를 사용하는 모습을 간단히 소개해드렸는데요, 이번에는 한 단계 더 나아가 직접 MCP 서버를 가져다가 사용해보도록 하겠습니다. 직접 개발하는 대신 이미 만들어진 GitHub MCP 서버를 활용하여 Claude와 연결하는 방법을 알아보겠습니다.

1. Claude에서 MCP 사용 준비하기

Claude로 MCP를 사용하기 위해서는 두 가지가 필요합니다:

Claude Pro 구독 결제
Claude 데스크톱 앱 설치

Claude 데스크톱 앱은 공식 웹사이트 좌측 하단에서 다운로드하실 수 있습니다.

이렇게 claude 앱을 다운로드 받고나면 설정-> 개발자 탭을 들어가줍니다.

윈도우의 경우 좌측 상단에 설정탭이 따로 있을 것이고, mac os의 경우 mac 화면 자체 좌측 상단에 보시면 claude 설정 탭이 있으니 그걸 사용하시면 됩니다.

2. MCP 설정하기

처음 개발자 탭을 들어가면 아무것도 뜨지않는데, 나중에 도구를 추가하면 우리가 추가한 도구의 리스트들이 이 화면에서 보여지게됩니다.

여기서 "시작하기"를 누르면 MCP 설정에 도움을 주는 공식문서로 넘어가고, "설정 편집"을 누르시면 claude가 설치되어있는 폴더로 들어오게 됩니다. 이걸 원하는 에디터로 열어줍니다.

처음 들어오게 되면 저처럼 아무것도 없는 비어있는 Json 코드가 보이실 겁니다.

이제 저희가 여러가지 MCP 들을 여기에 넣어주고 저장해주면 Claude에서 사용이 가능합니다.

3. Github MCP 서버 연결하기

이제 실제로 MCP를 추가해보겠습니다. 저는 Smithery에서 제공하는 Github MCP 서버를 사용하여 제 리포지토리의 README.md 내용을 작성해보겠습니다.

github login을 해주고 Access token을 입력해줍니다. Token은 Github -> Settings -> 좌측 하단의 Developer settings -> Personal access tokens -> Fine-grained tokens 에서 발급받아주시면 됩니다.

한가지 주의할점은 "command" : "npx"로 되어있는데 우리가 사용하려는 Pc에 node.js가 설치되어있어야지만 이 명령어를 사용할 수 있다는 의미이기 때문에 pc에 node.js가 설치되어있지 않은분들은 설치 후에 진행해주시면 되겠습니다. 그리고 json 파일을 복사해서 "claude_desktop_config.json"에 붙혀넣어줍니다. 그 후 Calude 앱을 껐다가 다시 실행해주면

MCP Server가 성공적으로 연결된 모습을 볼 수 있습니다.

4. MCP 서버 사용해보기

질문을 하면 MCP Server를 연결한 도구를 사용하려고할때 사용해도 될지 물어보는데 이때 허용을 눌러주면 도구를 사용해서 답변을 생성하게 됩니다.

Claude가 생성한 답변이고,

제 Repositorys에 대한 내용입니다. 틀린 내용없이 잘 가져온 모습을 볼 수 있습니다.

원래 생각했던 md 파일을 만들어달라고 해보니 생각보다 잘 만들어주는 모습입니다.

MCP를 사용해보니 꽤 유용한 기능이지만, 질문에 따라 가끔 MCP 서버 오류가 발생하기도 합니다. 이는 질문을 얼마나 정확하게, 어떤 방식으로 하는지가 중요한 요소로 작용함을 의미합니다. 현재 단계에서는 완전히 안정적이라고 느끼지는 않았지만, 유용성과 발전 가능성이 충분히 있다고 생각됩니다. 앞으로 더 깊이 탐구해볼 가치가 있는 기술이라고 판단됩니다.

참고자료

https://www.youtube.com/watch?v=0sUN3d4atoc

[LLMops] Opik으로 LLM 평가하기

dong_seok — Fri, 28 Mar 2025 17:47:30 +0900

이전 포스팅에서 소개한 Opik 프레임워크를 활용하여 실제 LLM 응답을 평가하는 방법에 대해 알아보겠습니다. Opik은 다양한 메트릭을 통해 LLM 출력물의 품질을 체계적으로 평가할 수 있는 프레임워크를 제공합니다.

1. Opik 평가의 주요 구성 요소

Opik에서 평가를 진행하기 위해서는 다음 세 가지 핵심 구성요소가 필요합니다:

1) 데이터 세트
- LLM 응용 프로그램에 대한 입력과 선택적으로 예상 출력을 나타내는 샘플의 컬렉션
- 각 샘플에 대한 입력 및 예상 출력만 저장하며, LLM 지원서의 출력은 평가 프로세스 중에 계산되고 점수가 매겨집니다.

2) 평가 과제
- 데이터 세트에 저장된 입력을 점수를 매기고 싶은 출력에 매핑합니다. 평가 과제는 일반적으로 프롬프트 템플릿 또는 빌드 중인 LLM 애플리케이션입니다.

3) 메트릭
- LLM 결과물을 채점할 때 사용하려는 메트릭

2. 데이터 세트 생성 방법

평가 과제는 직접 만든 LLM 애플리 케이션을 사용하면 되고 메트릭은 이후에 자세히 설명하겠지만 Opik에서 기본적으로 제공해주는 메트릭의 종류가 비교적 다양하기 때문에 이걸 사용해도 됩니다. 그렇다면 문제는 데이터 세트입니다. LLM을 평가하기 위해 필수적으로 요구되는 데이터세트에 대해 Opik은 3가지 생성 방법을 말해주고있습니다.

Python SDK: Python SDK를 사용하여 데이터 세트를 만들고 여기에 항목을 추가할 수 있습니다.
추적 테이블: 기존에 기록된 추적 내용(예: 프로덕션 애플리케이션의 추적 내용)을 데이터 세트에 추가할 수 있습니다.
Opik UI: 수동으로 데이터 세트를 만들고 항목을 추가할 수 있습니다.

SDK를 사용해 데이터 세트를 생성하는 방법에 대해 샘플코드를 살펴보겠습니다.

from opik import Opik

# Get or create a dataset
client = Opik()
dataset = client.get_or_create_dataset(name="My dataset")

# Add dataset items to it
dataset.insert([
    {"user_question": "Hello, world!", "expected_output": {"assistant_answer": "Hello, world!"}},
    {"user_question": "What is the capital of France?", "expected_output": {"assistant_answer": "Paris"}},
])

SDK 활용 시 주요 특징

자동 중복 제거: 동일한 항목을 여러 번 삽입해도 데이터 세트에는 한 번만 저장됩니다.
get_or_create_dataset(): 지정된 이름의 데이터 세트가 있으면 가져오고, 없으면 새로 생성합니다.
다양한 형식 지원: JSONL, Pandas 데이터프레임 등 다양한 형식으로 데이터를 추가할 수 있습니다.

3. Online Evaluation 설정 방법

제가 개발하고 있는 에이전트에 평가를 적용하기 위해서는 어떤 방법을 사용하던 retrieval에 사용한 데이터를 기반으로 별도의 dataset을 새롭게 만들어줘야한다는 사실은 변함이 없었습니다. 그래서 dataset 구축에 대해 더 알아볼까하던참에 Opik에서 제공하는 Online Evaluation을 발견했습니다. Online Evaluation 기능을 활용하면 프로덕션 환경에서 실시간으로 LLM을 평가 할 수 있습니다. 이 기능은 별도의 데이터 세트 구축 없이도 실시간 평가가 가능한 장점이 있습니다.

먼저 project를 지정하고 online evaluation Tab에 들어가서 Create new rule를 클릭합니다.

평가 규칙에 필요한 정보를 입력해주겠습니다.

아직까지 제공하는 Model은 OpenAI, Anthropic, OpenRouter, Ollama, Gemini 처럼 자주 언급되고 활용되는 Modle 위주로 사용이 가능한 것 같았습니다.

Model을 사용하기 위해서는 해당 LLM의 공급사과 Key를 발급받아 입력해주면 관련 Model을 사용할 수 있게됩니다.

기본적으로 제공되는 평가지표로는 Hallucination, Moderation, AnswerRelevance가 있고, 기호에 따라 직접 프롬프트를 조정하거나 Custom LLM-as-judge를 만들어서 사용할 수 있습니다.

기본적으로 제공해주는 Metric이 의미하는 바는 아래와 같습니다.

Hallucination: LLM 출력에 환각 정보 포함 여부 검사
Moderation: LLM 출력에 부적절한 내용 포함 여부 검사
AnswerRelevance: LLM 출력이 주어진 맥락과 관련성 검사

저는 생성된 답변이 context와 관련이 있는지 확인하고 싶어서 AnswerRelevance를 선택했습니다. 그리고 이제 하단에 input, output, context에 해당하는 값을 mapping을 시켜줘야하는데, 종류가 다양하고 자세한 설명이 없어서 실행 결과값이 계속 0으로 나와서 혼란을 겪었습니다. 여러 시행착오끝에 context는 output.documents를 선택하거나 기본 제공하는 값은 아니지만 input.context라고 입력해도 정상 작동하는 걸 확인했습니다. input은 question이 아닌 query로 하고 output은 answer를 선택하니 정상적으로 작동하였습니다.

평가가 완료되면 "Feedback scores" 섹션에서 점수와 함께 상세한 평가 이유를 확인할 수 있습니다. 이를 통해 LLM 응답의 품질을 객관적으로 분석할 수 있습니다.

Opik의 Online Evaluation 기능을 활용하면 배포된 LLM 애플리케이션의 성능을 실시간으로 모니터링하고 평가할 수 있습니다. 현재는 AnswerRelevance 메트릭만 활용했지만, 향후에는 다양한 메트릭과 커스텀 평가 방식을 적용해볼 예정입니다. 또한 별도의 데이터 세트를 구축하여 더 체계적인 평가도 진행할 계획입니다.

[LLM] context 기반 답변 비교

dong_seok — Thu, 27 Mar 2025 15:35:48 +0900

이전에 재무제표 데이터로 DB를 구축했으니 이 데이터를 이용해 사용자 쿼리에 대해 답변을 생성해 보도록하겠습니다.

1. DB 조회해서 데이터 가져오기

psycopg2.connect()을 사용해 디비에 연결된 상황고 query 변수로 사용자가 원하는 해외 기업이 input으로 들어왔다고 가정하고 진행하도록 하겠습니다.

def get_company_financial_data(conn, ticker):
    """특정 기업의 모든 재무 데이터 조회"""
    cursor = conn.cursor()

    # 기업 정보 확인
    cursor.execute(
        "SELECT ticker, company_name FROM companies WHERE ticker = %s", (ticker,)
    )
    company = cursor.fetchone()

    if not company:
        return None

    ticker, company_name = company

    # 재무 데이터 조회
    cursor.execute(
        """
        SELECT rt.name as report_type, m.name as metric, fd.value
        FROM financial_data fd
        JOIN metrics m ON fd.metric_id = m.id
        JOIN report_types rt ON m.report_type_id = rt.id
        WHERE fd.ticker = %s
        ORDER BY rt.name, m.name
    """,
        (ticker,),
    )

    results = cursor.fetchall()

    # 결과 포맷팅
    formatted_data = {"ticker": ticker, "company_name": company_name, "financials": {}}

    for report_type, metric, value in results:
        if report_type not in formatted_data["financials"]:
            formatted_data["financials"][report_type] = {}

        formatted_data["financials"][report_type][metric] = value

    return formatted_data

query="AAPL"

# 예시: 애플(AAPL) 재무 데이터 조회
financial_data = get_company_financial_data(conn, query)

해당 코드로 재무데이터를 조회하고 financial_data를 출력해보면

{'balance_sheet': {'Cash On Hand': '$53,775',
  'Long Term Debt': '$83,956',
  'Share Holder Equity': '$66,758',
  'Total Assets': '$344,085',
  'Total Current Assets': '$133,240',
  'Total Current Liabilities': '$144,365',
  'Total Liabilities': '$277,327',
  'Total Liabilities And Share Holders Equity': '$344,085'},
 'cash_flow': {'Cash Flow From Financial Activities': '$-39,371',
  'Cash Flow From Investing Activities': '$9,792',
  'Cash Flow From Operating Activities': '$29,935',
  'Net Cash Flow': '$356'},
 'financial_ratios': {'Book Value Per Share': '4.4385',
  'Current Ratio': '0.9229',
  'Debt/Equity Ratio': '1.45',
  'Free Cash Flow Per Share': '1.7817',
  'Gross Margin': '46.8825',
  'Net Profit Margin': '29.2277',
  'Operating Margin': '34.4586',
  'ROA - Return On Assets': '10.5584',
  'ROE - Return On Equity': '54.4204'},
 'income_statement': {'Basic EPS': '$2.41',
  'EBIT': '$42,832',
  'EBITDA': '$45,912',
  'EPS - Earnings Per Share': '$2.40',
  'Gross Profit': '$58,275',
  'Net Income': '$36,330',
  'Operating Income': '$42,832',
  'Pre-Tax Income': '$42,584',
  'Revenue': '$124,300'}}

Json 형태로 데이터들이 잘 조회 된 모습을 볼 수 있습니다.

2. PromptTemplate으로 prompt 만들기

추후에 chain을 구성하기 위해 prompt를 PromptTemplate()를 사용해서 객체로 구성해주겠습니다. 그전에 먼저 .env 파일에 llm으로 사용할 OPENAI_API_KEY 에 대한 값을 저장해주고 load_dotenv()를 실행해줍니다.

from dotenv import load_dotenv

load_dotenv()

쿼리 조회를 해서 가져온 재무제표 데이터를 활용해 답변을 하는지 확인하기 위해, 재무제표 데이터를 사용했을때와 사용하지 않았을때 2개의 프롬프트로 나눠서 chain을 구성해보았습니다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate

llm = ChatOpenAI(model="gpt-4o-mini")

template_1 = "너는 해외 금융 투자 전문가야. {ticker} 종목에 대해서 투자 판단을 내릴 수 있도록 보고서 형태로 일목요연하게 정리해줘."
template_2 = "너는 해외 금융 투자 전문가야. {ticker} 종목에 대해서 {context}를 활용해서 투자 판단을 내릴 수 있도록 보고서 형태로 일목요연하게 정리해줘."

prompt_1 = PromptTemplate(
    template=template_1,
    input_variables=["ticker"],
)

prompt_2 = PromptTemplate(
    template=template_2,
    input_variables=["ticker", "context"],
)

chain_1 = prompt_1 | llm
chain_2 = prompt_2 | llm

chain을 invoke()로 실행할때 프롬프트에에 지정한 input_variables의 값을 딕셔너리{ } 형태로 전달해주어야합니다. 그리고 content key 값을 출력하면 응답을 확인할 수 있습니다.

chain_1.invoke({"ticker": financial_data["ticker"]}).content

결과를 확인해보면

## AAPL (Apple Inc.) 투자 보고서

### 1. 개요
- **회사명**: Apple Inc.
- **티커**: AAPL
- **산업 분야**: 소비자 전자제품 및 기술
- **상장시장**: 나스닥

### 2. 최근 성과
- **주가동향**: 최근 1년간 AAPL 주가는 약 X% 상승했습니다. (X%는 실제 데이터를 기반으로 수정 필요)
- **시가총액**: 약 $X trillion (마찬가지로 데이터 보강 필요)
- **P/E 비율**: AAPL의 현재 주가수익비율(P/E)은 X로, 이는 같은 업종 내 평균인 Y와 비교할 때 (고평가/저평가)되며, 성장 잠재력을 반영합니다.

### 3. 재무 현황
- **매출 성장률**: 최근 분기 매출은 $X billion으로, 전년 대비 Y% 증가하였습니다.
- **순이익**: 순이익은 $X billion이며, 이는 증가 추세를 보이고 있습니다.
- **부채 비율**: 총 부채는 X%로 상대적으로 안전한 수준입니다.
- **현금 흐름**: AAPL은 강력한 자유 현금 흐름을 유지하고 있으며, 이는 배당금 지급 및 주식 재구매에 기여하고 있습니다.

### 4. 시장 동향
- **경쟁사 분석**: 주요 경쟁사로는 삼성전자, 구글, 마이크로소프트 등이 있으며, 이들과의 비교에서 AAPL의 시장 점유율이 X%로 나타났습니다.
- **소비자 트렌드**: 소비자 기술에 대한 수요 증가와 맞물려 AAPL의 아이폰, 아이패드 및 기타 제품의 판매가 호조를 보이고 있습니다.

### 5. 위험 요인
- **경쟁 심화**: 기술 발전과 시장의 변화로 인해 경쟁이 심화되고 있습니다.
- **거시경제적 요인**: 글로벌 경제 둔화 및 무역 긴장 등이 사업에 부정적인 영향을 줄 수 있습니다.
- **공급망 문제**: 코로나19 이후 공급망의 불안정성이 지속되고 있으며, 이는 생산 및 배송에 영향을 미칠 수 있습니다.

### 6. 결론 및 투자 판단
AAPL은 여전히 강력한 브랜드 파워와 견고한 재무 상태를 바탕으로 성장 가능성이 높습니다. 하지만 경직된 시장과 경쟁 심화, 거시경제적 요인들에 유의해야 합니다.

**투자 판단**:
- **매수**: 현재 주가가 저평가되어 있으며 향후 매출 성장 및 새로운 제품 출시가 기대되는 경우.
- **유지**: 주가가 상당히 상승하여 현재 경쟁 우위가 약해질 경우 보유를 유지.
- **매도**: 시장 불확실성 증가 시 판별이 필요한 매도 시점.

### 추가 권장 사항
- 정기적으로 재무 보고서 및 시장 동향을 주시하고, 전문가 의견 및 신뢰할 수 있는 데이터에 기반한 평가를 지속적으로 업데이트하는 것이 중요합니다.

---

(상기 자료의 숫자는 실제 시장 데이터에 따라 업데이트 필요)

보고서 형식으로 깔끔하게 정리한것 같지만, 내용을 살펴보면 구체적인 데이터도 없고 투자판단도 확실하게 내리지 않는 모습을 볼 수 있습니다. 이번엔 재무제표 데이터를 활용한 LLM의 답변을 살펴보겠습니다.

chain_2.invoke(
    {"ticker": financial_data["ticker"], "context": financial_data["financials"]}
).content

똑같이 딕셔너리 형태로 input_variables의 값을 채워주고 결과를 확인해보았습니다.

# Apple Inc. (AAPL) 투자 분석 보고서

## 1. 회사 개요
Apple Inc. (AAPL)은 전 세계에서 가장 가치 있는 기술 기업 중 하나로, 하드웨어, 소프트웨어 및 서비스 분야에서 폭넓은 제품과 서비스를 제공합니다. 본 보고서는 AAPL의 재무 상태, 현금 흐름, 재무 비율 및 수익성을 분석하여 투자 판단을 돕기 위해 작성되었습니다.

## 2. 재무제표 요약

### 2.1. 대차대조표 (Balance Sheet)
- **현금 및 현금성 자산 (Cash On Hand)**: $53,775M
- **장기 부채 (Long Term Debt)**: $83,956M
- **주주 자본 (Share Holder Equity)**: $66,758M
- **총 자산 (Total Assets)**: $344,085M
- **총 현재 자산 (Total Current Assets)**: $133,240M
- **총 현재 부채 (Total Current Liabilities)**: $144,365M
- **총 부채 (Total Liabilities)**: $277,327M
- **부채 및 주주 자본 합계 (Total Liabilities And Share Holder Equity)**: $344,085M

### 2.2. 현금 흐름 (Cash Flow)
- **재무 활동으로 인한 현금 흐름 (Cash Flow From Financial Activities)**: $-39,371M
- **투자 활동으로 인한 현금 흐름 (Cash Flow From Investing Activities)**: $9,792M
- **운영 활동으로 인한 현금 흐름 (Cash Flow From Operating Activities)**: $29,935M
- **순 현금 흐름 (Net Cash Flow)**: $356M

### 2.3. 손익계산서 (Income Statement)
- **기본 주당순이익 (Basic EPS)**: $2.41
- **EBIT (세전 영업 이익)**: $42,832M
- **EBITDA (상각 전 영업 이익)**: $45,912M
- **주당 순이익 (EPS - Earnings Per Share)**: $2.40
- **총 수익 (Revenue)**: $124,300M
- **순이익 (Net Income)**: $36,330M

## 3. 재무 비율 분석
- **주당 장부가치 (Book Value Per Share)**: $4.44
- **유동 비율 (Current Ratio)**: 0.92
- **부채/자본 비율 (Debt/Equity Ratio)**: 1.45
- **자유 현금 흐름 주당 (Free Cash Flow Per Share)**: $1.78
- **총 이익률 (Gross Margin)**: 46.88%
- **순 이익률 (Net Profit Margin)**: 29.23%
- **영업 이익률 (Operating Margin)**: 34.46%
- **자산 수익률 (ROA)**: 10.56%
- **자기 자본 수익률 (ROE)**: 54.42%

## 4. 투자 판단
### 4.1. 강점
- **높은 수익성**: AAPL의 순 이익률(29.23%)과 영업 이익률(34.46%)은 업계 평균보다 높아 안정적인 수익 구조를 나타냅니다.
- **강력한 재무 구조**: 높은 자산 총액($344,085M)과 대비해 상대적으로 적은 부채(총 부채 $277,327M)는 재무적 안정성을 보여줍니다.
- **높은 ROE**: 54.42%의 자기 자본 수익률은 주주들에게 높은 이익을 가져다줄 잠재력을 보여줍니다.

### 4.2. 우려 사항
- **부채 비율**: 부채/자본 비율이 1.45로 상대적으로 높아, 향후 이자 지급 능력에 대한 우려를 초래할 수 있습니다.
- **유동성 문제**: 유동 비율(0.92)이 1 이하로, 단기 채무 상환 능력에 일부 부담이 있을 수 있습니다.

### 4.3. 결론
Apple Inc. (AAPL)은 강력한 재무 성과와 높은 수익성을 자랑하며, 안정적인 현금 흐름을 보여줍니다. 그러나 높은 부채 비율과 낮은 유동 비율은 잠재적인 위험 요소이므로, 주의가 필요합니다. 장기적인 투자 관점에서 볼 때, AAPL은 여전히 매력적인 투자처로 평가됩니다. 따라서, 투자 결정을 내리기 전에 보다 면밀한 시장 동향과 경쟁 환경 분석이 필요합니다.

## 5. 추천
AAPL 주식에 대한 투자는 중장기적으로 긍정적이지만, 시장의 변동성을 고려하여 적절한 포트폴리오 분산 및 리스크 관리를 권장합니다.

주어진 재무제표 데이터를 바탕으로 더 확실하게 수치화 된 보고서가 생성됐고, 데이터를 분석해서 기존 chain_1 대비 투자에 대한 조언과 적당한 판단도 내린 모습을 볼 수 있습니다.

3. Prompt 템플릿 관리하기

꼭 필요한 과정은 아니지만, 우리가 추후에 프롬프트를 계속 수정해간다거나 여러 종류의 프롬프트가 생겼을때 이를 LangChain Hub를 활용해서 쉽게 관리하는 방법을 간단하게 살펴보겠습니다. LangChain Hub를 사용하기 위해서는 LangSmith에서 API key를 꼭 발급받아줘야합니다.

LangChain Hub에는 내가 작성한 프롬프트를 자유롭게 업로드할 수 있고, 다른 사람이 작성하고 공유한 프롬프트도 손쉽게 사용할 수 있습니다. 우측에 보면 목적별 프롬프트가 다양하게 존재하는 모습을 볼 수 있습니다. 프롬프트를 가져오는 코드는 langchain을 활용해 아주

쉽게 작성할 수 있습니다.

from langchain import hub

# 가장 최신 버전의 프롬프트를 가져옵니다.
prompt = hub.pull("rlm/rag-prompt")

# 특정 버전의 프롬프트를 가져오려면 버전 해시를 지정하세요
prompt = hub.pull("rlm/rag-prompt:50442af1")

이제 제가 작성한 프롬프트를 Langchain Hub에 업로드해서 확인해보겠습니다.

from langchain import hub

# 프롬프트를 허브에 업로드합니다.
hub.push("{repo_full_name}", prompt_2)

코드는 굉장히 간단한데 문제가 조금 있었습니다. repo_full_name에 자신의 langsmith Id를 입력해야하는데 이 부분이 조금 어려웠습니다. 초기에는 Langsmith에 ID가 만들어지지않는게 default이기때문에 ID를 새로 만들어줘야합니다. 우선 공유되어있는 프롬프트중 하나를 아무거나 선택하고 우측상단에 Fork를 눌러줍니다.

prmpt name을 자유롭게 입력해주고 Fork를 누릅니다.

이제 여기서 Langsmith id를 입력하면 됩니다. 한번 설정하면 바꿀 수 없으니 신중하게 입력하면 되겠습니다. 그리고나서 다시 코드로 돌아가서 hub.push를 진행해보았습니다.

성공적으로 제 Langchain Hub 레파지토리에 프롬프트가 생성된 모습입니다. 혹시 몰라 hub.pull을 사용해 프롬프트가 잘 가져와지는지까지 테스트해보았습니다.

프롬프트가 잘 가져와지는 모습을 볼 수 있었습니다. 이제 앞으로 Langchain Hub를 사용해 목적에 맞는 프롬프트를 손쉽게 가져다 사용할 수 있고, 내가 사용하는 프롬프트들도 버전별로 업로드하면서 편리하게 유지보수할 수 있습니다.

참고자료

https://github.com/teddylee777/langchain-kr/blob/main/02-Prompt/01-PromptTemplate.ipynb

[DB] Postgresql DB 구축하기

dong_seok — Wed, 26 Mar 2025 22:35:13 +0900

일전에 크롤링을 통해 얻었던 재무제표 데이터를 활용해 로컬에서 postgresql DB를 구축해 자연어 쿼리에서 엔티티를 추출했다는 가정하에, 특정 기업에 대한 데이터를 디비에서 조회해서 LLM에게 context로 제공해 답변을 생성해보도록 하겠습니다.

1. Postgresql 설치

도커 컨테이너를 사용하지않고 가장 기본적인 로컬 환경에서 실행을 할 것이기 때문에 아래 명령어로 먼저 Postgresql 서버가 실행중인지 확인해줍니다.

brew services list

초기엔 당연히 postgresql이 안나올것이고 실행을 위해서는 "brew services start postgresql" 명령어를 입력해줘야합니다.

실행후 사진과같은 에러가 발생했다면, postgresql이 설치되어있지 않아서 생긴 에러이기 때문에 하단 명령어로 설치해줍니다.

brew install postgresql

이후 다시 "brew services start postgresql" 명령어를 입력하고 "brew services list"로 확인해보면 로컬에서 postgresql이 정상적으로 실행되고 있는 모습을 볼 수 있습니다. 나중에는 이렇게 로컬에 다운로드 받아서 실행시키는게 아니라 도커 컨테이너 환경에서 다운로드받아서 실행하는 것도 일반적으로 사용되는 방법입니다.

2. server & DB create

postgresql을 설치하고 실행했으니 이제 내부에 디비를 만들고 테이블을 만들도록 하겠습니다.

좀 더 시각적으로 편하게 작업하기 위해 GUI 도구인 pgAdmin을 설치해고 실행해주었습니다. 가장 처음 실행 시켰을때 화면인데, 여기서 로컬에서 실행한 postgresql 서버를 연결해줍니다. Servers -> Register -> server... 를 클릭해줍니다

서버의 이름은 자신이 하고싶은 이름을 지정해주면됩니다.

로컬에서 실행시킨 postgresql 서버에 연결할 것이기 때문에 Host name은 localhost로 하고 별도의 설정을 해주지 않았기 때문에 Username은 기본적으로 현재 macOS 사용자이름이 기본값이고 Password는 없기때문에 나중에 값을 입력해주면 됩니다.

그러면 이제 "financial_data"라고 하는 새로운 server가 생긴 모습을 볼 수 있습니다.

이제 새 서버에 DB와 Table을 생성해주도록 하겠습니다. 기본적으로 Postgresql은 기본 제공해주는 postgres DB에 먼저 연결한 후, 사용자가 원하는 새로운 DB를 생성한 다음, 해당 데이터베이스에 다시 연결하는 구조입니다. 따라서 먼저 postgres DB에 연결하는 코드를 작성해줍니다.

import psycopg2
from psycopg2.extensions import ISOLATION_LEVEL_AUTOCOMMIT

# 데이터베이스 연결 및 생성
conn = psycopg2.connect(
    database="postgres",
    user="dongseok",
    password="qwe123",  # 실제 비밀번호로 변경
    host="localhost",
    port="5432"
)
conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
cursor = conn.cursor()

CREATE DATABASE 명령은 트랜잭션 안에서 실행할 수 없어서 "conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)" 코드로 트랜잭션 자동 커밋 설정을 추가해줘야합니다. 그리고 이제 내가 원하는 DB를 만들어줍니다.

# 데이터베이스 생성
db_name = "financial_data"
cursor.execute(f"CREATE DATABASE {db_name}")
cursor.close()
conn.close()

PostgreSQL에서는 특정 데이터베이스 내부에서 새로운 데이터베이스를 생성하는 것이 아니라, PostgreSQL 서버 자체에서 관리하는 데이터베이스 리스트에 새로운 데이터베이스를 추가하는 방식입니다. 따라서 "CREATE DATABASE financial_data" 명령은 postgres 데이터베이스에 연결된 상태에서 실행하지만, 새로운 financial_data 데이터베이스는 PostgreSQL 서버의 데이터베이스 리스트에 등록됩니다.

이제 새로 만든 financial_data db에 연결하고 테이블을 만들어보도록 하겠습니다.

# 새 데이터베이스에 연결
conn = psycopg2.connect(
    database=db_name,
    user="dongseok",
    password="qwe123",  # 실제 비밀번호로 변경
    host="localhost",
    port="5432",
)
cursor = conn.cursor()

# 테이블 생성
cursor.execute(
    """
CREATE TABLE companies (
    ticker VARCHAR(20) PRIMARY KEY,
    company_name VARCHAR(200) NOT NULL
);
"""
)

cursor.execute(
    """
CREATE TABLE report_types (
    id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);
"""
)

cursor.execute(
    """
CREATE TABLE metrics (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    report_type_id INTEGER REFERENCES report_types(id),
    UNIQUE(name, report_type_id)
);
"""
)

cursor.execute(
    """
CREATE TABLE financial_data (
    id SERIAL PRIMARY KEY,
    ticker VARCHAR(20) REFERENCES companies(ticker),
    metric_id INTEGER REFERENCES metrics(id),
    value TEXT,
    report_date DATE,
    UNIQUE(ticker, metric_id, report_date)
);
"""
)

# 보고서 유형 초기 데이터 삽입
report_types = ["income_statement", "balance_sheet", "cash_flow", "financial_ratios"]

for rt in report_types:
    cursor.execute("INSERT INTO report_types (name) VALUES (%s)", (rt,))

conn.commit()

새로운 테이블들이 잘 생성된 모습을 볼 수 있습니다.

이제 이전에 크롤링했던 재무제표 파일에서 데이터를 파싱해서 테이블에 인덱싱해주면,

쿼리에 따른 테이블 조회가 잘 되는 모습을 볼 수 있습니다. 다음에는 이러한 RDBMS에 저장한 값을 LLM에게 context로 줘서 사용자 쿼리에 대해 답변을 생성해보고 더 나아가 pgvector를 활용해 시맨틱 서치도 진행해보도록 하겠습니다.

[crawling] 해외 기업 재무제표 crawling 해오기

dong_seok — Tue, 25 Mar 2025 23:25:15 +0900

국내 주식을 대상으로 Agent를 개발하던 중 대상이 해외 종목으로 바뀌면서, 기존에 "한경컨센서스"에서 가져오던 재무제표 데이터를 새로운 출처에서 확보해야 했습니다. 이 과정에서 발견한 유용한 해외 종목 데이터 사이트들과 크롤링 과정을 소개합니다.

1. 해외 기업 데이터 사이트 소개

1) Macrotrends

Macrotrends는 미국 기업들의 재무정보를 무료로 제공하는 사이트입니다. 중앙 검색창을 통해 원하는 기업을 찾으면 해당 기업의 재무 데이터를 종합적으로 확인할 수 있습니다.

중앙 서치바를 통한 기업 검색을 통해 해당 기업의 매출, 이익, 가격 지표 등 다양한 데이터를 확인할 수 있습니다.

주요 특징:

기업의 과거 15년 치 데이터 제공 (매출, 순이익, 자산, 부채, 현금흐름 등)
모든 주요 재무 정보를 한눈에 확인 가능
과거와 현재 비교를 통한 장기 추세 분석 가능
간편한 데이터 검색 및 비교 기능
직관적인 그래프와 차트 제공

2) DataRoma

DataRoma는 기관 투자자들의 포트폴리오 정보를 분석할 수 있는 플랫폼입니다. 운영 자산 규모 1억 달러 이상의 기관 투자자들은 매 분기 말 45일 이내에 증권 포트폴리오 정보를 SEC에 제출해야 하며, DataRoma는 이 데이터를 활용해 투자 대가들의 매매 동향을 추적합니다.

주요 특징:

여러 포트폴리오에 반복 등장하는 종목의 신뢰도 평가 가능
분기별로 업데이트되는 포트폴리오 변화 추적
투자자들의 전략 분석 가능
'Top 10 stocks by %' 기능을 통해 중점 투자 종목 파악
개별 투자자 포트폴리오 세부 분석 제공

3) Value Investors Club

Value Investors Club은 실력 있는 가치 투자자들이 모여 투자 아이디어와 심층 기업 분석을 공유하는 커뮤니티입니다. 이 사이트는 기업 분석을 작성하는 회원과 열람만 가능한 회원으로 구분됩니다. 분석 작성 회원은 엄격한 심사를 통과해야 하지만, 열람 회원은 간단한 회원가입만으로도 양질의 기업 분석 자료에 접근할 수 있습니다.

2. 데이터 사이트 및 재무제표 데이터 선정

앞서 말했듯 유용한 데이터 사이트가 많았지만, 저는 이중에서 macrotrends를 선택했습니다. DataRoma와 Value Investors Club도 유용했지만, 저는 LLM에게 제공해줄 객관적인 데이터가 필요했기 때문에, 타인의 의견이 포함되지 않고 오직 데이터만을 객관적으로 표현한 macrotrends를 선택했습니다. 그리고 재무제표에 지표가 너무 많기 때문에 그 중 투자 판단을 내리는데 도움을 줄 수 있는 값들만 따로 선정하였습니다.

1) 대차대조표(Balance Sheet)

Cash On Hand: 회사가 보유한 현금과 즉시 현금화 가능한 자산
Long Term Debt: 1년 이상의 상환 기간을 가진 회사의 장기 부채
Share Holder Equity: 주주들이 소유한 회사 가치(자산-부채)
Total Assets: 회사가 소유한 모든 자산의 총합
Total Current Assets: 1년 내에 현금화 가능한 단기 자산
Total Current Liabilities: 1년 내에 갚아야 하는 단기 부채
Total Liabilities: 회사의 모든 부채 총합
Total Liabilities And Share Holders Equity: 부채와 자본의 총합(자산 총계와 일치)

2) 현금흐름표(Cash Flow)

Cash Flow From Financial Activities: 자금조달 활동(대출, 주식발행 등)으로 인한 현금흐름
Cash Flow From Investing Activities: 투자 활동(자산 구매/매각)으로 인한 현금흐름
Cash Flow From Operating Activities: 영업 활동에서 발생한 현금흐름
Net Cash Flow: 모든 현금흐름을 합산한 순 현금흐름

3) 재무비율(Financial Ratios)

Book Value Per Share: 주당 순자산 가치(자기자본÷발행주식수)
Current Ratio: 유동비율(유동자산÷유동부채), 단기 지급능력 지표
Debt/Equity Ratio: 부채비율(총부채÷자기자본), 재무 레버리지 지표
Free Cash Flow Per Share: 주당 잉여현금흐름, 배당여력 평가 지표
Gross Margin: 매출총이익률((매출-매출원가)÷매출), 기본 수익성 지표
Net Profit Margin: 순이익률(순이익÷매출), 최종 수익성 지표
Operating Margin: 영업이익률(영업이익÷매출), 핵심사업 수익성 지표
ROA: 총자산수익률(순이익÷총자산), 자산 활용 효율성 지표
ROE: 자기자본수익률(순이익÷자기자본), 주주투자 수익성 지표

4) 손익계산서(Income Statement)

Basic EPS: 기본 주당순이익(순이익÷보통주식수)
EBIT: 이자 및 세전이익, 영업성과 평가 지표
EBITDA: 이자, 세금, 감가상각비 차감 전 이익, 현금창출능력 지표
EPS: 주당순이익, 주주에게 돌아가는 이익 지표
Gross Profit: 매출총이익(매출-매출원가)
Net Income: 당기순이익, 모든 비용 차감 후 최종 이익
Operating Income: 영업이익, 본업에서 발생한 이익
Pre-Tax Income: 세전이익, 세금 납부 전 이익
Revenue: 매출액, 주요 사업활동으로 발생한 총수입

3. 재무제표 추출하기

선정한 지표들에 대한 값을 crawling으로 가져오도록 하겠습니다. 이 부분에서 고민을 되게 많이했는데, 처음에는 RSS feed 활용법으로 접근했습니다.

원하는 지표를 클릭하고 우측 'View Reports'를 선택하면 보고서 모음 화면으로 이동합니다.

이후 검색된 보고서들에 대해 RSS Feed를 활용해 XML 파일에 포함된 보고서별 링크를 통해 필요한 데이터만 파싱하려 했습니다. 그러나 이 방법에는 큰 문제가 있었습니다. 기업별로 보고서 형식과 재무제표 구성이 상이했던 것입니다. 동일한 재무지표라도 기업마다 사용하는 태그나 명칭이 달라 일관된 크롤링이 어려웠습니다. 이런 문제를 해결하기 위해 공시 데이터를 구조화된 형태로 제공하는 표준 포맷인 XBRL을 활용해보려 했습니다. XBRL은 이전보다 통일된 형식을 제공했지만, 여전히 기업마다 차이가 존재했습니다. 결국 모든 기업에서 공통적으로 사용하는 표준 명칭이 필요하다고 판단했습니다. 이에 처음 검색 결과 화면에 표시되는 데이터를 기준으로 크롤링하는 방법을 선택했습니다. 이 방법을 통해 일관된 형식의 재무지표 데이터를 수집할 수 있었습니다.

참고자료

https://www.youtube.com/watch?v=Mm5dw9JPBxs

MCP (Model Context Protocol)

dong_seok — Sat, 22 Mar 2025 16:52:14 +0900

1. MCP란?

MCP는 Model Context protocal의 약자로 2024년 11월에 앤트로픽에서 발표한 개념으로 최근 이슈가 되고 있습니다. 이러한 MCP는 아래와 같이 다양하게 정의되고 있습니다.

- AI 에이전트가 웹 브라우저 없이도 직접 다양한 인터넷 서비스와 소통할 수 있게 해주는 표준 프로토콜

- AI 모델이 외부 데이터 및 도구와 상호 작용할 수 있도록 설계된 표준 프로토콜

- Client(클로드,커서,...)에서 다른 도구들도 쓸 수 있게 통일을 시켜주는 하나의 프로토콜

이와 같이 부르는 사람에따라 다양한 의미로 표현되고 있지만, 간단하게 말하면 " Client, LLM, Server를 이어주는 USB-C 포트와 유사한 역할"이라고 할 수 있습니다. 아래 이미지를 참고하면 더 쉽게 이해할 수 있습니다.

그렇다면 MCP가 최근 이슈가 되고 있는 이유에 대해서도 생각해 보았습니다. 기존 에이전틱 워크플로우를 구성할 때는, LLM이 중앙에 위치하고, 데이터베이스를 연결하는 별도의 툴을 만든 뒤, LangGraph로 이 툴과 LLM을 연결하는 등의 복잡한 과정이 필요했습니다. 추가 기능이 필요할 때마다 이러한 과정을 반복해야 했죠.

MCP의 등장으로 이런 복잡한 과정이 크게 간소화되었습니다. 기존에는 LangChain, LangGraph와 같은 LLM 프레임워크에 통합된 툴을 사용하거나, 직접 툴을 개발한 후 LLM 프레임워크를 통해 에이전트를 구축해야 했습니다. 하지만 MCP를 활용하면 LangChain이나 LangGraph에 대한 전문 지식이 없는 개발자들도 LLM과 원하는 외부 프로그램을 쉽게 연결할 수 있습니다. 이것이 제가 생각하는 MCP의 가장 큰 장점입니다.

이제 MCP가 어떤 방식으로 개발 과정을 간소화하는지 자세히 알아보겠습니다.

2. MCP 구성요소

MCP는 크게 3가지로 구성되어 있습니다.

1) MCP 클라이언트

서버와 1:1 연결을 유지하는 프로토콜 클라이언트 (Host & Server 간에 연결을 위한 중개자)

2) MCP 서버

표준화된 모델 컨텍스트 프로토콜을 통해 각각 특정 기능을 노출하는 경량 프로그램

3) MCP 호스트

MCP를 통해 데이터에 액세스하려는 Claude Desktop, IDE 또는 AI 도구와 같은 프로그램

앞에서 설명했던 LangGraph를 활용한 별도의 워크플로우 구축 없이 우리가 LLM에게 주고싶은 툴(DB 조회, 로컬 컴퓨터파일 조작 등) 을 따로 코드를 일일히 작성하고 연결할 필요 없이 이미 잘 만들어져있는 MCP Server를 사용해 LLM에게 지정만해주면 전보다 간단하고 더 다양한 기능을 제공할 수 있습니다. 기존 API 방식과 비교하면 아래와 같은 차이를 지니고 있습니다.

그렇다면 이러한 MCP는 어디서 어떻게 사용해야할까요?

3. MCP 사용방법

가장 간단하게 우리가 사용할 수 있는 방법은 클로드 프로를 결제하고 사용하는 방법입니다. 클로드 프로를 구매하고 클로드 앱을 다운로드 받은 후 "Claude_desktop_config.json" 파일의 구성을 변경해주면 됩니다. 먼저 파일->설정을 들어가줍니다.

아무것도 설정하지 않은 처음에는 아래와 같은 화면이 나올 것 입니다.

여기서 시작하기를 누르면 MCP 공식문서로 넘어갑니다. 그리고 설정 편집을 누르면 클로드가 설치되어있는 폴더로 넘어오게 되는데, 여기서 " Claude_desktop_config.json" 파일을 수정해주면 됩니다. 파일을 클릭해보면 비어있는 json 파일이 열릴텐데 여기서 내가 사용하고 싶은 mcpServer를 아래 예시처럼 추가하고 저장해주면 됩니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

그 후, 클로드 앱을 껏다가 키면 해당 mcpServer를 클로드가 인지하고 사용할 수 있게됩니다. 그렇다면 이러한 MCP는 어디서 사용할 수 있을까요? 물론 직접 만들 수 있습니다. 하지만 이미 잘 만들어져있는 MCP가 많기때문에 이것들을 활용하는 것만으로도 충분할 수 있습니다.

1) MCP Server Directory

검색 기능도 있고, 우리가 사용하고싶은 MCP Server들을 좀 더 직관적으로 보고 선택할 수 있습니다.

2) Awesome MCP Servers

github 레파지토리형태로 제공되기때문에 MCP Server Direcotry보다는 직관적이지 않을 수 있지만 마찬가지로 유용하기 때문에 본인에게 맞는 방법을 사용해서 자신에게 맞는 MCP 서버를 찾으면 되겠습니다.

3) smithery

4. MCP 장단점

앞에서 기존 AI 에이전트와 API 방식 대비 이점에 대해 간단하게 설명했지만, MCP를 사용했을때의 장단점에 대해 조금 더 명확히 작성해보고자 합니다.

1) 장점

외부 도구 연결 가능

- AI 모델이 원래 지원하지 않는 새로운 도구를 쉽게 추가할 수 있습니다

유연성과 확장성

- AI 모델이 다양한 데이터 소스와 유연하게 연결이 가능하고 확장성이 뛰어납니다

양방향 통신과 간편한 유지보수

- 실시간 상호작용이 가능하여 반응 속도가 향상되며 상대적으로 유지보수가 간편합니다

2) 단점

AI 에이전트와 도구 통합 문제

- 모델에 기존에 설계된 내용이 있기 때문에 도구를 추가하는 것만으로 AI가 제대로 작동하는 것은 아니며, 추가시 전체적인 시스템 구조와 조정이 필요합니다.

정확도와 신뢰성

- 새로운 도구를 추가하는 것은 쉽지만, 그 도구를 얼마나 정확하게 사용할 수 있을지는 보장할 수 없습니다.

보안 및 데이터 관리

- 서버 기반으로 동작하려면 사용자 인증 및 보안 문제를 해결해야하고, 데이터 유출이나 악성 도구 연결 등의 보안 관리가 면밀히 검토 될 필요가 있습니다.

추가로, MCP가 공개된 지 3개월 정도 지난 지금에서야 주목받게 된 이유는 Cursor AI에서 2월에 발표한 MCP 업데이트와 밀접한 연관이 있다는 테디노트님의 의견이 있었습니다. 생각해보면 Cursor AI의 도입이 없었다면 MCP가 지금처럼 인기를 얻지 못했을 수도 있었을 것 같습니다.

이처럼 기술이 주목받게 된 배경을 살펴보니, 아무리 혁신적인 기술을 개발하더라도 사람들이 쉽게 접근하고 활용할 수 있는 환경을 만드는 것이 얼마나 중요한지 다시금 생각하게 되었습니다.

참고자료

https://www.youtube.com/watch?v=0sUN3d4atoc

https://vision-ai.tistory.com/235

https://digitalbourgeois.tistory.com/875

https://www.youtube.com/watch?v=VKIl0TIDKQg&t=27s

https://www.youtube.com/watch?v=ISrYHGg2C2c

[Github 잔디 심기]티스토리 블로그 + Github 연동

dong_seok — Fri, 21 Mar 2025 15:35:37 +0900

티스토리 블로그에 글을 작성하면 깃허브 계정에서 자동으로 잔디가 심어지도록 설정해보도록 하겠습니다. 그러기 위해 Github Action을 이용하여 하루에 한번 티스토리의 RSS를 기반으로 Github에 커밋이 되도록 하겠습니다.

1. 티스토리 RSS 설정

먼저 티스토리 블로그에서 RSS 를 설정해줍니다. 내 블로그 설정 -> 관리 -> 블로그 -> 기타 설정에 위치한 RSS를 "전체 공개"로 설정 후 저장해줍니다. "https://striver.tistory.com/rss" 와 같이 자신의 블로그 주소에 접속하면 RSS 정보가 확인 가능합니다.

2. Repository 생성

Github Action으로 연동할 새로운 repository를 생성합니다.

3. 로컬 환경과 Repository 연동

자신이 편한 위치에 폴더를 하나 만들고 vscode로 들어간 후 해당 폴더를 이전에 만들었던 Repository와 연동해주었습니다.

git init
git branch -M main
git remote add origin https://github.com/ehdtjr/ehdtjr.git

연동이 잘 되었는지는 "git remote -v" 로 확인해 볼 수 있습니다.

4. RSS 및 Git Action 파일 작성

package.json 파일을 생성하기 위해 아래 명령어를 입력합니다.

npm init -y

만약 npm이 설치되지 않았을 경우 "brew install node" 명령어를 선행으로 실행하여 설치해줍니다. (mac os 기준)

이어서 RSS 정보를 파싱할 수 있는 rss-parser 라이브러리를 설치합니다.

npm i rss-parser

생성된 package.json 파일을 열어서 "type": "module", "start": "node index.js",를 추가합니다.

{
  "name": "github_tistory",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/ehdtjr/ehdtjr.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/ehdtjr/ehdtjr/issues"
  },
  "homepage": "https://github.com/ehdtjr/ehdtjr#readme",
  "description": "",
  "dependencies": {
    "rss-parser": "^3.13.0"
  }
}

마지막으로 프로젝트의 root에 index.js 파일을 새롭게 만들고 아래와같이 작성합니다.

import { writeFileSync } from 'node:fs';
import Parser from "rss-parser";

/**
 * README.MD에 작성될 페이지 텍스트
 * @type {string}
 */
let text = `# Hi there  

## 이런 환경에 익숙해요✍ 

## 언어

<p>
  <img alt="" src= "https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54"/> 
</p>

##   Latest Blog Posts

`;

// rss-parser 생성
const parser = new Parser({
    headers: {
        Accept: 'application/rss+xml, application/xml, text/xml; q=0.1',
    }});

(async () => {

    // 피드 목록
    const feed = await parser.parseURL('https://striver.tistory.com/rss'); // 본인의 블로그 주소
    
    text += `<ul>`;
    
    // 최신 10개의 글의 제목과 링크를 가져온 후 text에 추가
    for (let i = 0; i < 10; i++) {
        const {title, link} = feed.items[i];
        console.log(`${i + 1}번째 게시물`);
        console.log(`추가될 제목: ${title}`);
        console.log(`추가될 링크: ${link}`);
        text += `<li><a href='${link}' target='_blank'>${title}</a></li>`;
    }

    text += `</ul>`;
    
    // README.md 파일 생성
    writeFileSync('README.md', text, 'utf8', (e) => {
        console.log(e);
    })
    console.log('업데이트 완료');
})();

5. main.yml 생성

Git action 파일을 생성하기 위해 프로젝트 루트에서 .github\workflows 폴더를 생성하고 해당 폴더 안에 main.yml을 생성합니다.

# This is a basic workflow to help you get started with Actions

name: Readme Update

# Controls when the workflow will run
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  # 1시간에 한번씩 아래 스크립트를 실행한다.
  schedule:
    - cron: "0 */1 * * *"
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install dependencies
        run: | 
          npm ci
          npm install rss-parser

      - name: Update README
        run: npm start

      - name: Check if there are any changes
        id: verify_diff
        run: |
          git diff --quiet . || echo "changed=true" >> $GITHUB_OUTPUT

      - name: Commit README
        if: steps.verify_diff.outputs.changed == 'true'
        run: |
          git config --local user.email "dskang207@gmail.com"
          git config --local user.name "ehdtjr"
          git add .
          git commit -m "Update README.md"
          git push origin main

제일 하단의 run 부분을 자신의 github email, name으로 변경해줘야하고 cron으로 스크립트 실행 주기를 설정할 수 있습니다.

6. Git action permission 설정

Github Action 과정에서 발생할 403 permission 오류를 제어하기 위해 설정을 해줘야합니다. Settings -> Actions -> General에 들어가 하단 설정을 바꾸고 Save를 눌러줍니다.

참고자료

https://peterica.tistory.com/554

https://leejaehoon.tistory.com/entry/Github-Tistory-Github-%EC%97%B0%EB%8F%99%ED%95%98%EA%B8%B0

[LLMops] 오픈소스 LLM 평가 프레임워크 opik

dong_seok — Wed, 12 Mar 2025 19:15:48 +0900

오늘은 오픈소스로 제공되는 LLM 평가 프레임워크인 opik을 처음 접하게 되어 간단한 설명과 활용방법에 대해 얘기해보겠습니다.

opik은 LLM 애플리케이션을 평가, 테스트 및 모니터링하기 위한 오픈소스 플랫폼입니다. 저는 보통 RAG 파이프라인을 구성한후 추적을 하는 용도로 Langsmith를 많이 사용했는데, opik에서 좀 더 직관적인 ui와 LLM 성능을 자동으로 평가하는 기능도 제공한다고해서 사용해보게 되었습니다.

로그인하고 볼 수 있는 메인 화면인데 상당히 깔끔한 구조입니다.

하단의 Quickstart guide를 보면 사용하는 프레임워크별로 LLM을 추적할 수 있게끔 샘플 코드가 작성되어있습니다.

from langchain_openai import ChatOpenAI
from common.state_graph import GraphState
from retrieve_docs import retrieve_docs, summary_docs, evaluate_docs
from langgraph.graph import StateGraph, START, END
from opik.integrations.langchain import OpikTracer

# 모델 설정
model = ChatOpenAI(model_name="gpt-4o-mini")

# 워크플로우 생성 및 노드 등록
workflow = StateGraph(GraphState)

workflow.add_node("retrieve_docs", retrieve_docs)
workflow.add_node("summary_docs", summary_docs)
workflow.add_node("evaluate_docs", evaluate_docs)

##### 엣지 정의 예시 #####
workflow.add_edge(START, "retrieve_docs")
workflow.add_edge("retrieve_docs", "summary_docs")
workflow.add_edge("summary_docs", "evaluate_docs")
# workflow.add_edge("evaluate_docs", "retrieve_docs")
workflow.add_edge("evaluate_docs", END)

app = workflow.compile()

tracer = OpikTracer(graph=app.get_graph(xray=True))
inputs = {"question": "안녕하세요"}
result = app.invoke(inputs, config={"callbacks": [tracer]})

print(result)

제가 사용하고 있는 프레임워크는 LangGraph여서 관련 샘플 코드를 참고해서 제 코드에 추가하였습니다.

OPIK_API_KEY=Md3KFb....
OPIK_WORKSPACE=retrieve_docs

추가로 저는 Opik api key와 project명에 대한 설정을 .env 파일에 작성해주고 코드를 실행하였습니다.

OPIK: Failed to process CreateSpansBatchMessage. Error: status_code: 400, body: {'code': 400, 'message': 'No such workspace: retrieve docs'}
OPIK: Failed to process CreateTraceBatchMessage. Error: status_code: 400, body: {'code': 400, 'message': 'No such workspace: retrieve docs'}

그런데 분명 가이드라인을 따라 코드를 작성했고, 별도의 커스텀도 하지않았는데 위 에러가 계속 발생하였습니다.

제가 원하는 프로젝트명도 분명 만들어둔 상태였는데 에러가 계속 발생해서 원인을 찾지 못하고 있었습니다. 그러다 문득 retrieve docs를 만들어둔 Projects가 workspace와 다른게 아닐까? 라는 의문이 들었고 OpikTracer 클래스 내부를 살펴보니 매개변수로 project_name 값을 선택적 Input으로 받는걸 확인했습니다. 그래서 .env의 OPIK_WORKSPACE를 지우고 새롭게 아래와 같이 코드를 수정하고 다시 실행해 보았습니다.

tracer = OpikTracer(graph=app.get_graph(xray=True), project_name="retrieve_docs")

코드 실행후, 화면을 확인해보니 성공적으로 추적이 되고 있는 모습을 볼 수 있었습니다.

추적한 내용을 살펴보면, 각 노드에서 소요되는 시간과, 노드별 In/Output 결과를 직관적으로 볼 수 있었습니다. 더 사용해봐야겠지만 상당히 편리하고 유용하다는 느낌을 받았습니다. 이제 평가에 대한 작업도 진행해보도록 하겠습니다.

참고자료

https://github.com/comet-ml/opik?tab=readme-ov-file

[Fine-Tuning] LLM 파인튜닝 솔루션 - Unsloth

dong_seok — Wed, 26 Feb 2025 23:07:19 +0900

LLM을 클라우드 환경이나 Google Colab에서 파인튜닝하는 과정에서 종종 라이브러리 간 의존성 충돌로 인해 실행 오류가 발생하고, 높은 메모리 사용량과 긴 학습 시간이 문제가 되곤 합니다. 이러한 문제를 해결할 수 있는 보다 효율적인 방법을 찾던 중, 단일 GPU 환경에서도 최적의 성능을 제공하는 "Unsloth"를 접하게 되어 소개해 보겠습니다.

1. Unsloth란 무엇인가?

Unsloth는 LLM(대형 언어 모델) 파인튜닝을 보다 효율적으로 수행할 수 있도록 설계된 혁신적인 도구입니다. Michael과 Daniel Han 형제가 개발한 이 프로젝트는 적은 자원으로도 강력한 성능을 발휘할 수 있도록 최적화되어 있으며, 학습 속도 향상과 메모리 사용량 절감을 주요 목표로 하고 있습니다.

Unsloth는 NVIDIA의 GTX 1070과 같은 저사양 GPU부터 최신 H100까지 폭넓은 하드웨어를 지원하며, 허깅페이스(Hugging Face) 생태계와 완벽히 호환됩니다. 이를 통해 연구자와 개발자들은 기존 환경에서 쉽게 활용할 수 있습니다.

1.1 Unsloth의 주요 특징

고속 학습: 기존 기법보다 빠른 학습 속도를 제공하며, 대부분의 GPU 환경에서 뛰어난 성능을 발휘합니다.
메모리 최적화: 대형 모델을 단일 GPU에서도 학습할 수 있도록 메모리 사용량을 최소화합니다.
다양한 호환성: 허깅페이스의 SFTTrainer, DPOTrainer, PPOTrainer 등과 연동되어 익숙한 환경에서 활용할 수 있습니다.

2. Unsloth의 최적화 기술

Unsloth는 다양한 최적화 기술을 활용하여 학습 속도를 향상시키고 메모리 사용량을 줄일 수 있도록 설계되었습니다. 대표적인 기술들을 살펴보겠습니다.

2.1 Intelligent Weight Upcasting (지능형 가중치 업캐스팅)

기존 QLoRA(양자화된 Low-Rank Adaptation) 기법에서는 모델 안정성을 위해 일부 계층을 FP32로 변환합니다. Unsloth는 특정 모델(Mistral, LLaMA 등)에 최적화된 방식으로 업캐스팅을 수행하여 메모리 및 연산 효율성을 극대화합니다.

2.2 Manual Autograd (수동 그래디언트 계산)

Pytorch의 자동 미분 시스템(AutoGrad)은 LoRA 기반 파인튜닝 과정에서 비효율적일 수 있습니다. Unsloth는 자동 미분을 수동으로 최적화하여 연산 비용을 줄이고 속도를 높였습니다.

2.3 Triton 커널 최적화

Unsloth는 OpenAI에서 개발한 Triton을 활용하여 GPU 연산 성능을 극대화하였습니다. 이를 통해 연산 코드의 핵심 부분을 최적화하여 높은 학습 성능을 제공합니다.

2.4 xFormers 프레임워크 활용

Unsloth는 xFormers 프레임워크와 Flash-Attention을 활용하여 메모리 사용량을 절감하고 연산 속도를 가속화합니다.

3. Unsloth를 활용한 LLM 파인튜닝

Unsloth를 사용하면 복잡한 최적화 작업 없이 간편하게 LLM을 파인튜닝할 수 있습니다. 아래는 Gemma-2-9b 모델을 Google Colab에서 파인튜닝하는 예제입니다.

3.1 Unsloth 설치

!pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
!pip install --no-deps "xformers<0.0.27" "trl<0.9.0" peft accelerate bitsandbytes

# %%capture
# !pip install unsloth
# # Also get the latest nightly Unsloth!
# !pip uninstall unsloth -y && pip install --upgrade --no-cache-dir --no-deps git+https://github.com/unslothai/unsloth.git

# # Install Flash Attention 2 for softcapping support
# import torch
# if torch.cuda.get_device_capability()[0] >= 8:
# !pip install --no-deps packaging ninja einops "flash-attn>=2.6.3"

3.2 FastLanguageModel을 이용한 모델 로딩

Unsloth 라이브러리에서 FastLanguageModel 클래스를 import 합니다. FastLanguageModel 클래스는 Unsloth에서 가장 중요한 클래스 입니다. 허깅페이스 Transformers의 다양한 라이브러리들을 기본으로 하여 추가적인 최적화 및 패치 작업을 진행하게 됩니다.

from unsloth import FastLanguageModel
import torch

max_seq_length = 2048
dtype = None
load_in_4bit = True

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/gemma-2-9b",
    max_seq_length=max_seq_length,
    dtype=dtype,
    load_in_4bit=load_in_4bit,
)

3.3 PEFT 설정

FastLanguageModel 클래스의 get_peft_model 메서드는 주어진 모델과 설정을 기반으로 PEFT 객체를 반환합니다.

from trl import SFTTrainer
from transformers import TrainingArguments
from unsloth import is_bfloat16_supported

model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    lora_alpha=16,
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",
    random_state=3407,
    use_rslora=False,
    loftq_config=None,
)

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=max_seq_length,
    dataset_num_proc=2,
    packing=False,
    args=TrainingArguments(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        warmup_steps=5,
        max_steps=60,
        learning_rate=2e-4,
        fp16=not is_bfloat16_supported(),
        bf16=is_bfloat16_supported(),
        logging_steps=1,
        optim="adamw_8bit",
        weight_decay=0.01,
        lr_scheduler_type="linear",
        seed=3407,
        output_dir="outputs",
    ),
)

trainer.train()

3.4 Data Prep

Alpaca dataset으로 샘플 데이터셋을 구성해줍니다.

alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.

### Instruction:
{}


### Input:
{}


### Response:
{}"""



EOS_TOKEN = tokenizer.eos_token # Must add EOS_TOKEN
def formatting_prompts_func(examples):
instructions = examples["instruction"]
inputs = examples["input"]
outputs = examples["output"]
texts = []
for instruction, input, output in zip(instructions, inputs, outputs):
# Must add EOS_TOKEN, otherwise your generation will go on forever!
text = alpaca_prompt.format(instruction, input, output) + EOS_TOKEN
texts.append(text)
return { "text" : texts, }
pass

from datasets import load_dataset
dataset = load_dataset("yahma/alpaca-cleaned", split = "train")
dataset = dataset.map(formatting_prompts_func, batched = True,)

3.5 Train the model

Unsloth 모델은 SFTTrainer을 그대로 사용할 수 있으므로 별도의 랩핑된 학습 라이브러리가 필요하지 않습니다. SFTTrainer를 통해 기존에 사용하던 방식대로 모델, 토크나이저, 데이터셋 및 학습과 관련된 파라미터들을 설정하면 됩니다.

from trl import SFTTrainer
from transformers import TrainingArguments
from unsloth import is_bfloat16_supported

trainer = SFTTrainer(
model = model,
tokenizer = tokenizer,
train_dataset = dataset,
dataset_text_field = "text",
max_seq_length = max_seq_length,
dataset_num_proc = 2,
packing = False, # Can make training 5x faster for short sequences.
args = TrainingArguments(
per_device_train_batch_size = 2,
gradient_accumulation_steps = 4,
warmup_steps = 5,
max_steps = 60,
learning_rate = 2e-4,
fp16 = not is_bfloat16_supported(),
bf16 = is_bfloat16_supported(),
logging_steps = 1,
optim = "adamw_8bit",
weight_decay = 0.01,
lr_scheduler_type = "linear",
seed = 3407,
output_dir = "outputs",
report_to = "none", # Use this for WandB etc
),

)

trainer_stats = trainer.train()

QLoRA를 통해 학습될 파라미터 수의 비율을 확인할 수 있습니다.

model.print_trainable_parameters()

# trainable params: 54,018,048 || all params: 10,213,228,032 || trainable%: 0.5289

Show current memory stats

현재 사용하고 있는 GPU의 타입과 메모리에 대한 정보를 얻을 수 있습니다.

#@title Show current memory stats
gpu_stats = torch.cuda.get_device_properties(0)
start_gpu_memory = round(torch.cuda.max_memory_reserved() / 1024 / 1024 / 1024, 3)
max_memory = round(gpu_stats.total_memory / 1024 / 1024 / 1024, 3)
print(f"GPU = {gpu_stats.name}. Max memory = {max_memory} GB.")
print(f"{start_gpu_memory} GB of memory reserved.")

Show final memory and time stats

학습 시간, 사용 메모리 등 파인 튜닝 과정에 대한 전반적인 정보들을 알 수 있습니다.

#@title Show final memory and time stats
used_memory = round(torch.cuda.max_memory_reserved() / 1024 / 1024 / 1024, 3)
used_memory_for_lora = round(used_memory - start_gpu_memory, 3)
used_percentage = round(used_memory /max_memory*100, 3)
lora_percentage = round(used_memory_for_lora/max_memory*100, 3)
print(f"{trainer_stats.metrics['train_runtime']} seconds used for training.")
print(f"{round(trainer_stats.metrics['train_runtime']/60, 2)} minutes used for training.")
print(f"Peak reserved memory = {used_memory} GB.")
print(f"Peak reserved memory for training = {used_memory_for_lora} GB.")
print(f"Peak reserved memory % of max memory = {used_percentage} %.")
print(f"Peak reserved memory for training % of max memory = {lora_percentage} %.")

4. 결론

Unsloth는 LLM 파인튜닝을 위한 최적화된 솔루션으로, 적은 자원으로도 강력한 성능을 제공합니다. 다양한 최적화 기술을 통해 속도와 메모리 효율을 극대화하며, 허깅페이스 생태계와의 높은 호환성 덕분에 손쉽게 적용할 수 있습니다.

LLM 파인튜닝을 보다 빠르고 효율적으로 수행하고 싶다면, Unsloth를 적극 활용해보는 것을 추천합니다.

참고자료

https://devocean.sk.com/blog/techBoardDetail.do?ID=166285&boardType=techBlog

https://digitalbourgeois.tistory.com/433

https://colab.research.google.com/drive/1vIrqH5uYDQwsJ4-OO3DErvuv4pBgVwk4?usp=sharing

[Fine-Tuning] LLM fine-tuning (/w Elice Cloud) (2)

dong_seok — Mon, 24 Feb 2025 23:09:17 +0900

저번 글에 이어서 이번엔 파인 튜닝을 통해 추론 성능을 상승시켜보도록 하겠습니다. 어떻게 접근할지 고민하다가 누가 Dacon에 "Gemma-2-2B-it Full Finetuning 모델"을 공유 해주어서 이 코드를 먼저 실행 해 보았습니다.

!pip install transformers==4.40.1 accelerate==0.30.0 bitsandbytes==0.43.1 auto-gptq==0.7.1 autoawq==0.2.5 optimum==1.19.1 -qqq

!pip uninstall -y torch torchvision torchaudio
!pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu122

!pip uninstall -y bitsandbytes triton
!pip install --no-cache-dir bitsandbytes triton

!pip install -U transformers

from datetime import datetime, timedelta, timezone

# KST (한국 표준시, UTC+9) 설정
kst = timezone(timedelta(hours=9))

# 현재 시간 (KST)
kst_now = datetime.now(kst)
print(kst_now.strftime("%Y-%m-%d %H:%M:%S KST"))

import pandas as pd 
import torch 
from transformers import AutoTokenizer, AutoModelForCausalLM

def remove_repeated_phrases(text):
    phrases = text.split(" ")
    seen = set()
    result = []
    for phrase in phrases:
        if phrase not in seen:
            result.append(phrase)
            seen.add(phrase)
    result[0] = result[0].replace("model\n", "")
    return " ".join(result)

train = pd.read_csv('./train.csv', encoding = 'utf-8-sig')
test = pd.read_csv('./test.csv', encoding = 'utf-8-sig')

samples = []

for i in range(10):
    sample = f"input : {train['input'][i]} \n output : {train['output'][i]}"
    samples.append(sample)

model_name = "mindw96/Gemma-2-2B-it-DACON-LLM"
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = 'right'

restored_reviews = []


for index, row in test.iterrows():
    query = row['input']
    system_prompt = f"You are a helpful assistant specializing in restoring obfuscated Korean reviews. \
					Your task is to transform the given obfuscated Korean review into a clear, correct,\
					and natural-sounding Korean review that reflects its original meaning.\
					Below are examples of obfuscated Korean reviews and their restored forms:\n\n \
					Example, {samples[0]} \n {samples[1]} \n {samples[2]} \n {samples[3]} \n {samples[4]} \
					Spacing and word length in the output must be restored to the same as in the input.\
					Do not provide any description. Print only in Korean."

    messages = [
			{"role": "user", "content": '{}\ninput: {}, output:'.format(system_prompt, query)}
		]
    input_ids = tokenizer.apply_chat_template(messages, return_tensors="pt", return_dict=True).to("cuda")

    outputs = model.generate(**input_ids, max_new_tokens=len(query))
    generated_text = tokenizer.decode(outputs[0], skip_special_tokens=True)
    result = generated_text[len(messages[0]['content'])+6:].strip()
    result = remove_repeated_phrases(result)

    restored_reviews.append(result)
    print(index, result)

submission = pd.read_csv('./sample_submission.csv', encoding = 'utf-8-sig')
submission['output'] = restored_reviews
submission.to_csv('./gemma_2b_it_submission.csv', index = False, encoding = 'utf-8-sig')

from datetime import datetime, timedelta, timezone

# KST (한국 표준시, UTC+9) 설정
kst = timezone(timedelta(hours=9))

# 현재 시간 (KST)
kst_now = datetime.now(kst)
print(kst_now.strftime("%Y-%m-%d %H:%M:%S KST"))

위 코드로 실행해보았는데

10시간이 소요되었습니다... max_token을 Input 길이만큼 하도록 코드를 작성해서 배치 처리가 힘들었고, 제한된 gpu 메모리 상황에서 처리하다보니 생각보다 긴 시간이 소요되었습니다...

제출해보았는데 이전 샘플코드에 비해 확실히 정확도가 올라간 모습입니다. 그치만 위 소스코드는 남이 파인튜닝 해놓은 모델을 가져다 추론만 한 것이기때문에 제가 직접 모델을 파인튜닝해서 정확도를 상승시켜보고 싶단 생각이 들었습니다. 처음엔 2B 모델을 풀파인튜닝을 했을때 0.75의 수치가 나왔으니, 7~8B 정도의 모델로 풀 파인튜닝을 한다면 쉽게 성능이 나올 것이라고 생각했습니다. 하지만 문제는 너무나도 부족한 GPU 메모리였습니다. 엘리스 클라우드가 저렴하다고해도 고스펙 혹은 장시간 사용하기에는 금전적 부담이 됐습니다. (제가 코드를 잘못 작성한건지 Epoch가 1일경우에도 몇십시간 걸려서 이건 아니다 싶었습니다...) 결국 모델의 크기를 낮추고 양자화를 해서 적은 리소스로 파인튜닝을 진행하였습니다. 대신 기존 train 데이터를 증강시켜서 더 다양한 패턴을 학습시키자는 생각이 들어서 데이터를 증강하는 방법을 선택했습니다.

import pandas as pd
from konoise import NoiseGenerator

# train.csv 파일 불러오기
train_df = pd.read_csv("train.csv")

# NoiseGenerator 객체 초기화 (konoise)
generator = NoiseGenerator()

# 증강된 데이터 저장할 리스트
augmented_data = []

# 각 데이터에 대해 증강
for idx, row in train_df.iterrows():
    input_text = row['input']
    output_text = row['output']
    
    # input 텍스트에 대해 노이즈 추가 (난독화된 텍스트 생성)
    augmented_input_list = generator.generate(input_text, methods='disattach-letters', prob=1.0)
    
    # 리스트에서 첫 번째 항목을 가져와서 슬라이싱
    augmented_input = augmented_input_list[0][0]
    
    # output 텍스트는 그대로 교정된 상태로 유지
    augmented_output = output_text.strip()  # 교정된 텍스트
    
    # 증강된 데이터를 리스트에 저장
    augmented_data.append([augmented_input, augmented_output])

# 증강된 데이터를 새로운 DataFrame에 저장
augmented_df = pd.DataFrame(augmented_data, columns=['input', 'output'])

# 증강된 데이터만 저장한 CSV 파일
augmented_df.to_csv("augmented_data.csv", index=False)

# 기존 데이터와 증강된 데이터를 합친 CSV 파일
combined_df = pd.concat([train_df[['input', 'output']], augmented_df], ignore_index=True)
combined_df.to_csv("combined_data.csv", index=False)

konise 라이브러리를 이용해 기존 난독화 텍스트에 노이즈를 추가해 새로운 데이터셋을 만들었고, 기존 데이터셋과 결합한 csv 파일과 증강한 데이터셋만 가진 csv 파일 2개를 만들었습니다.

데이터가 준비되었으니 파인튜닝을 진행하려했는데 파인튜닝에 필요한 여러 라이브러리들이 서로 의존성 충돌이 많이 일어나서 위와 같은 에러들이 너무 많이 발생하였습니다. 물론 버전만 잘 맞춰줬다면 실행에 큰 문제는 없었겠지만, 경험도 부족하고 시간도 부족하였기에 다른 사람들에게 조언을 구했습니다. 조언을 통해 제가 선택한 방법은 "unsloth"를 사용하는 것이었습니다. unsloth에 대한 자세한 소개는 다른 글에서 추가적으로 남기고 여기서는 "단일 gpu 환경에서 적은 리소스로도 파인튜닝을 쉽게할 수 있도록 도와주는 편리한 라이브러리다. "정도만 이해하고 넘어가시면 되겠습니다. 보일러플레이트 코드도 제공해주어서 자신의 task에 맞게 편하게 커스터마이징 할 수 있었습니다.

unsloth에서 지원하는 llm 모델중 선택해서 사용하면 되는구조였는데 저는 llama 3B 모델을 선택했습니다.

빠르게 프로토타입을 만들어보고자 Epoch를 1로 해서 학습시켜보았습니다. 몇십시간이 예상되던때와 다르게 2시간도 안돼서 학습이 완료됐습니다. 이어서 추론도 진행해보았습니다.

제가 간과한 사실이 있었습니다... 초반 추론과정에선 문제가 없었는데 중간부터 input 데이터중에 모델의 최대 시퀀스 길이를 넘어가는 데이터가 있었던겁니다... 별 생각 없이 예제코드로나온 2048을 값으로 주면 충분할 것이라고 생각했는데 에러가 발생했고 input 데이터중 제일 길이가 큰 값이 몇인지 확인해보았습니다.

import pandas as pd

# test.csv 파일을 불러옵니다.
test_df = pd.read_csv("test.csv")

max_len = 0
max_index = None

# 각 input 텍스트의 토큰 길이를 계산 (특수 토큰 포함 여부는 필요에 따라 조정)
for i, text in enumerate(test_df['input']):
    tokens = tokenizer.encode(text, add_special_tokens=True)
    if len(tokens) > max_len:
        max_len = len(tokens)
        max_index = i

print("최대 토큰 길이:", max_len)
print("해당 인덱스:", max_index)

최대 토큰길이가 2439로 나왔습니다... 추론에 사용할 프롬프트도 생각해서 여유롭게 최대 시퀀스 값을 조정해야겠다는 생각이 들었습니다. 그래도 값을 4096으로 바꾸고 이참에 Epoch 수도 증가시켜서 테스트 해보기로했습니다.

3시간이라는 비교적 짧은 시간이 소요된 모습입니다.

사용된 메모리도 많지 않습니다. 추론도 약 3시간 정도 소요되었습니다.

제출결과 Gemma 2B 풀파인튜닝 모델보다 더 좋은 성적을 받은 모습입니다! 대회를 늦게 접해 더 다양한 방법을 시도하며 최적화 해보지 못한게 아쉬웠지만 LLM Fine-Tuning을 경험해본 뜻깊은 시간이었습니다.

참고자료

https://dacon.io/competitions/official/236446/codeshare/12157?page=1&dtype=recent

https://huggingface.co/mindw96/Gemma-2-2B-it-DACON-LLM

https://issul.tistory.com/447

https://github.com/wisenut-research/konoise

[Fine-Tuning] LLM fine-tuning (/w Elice Cloud) (1)

dong_seok — Wed, 19 Feb 2025 23:12:45 +0900

Dacon에서 진행하는 "난독화된 한글 리뷰 복원 AI 경진대회"를 뒤늦게 접하게 되어 LLM을 활용한 문제해결능력을 기르고자 경진대회에 참여하기로 하였습니다. 핵심 주제는 "식별하기 어렵게 쓴 한글 리뷰를 원래 한글 리뷰로 복원하는 AI 알고리즘 개발" 이었습니다.

데이터셋과 샘플 코드를 모두 제공해주었기에 이를 먼저 실행해보았습니다.

import pandas as pd
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig, pipeline

train = pd.read_csv('./drive/MyDrive/data_set/open/train.csv', encoding = 'utf-8-sig')
test = pd.read_csv('./drive/MyDrive/data_set/open/test.csv', encoding = 'utf-8-sig')

samples = []

for i in range(10):
    sample = f"input : {train['input'][i]} \n output : {train['output'][i]}"
    samples.append(sample)
    
    
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type= 'nf4',
    bnb_4bit_use_double_quant = True,
    bnb_4bit_compute_dtype=torch.bfloat16
)
model_id = 'beomi/gemma-ko-7b'
model = AutoModelForCausalLM.from_pretrained(model_id, quantization_config = bnb_config, device_map={"":0})
tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = 'right'

pipe = pipeline(
    task="text-generation",
    model=model,
    tokenizer=tokenizer
)

restored_reviews = []


for index, row in test.iterrows():
    query = row['input']

    messages = [
        {
            "role": "system",
            "content": (
                "You are a helpful assistant specializing in restoring obfuscated Korean reviews. "
                "Your task is to transform the given obfuscated Korean review into a clear, correct, "
                "and natural-sounding Korean review that reflects its original meaning. "
                "Below are examples of obfuscated Korean reviews and their restored forms:\n\n"
                f"Example, {samples}"
                "Spacing and word length in the output must be restored to the same as in the input. "
                "Do not provide any description. Print only in Korean."
            )
        },
        {
            "role": "user",
            "content": f"input : {query}, output : "
        },
    ]

    prompt = "\n".join([m["content"] for m in messages]).strip()


    outputs = pipe(
        prompt,
        do_sample=True,
        temperature=0.2,
        top_p=0.9,
        max_new_tokens=len(query),
        eos_token_id=pipe.tokenizer.eos_token_id
    )

    generated_text = outputs[0]['generated_text']
    result = generated_text[len(prompt):].strip()


    restored_reviews.append(result)
    
submission = pd.read_csv('./drive/MyDrive/data_set/open/sample_submission.csv', encoding = 'utf-8-sig')
submission['output'] = restored_reviews
submission.to_csv('./baseline_submission.csv', index = False, encoding = 'utf-8-sig')

gemma 7b 모델을 4비트 양자화를 사용하여 추론하는 코드였습니다.

구글 코랩 무료 버전을 사용하니 거의 2시간을 추론과정에서 사용하더니 OOM이 발생하였습니다...cpu 메모리도 사용하게 수정해서 다시 실행해도 똑같이 OOM이 발생하여 이번 기회에 클라우드 환경에서 코드를 실행하고 모델을 파인튜닝 해보도록 하였습니다. 비용이 너무 비싸서 고민하다가 "elice cloud"가 비용이 저렴하고 무료 크레딧을 제공하는걸 보고 사용해보게되었습니다.

가입을하고 클라우드를 사용하려고할때 위와같이 기관 정보를 입력하라고 나오는데 크게 의미는 없고 그냥 도메인 정도라고 생각하시면 될 것 같습니다.

이벤트중인지 결제 수단을 등록하면 무료 크레딧을 제공해줘서 좋았습니다. 그럼 이제 본격적으로 인스턴스를 생성하고 GPU를 활용해 보도록 하겠습니다.

인스턴스가 여러 유형이 있는데 코랩 무료 버전보다는 gpu 메모리의 양이 많으면서도 최소한의 비용을 사용하고자 "G-NAHPM-20" 인스턴스를 선택하였습니다.

환경은 주피터 노트북으로 하였고 크게 설정할 것 없이 유형과 환경을 지정하고 기다리면 금방 인스턴스가 생성되고 이용할 수 있어서 굉장히 편리했습니다.

상단 크레딧이 시간 단위가 아니라 실시간으로 차감 돼서 지출이 직관적으로 보여서 좋았습니다.

인스턴스가 잘 생성되었는지 Gpu 메모리를 확인해보았고, 잘 만들어진 모습을 볼 수 있었습니다. 이제 기존 코랩에서 OOM이 발생했던 샘플코드를 다시 실행해 보았습니다. 그런데 샘플 코드를 실행하기에 GPU 메모리가 부족해서 다른 에러가 발생했어. 40GB의 인스턴스를 다시 생성해서 진행하였습니다.

코드 시작 시간이고,

추론이 모두 끝났을때 시간입니다. 약 5시간 정도가 소모됐고,

GPU 메모리를 30GB정도 사용한 모습입니다.

test 데이터셋 추론 결과를 제출하니 샘플 코드답게 현저히 낮은 스코어를 볼 수 있었습니다. 이제 여러 기법들을 활용해 추론 시간을 단축시키고 추론 성능을 상승시켜보도록 하겠습니다.

참고자료

https://elice.io/ko

https://dacon.io/competitions/official/236446/leaderboard

[DeepLearning] 언어 모델 최적화 개념 정리

dong_seok — Fri, 14 Feb 2025 21:06:32 +0900

언어 모델을 효과적으로 활용하려면 모델을 최적화하고 경량화하는 과정이 중요합니다. 이번 포스트에서는 모델의 추론 과정, KV 캐시, 양자화, 지식 증류 등의 개념을 직관적으로 정리해보겠습니다.

1. 언어 모델이 텍스트를 생성하는 방식

1.1 언어 모델이 텍스트 생성을 마치는 이유

EOS(End of Sequence) 토큰 생성
문장이 끝났음을 알리는 특수 토큰을 생성할 경우 텍스트 생성을 종료합니다.
최대 길이 도달
사용자가 설정한 최대 토큰 길이에 도달하면 텍스트 생성을 종료합니다.

1.2 자기 회귀적(Auto-Regressive) 모델

언어 모델은 입력된 텍스트를 기반으로 다음 토큰을 하나씩 순차적으로 예측합니다. 즉, 이전에 생성된 토큰들을 다시 모델 입력으로 넣어 다음 토큰을 예측하는 과정을 반복합니다.

2. 중복 연산을 줄이는 KV 캐시

2.1 KV(Key-Value) 캐시란?

셀프 어텐션(self-attention) 과정에서 이미 계산된 키(Key)와 값(Value)을 저장해두었다가 재활용함으로써 중복 연산을 줄이는 기법입니다. 이를 통해 모델 추론 시 연산 비용과 시간을 절감할 수 있습니다.

2.2 KV 캐시의 메모리 사용량 예시

계산식 예시:
2(fp16) × 2(키와 값) × 레이어 수 × 토큰 임베딩 차원 × 최대 시퀀스 길이 × 배치 크기
예: Llama-2 13B 모델 기준
- 배치 크기 1당 약 3.125GB 메모리 사용
- NVIDIA A100(40GB)에서 최대 14GB까지 KV 캐시 활용 가능 → 배치 크기 최대 4
- 더 큰 배치 크기를 처리하려면 모델 또는 KV 캐시를 효율적으로 줄이는 추가 최적화가 필요합니다.

3. GPU 구조와 최적의 배치 크기

3.1 효율적인 서빙을 위한 주요 지표

비용: GPU 등 하드웨어 자원 사용 효율
처리량(Throughput): 일정 시간(초)당 처리 가능한 요청 수
지연 시간(Latency): 하나의 토큰을 생성하는 데 걸리는 시간

3.2 GPU 내부 구조

SM(Stream Multiprocessors)
Compute(연산)을 수행하는 부분과, 계산 할 값을 저장하는 SRAM으로 구성
SRAM(Static RAM)
L1 캐시 또는 공유 메모리 역할, 용량이 적음
HBM(High Bandwidth Memory)
대규모 데이터를 저장하는 고대역폭 메모리

**3.3 최적의 배치 크기(B*)**

배치 크기가 작으면 모델 파라미터 이동(메모리 I/O)에 시간이 많이 들고, 연산 자원 낭비가 발생합니다.
배치 크기가 너무 크면 연산 시간이 길어져 전체 지연 시간이 늘어납니다.
최적 배치 크기 공식 예시:
B* = 하드웨어 연산 속도 / (2 × 메모리 대역폭)
- A100 GPU 기준 약 102 정도가 최적 배치 크기로 추정
- 그러나 Llama-2 13B 모델은 실제 배치 크기가 4 정도로 제한 → 추가적인 모델 및 메모리 최적화가 요구됩니다.

4. KV 캐시 메모리 줄이기

4.1 효율적인 어텐션 방식

멀티 쿼리 어텐션(Multi-Query Attention)
모든 쿼리 토큰이 하나의 키와 값을 공유해 메모리를 절약하는 방식입니다.
그룹 쿼리 어텐션(Group Query Attention)
멀티 헤드 어텐션과 멀티 쿼리 어텐션의 절충안으로, 여러 쿼리를 그룹으로 묶어 키/값을 공유함으로써 메모리 사용량과 성능 간의 균형을 유지합니다.

5. 양자화(Quantization)로 모델 크기 줄이기

양자화란 모델의 가중치와 연산을 정수 기반의 낮은 정밀도로 표현하여 메모리를 절감하고 추론 속도를 높이는 방법입니다.

5.1 비츠앤바이츠 (BitsAndBytes)

8비트 행렬 연산
이상치가 포함된 열은 16비트로 유지하고, 정상 범위 값들은 8비트로 양자화하여 연산합니다.
4비트 정규 분포 양자화(QLoRA)
보다 높은 수준의 메모리 절감 효과를 기대할 수 있는 방식입니다.

5.2 GPTQ (GPT Quantization)

양자화 전후 모델 예측값의 차이를 최소화하도록 모델 파라미터를 조정하는 기법
예: 175B 규모 모델 양자화에 A100 GPU로 약 4시간 소요

5.3 AWQ (Activation-aware Weight Quantization)

모델의 모든 파라미터가 동일하게 중요하지 않다는 점을 고려하여, 활성화 값(Activation Magnitude)이 큰 채널의 파라미터를 더 중요하게 반영
스케일러(Scaler)를 적용해 양자화 시 발생할 수 있는 정밀도 손실을 보완할 수 있습니다.

6. 지식 증류(Knowledge Distillation)

지식 증류는 성능이 높은 대형 모델(Teacher Model)의 출력을 작은 모델(Student Model)에 학습시켜 성능을 향상하는 방법입니다. 작은 모델도 선생 모델이 가진 지식을 효율적으로 흡수할 수 있어, 파라미터 수는 적어도 성능을 높게 유지할 수 있습니다.

마무리

이상으로 언어 모델을 경량화하고 최적화하는 주요 방법들을 간략히 살펴보았습니다. 실제 환경에서 KV 캐시를 활용하고, 배치 크기를 최적화하며, 양자화와 지식 증류 같은 기술을 적절히 조합하면 더 적은 자원으로도 빠르고 효율적인 모델 서빙이 가능해집니다.

KV 캐시 최적화
배치 크기 조절
양자화를 통한 모델 축소
지식 증류 기반 압축

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

https://www.youtube.com/watch?v=gMOAud7hZg4&t=1980s

[DeepLearning] 용어 정리

dong_seok — Wed, 12 Feb 2025 23:31:39 +0900

공부하면서 생소한 용어나 원활한 플로우 이해를 돕기 위한 포스팅 공간을 마련하였습니다. 계속 수정해가면서 내용이 추가될 예정입니다.

파라미터(Parameter)

모델의 파라미터는 머신러닝 모델이 학습을 통해 조정하는 값들로, 모델의 예측 성능을 결정하는 중요한 요소입니다. 파라미터는 모델의 구조에 따라 다르며, 주로 가중치(weights)와 편향(biases)으로 구성됩니다.

가중치(Weights)
- 입력 데이터의 각 특징(feature)에 곱해지는 값입니다. 가중치는 모델이 입력 데이터의 중요도를 학습하는 데 사용됩니다.
편향(Biases)
- 모델의 출력에 더해지는 상수 값입니다. 편향은 모델이 데이터를 더 잘 맞추기 위해 조정됩니다.

예시: 선형 회귀 모델

[ y = w_1 x_1 + w_2 x_2 + b ]

( w_1 )과 ( w_2 )는 가중치 파라미터입니다.
( b )는 편향 파라미터입니다.
( x_1 )과 ( x_2 )는 입력 데이터의 특징입니다.
( y )는 모델의 출력입니다.

그래디언트(Gradient)

그래디언트는 함수의 기울기를 나타내는 벡터입니다. 머신러닝에서 그래디언트는 손실 함수의 출력이 모델의 각 파라미터에 대해 얼마나 변화하는지를 나타냅니다. 즉, 그래디언트는 손실 함수의 변화율을 나타내며, 이를 통해 모델의 파라미터를 업데이트하여 손실을 최소화할 수 있습니다.

학습률(Learning Rate)

그래디언트의 크기를 조절하는 중요한 하이퍼파라미터입니다. 학습률은 그래디언트를 얼마나 크게 적용할지를 결정합니다. 높은 학습률은 빠른 학습을 가능하게 하지만, 불안정할 수 있습니다. 반대로, 낮은 학습률은 안정적인 학습을 가능하게 하지만, 느릴 수 있습니다.

손실(Loss)

모델의 예측값과 실제 레이블간의 차이를 의미합니다. 손실 값이 작을수록 모델의 예측이 실제 값에 가까워진다는 의미입니다.

손실 함수(Loss Function)

모델의 예측값과 실제 레이블 간의 차이를 수치화하는 함수입니다. 손실 함수는 모델이 얼마나 잘 예측하고 있는지를 평가하는 데 사용됩니다. 손실 함수의 출력은 손실 값입니다. 손실 함수의 예시는 다음과 같습니다.

평균 제곱 오차(MSE, Mean Squared Error)
- 회귀 문제에서 자주 사용됩니다. 예측값과 실제 값의 차이를 제곱한 후 평균을 구합니다.
교차 엔트로피 손실(Cross-Entropy Loss)
- 분류 문제에서 자주 사용됩니다. 예측 확률 분포와 실제 레이블 간의 차이를 계산합니다.

옵티마이저(Optimizer)

step() 메서드를 활용해서 역전파 결과를 바탕으로 모델의 파라미터를 업데이트합니다.

역전파(Backpropagation)

역전파는 신경망의 학습 과정에서 그래디언트를 계산하는 알고리즘입니다. 역전파는 다음과 같은 단계로 이루어집니다:

순전파(Forward Pass): 입력 데이터를 모델에 통과시켜 예측값을 계산합니다.
손실 계산(Loss Calculation): 예측값과 실제 레이블 간의 차이를 통해 손실을 계산합니다.
역전파(Backward Pass): 손실을 통해 그래디언트를 계산합니다. 이 과정에서 체인 룰(chain rule)을 사용하여 각 파라미터에 대한 그래디언트를 계산합니다.
파라미터 업데이트(Parameter Update): 옵티마이저를 사용하여 그래디언트를 기반으로 모델의 파라미터를 업데이트합니다.

역전파 기반 모델 업데이트 원리

역전파를 통해 계산된 그래디언트를 사용하여 모델의 파라미터를 업데이트하는 과정은 다음과 같습니다:

순전파(Forward Pass): 입력 데이터를 모델에 통과시켜 예측값을 계산합니다.
손실 계산(Loss Calculation): 예측값과 실제 레이블 간의 차이를 통해 손실을 계산합니다.
역전파(Backward Pass): 손실을 통해 그래디언트를 계산합니다.
그래디언트 초기화(Gradient Zeroing): 옵티마이저의 zero_grad() 메서드를 호출하여 이전 배치에서 계산된 그래디언트를 초기화합니다.
그래디언트 계산(Gradient Calculation): 손실의 그래디언트를 계산하여 각 파라미터에 대한 변화율을 구합니다.
파라미터 업데이트(Parameter Update): 옵티마이저의 step() 메서드를 호출하여 그래디언트를 기반으로 모델의 파라미터를 업데이트합니다.

[DeepLearning] 제목 기반 카테고리 예측 모델 개발

dong_seok — Sun, 9 Feb 2025 00:24:36 +0900

본 내용은 하단 참고자료에 작성된 책에 대한 내용을 기반으로 다시한번 정리한 내용입니다.

예제를 통해 연합뉴스 기사의 제목을 바탕으로 카테고리를 예측하는 딥러닝 모델을 개발하는 과정을 정리하였습니다. 이를 위해 데이터셋 로드부터 모델 학습 및 평가까지의 전체 과정을 단계별로 설명하며, 주요 개념과 코드 실행 결과를 함께 살펴보도록 하겠습니다.

1. 모델 학습에 사용할 연합뉴스 데이터셋 다운로드

모델 학습을 위해 KLUE 데이터셋의 YNAT 서브셋을 사용합니다. datasets 라이브러리의 load_dataset 함수를 이용하여 데이터를 로드합니다.

from datasets import load_dataset
klue_tc_train = load_dataset('klue', 'ynat', split='train')
klue_tc_eval = load_dataset('klue', 'ynat', split='validation')

데이터를 출력해 보면 다음과 같은 구조를 확인할 수 있습니다.

# klue_tc_train
Dataset({
    features: ['guid', 'title', 'label', 'url', 'date'],
    num_rows: 45678
})

# klue_tc_train[0]
{'guid': 'ynat-v1_train_00000',
 'title': '유튜브 내달 2일까지 크리에이터 지원 공간 운영',
 'label': 3,
 'url': 'https://news.naver.com/main/read.nhn?mode=LS2D&mid=shm&sid1=105&sid2=227&oid=001&aid=0008508947',
 'date': '2016.06.30. 오전 10:36'}

각 샘플은 기사 제목(title), 카테고리(label), 기사 링크(url), 날짜(date) 등의 정보를 포함하고 있습니다. label 값은 숫자로 되어 있어 어떤 카테고리에 해당하는지 직관적으로 이해하기 어려우므로, 카테고리명을 확인해 보겠습니다.

# klue_tc_train.features['label'].names
['IT과학', '경제', '사회', '생활문화', '세계', '스포츠', '정치']

2. 불필요한 컬럼 제거

모델 학습에 불필요한 컬럼(guid, url, date)을 제거하고, 필요한 컬럼(title, label)만 남기도록 하겠습니다.

klue_tc_train = klue_tc_train.remove_columns(['guid', 'url', 'date'])
klue_tc_eval = klue_tc_eval.remove_columns(['guid', 'url', 'date'])

# klue_tc_train
Dataset({
     features: ['title', 'label'],
     num_rows: 45678
})

3. 카테고리를 문자로 표기한 label_str 컬럼 추가

필요한 컬럼들을 남겨놓았으나, label이 아직 숫자라 가독성이 떨어진다는 단점이 있습니다. 카테고리를 확인하기 쉽도록 새롭게 label_str 컬럼을 추가해주겠습니다.

# klue_tc_train.features['label']
ClassLabel(names=['IT과학', '경제', '사회', '생활문화', '세계', '스포츠', '정치'], id=None)

klue_tc_label = klue_tc_train.features['label']

def make_str_label(batch):
  batch['label_str'] = klue_tc_label.int2str(batch['label'])
  return batch

klue_tc_train = klue_tc_train.map(make_str_label, batched=True, batch_size=1000)

# klue_tc_train[0]
{'title': '유튜브 내달 2일까지 크리에이터 지원 공간 운영', 'label': 3, 'label_str': '생활문화'}

klue_tc_train.features['label'] 을 출력해보면 ClassLabel 객체로 이루어진걸 볼 수 있습니다. 해당 객체는 숫자를 입력하면 해당 숫자에 맵핑된 카테고리를 반환해주는 int2str() 함수를 지니고 있습니다. 그리고 데이터셋의 요소별로 함수를 실행시켜주는 map 함수를 이용해서 batch_size씩 make_str_label을 실행해서 데이터 요소별로 label_str 컬럼을 만들어주었습니다.

4. 학습/검증/테스트 데이터셋 분할

빠른 실습 진행을 위해 학습 데이터셋을 부분적으로 추출하고 학습이 잘 되고 있는지 확인할 검증 데이터와 성능 확인에 사용할 테스트 데이터는 검증 데이터셋에서 각각 추출하여 사용하였습니다.

train_dataset = klue_tc_train.train_test_split(test_size=10000, shuffle=True, seed=42)['test']
dataset = klue_tc_eval.train_test_split(test_size=1000, shuffle=True, seed=42)
test_dataset = dataset['test']
valid_dataset = dataset['train'].train_test_split(test_size=1000, shuffle=True, seed=42)['test']

train_test_split 메서드를 사용하면 입력한 test_size or train_size 값을 기준으로 학습 데이터셋과 테스트 데이터셋을 분리해줍니다.

shuffle는 데이터를 섞어서 분할한다는 의미를 지니고 있습니다.

train_dataset = klue_tc_train.train_test_split(test_size=10000, shuffle=True, seed=42)

# train_dataset
DatasetDict({
    train: Dataset({
        features: ['guid', 'title', 'label', 'url', 'date'],
        num_rows: 35678
    })
    test: Dataset({
        features: ['guid', 'title', 'label', 'url', 'date'],
        num_rows: 10000
    })
})

위에서 확인했던 전체 데이터수 45678개에서 명시한 test_size만큼 test 데이터셋이 생기고 나머지는 train 데이터셋으로 생성된 모습을 볼 수 있습니다. 테스트 데이터와 검증 데이터는 서로 다른 데이터를 사용해야하기 때문에 klue_tc_eval 데이터셋에서 1차적으로 train_test_split 메서드를 사용한 dataset의 test 데이터셋을 테스트 데이터로 이용했고, 남은 train 데이터셋에서 한번 더 train_test_split 메서드를 활용해 검증 데이터를 생성한 모습을 볼 수 있습니다.

5. Trainer를 사용한 학습

이제 모든 데이터셋을 준비하였으니 모델을 학습 시키도록 하겠습니다.

import torch
import numpy as np
from transformers import (
    Trainer,
    TrainingArguments,
    AutoModelForSequenceClassification,
    AutoTokenizer
)

def tokenize_function(examples):
    return tokenizer(examples["title"], padding="max_length", truncation=True)

model_id = "klue/roberta-base"
model = AutoModelForSequenceClassification.from_pretrained(model_id, num_labels=len(train_dataset.features['label'].names))
tokenizer = AutoTokenizer.from_pretrained(model_id)

train_dataset = train_dataset.map(tokenize_function, batched=True)
valid_dataset = valid_dataset.map(tokenize_function, batched=True)
test_dataset = test_dataset.map(tokenize_function, batched=True)

klue/roberta-base는 바디만 있는 모델인데, 이를 AutoModelForSequenceClassification로 불러오면 분류 헤드 부분이 랜덤으로 초기화됩니다. 따라서 분류 헤드의 분류 클래스 수를 지정하기 위해 num_labels에 데이터셋의 레이블 수를 지정해줬습니다.

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=1,
    per_device_train_batch_size=8,
    per_device_eval_batch_size=8,
    evaluation_strategy="epoch",
    learning_rate=5e-5,
    push_to_hub=False
)

def compute_metrics(eval_pred):
    logits, labels = eval_pred
    predictions = np.argmax(logits, axis=-1)
    return {"accuracy": (predictions == labels).mean()}

여기 코드 부분이 이해가 잘 되지 않았기에 자세하게 설명하고 넘어가도록 하겠습니다. 코드별 상세 설명은 다음과 같습니다.

output_dir : 결과를 저장할 디렉토리 위치

num_train_epochs : 학습할 에포크 수

per_device_train_batch_size : 학습 시 디바이스당 배치 크기

per_device_eval_batch_size : 평가 시 디바이스당 배치 크기

,evaluation_strategy="epoch" : 평가 전략, 여기서는 매 에포크마다 평가

learning_rate=5e-5 : 학습률

push_to_hub=False : 모델을 Hugging Face Hub에 푸시할지 여부

eval_pred : 평가 예측값과 실제 레이블을 포함하는 튜플 (logits, labels)

logits : 모델의 예측값

labels : 실제 레이블

predictions : logits에서 가장 높은 값을 가진 인덱스를 예측값으로 반환

accuracy : 예측값과 실제 레이블이 일치하는 비율을 계산하여 반환

compute_metric 메서드가 이해가 잘 되지 않았는데, 해당 평가 메트릭이 한번만 실행된다고 하는데, 어떤식으로 평가가 이루어지는가 이해가 잘 되지 않았고, logits와 labels에 값이 어떤 형태로 어떤 값이 들어가는지 잘 모르겠었습니다. 하지만 다음 샘플 코드를 통해 완벽하게 이해했습니다.

import numpy as np


# 샘플 데이터 (검증 데이터셋 크기: 1000개, 클래스 수: 6개)
logits = np.random.rand(1000, 6)  # 1000개의 샘플, 6개의 클래스에 대한 예측값
labels = np.random.randint(0, 6, size=1000)  # 1000개의 실제 레이블 (0, 1, 2, 3, 4, 5 중 하나)

# logits
logits = np.array([
    [0.1, 0.2, 0.3, 0.4, 0.5, 0.6],  # 첫 번째 샘플의 예측값
    [0.6, 0.5, 0.4, 0.3, 0.2, 0.1],  # 두 번째 샘플의 예측값
    [0.1, 0.3, 0.5, 0.7, 0.9, 0.2],  # 세 번째 샘플의 예측값
    # ... (997개의 샘플 더)
])

# labels
labels = np.array([5, 0, 4, ...])  # 1000개의 실제 레이블

앞에서 지정했던 레이블 수를 기준으로 각 데이터 요소별로 어떤 레이블에 해당하는지 예측값을 지정하고 배열형태로 담습니다. 그 후 labels에 저장된 정답 레이블과 비교를 하여 mean 메소드를 통해 일치하면 True, 그렇지 않으면 False로 이루어진 불리언 배열에서 True의 비율을 계산하여 최종 정확도를 반환하는 구조였습니다. 결국 정확도는 예측값인 logits와 실제 레이블값인 labels의 일치 비율을 나타낸 것이었습니다. 최종적인 모델 학습 및 평가 코드는 다음과 같았습니다.

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=valid_dataset,
    tokenizer=tokenizer,
    compute_metrics=compute_metrics,
)

trainer.train()

trainer.evaluate(test_dataset)

아래와 같은 84%의 정확도를 얻을 수 있었습니다.

참고자료

LLM을 활용한 실전 AI 애플리케이션 개발 - 허정준

[RAG] gemini api error

dong_seok — Fri, 24 Jan 2025 22:29:39 +0900

이전에 google의 gemini model을 활용해 Rag를 구현한 코드가 있는데, 오랜만에 실행시켜보니 에러가 발생해서 원인과 해결과정을 정리해 보았습니다.

오류가 작성한 코드는 아래와 같았습니다.

from langchain.chains.query_constructor.base import (
    StructuredQueryOutputParser,
    get_query_constructor_prompt,
)
from langchain_openai import ChatOpenAI
from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(temperature=0, model="gemini-1.5-flash")

크게 어려운 내용은 없고, model을 지정하는 코드였습니다. 그런데 아래 에러가 발생했습니다.

GPT에게 물어보니, 이 에러는 Google Cloud Application Default Credentials (ADC)와 관련된 문제였습니다. 간단히 말해, Google Cloud API를 사용하려면 애플리케이션이 인증을 통해 권한을 가져야 하는데, 이를 위한 기본 인증 자격 증명(Default Credentials)이 설정되지 않았기 때문에 발생한 것입니다. ADC는 일반적으로 Google Cloud SDK를 통해 설정된 기본 자격 증명을 사용하는데 "gcloud auth application-default login" 명령어를 실행하지 않았거나, gcloud CLI가 제대로 설치되지 않은 경우 에러가 발생할 수 있다고해서 다 설치를 해주도록 하였습니다.

1. brew install --cask google-cloud-sdk
2. gcloud init
3. gcloud auth application-default login

위 명령을 순차적으로 실행해주니 ADC 관련 오류가 해결되 고 코드가 정상적으로 실행되었습니다. 그런데 다른 코드에서 또 에러가 발생하였습니다.

이 에러는 Google Generative AI API에 요청을 보낼 때 인증 토큰의 인증 스코프(authentication scope)가 불충분하기 때문에 발생한 것이었습니다. 찾아보니 Google Cloud는 프로젝트 단위로 리소스와 API 사용을 관리하기 때문에, Google Gemini API를 사용하려면 Google Cloud 프로젝트를 반드시 생성하고 지정해줘야했습니다. 현재 제가 지정한 프로젝트가 있는지 "gcloud config list"로 확인해보았고 지정된 프로젝트가 없는걸 확인할 수 있었습니다.

따라서 우선 프로젝트를 지정해주었습니다.

gcloud config set project [PROJECT_ID]

그리고 다시 확인해보았습니다.

프로젝트가 잘 지정된 모습을 볼 수 있었습니다. 하지만 이후에도 같은 에러가 발생했고 몇가지 추가 작업을 거쳐야했습니다.

1. Google Cloud Consol 접속 및 로그인

2. 지정한 프로젝트에 접근하여 API 및 서비스 -> 라이브러리 -> Generative Language API 활성화

3. 사용자 인증 정보에서 제한사항 목록에 "Generative Language API"를 포함

4. 서비스 계정 생성 및 json 키 발급

5. json key 저장 및 환경 변수 설정

export GOOGLE_APPLICATION_CREDENTIALS="{경로}"

혹시 몰라 .env 파일에도 위의 경로르 지정해줍니다. 그 후, "echo $GOOGLE_APPLICATION_CREDENTIALS" 명령어로 json key 파일 경로가 정상 출력되는걸 확인하고 코드를 재실행해주면, 정상적으로 gemini api 가 호출 되는걸 볼 수 있습니다.

[AWS] s3에 이미지 업로드

dong_seok — Fri, 3 Jan 2025 20:02:29 +0900

1. 이미지 추출
2. 이미지 업로드
3. 이미지 클라이언트에게 전달

이전 포스팅에서 만들었던 s3를 활용해 자취방 이미지들을 s3에 업로드해서 사용해보도록 하겠습니다.

1. 이미지 추출

먼저 pdf에서 이미지를 추출해보도록하겠습니다. 전에 upstage의 document parser를 사용해봤었는데 이미지만 추출하는게 아니라 텍스트,이미지 등을 종류별로 추출해서 마크다운, html 형식으로 변환해주다보니 이미지 추출쪽에서는 성능이 부족한 상황을 경험했습니다. 따라서 이번엔 이미지 추출만을 목적으로 하는 라이브러리를 사용해서 성능에 중점을 맞추고 진행해보았습니다.

1 ) PyMuPDF

PyMuPDF 는 PDF에 포함된 원본 이미지 파일을 별도의 변환 없이 추출합니다. 변환 과정이 없기 때문에 속도와 품질 모두 우수합니다.

import fitz  # PyMuPDF
import os

def extract_images_from_pdf(pdf_path, output_dir):
    # PDF 열기
    pdf_document = fitz.open(pdf_path)
    os.makedirs(output_dir, exist_ok=True)
    image_paths = []

    for page_num in range(len(pdf_document)):
        page = pdf_document[page_num]
        images = page.get_images(full=True)  # 이미지 정보 가져오기

        for img_index, img in enumerate(images):
            xref = img[0]  # 이미지 xref 값
            base_image = pdf_document.extract_image(xref)  # 이미지 추출
            image_bytes = base_image["image"]
            image_ext = base_image["ext"]  # 이미지 확장자 (png, jpeg 등)
            image_path = os.path.join(output_dir, f"{page_num + 1}_{img_index + 1}.{image_ext}")

            # 이미지 파일 저장
            with open(image_path, "wb") as image_file:
                image_file.write(image_bytes)
            image_paths.append(image_path)
    
    pdf_document.close()
    return image_paths

# PDF 경로와 이미지 저장 디렉토리
pdf_path = './data/pdf_data/back_gate.pdf'
output_dir = './data/images/back_gate'

# 이미지 추출
images = extract_images_from_pdf(pdf_path, output_dir)
print(f"Extracted images: {images}")

테스트용으로 후문에 위치한 자취방들을 대상으로 이미지 추출을 진행해주었습니다. 저장할 이미지명은 "(page_num)_(img_index)" 형식으로 지정했습니다. 후에 page_num으로 이미지를 구분해서 s3에 page_num별로 폴더를 만드려고 위와 같은 형식으로 이미지를 저장했습니다.

상당히 괜찮은 화질로 이미지가 추출된걸 확인하고 이제 s3에 이미지를 저장하는 작업을 진행하였습니다.

2. 이미지 업로드

import boto3
import os
import re

# S3 클라이언트 생성
s3 = boto3.client('s3')
BUCKET_NAME = '{버킷명}'
BASE_FOLDER = 'rooms/'  # S3 내 기본 폴더

def upload_images_to_s3(folder_path):
    # 폴더 내 파일 가져오기
    files = os.listdir(folder_path)

    # 정규식으로 파일 이름에서 room_id와 이미지 번호 추출
    pattern = r"(\d+)_(\d+)\.(\w+)"  # ex: 1_1.jpg, 2_2.png

    for file_name in files:
        match = re.match(pattern, file_name)
        if match:
            room_id, img_num, extension = match.groups()
            room_folder = f"{BASE_FOLDER}{room_id}/"  # S3의 room_id 폴더 경로
            s3_key = f"{room_folder}{file_name}"  # S3에 업로드할 전체 경로

            # 로컬 파일 경로
            local_path = os.path.join(folder_path, file_name)

            # S3에 파일 업로드
            s3.upload_file(local_path, BUCKET_NAME, s3_key)
            print(f"Uploaded {file_name} to s3://{BUCKET_NAME}/{s3_key}")

# 로컬 이미지 폴더 경로
local_folder_path = './data/images/back_gate'

# 이미지 업로드 실행
upload_images_to_s3(local_folder_path)

앞에서 말했던 대로 이미지명에서 room_id로 사용할 이름을 정규표현식으로 추출해서 s3에 room_id 폴더를 만들고 내부에 이미지들을 저장해주었습니다.

정상적으로 이미지가 업로드 된 모습입니다. 이제 업로드된 이미지가 잘 가져와지는지 테스트 해보았습니다.

import boto3

# S3 클라이언트 생성
s3 = boto3.client('s3')
BUCKET_NAME = '{버킷명}'
BASE_FOLDER = 'rooms/'  # S3 내 기본 폴더 경로

def list_images_in_room(bucket_name, room_id):
    folder_prefix = f"{BASE_FOLDER}{room_id}/"  # room_id에 해당하는 폴더 경로
    images = []

    # S3에서 특정 폴더의 객체 리스트 가져오기
    response = s3.list_objects_v2(Bucket=bucket_name, Prefix=folder_prefix)

    # 객체 리스트에서 파일 경로만 추출
    if 'Contents' in response:
        for obj in response['Contents']:
            images.append(obj['Key'])  # S3 객체 키 (파일 경로)

    return images

# 예시: room_id가 1인 경우
room_id = '1'
images = list_images_in_room(BUCKET_NAME, room_id)
print(f"Images in room {room_id}: {images}")

1번 room_id에 해당하는 이미지들을 가져오는 샘플 코드를 작성해서 실행해보았고 아래 에러가 발생했습니다.

이 에러는 AWS IAM 정책이 S3 버킷에 대해 s3:ListBucket 액션을 허용하지 않아서 발생하는 문제입니다. 현재 사용 중인 IAM 사용자 또는 역할에게 s3:ListBucket 권한이 필요한 것 이었습니다. 이를 해결해주기 위해 s3:ListBucket 권한을 부여해주도록 하겠습니다.

"AmazonS3FullAccess" 를 추가해서 s3 에 대한 모든 요청을 허용하도록 하였습니다.

코드를 다시 실행해보니 정상적으로 이미지가 가져와지는 모습을 볼 수 있었습니다.

3. 이미지 클라이언트에게 전달

지정한 room_id에 맞는 이미지들을 추출할 수 있지만 위의 형태로는 클라이언트에게 이미지를 보여줄 수 없습니다. 클라이언트에서 room_id로 요청이 들어오면 해당 이미지들에 대한 객체 URL을 json format으로 바꿔서 클라이언트에게 전달해 주도록 하겠습니다.

객체 URL은 "https://<bucket-name>.s3.<region>.amazonaws.com/<object-key>" 의 형태를 지니고 있습니다.

import boto3
import json

# S3 클라이언트 생성
s3 = boto3.client('s3')
BUCKET_NAME = '{버킷명}'
BASE_FOLDER = 'rooms/'  # S3 내 기본 폴더 경로
REGION = 'ap-northeast-2'  # S3 버킷이 위치한 AWS 리전

def list_images_in_room(bucket_name, room_id):
    folder_prefix = f"{BASE_FOLDER}{room_id}/"  # room_id에 해당하는 폴더 경로
    images = []

    # S3에서 특정 폴더의 객체 리스트 가져오기
    response = s3.list_objects_v2(Bucket=bucket_name, Prefix=folder_prefix)

    # 객체 리스트에서 파일 경로만 추출
    if 'Contents' in response:
        for obj in response['Contents']:
            if not obj['Key'].endswith('/'):  # 폴더 자체는 제외
                images.append(obj['Key'])  # S3 객체 키 (파일 경로)

    return images

def generate_image_urls(bucket_name, region, keys):
    urls = [
        f"https://{bucket_name}.s3.{region}.amazonaws.com/{key}"
        for key in keys
    ]
    return urls

# 예시: room_id가 1인 경우
room_id = '1'
keys = list_images_in_room(BUCKET_NAME, room_id)

# S3 객체 키를 URL로 변환
image_urls = generate_image_urls(BUCKET_NAME, REGION, keys) if keys else []

# JSON 응답 생성
response_data = {
    "room_id": room_id,
    "images": image_urls
}
response_json = json.dumps(response_data, indent=4)  # JSON 문자열로 변환 (보기 좋게 들여쓰기 포함)

# 클라이언트에게 전송 (예: 출력)
print(response_json)

따라서 위와 같이 코드를 작성해서 image가 있는 room_id 요청에 대해서는 적절한 이미지들을 json 으로 전달하고, 이미지가 없는 경우 비어있는 images를 전달하게끔 코드를 작성하였습니다.

[AWS] s3

dong_seok — Fri, 3 Jan 2025 01:21:01 +0900

1. s3 용어
2. s3 버킷 생성

프로젝트 진행도중 이미지를 저장하고 관리해야할 일이 생겨서 AWS의 s3 시스템을 사용해보도록 하였습니다.

1. s3 용어

1) 버킷

객체를 저장하는 공간

2) 객체

이미지나 동영상 같은 파일

3) 버킷명

유일한 이름

4) 객체 키

객체 식별자 (모든 객체가 하나씩 가짐)

2. s3 버킷 생성

본격적으로 aws 콘솔에 접속해서 버킷을 생성해보도록 하겠습니다.

s3 서비스는 사용한만큼 요금이 지불되기 때문에 현재 사용중인 프리티어 기준에 맞게 이미지 용량을 사용할 생각입니다.

버킷 이름 규칙에 맞게 이름을 지정하고 넘어가줍니다.

다른 값들은 추가로 건들이지않고 테스트를 위해 태그를 하나 생성해주었습니다.

버킷이 잘 만들어진 모습을 볼 수 있습니다. 이제 버킷을 들어가서 이미지를 업로드 해주었습니다.

이미지 업로드는 잘 됐지만 url로 들어가보면 위와 같은 에러가 발생하는 모습이었습니다. 원인은 버킷 정책을 지정해주지않아서 이미지를 읽어오는 과정에서 문제가 생긴 것 이었습니다.

버킷 정책에 들어가서 편집을 선택합니다.

화면과 같이 값을 입력해서 json 형태의 정책을 생성했습니다. 여기서 주의할점은 Resource의 나의 버킷 ARN 뒤에 (/*)을 꼭 붙혀줘야한다는 것입니다. 그렇지 않으면 아래와같은 에러가 발생합니다.

이제 잘 생성된 json 형태의 정책을 복사하여 붙혀넣었습니다.

이번에 다른 에러가 발생했습니다. 찾아보니 처음 버킷을 생성할때 퍼빌릭 액세스를 모두 차단하면서 생긴 에러였습니다. 역할을 지정하던가 다른 방법을 사용해서 퍼블릭 액세스 차단을 유지할 수 있지만 우선 지금은 퍼블릭 액세스 차단을 모두 해제하고 넘어가도록 하겠습니다.

기존 차단 되어있던부분을 모두 해제해 주었습니다.

정책이 정상적으로 편집된 모습을 볼 수 있었습니다. 이제 이미지 링크를 타고 들어가면 s3 에 저장된 이미지를 볼 수 있습니다.

참고자료

https://growth-coder.tistory.com/114

[Backend] Access Token & Refresh Token

dong_seok — Thu, 12 Dec 2024 18:33:17 +0900

1. Access Token과 Refresh Token의 필요성
2. JWT 인증 체계 설계
3. 결론

이전 블로그에서 JWT에 대해서 알아보았습니다. 그렇다면, 이러한 JWT가 일반적으로 많이 사용되는 곳이 어디일까?를 생각해보면 인증 체계였습니다. JWT인 Access Token과 Refresh Token을 만들고 이를 이용해 인증 체계를 구축한 과정에 대해 말씀드리도록 하겠습니다.

1. Access Token과 Refresh Token의 필요성

Access Token 하나만 가지고도 인증할 수 있지 않을까? 라는 생각이 들 수 있지만, 실제로는 하나의 토큰으로는 여러 문제점들이 발생할 수 있습니다. Access Token만 사용한다고 가정해보겠습니다. Payload에 사용자 정보를 담아 통신 간에 JWT를 사용할 것입니다. 서버는 전달받은 Access Token을 디코딩하고 저장된 Secret Key를 이용해 유효성을 검증함으로써 인증을 수행할 수 있습니다.

하지만, 만약 이 Access Token이 한번 탈취되었다고 가정해봅시다. 서버는 이 Access Token이 정상적인 클라이언트에서 온 것인지, 아니면 탈취된 악의적인 이용자로부터 온 것인지 구분할 수 없기 때문에 토큰을 무기한으로 갱신하게 될 것입니다. 이는 탈취된 토큰이 장기간 동안 악용될 수 있다는 것을 의미합니다. 또한, Access Token에 사용자 정보가 포함되어 있기 때문에, 탈취된 토큰을 통해 지속적으로 사용자 정보를 악의적으로 사용할 수 있습니다.

이러한 문제들을 해결하기 위해 등장한 것이 Refresh Token입니다. Refresh Token은 Access Token과 마찬가지로 JWT 형식을 사용하지만, 몇 가지 중요한 차이점이 있습니다.

	Access Token	Refresh Token
목적	인증이 필요한 요청을 처리하는 데 사용됩니다. 필요한 사용자 정보와 권한을 담고 있습니다.	Access Token을 재발급 받기 위해 사용됩니다. 불필요한 사용자 정보를 담지 않고, 오직 토큰 재발급에만 관여합니다.
일반적인 유효기간	30분~1시간	1주~2주

이처럼 Access Token과 Refresh Token을 함께 사용함으로써 보안을 강화하고, Access Token의 짧은 유효 기간 동안만 인증을 수행할 수 있습니다.

2. JWT 인증 체계 설계

1) 인증 체계 설계

제가 구성한 인증 체계 로직은 다음과 같습니다:

로그인 과정:
- 사용자가 ID와 비밀번호를 통해 정상적으로 로그인합니다.
- 서버는 회원 DB를 조회하여 사용자를 확인합니다.
- 로그인에 성공하면 서버는 Access Token과 Refresh Token을 생성하여 클라이언트에게 발급하고, Redis에 Refresh Token을 저장합니다.
토큰 저장:
- 클라이언트는 전달받은 토큰들을 안전한 로컬 저장소(예: Secure Storage)에 저장합니다.
인증 요청:
- 클라이언트는 인증이 필요한 API 요청 시마다 Access Token을 헤더에 담아 서버로 전송합니다.
Access Token 검증:
- 서버는 전달받은 Access Token을 검증하여 유효한 경우 요청에 알맞은 데이터를 응답합니다.
Access Token 만료 처리:
- 시간이 지나 Access Token이 만료되면, 클라이언트는 만료된 Access Token을 사용해 API 요청을 보냅니다.
- 서버는 만료된 Access Token을 검증하고, 만료되었다는 응답을 클라이언트에게 반환합니다.
토큰 갱신 요청:
- 클라이언트는 만료된 Access Token과 저장된 Refresh Token을 함께 헤더에 담아 Access Token 재발급 API를 호출합니다.
토큰 검증 및 재발급:
- 서버는 받은 Access Token이 변조되지 않았는지 검증합니다.
- Refresh Token을 Redis에 저장된 토큰과 비교하여 동일하고 유효기간이 지나지 않았다면, 새로운 Access Token과 Refresh Token을 발급하고 Redis에 업데이트합니다.
새 토큰 저장 및 재요청:
- 클라이언트는 새로 발급받은 토큰들을 다시 로컬 저장소에 저장하고, 새로운 Access Token을 사용해 원래의 API 요청을 재전송합니다.

2) 설계 과정

JWT를 이용한 인증 체계 구축은 Access Token과 Refresh Token을 사용하는 공통점이 있지만, 전달할 토큰의 종류, 저장 위치 등 여러 방식으로 구현할 수 있습니다. 제가 위와 같은 인증 체계를 구축하게 된 근거와 과정에서 겪었던 궁금증들에 대해 설명드리겠습니다.

(1) Access Token 만료 시 바로 재발급 가능 여부

클라이언트가 만료된 Access Token으로 API를 호출하면, 서버는 에러 코드를 반환한 뒤 클라이언트가 Refresh Token을 사용해 Access Token 갱신 API를 호출하도록 유도합니다. 그런데, 서버에서 바로 저장된 Refresh Token을 디코딩해 유저 정보를 확인한 뒤 Access Token을 재발급하면, 불필요한 API 호출을 줄일 수 있지 않을까?

-> 이 질문은 JWT에 대한 이해도 부족으로 생겼던 궁금증이라고 생각합니다. 이론적으로 가능하지만, 일반적인 구현 방식과는 다릅니다. 이유는 다음과 같습니다.

Payload 차이:
- Access Token의 Payload는 유저 정보(예: 권한, 사용자 ID 등)를 담는 경우가 많습니다.
- Refresh Token의 Payload는 보안성을 높이기 위해 최소한의 정보(예: 사용자 ID)만 담습니다.
서명 불일치:
- Access Token과 Refresh Token은 서로 다른 Payload를 가지며, 서명(Signature)도 각각 다릅니다.
- 서버는 Refresh Token으로 Access Token을 대체하려고 하면 서명 검증에서 실패하여 인증 오류가 발생합니다.

결론적으로, Refresh Token을 사용한 Access Token 갱신은 별도의 API 호출로 처리하는 것이 일반적이며, 이는 보안성과 구조적 일관성을 유지하기 위해 중요합니다.

(2) JWT 생성 시 Header 명시 여부

아래 코드에서 jwt.encode 호출 시 Header를 명시하지 않았습니다. 이런 경우 JWT가 정상적으로 생성되는가?

access_token = jwt.encode(
	access_token_payload, self.secret, algorithm=ALGORITHM
)

-> 처음 FastAPI에서 JWT를 인코딩하려고 할 때, 이론적으로 JWT를 생성할 때 Header, Payload, Signature 세 가지 요소를 명시해야 한다고 공부했습니다. 그러나 jwt.encode 함수에 Payload, Secret Key, Algorithm만 인자로 전달했는데도 JWT가 정상적으로 생성되는 것을 보고 혼동하게 되었습니다.

조사를 해보니, jwt.encode 메서드는 내부적으로 Header를 자동으로 생성하여 JWT 토큰에 포함시킵니다. 따라서, 코드에서 명시적으로 Header를 지정하지 않아도 algorithm 매개변수에 따라 기본 Header가 생성됩니다.

예를 들어, HS256 알고리즘을 사용할 경우 Header는 다음과 같이 자동으로 생성됩니다:

{
  "alg": "HS256",
  "typ": "JWT"
}

결론적으로, jwt.encode 함수는 Header를 자동으로 생성하고, 이 Header와 Payload를 Secret Key를 이용해 Signature로 만듭니다. 이 세 요소를 Base64로 인코딩하여 최종적인 JWT를 생성하게 됩니다. 이는 제가 이론적으로 공부한 내용과 일치하지만, encode 함수의 구현 차이로 인해 Header를 별도로 지정할 필요가 없다는 것을 알게 되었습니다.

(3) Refresh Token 없이 Access Token만 사용하는 경우의 문제점

Access Token의 유효성을 서버에서 Secret Key를 이용해 검증하면 데이터베이스 조회 없이도 인증이 가능합니다. 그렇다면 Refresh Token 없이 Access Token만으로 인증 체계를 구축해도 문제가 없지 않을까요? Refresh Token이 필요한 이유는 무엇인가요?

-> 이 질문 역시 JWT 이론에서 비롯된 오해였습니다. 처음에는 서버에 저장된 Secret Key로 토큰의 유효성을 검증하고, 유효하면 바로 새로운 Access Token을 발급하는 방식으로 생각했으나, 이는 여러 문제를 초래할 수 있습니다.

Access Token 탈취 위험:
- 사용자가 만료된 액세스 토큰으로 갱신 요청을 보내는 것과 탈취된 만료 액세스 토큰으로 갱신 요청을 보내는 것을 서버는 구분할 수가 없습니다. 즉, 탈취된 Access Token은 만료되기 전까지 악용될 수 있습니다.
- 만약 탈취된 Access Token으로 갱신 요청을 하면, 서버는 클라이언트와 공격자를 구분할 수 없어 무한 갱신 요청을 허용하게 됩니다.
Refresh Token의 역할:
- Access Token 갱신 시 반드시 Refresh Token을 사용하도록 설계하면, 탈취된 Access Token만으로는 갱신이 불가능합니다.
- Refresh Token은 클라이언트의 안전한 저장소에 보관되며, 상대적으로 탈취 가능성이 낮습니다.
세션 제어 가능:
- Refresh Token을 서버에서 관리하면, 특정 사용자 세션을 강제로 종료하거나 로그아웃 시 모든 세션을 무효화할 수 있습니다.
- 반면, Access Token만 사용하는 경우 서버에서 세션을 제어할 방법이 없습니다.

(4) 인증 요청 시 Access Token만 전송 vs Access Token과 Refresh Token 함께 전송

인증이 필요한 요청을 보낼 때 클라이언트에서 헤더에 Access Token만 담는 경우와 Refresh Token까지 함께 담아서 보내는 경우 중 어떤 방법이 옳을까?

-> 각각의 방법에는 장단점이 있어 고민이 많았으나, 저는 Access Token만 헤더에 담아 전송하는 방식을 선택했습니다. 이유는 다음과 같습니다:

보안성 강화:
- Refresh Token을 매 요청마다 전송하지 않음으로써, Refresh Token의 노출 위험을 줄였습니다.
네트워크 효율성:
- 일반적인 API 요청 시 Refresh Token을 포함하지 않아 네트워크 트래픽을 줄일 수 있습니다.
클라이언트 복잡성 감소:
- Refresh Token을 별도로 관리하여, 클라이언트 측에서 토큰 갱신 로직을 명확히 분리할 수 있습니다.
사용자 경험:
- Access Token이 만료되었을 때, 클라이언트가 자동으로 갱신 API를 호출하여 새로운 토큰을 받음으로써 사용자는 인증 과정의 복잡성을 느끼지 않습니다.

이러한 이유로, Access Token만을 사용하고, 만료 시 Refresh Token을 별도로 사용하는 방식이 보안과 효율성 면에서 더 적합하다고 판단했습니다.

(5) Refresh Token을 Redis에 저장하는 이유

왜 Refresh Token을 Redis에 저장하는 것이지?

->JWT 인증 체계에서 Refresh Token을 Redis에 저장하는 이유는 서버 부하를 줄이면서도 보안과 세션 관리를 효율적으로 유지하기 위함입니다. 자세한 이유는 다음과 같습니다:

고속 데이터 접근:
- Redis는 메모리 기반 저장소로, 데이터 읽기/쓰기가 매우 빠릅니다.
- Refresh Token의 조회와 갱신 작업을 빠르게 처리하여 서버 부하를 최소화할 수 있습니다.
효율적인 TTL 관리:
- Redis는 각 키에 대해 TTL(Time-To-Live)을 설정할 수 있어, Refresh Token의 만료를 자동으로 관리할 수 있습니다.
- 만료된 Refresh Token은 자동으로 삭제되므로, 추가적인 관리 작업이 필요 없습니다.
One-Time Token 방식 적용:
- Refresh Token을 갱신 요청 시마다 새로운 토큰으로 교체하고 기존 토큰을 삭제함으로써, Refresh Token의 재사용 공격을 방지할 수 있습니다.
- Redis는 이러한 갱신 과정을 빠르게 처리할 수 있어 서버 부하를 크게 줄일 수 있습니다.

이러한 이유로, Refresh Token을 Redis에 저장하는 방식은 보안성과 성능을 모두 만족시키며, 서버 부하를 효과적으로 관리할 수 있는 최적의 방법입니다.

결론

JWT 인증 체계는 Access Token과 Refresh Token을 함께 사용함으로써 보안성과 효율성을 동시에 높일 수 있습니다. Access Token은 짧은 유효 기간으로 인증을 수행하고, Refresh Token은 장기간 동안 안전하게 토큰을 갱신하는 역할을 합니다. 이를 통해 토큰 탈취 시의 위험을 줄이고, 사용자 세션을 효과적으로 관리할 수 있습니다.

Refresh Token을 Redis와 같은 서버 측 스토리지에 저장함으로써, 토큰의 유효성을 검증하고 보안을 강화할 수 있습니다. 이러한 인증 체계는 대규모 서비스나 보안이 중요한 애플리케이션에서 특히 유용하게 사용됩니다.

(추가 수정사항)

기존에 Refresh Token Rotation 방식으로 구현한 인증 로직을 팀원들과 검토하던 중, 한 가지 의견이 제시되었습니다.

의견 제시사항

"Refresh Token이 한 번 탈취되면, 이를 이용해 계속해서 Access Token과 Refresh Token을 새로 발급받을 수 있는 구조가 아닌가?"

이 의견에 동의하게 되었고, 인증 로직을 수정하기로 결정했습니다. 기존 방식에서는 Access Token이 만료될 때마다 Refresh Token을 함께 새롭게 발급했지만, 수정된 로직에서는 Access Token만 새롭게 발급하고, Refresh Token은 계속 재사용하도록 변경하였습니다.

이 과정에서 한 가지 우려되었던 점은, ""사용자가 앱을 정상적으로 사용하더라도 Refresh Token의 유효기간이 지나면 강제로 로그인을 다시 해야 하는 상황이 발생하지 않을까?"" 라는 부분이었습니다. 이를 해결하기 위해 앱 실행하면서 자동로그인할때 Access Token과 Refresh Token을 새롭게 발급하도록 로직을 보완하였습니다.

참고자료

https://inpa.tistory.com/entry/WEB-%F0%9F%93%9A-Access-Token-Refresh-Token-%EC%9B%90%EB%A6%AC-feat-JWT

[Backend] JWT

dong_seok — Wed, 11 Dec 2024 14:30:12 +0900

1. JWT (JSON Web Token)란?
2. 쿠키 기반 인증 vs JWT

1. JWT (JSON Web Token)란?

JWT는 Header, Payload, Signature로 구성된 토큰 기반 인증 방식입니다. 데이터를 Base64로 인코딩하고, 세 요소를 마침표(.)로 연결하여 하나의 토큰으로 만듭니다.

1 ) JWT 구조

(1) Header: 서명 알고리즘과 토큰 타입 정보를 포함.

예: {"alg": "HS256", "typ": "JWT"}

(2) Payload: 사용자 정보와 클레임(예: 만료 시간 exp, 사용자 ID sub) 등을 포함.

예: {"sub": "user123", "exp": 1700000000}

(3) Signature: Header + Payload를 서버의 Secret Key로 서명한 값.

예: HMACSHA256(Base64UrlEncode(Header) + "." + Base64UrlEncode(Payload), SecretKey)

-> 이 3가지 값들이 BAse64Url로 인코딩 되어 마침표(.)으로 연결함으로써 JWT가 구성

2) JWT 인증 원리

(1) 클라이언트가 서버로부터 JWT를 전달받아 저장.

(2) 클라이언트가 요청 시 JWT를 함께 전송.

(3) 서버는 전달받은 JWT의 Signature를 검증하여 토큰이 조작되지 않았음을 확인.

서명 알고리즘, Payload, Secret Key를 이용해 Signature를 생성하고, 전달받은 토큰의 Signature와 비교.
토큰 검증 과정에서 DB를 조회하지 않아도 되기 때문에 서버 부하를 줄일 수 있음

2. 쿠키 기반 인증 vs JWT

1) 쿠키 기반 인증

브라우저가 로그인을 시도하면 애플리케이션 서버는 DB를 조회해서 회원 유무 확인
회원 정보가 있다면 Session table에 어떤 사용자가 로그인했고 session id 라고 하는 임시 비밀번호를 발급
이를 서버가 다시 쿠키값으로 브라우저에게 응답
이 값은 브라우저에 저장되고 다음에 접속할때마다 서버에 저장됨.

단점

추가 조회 필요: Session ID만으로는 사용자의 세부 정보를 알 수 없어 추가적인 DB 조회가 필요.
서버 부하: 요청마다 Session Table 확인이 필요.
확장성 부족: 새로운 장치로 로그인 시 Session Table에 새로운 데이터가 추가되어 관리 부담 증가.

2) JWT

브라우저에서 로그인을 시도하면, 애플리케이션 서버는 데이터베이스를 조회하여 회원 유무를 확인
회원 정보가 존재하면, 서버는 JWT를 생성하여 브라우저로 전달
클라이언트는 전달받은 JWT를 쿠키나 로컬스토리지와 같은 저장소에 보관
클라이언트는 인증이 필요한 서비스 이용 시 저장된 JWT를 포함하여 서버에 요청
서버는 전달받은 JWT를 디코딩하여 Header, Payload, Signature 정보를 추출
서버는 Secret Key를 사용해 Header와 Payload로 새로운 Signature를 생성하고, 이를 JWT의 Signature와 비교합니다. Signature가 일치하고 JWT가 유효한 경우, 클라이언트의 요청에 필요한 응답을 반환

장점

1. 애플리케이션에 필요한 정보를 payload에 담아둘 수 있음

2. 로그인과정에서 한번만 DB에 접근하고 그 이후의 인증과정에서는 DB에 접근할 필요가 없음

-> 서버의 부담을 완화 할 수 있음

참고자료

https://www.youtube.com/watch?v=36lpDzQzVXs