아주 오랜만에 Github Pages 글을 작성하는 것 같다. 이번 글에는 최근에 내가 진행한 GitHub Pages 디자인 개선과 서버리스 구조로 변경한 작업을 정리해보려고 한다.

🛠️ Serverless...

원래는 백엔드를 하나 두어서, 일정과, Velog 데이터 및 Github 데이터를 가져오도록 구성을 해두었다. 그런데 AWS 프리티어로 구동 중이다 보니 관리도 너무 힘들고, 서버가 먹통이 되거나 이런 현상이 많았다. 그래서 과감하게 일정 페이지를 삭제하고 단순히 렌더링 타임에 Velog 및 Github 데이터를 호출하도록 바꾸었다. 구매해둔 DNS는 다른 프로젝트에서 사용할 예정이다.

📌 Velog 데이터 가져오기

GitHub 데이터는 단순히 내 계정의 정보와 public repo 정보를 가져오면 되므로, API를 호출하면 된다. 그런데 문제는 Velog 데이터를 가져오는 것이었다. Velog는 RSS로 가져오거나, GraphQL로 가져오는 방식 두개가 있는데, 상세한 정보를 가져오고 싶으면 GraphQL을 가져와야 한다. 나는 글의 태그들도 가져오기를 원해서 GraphQL 방식을 채택하였다. 그런데 Velog의 GraphQL은 브라우저 호출을 허용하지 않기에 다른 방법을 찾아야 했다.

나는 예전에 구성한 VelogSync 프로젝트로 내 Github repo에 Velog 글들을 자동 백업을 하고 있다.

관련글

• [Mini Project] Velog Backup 프로그램 만들기

따라서 해당 repo의 정보를 가져오는 방식으로 구성을 하였다. 간단하게 해결이되어서 다행이지만, 일단 시간당 60회 호출 제한이 있긴 해서, 완전하지는 않다. 이 부분은 나중에 개선하기로 하겠다.

디자인 개선

디자인 개선은 Codex CLI의 힘을 빌러서 진행했다. Codex CLI에 최근 트렌드에 맞춰서 디자인 개선을 진행하도록 프롬프팅을 하고 작업을 하였다.

Profile Page

Github Page

Velog Page

Codex CLI를 써보니 나같은 디자인 잼병이나 프론트에 익숙하지 않은 주니어 개발자 혹은 백엔드 개발자한테 매우 좋은 툴인 것 같다. 백엔드를 구현할 때도 사용을 하지만, 프론트를 구현할 때 강력한 기능을 제공하는 것 같다. 로그인 페이지나 이번에 구성한 프로필 혹은 기타 카드로 이루어진 매우 심플한 페이지를 구성할 때, 시간 단축과 세련된 디자인을 제시해준다. Codex CLI에 대해서는 따로 글로 작성해서 MCP 도구 세팅과 유용한 사용법을 정리할 생각이다.

😁 마무리

이렇게 서버리스로 바꾸고 디자인 개선을 진행해보니, 한결 마음이 편해진 것 같다. AWS도 빨리 정리해서 지금 진행중인 HippoBox 프로젝트에서 해당 DNS와 서버를 사용하도록 바꿔야 겠다.

Github Page choi-hyk.github.io

너무 오랜만에 Velog 글을 작성하는 것 같다. 거의 2개월 만에 작성하는 것 같은데, 바빠서 작성을 못한 것은 아니고, 뭔가 열정이 없어져서 미루다 보니 이렇게 된 것 같다.

그래도 최근에 개인 프로젝트를 하나 시작해서 해당 프로젝트에 대해서 글을 작성할 생각이다. 시작한 프로젝트는 HippoBox라는 이름의 프로젝트이다. 프로젝트 내용은 여러 AI 서비스에서 사용 가능한 지식 베이스 서비스를 구성하는 것이다.

프로젝트를 시작한 이유는 최신 개발 트렌드를 익히고, AI 서비스와 접목시킬 수 있는 프로젝트가 뭐가 있을지 고민해 보았을 때, 지식 베이스를 통합시켜 서비스를 제공한다는 것이 괜찮은 아이디어 같아서 진행하게 되었다. 그리고 Github의 유명 오픈소스들을 토대로 워크플로우를 구성할 생각이다. 이 과정에서 영어 실력도 좀 늘리고, 실무에서 진행하는 패턴들을 익혀서 적용할 생각이다.

🛠️ Stack

일단 FastAPI를 기반으로 빠르게 MCP 서버를 제공하는 것이 목표이다 (사실 이미 백엔드 환경은 얼추 구현함...). FastAPI에서 MCP 서버를 구성하도록 도와주는 라이브러리를 찾아보니 대표적으로 FastMCP와 fastapi-mcp 두 개가 있었다. FastMCP는 간단하게 도구 기능을 FastAPI 객체에 주입하여 MCP 엔드포인트를 만들어주는 라이브러리이다. fastapi-mcp는 라우터 자체를 도구로 호출할 수 있도록 해주는 라이브러리이다. 나는 fastapi-mcp를 선택하였으며, 이유는 단순히 MCP를 통해 서비스를 호출하는 것이 아닌, 프론트 서비스도 같이 제공하기 위해서이다. 그러기 위해서 API와 MCP 호출을 통합시키는 것이 개발에 편할 것이라고 판단하였다.

프론트 서비스는 아직 스택을 정하진 않았다. Svelte와 React 중에 고민 중인데, 아마 React로 진행할 것 같다.

🛠️ 서비스 구조

서비스 구조는 매우 간단하다. 단순하게 지식 베이스 저장소를 제공하는데, 일단 데이터베이스와 벡터 데이터베이스 두 개를 제공하여, 자신의 지식 베이스에서 임베딩 검색이 가능하도록 하는 것이 주된 목적이다.

따라서 사용자는 ChatGPT, Claude, Cursor 등 여러 가지 AI 플랫폼에서 자신의 지식을 관리할 수 있게 하는 것이 최종적인 프로젝트 목표이다. 일단 개발자 위주의 서비스 제공이지만, 추후에 해당 AI 서비스들이 확장되어서, 일반 사용자들도 여러 가지 AI 서비스들에서 자신의 저장된 지식을 제한 없이 사용할 수 있게 하는 것이 최종적인 목적이다.

😘 마무리

앞으로 해당 프로젝트에 대해서 글을 작성할 생각이다. 현재는 일단 User와 Knowledge API는 구성이 완료되었고, MCP 호출 동작도 확인한 상태이다. 해당 내용은 다음 글에서 다룰 예정이다.

Github 프로젝트 URL

이제 회사에서 본격적으로 개발 일을 시작한지 1달 반이 다 되어간다. 현재 Svelte와 FastAPI 기반의 Monolothic 구조의 프로젝트를 유지보수 하고 있는데, 해당 프로젝트에서 이해가 안되는 부분이 매우 많이 있다. 특히 FastAPI의 coroutine을 통한 라우터 설정에 애를 먹고 있는데, 규모가 큰 오픈소스다 보니까, 어떤 기준으로 해당 함수는 async를 통해 코루틴 처리를 하였는지, 어떤 함수는 일반 함수 정의를 통해 thread pool로 관리하는지 이해가 안되고 있다.

아마도 나 같은 신입 개발자들은 이러한 동시성 관리가 익숙치 않을 것이다. 신입 개발자들은 다른 WAS 프레임워크들 또한 이러한 동시성 관리, 더 나아가 Python 기반이 아닌 Spring Boot 같은 다른 언어 진영의 병렬 처리 같은 물리적 구조를 고려한 프로그래밍을 경험할 기회가 없다. 본인이 개인 프로젝트나, 백엔드 서비스를 개발한 경험이 있어도 실무에서 요구하는 것 과는 분명히 차이가 있을 것이다.

물론 현재 나는 FastAPI를 사용 중이어서, 고 수준의 병렬 처리는 고려할 상황이 아니지만, 개발을 하면서, 성능 개선을 위해 동시성 강화같은 이슈를 처리를 하면 벽이 느껴진다... 심지어 이러한 동시성 관리와 성능 개선을 위해 ThreadPool을 사용해 블록킹 함수를 추가를 하면, 이러한 수정이 오히려 전체 프로젝트의 성능에 어떠한 영향을 미칠지 모르겠는 경우가 허다하다. 그래서 이번 시리즈에서는 ASGI 기반의 서버인 FastAPI가 어떤식으로 동시성을 관리하는지와 다른 서버 프레임워크들과 비교를 통해 어떤 식으로 요청을 받고, 처리하는지 정리를 해보려고 한다.

🛠️ Blocking vs Non-Blocking

알아보기 전에 Blocking과 Non-Blocking에 대해서 자세히 알아볼 필요가 있다. 많은 사람들이 오해를 하는 것이 Blocking 함수와 Non-Blocking 함수의 구분 방법이다. 두 함수는 개발자가 저수준의 구현을 통해서 Blocking, Non-Blocking을 설정을 하는 것이 아닌, 기존에 존재하는 라이브러리나 구문을 통해서 설정된다. 또한 기본적인 함수들은 동기 실행을 가정한다. 여기서 가장 오해하는 부분이 동기와 Blocking 그리고 비동기와 Non-Blocking의 관계이다. 앞에서 이야기한 "기본적인 함수들은 동기 실행을 가정한다" 의 의미는 기본적인 함수들은 모두 동기로 처리된다는 의미이다. 당연한 이야기지만, 여기에 Blocking과 Non-Blocking을 고려해보자.

CPU bound vs I/O bound

Blocking은 I/O 바운드 를 통한 쓰레드의 대기 상태를 의미한다. 그러면 I/O 바운드가 아닌 CPU 바운드를 생각해보자 만약 개발자가 루프문을 $O(n^3)$ 의 시간복잡도 동안 실행한다고 해보자. 이 상황에서도 Blocking 이라고 할 수 있는가? 루프문을 실행하는 동안 같은 쓰레드 내의 다른 함수들은 실행되지 않지만, 분명 해당 쓰레드는 실행 중이다. 이러한 쓰레드 내의 작업을 CPU 바운드라고 한다. 뭔가 거창하게 설명했지만, 그냥 일반적인 함수 실행이다...

비동기와 Non-Blocking의 논리적 실행

그러면 다시 Blocking 함수로 돌아가서 I/O 바운드는 정확히 무엇을 의미를 할까? 우리가 서버 환경에서 클라이언트로부터 요청을 받고, 데이터베이스에서 사용자의 정보를 확인한다고 해보자.

def get_user_from_db(username: str):
    conn = sqlite3.connect("users.db")
    cursor = conn.cursor()
    cursor.execute("SELECT username, password FROM users WHERE username = ?", (username,))
    user = cursor.fetchone()
    conn.close()
    return user

@app.post("/login/blocking")
def login_blocking(username: str, password: str):
    user = get_user_from_db(username)
    if not user or user[1] != password:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    return {"message": f"Welcome, {username}!"}

위의 함수는 동기 상태로 정의된 FastAPI 라우터이다. 위의 get_user_from_db()에서 내부 sqlite db에서 DML을 실행 중이다. 이때, cursor.execute("SELECT username, password FROM users WHERE username = ?", (username,)) 는 CPU 바운드인가 I/O 바운드인가? 답은 I/O 바운드이다. 해당 함수를 실행을 하면, 현재 쓰레드는 추가적인 작업이 필요한지를 생각해보면, 전혀 아니다. 현재 쓰레드에서는 단순히 해당 함수가 끝나길 기다릴 것이다. 즉 Waiting 상태가 된다. 그리고 CPU는 해당 DML을 수행하고 있는 DBMS가 점유할 것이다. 그리고 작업이 끝나면, 함수를 반환하고, 다시 현 쓰레드를 실행할 것이다. 다시 말해, 서버의 스레드는 멈춰 있고, DBMS 프로세스가 디스크에서 데이터를 읽거나 쓰는 작업을 수행하는 것이다. 작업이 완료되면 DBMS는 결과를 반환하고, 커널은 대기 중이던 쓰레드를 깨워 이전의 함수 실행 지점부터 코드를 이어서 수행한다. 즉, 코드 상으로는 함수가 멈춰 있는 것처럼 보이지만, 실제로는 쓰레드가 CPU를 전혀 사용하지 않고, 외부 자원(디스크)의 응답을 기다리는 I/O Bound + Blocking 상황이 발생한 것이다. 그러면 생각해보자 여기서 어떻게 성능을 개선 할 수가 있을까?

위의 코드처럼 라우터에 1개의 요청 또는 1개의 Blocking 함수만 있으면 별로 상관이 없을 것이다. 이번에는 Blocking 함수가 여러 개가 있다고 생각해보자.

def get_user_from_db(username: str):
    conn = sqlite3.connect("users.db")
    cursor = conn.cursor()
    time.sleep(1)
    cursor.execute("SELECT username, password, info, history FROM users WHERE username = ?", (username,))
    user = cursor.fetchone()  
    conn.close()
    return user

@app.post("/login/blocking")
def login_blocking(username: str, password: str):
    user = get_user_from_db(username)
    if not user or user[1] != password:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    return {"message": f"Welcome, {username}!"}


@app.post("/info/blocking")
def get_user_info_blocking(username: str):
    user = get_user_from_db(username)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return {"username": user[0], "info": user[2]}


@app.post("/history/blocking")
def get_user_history_blocking(username: str):
    user = get_user_from_db(username)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return {"username": user[0], "history": user[3]}

위의 함수에 사용자 3명이 동시다발적으로 3개의 요청을 각각 보낸다고 생각해보자.

FastAPI 에서는 일반 def 요청은 쓰레드 풀의 개별적인 쓰레드 워커에서 실행된다. 해당 부분은 다음 글에서 자세히 설명을 하고 지금은 단일 쓰레드에서 실행되는 것으로 가정 하겠다.

8000포트에서 Listen 중인 상태로 프로세스를 실행하고, 사용자1이 login_blocking(), 사용자2가 get_user_info_blocking() 그리고 사용자3이 get_user_history_blocking()을 순서대로 요청을 보냈다고 가정하자. 또한 DML 실행시간은 1초라고 가정하자. 그리고 Task Queue에는 실행 프로세스의 쓰레드가 Task로 들어간다고 가정하자. 여기서 고려해야 되는 부분은,쓰레드가 하나이므로 만약 쓰레드가 Waiting 상태가 되면, 요청을 받지 못한다는 것이다. 간단히 생각해보면, 이미 실행 중인 프로세스에 추가적인 작업이 쌓이는 것을 생각하면 된다. 메인 워커 쓰레드를 $W$이라 하겠다. 또한 각 Task Queue에는 쓰레드 단위로 Task가 들어간다고 가정하겠다.

OS 수준에서는 1개의 프로세스와 1개의 단일 쓰레드를 Task Queue에서 실행 중이지만, 프로세스 관점에서는 프로세스에 추가적인 작업이 쌓이고 있다. 사용자1의 login_blocking()가 들어오는 순간 현재 쓰레드는 약 1초간 Waiting 상태가 될 것이다. Waiting 이 되는 1초 동안 나머지 2개의 요청을 받았다고 가정하자. 또한 2개의 코어로 병렬 처리가 된다고 가정하자.

위의 다이어그램은 Request를 받았을 때, 요청과 단일 쓰레드가 어떻게 처리되는지 보여준다. 현재 Blocking 함수는 time.sleep(), cursor.execute() 가 존재한다. 또한 $T_n$에서 $n$ 은 초 단위라고 가정을 하겠다. accept queue는 생소할텐데, listen 상태의 소켓을 지니고 있는 프로세스가 보유하는 큐로 아직 애플리케이션 레벨에서 accept() 호출로 가져가지 않은 연결들이 일시적으로 쌓여 있는 공간이다. 위의 그림을 보면, 당연하게도 $R_2$, $R_3$는 $R_1$이 처리되어야지 순서대로 처리될 것이다. 그러면 약 $T_4$에 모든 처리가 완료 될 것이다. 2개의 코어가 존재해도 $W$ 가 waiting이 되어 있으면, DB process가 실행 중일때 나머지 코어에 $W$를 실행하지 못할 것이다.

그러면 여기서 개선을 어떻게 할까? FastAPI 는 ASGI 기반이다. 이 말은 모든 요청을 async 인터페이스로 받는 웹 서버를 가정하는 프레임워크란 뜻이다. 위의 다이어그램을 봤을 때, 비동기로 처리를 한다고 하면, $R_1$ 처리 중에 다른 요청을 처리 할 수 있게 해야 한다. 여기서 사용하는 것이 바로 async 함수 내의 await 구문이다. 그리고 해당 구문으로 Non-Blocking의 진정한 의미를 알 수 있는데, 바로 실행 제어권을 반납하는 것이다. 매우 간단하다. async 함수 내에서 await를 만나면 해당 함수를 Non-Blocking 으로 실행하겠다는 의미이다. 그럼 여기서 드는 생각이, 결국에는 FastAPI 같은 ASGI 기반의 웹서버는 애플리케이션 수준에서 비동기를 지원하는 것이다. 즉 단일 쓰레드의 코루틴 내에서 비동기를 지원하여 동시성을 강화하는 것이다. 위의 다이어그램이 비동기로 처리될때, 차이점은 I/O 바운드 작업시에 $W$를 Waiting 상태에 빠지지 않도록하는 Non-Blocking 처리만 존재한다. 그러면 이게 어떻게 가능할까? 단일 쓰레드 내에서도 스케줄러같은 실행 처리를 도와주는 로직이 있는 것일까?

Coroutine

Coroutine이 바로 이 비동기 처리를 구현하는 기법이다. OS는 Context switch같은 기법을 통해 동시성을 강화한다. 그럼 OS가 비동기를 처리한다고 할 수 있을까? 절대 아니다. 이유는 동시성 강화는 비동기 처리가 아니기 때문이다. 하지만 비동기 처리는 동시성을 강화하는 기법 중 한가지이다. OS가 동시성을 강화하는 이유는 여러가지의 작업을 효울적으로 처리하기 위해서다. 이를 통해 사용자는 작업이 동시에 이루어지는 환상을 만들어준다. 하드웨어적인 관점으로 자원을 최소한으로 사용하여 가장 효율적인 스케줄을 통해 프로세스를 관리하는 것 이것이 목적이다. 그러면 Coroutine을 통한 비동기 처리는 무엇이 목적일까? 말한대로 동시성 강화가 목적이다. 하지만 하드웨어적인 관점에서 굳이 애플리케이션 수준에서 자원의 효율성같은 요소를 신경쓰지는 않을 것이다. 주요 목적은 위에서 말한 것 처럼, I/O 바운드 작업시에 코루틴 쓰레드를 Waiting 상태에 빠지지 않도록하는 Non-Blocking 처리를 하는 것이다. 이를 통해 Waiting이라는 요소를 제외하고 실행이 가능하다. 그리고 이것은 Event Loop를 통해 단일 쓰레드의 Call Stack의 Task switch로 이루어진다. 이는 OS 수준의 Context switch와 비슷한 기법이다. Event Loop 는 CPU 스케줄러 그리고 Task Switch는 Context switch로 비유할 수 있을 것이다.

Coroutine은 OS처럼 물리적인 스케줄링을 수행하는 것이 아난, 단일 스레드 내부에서 실행 흐름을 논리적으로 전환(switch)하여 동시성을 달성하는 방식

OS의 Context switch가 커널이 직접 개입하여 CPU 레지스터, 프로그램 카운터, 스택 포인터 등 하드웨어 상태를 저장하고 복원하는 무거운 전환이라면, Coroutine의 Task switch는 단지 함수의 실행 위치와 로컬 상태를 저장하고 이벤트 루프가 다음 코루틴을 재개(resume)하는 가벼운 사용자 레벨 전환이라 할 수 있다.

따라서 Coroutine은 커널이 아닌 애플리케이션 레벨에서 구현된 경량화된 동시성 메커니즘이며, Context switch의 하드웨어적 문맥 교환에 대응되는 소프트웨어적 제어 흐름 교환(Control-flow switching) 이라고 할 수 있다.

위의 다이어그램을 통해 비동기 처리가 구현된 다이어그램을 살펴보겠다. 이를 위해서 async 함수에서 time.sleep() 은 await asyncio.sleep() 로 바꾸고, DML 함수도 비동기 처리를 해야 한다. 이렇게 비동기 처리가 완료되면 다이어그램을 아래와 같을 것이다.

asyncio sleep() 과 cursor.execute() 같은 I/O 바운드가 실행되면, Event Loop는 등록된 다른 코루틴을 실행한다. 즉 위의 그림에서 coroutine1 이 asyncio sleep()을 통해 대기 상태에 들어가면 Event Loop는 Accept Queue에서 바로 $R_2$를 가져와서 coroutine2로 실행을 한다. 이때 오해를 하면 안되는 것이, coroutine은 병렬 실행이 절대 아니란 점이다. 위에 그림만 보면 오해를 할 수도 있지만, coroutine이 실행되는 로직은 기존에 실행 중이던 coroutine이 I/O 바운드로 인해 대기 상태에 들어갔을때만, 실행이 되는 동시성 강화이다. 따라서 위에서 OS 수준의 Context switch로 비유한 이유가 바로 이러한 Event Loop를 통한 coroutine 실행 관리 로직 때문이다. 이러한 동시성 강화를 통해 약 $T_{1.5}$ 에 모든 실행이 완료되는 것을 볼 수 있다. 기억하자 coroutine은 단일 쓰레드 내에서 이루어지는 비동기를 통한 동시성 강화 기법이라는 것을.

비동기 코루틴은 단일 스레드 내에서 오직 하나의 Call Stack 위에서만 실행되며, 동시에 여러 coroutine이 CPU를 점유하는 일은 없다.

OS 수준에서는 단순히 $W$를 실행하고 있으면 되고 이러한 비동기 처리는 애플리케이션 수준의 쓰레드 내부에서 전부 이루어지는 추상화가 ASGI 아키텍처의 철학이다.

😘 마무리

비동기 모델에서의 동시성 강화는 OS 수준의 선점형 스케줄링(preemptive scheduling) 이 아닌, Event Loop를 중심으로 한 협력형(Cooperative) 스케줄링 에 의해 이루어지고 Event Loop는 OS의 CPU 스케줄러에 대응되는 역할을 수행하며, coroutine 간 전환(Task Switching)은 커널 수준의 Context Switch 대신 사용자 레벨에서 수행되는 가벼운 실행 흐름 전환(Control-flow switching) 으로 처리된다. 이번 글에서는 FastAPI를 비롯한 비동기 처리가 논리적으로 어떻게 이루어지는 지와 OS 수준과 애플리케이션 수준에서 헷갈리지 않도록 설명을 해보았다. 다음 글에서는 FastAPI의 비동기 처리 로직을 코드를 통해 알아보고 일반 def 선언은 어떻게 처리되는지 그리고 lifespan을 통한 coroutine 처리를 심도있게 다뤄보겠다.

오늘은 Pydantic에 대해서 알아보려고 한다. 최근에 오픈소스로 이루어진 프로젝트들을 보면, 백엔드 서버를 FastAPI를 사용하는 경우가 많은데, Pydantic은 FastAPI에서 데이터 스키마를 정의하고 데이터 직렬화/역직렬화를 위해 많이 사용하는 라이브러리이다. 최근 회사에서 오픈소스를 활용한 프로젝트를 유지보수하는 업무를 하고 있는데, 해당 프로젝트가 나는 별로 사용해본 적이 없는 Svelte를 프론트로 사용 중이고 백엔드는 FastAPI 기반의 Monolithic 아키텍처를 구성하고 있다. 당연하게도 해당 프로젝트에서 백엔드는 Pydnatic으로 DTO를 구성하고 있다. Pydantic은 얼핏보면 간단해 보이지만, 수 많은 ASGI 코드들과 정의되어 있는 스키마를 보면 어지러워 질때가 있다. 그래서 해당 라이브러리에 익숙해질 필요를 느껴서 이렇게 정리를 해보려고 한다.

찾아보니 Pydantic은 처음에는 Samuel Colvin 이라는 사람이 2018년 쯤에 Python 환경에서 타입 힌트화를 통한 데이터 무결성 보장과 타입 직렬화/역직렬화를 지원하기 위해 만들었다고 한다. GPT 피셜. 나중에 FastAPI에서 공식적으로 Pydantic을 스키마 라이브러리로 채택하면서 널리 쓰이게 됐다고 한다. 특히, 데이터 스키마 정의를 통해 API 기반의 백엔드 서버의 라우터 문서화 (OpenAPI/Swagger) 를 자동화 하는 점이 큰 장점이다.

사용법 🛠️

거두절미하고 바로 사용법을 알아보겠다. Pydantic을 써보면서 느낀점은 사용자 입맛대로 강력한 데이터 강제성을 주입 시킬 수 있다. 참고로 사용한 Pydantic 버전은 2.9.2 이다.

BaseModel

class User(BaseModel):
    id: int = Field(
        default_factory=lambda: int(uuid.uuid4()),
        description="사용자의 고유 ID",
    )
    name: str = Field(
        ..., min_length=1, max_length=20, description="사용자의 이름 (1~20자)"
    )
    email: str = Field(..., description="사용자의 이메일 주소")
    age: Optional[int] = Field(None, ge=0, description="사용자의 나이 (0 이상)")

    def __str__(self):
        return f"User(id={self.id}, name='{self.name}', email='{self.email}', age={self.age})"

    def to_model_dump(self):
        return self.model_dump()

    @classmethod
    def from_model_dump(cls, data):
        return cls.model_validate(data)

    @model_validator(mode="before")
    def check_email(cls, values):
        email = values.get("email")
        if email and "@" not in email:
            raise ValueError("Invalid email address")
        return values

이제 위의 코드를 보면 좀 어지러워 질텐데, 일단 User 스키마만 살펴보자.

class User(BaseModel):
    id: int 
    name: str
    email: str 
    age: int

위의 스키마를 최대한 간단하게 정의하면 이렇게 작성할 수 있다. 먼저 BaseModel 은 Pydantic에서 해당 클래스가 스키마라는 것을 정의해주는 기본 클래스이다. 해당 클래스를 상속 함으로서 User 는 Pydantic 의 데이터 검증과 직렬화/역직렬화를 사용 가능하다.

user = User(id="123", name="Alice", email="user@example.com, age="25")
print(user) 

위 처럼 User를 정의했다고 생각해보자, 현재 id 와 age 는 int 형인데 str 형이 할당 되어있다. 마치 JavaScript 의 타입 캐스팅 처럼 Pydantic 은 바꿀 수 있는 타입은 알아서 바꿔 준다. 위의 경우에는 문제 없이 int 형으로 바뀔 것이다. 그러나 만약 "one two three" 같은 것이 할당되어 있으면, ValidationError를 발생 시킨다.

Field

class User(BaseModel):
    id: int = Field(
        default_factory=lambda: int(uuid.uuid4()),
        description="사용자의 고유 ID"
    )
    name: str = Field(
        ..., min_length=1, max_length=20, description="사용자의 이름 (1~20자)"
    )
    email: str = Field(
        ..., description="사용자의 이메일 주소"
    )
    age: Optional[int] = Field(
        None, ge=0, le=150, description="사용자의 나이 (0~150)"
    )

이번에는 Field에 대해서 알아보자. Field는 일종의 데이터 명세서로 단순히 타입만 지정했을 때보다 훨씬 세밀하게 제약조건과 메타데이터를 설정할 수 있게 해준다. 위 코드를 보면, 모든 필드가 description 을 통해 필드 설명을 제공 중이다. 이 값은 문서화가 되었을 때, API 설명 부분에 자동을 할당된다.

각 필드를 살펴보면, id의 default_factory 를 볼 수 있는데, 해당 인자는 해당 필드를 동적으로 값을 생성한다는 의미이다. default 도 있는데, 해당 값은 동적이 아니라 정해진 값을 생성해주는 인자이다. 참고로 밑에 처럼 Field를 사용 안하고, default 선언도 가능하다.

class User(BaseModel):
    id: int = 10

다음으로는 ... 을 볼 수 있는데, 해당 값은 필수 인자라는 뜻이다. 따라서 해당 스키마를 정의할 때, 해당 값들을 할당하지 않고 정의하면 ValidationError 가 발생한다.

그 밖에도 여러가지 인자가 있는데, 밑에 표로 정리한 것을 살펴보면 이해가 편할 것이다.

Field 주요 인자 정리

Typing

Pydantic 은 typing 모듈의 정의 타입들을 사용하는데, 대표적으로 Optional이 있다.

class User(BaseModel):
    id: int = Field(..., description="사용자 ID (필수)")
    name: str = Field(..., min_length=1, max_length=20, description="사용자 이름")
    age: Optional[int] = Field(None, ge=0, le=150, description="나이 (없으면 None)")
    phone: Union[str, int, None] = Field(
        None, description="전화번호 (문자열 또는 숫자 허용, 없으면 None)"
    )
    role: Literal["admin", "user", "guest"] = Field(
        "user", description="권한 (admin, user, guest 중 하나)"
    )
    tags: List[str] = Field(default_factory=list, description="사용자 태그 목록")
    preferences: Dict[str, str] = Field(
        default_factory=dict, description="사용자 환경설정"
    )

이런식으로 타입 정의가 가능한데, 참고로 Union 보다는 간단하게 파이프 연산자를 사용하는 것을 추천한다. 다른 타입도 많은데, FastAPI 데이터 스키마에서는 이 정도면 사용하는 것 같다.

Method

Pydantic 은 기본 Method 기능을 제공한다. 오픈소스 코드에서도 이러한 기본 함수를 적극적으로 활용하고 있어서, 반드시 알아둬야 된다.

1. __str__

→ 객체를 print 했을 때 사람이 읽기 좋은 문자열 반환

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str

    def __str__(self):
        return f"User(id={self.id}, name={self.name}, email={self.email})"

u = User(id=1, name="Alice", email="alice@example.com")
print(u)  
# 출력: User(id=1, name=Alice, email=alice@example.com)

2. model_dump()

→ 객체 → dict 직렬화

data = u.model_dump()
print(data)
# 출력: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}

3. model_validate()

→ dict → 객체 (검증 포함)

user_dict = {"id": 2, "name": "Bob", "email": "bob@example.com"}
u2 = User.model_validate(user_dict)
print(u2)
# 출력: User(id=2, name=Bob, email=bob@example.com)

위의 함수들을 통해 Pydantic의 핵심 기능인, 데이터 검증과 직렬화/역직렬화를 간편하게 적용 가능하다.

4. @model_validator

→ 모델 생성 시 비즈니스 규칙 검증

from pydantic import model_validator

class User(BaseModel):
    id: int
    name: str
    email: str

    @model_validator(mode="before")
    def check_email(cls, values):
        email = values.get("email")
        if email and "@" not in email:
            raise ValueError("Invalid email address")
        return values

# 올바른 입력
User(id=3, name="Charlie", email="charlie@example.com")

# 잘못된 입력 → 예외 발생
User(id=4, name="Dave", email="invalid-email")
# ValueError: Invalid email address

해당 함수는 model_validate 기능을 제공한다는 의미로 데코레이터로 정의 가능하다. 옆에 (mode="before") 는 스키마가 정의되기 전에 실행되는 함수라는 뜻이다. 따라서 이러한 검증 함수를 여러가지 만들 수가 있다.

Model Nested

이제 Pydantic의 가장 강력한 기법이라 볼 수 있는 중첩을 알아보자.

class ProjectConfig(BaseModel):
    owner: User
    members: List[User]

위의 방식 처럼 중첩을 사용해서 상위 스키마를 제공이 가능하다. 당연한 기능 같지만, Pydantic의 BaseModel 은 Dict 타입을 위에서 살펴본 모델 검증 과정을 통해 객체형으로 바꿔준다.

만약 위의 스키마대로 Dict 타입을 정의했다고 해보자

config = {
    "owner": {
        "name": "Alice",
        "email": "alice@example.com"
    },
    "members": [
        {"name": "Bob", "email": "bob@example.com"},
        {"name": "Charlie", "email": "charlie@example.com"}
    ]
}

위에서 정의된 config 에서 members[0] 를 살펴보려면 config["members"][0] 으로 접근이 가능하다.

project = ProjectConfig.model_validate(config)

이제 BaseModel의 model_validate 로 변환을 해보자. 그러면 project는 객체가 되어서 config.members[0] 으로 접근이 가능하게 된다. 수 많은 FastAPI를 사용한 오픈소스 에서는 이러한 형태로 강력한 타입 설정을 하여, 관리를 하고있다. FastAPI 에서는 resquest 와 response 에 스키마를 설정하여, 자동으로 JSON이 직렬화 된 데이터를 객체 형태로 받게된다.

FastAPI

from typing import List
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int 
    name: str 
    email: str 
    age: Optional[int]

class ProjectConfig(BaseModel):
    owner: User
    members: List[User]

class ProjectResponse(BaseModel):
    owner_name: str
    member_count: int

@app.post("/projects", response_model=ProjectResponse)
async def create_project(project: ProjectConfig):
    return ProjectResponse(
        owner_name=project.owner.name,
        member_count=len(project.members)
    )

위의 코드를 보면, create_project에서 project 를 ProjectConfig 로 받고 있다. 만약에 클라이언트가 Dict 형태로 인자를 보내게 되면, 위의 포스트 라우터는 자동으로 project를 검증 및 변환하여 ProjectConfig 로 만들어 준다.

경로 옆 response_model 은 응답 타입도 정해주는 설정이다. 반환 값으로 ProjectResponse 스키마대로 반환을 하고 있다. 클라이언트는 해당 응답을 받으면, Dict 형태로 받게 된다. 이렇게도 쓸 수 있다.

@app.post("/projects", response_model=ProjectResponse)
async def create_project(project: ProjectConfig):
    return {
        "owner_name": project.owner.name,
        "member_count": len(project.members)
    }

FastAPI 에서 Dict 형으로 반환을 해도, 자동으로 스키마를 감지해준다. 컨벤션에 맞게 두가지를 조율해서 사용하면 될 것 같다. 보통의 API에서는 클라이언트는 항상 JSON 으로 직렬화 된 데이터를 보내므로, 이러한 데이터를 검증하고 좀 더 쉽게 관리가 가능하다.

참고로 상속 기능이 있긴 하지만, 상속 기능은 사용하면 너무 복잡해져서 많이 보진 못한 것 같다. 그래서 설명은 넘어가겠다.

마무리 😁

오늘은 Pydantic에 대해서 알아보았다. 처음에는 그냥 단순한 타입 정의 라이브러리라 생각하고, 찾아보지 않았다가, 실수나 타입 불일치 오류를 많이 보게 되었는데, 이번 기회에 제대로 알아보고 작업을 할 수 있을 것 같다. 기회가 되면, 회사에서 사용하는 스텍이나 라이브러리들을 하나씩 정리해서 학습을 해야겠다.

이번에는 Bridge Pattern 에 대해서 알아보겠다. Bridge Pattern은 말 그대로 클래스와 클래스를 가교(Bridge)라는 관계로 정의하는 패턴이다. 한번 생각해보자, 우리가 어떠한 클래스를 상속을 통해 구현을 할때, 깊이 1에 있는 클래스들은 해당 클래스의 원형을 그대로 따라갈 것이다. 근데 만약에, 부모 클래스가(깊이 0) 새로운 개념의 서브 클래스를 생성한다 생각해보자.

위의 이미지는 GOF 책에서 예시로 든 사용자 인터페이스 툴킷인 Winodow 클래스의 클래스 폭발을 보여준다. 툴킷인 Window 클래스를 사용해서 우리가 각 플랫폼의 특성이 반영된 XWindow 와 PMWindow 플랫폼을 구현했다고 해보자, 해당 구현만 존재하면 사용하는데는 문제가 없을 것이다. 그런데, Window 구현자가 새로운 기능을 담은 Window 인 IconWindow 를 출시 했다. 그러면 우리는 기존의 XWindow 와 PMWindow 를 다시 IconWindow 에 상속 받아서 해당 Icon 기능이 포함된 클래스들을 재정의 해야 한다. 매우 번거롭지 않은가?

그래서 사용되는 패턴이 Bridge Pattern이다.

구현에서 추상을 분리하여, 이들이 독립적으로 다양성을 가질 수 있도록 합니다.

구현에서 추상을 분리한다는 것은, 구현체와 추상으로 생성된 추가 클래스들을 분리한다는 것이다. 참고로 Bridge Pattern은 핸들/구현부(Handle/Body) 라는 이름으로도 불린다.

언제 사용하나? 📌

책에서는 위에서 말한 예시로 Bridge Pattern을 설명한다.

이미지를 보면, Window 의 추상 클래스로 IconWindow, TransientWindow 가 설정되어 있고, Window는 imp 라는 구현체 인스턴스를 가지게 된다. 이 imp 는 WindowImp 를 참조하게 된다. IconWindow, TransientWindow는 기존의 Winodw 에서 제공하는 DrawText() 와 DrawRect() 로 자신들이 제공하는 기능을 구현하고 있다. 여기서 해당 패턴의 핵심이 나오는데, 바로 WindowImp는 DrawRect()를 4개의 DevDrawLine() 으로 구현 중이다. 이것이 Bridge Pattern 의 구현부의 역할이다. 구현부는 가장 저수준의 구현을 제공하고, 추상부는 해당 구현체들을 활용해서 실질적인 동작을 수행한다. 그리고 이러한 저수준의 구현을 하나의 클래스로 정의하면 해당 클래스의 서브 클래싱을 통해 여러가지 플랫폼에서 활용이 가능하다.

이렇게 함으로써 얻는 가장 큰 이점은, 기능(추상화 계층)과 플랫폼(구현 계층)을 각각 독립적으로 관리할 수 있다는 점이다. 기능이 늘어날 때마다 모든 플랫폼별 클래스를 다시 작성해야 하는 클래스 폭발 문제를 피할 수 있고, 새로운 플랫폼을 지원하는 것도 훨씬 수월하다.

구조 🏗️

구조는 위의 예시를 이해했으면, 바로 파악이 될것이다. 정리하자면, Bridge Pattern은 상속으로 인해 기능 × 플랫폼 조합이 기하급수적으로 늘어나는 문제를 해결하기 위해, 추상 계층과 구현 계층을 분리하고, 이를 가교(imp)로 연결하는 방식이다. 이 덕분에 기능과 구현을 분리된 축(axis)으로 관리할 수 있어 확장성과 유지보수성이 크게 향상된다.

여기서 핵심 포인트는 추상은 고수준 동작을 정의, 구현은 저수준 세부사항을 담당, 그리고 둘은 런타임에 조합된다 라는 구조다.

구현 💻

#include <iostream>
#include <memory>
#include <string>
#include <algorithm>

// -------- Primitive --------
struct Point { int x{}, y{}; };

// -------- Implementor --------
class WindowImp {
public:
    virtual ~WindowImp() = default;
    virtual void DeviceRect(int x0, int y0, int x1, int y1) = 0;
    virtual void DeviceText(const char* s, int x, int y) = 0;
};

// -------- Concrete Implementors --------
class XWindowImp : public WindowImp {
public:
    void DeviceRect(int x0, int y0, int x1, int y1) override {
        int x = std::min(x0, x1);
        int y = std::min(y0, y1);
        int w = std::abs(x1 - x0);
        int h = std::abs(y1 - y0);
        std::cout << "[X] Rect (" << x << "," << y << ") w=" << w << " h=" << h << "\n";
    }
    void DeviceText(const char* s, int x, int y) override {
        std::cout << "[X] Text \"" << s << "\" @(" << x << "," << y << ")\n";
    }
};

class PMWindowImp : public WindowImp {
public:
    void DeviceRect(int x0, int y0, int x1, int y1) override {
        int left   = std::min(x0, x1);
        int right  = std::max(x0, x1);
        int bottom = std::min(y0, y1);
        int top    = std::max(y0, y1);
        std::cout << "[PM] Rect L=" << left << " R=" << right
                  << " B=" << bottom << " T=" << top << "\n";
    }
    void DeviceText(const char* s, int x, int y) override {
        std::cout << "[PM] Text \"" << s << "\" @(" << x << "," << y << ")\n";
    }
};

// -------- Abstraction --------
class Window {
public:
    explicit Window(std::unique_ptr<WindowImp> imp) : imp_(std::move(imp)) {}
    virtual ~Window() = default;

    // 고수준 API
    virtual void DrawRect(const Point& p1, const Point& p2) {
        imp_->DeviceRect(p1.x, p1.y, p2.x, p2.y);
    }
    virtual void DrawText(const std::string& s, const Point& at) {
        imp_->DeviceText(s.c_str(), at.x, at.y);
    }
    virtual void DrawContents() = 0; 

protected:
    WindowImp* imp() { return imp_.get(); }

private:
    std::unique_ptr<WindowImp> imp_; 
};

// -------- Refined Abstractions --------
class IconWindow : public Window {
public:
    IconWindow(std::unique_ptr<WindowImp> imp, std::string iconName)
        : Window(std::move(imp)), icon_(std::move(iconName)) {}
    void DrawContents() override {
        DrawText(("ICON:" + icon_), {0, 0});
        DrawRect({0, 0}, {32, 32});
    }
private:
    std::string icon_;
};

class TransientWindow : public Window {
public:
    explicit TransientWindow(std::unique_ptr<WindowImp> imp)
        : Window(std::move(imp)) {}
    void DrawContents() override {
        DrawText("Transient", {8, 16});
        DrawRect({4, 4}, {128, 64});
    }
};

// -------- Client --------
int main() {
    // 런타임에 구현 선택 → 같은 추상도 다른 구현과 조합 가능
    IconWindow w1(std::make_unique<XWindowImp>(), "app.png");
    TransientWindow w2(std::make_unique<PMWindowImp>());

    w1.DrawContents(); // X 구현으로 그리기
    w2.DrawContents(); // PM 구현으로 그리기
    return 0;
}

전체 코드는 이렇게 되는데, 책에서 제시한 코드는 기능이 너무 많아서 간단하게 DrawRect()와 DrawText()만 구현을 했다. 그리고 Refined Abstraction으로 IconWinodw 만 구현을 했다.

Implementor

// -------- Implementor --------
class WindowImp {
public:
    virtual ~WindowImp() = default;
    virtual void DeviceRect(int x0, int y0, int x1, int y1) = 0;
    virtual void DeviceText(const char* s, int x, int y) = 0;
};

// -------- Concrete Implementors --------
class XWindowImp : public WindowImp {
public:
    void DeviceRect(int x0, int y0, int x1, int y1) override {
        std::cout << "[X] Rect (" << x0 << "," << y0
                  << ")-(" << x1 << "," << y1 << ")\n";
    }
    void DeviceText(const char* s, int x, int y) override {
        std::cout << "[X] Text \"" << s << "\" @(" << x << "," << y << ")\n";
    }
};

class PMWindowImp : public WindowImp {
public:
    void DeviceRect(int x0, int y0, int x1, int y1) override {
        std::cout << "[PM] Rect (" << x0 << "," << y0
                  << ")-(" << x1 << "," << y1 << ")\n";
    }
    void DeviceText(const char* s, int x, int y) override {
        std::cout << "[PM] Text \"" << s << "\" @(" << x << "," << y << ")\n";
    }
};

Bridge Pattern의 Implementation(구현부) 는 WindowImp라는 인터페이스를 중심으로 구성된다. 이 클래스는 DeviceRect, DeviceText와 같이 플랫폼 의존적인 저수준 API(Application Programming Interface)를 정의한다. 그리고 실제 구현은 XWindowImp, PMWindowImp에서 이루어진다. 예를 들어 XWindowImp는 X 윈도우 시스템 호출을, PMWindowImp는 프레젠테이션 매니저 호출을 각각 캡슐화한다. 즉, 어떻게 그릴 것인가라는 부분을 담당하는 것이 바로 구현부이며, 추상부와 독립적으로 교체하거나 확장할 수 있다.

Abstraction

// -------- Abstraction --------
class Window {
public:
    explicit Window(std::unique_ptr<WindowImp> imp) : imp_(std::move(imp)) {}
    virtual ~Window() = default;

    virtual void DrawRect(const Point& p1, const Point& p2) {
        imp_->DeviceRect(p1.x, p1.y, p2.x, p2.y);
    }
    virtual void DrawText(const std::string& s, const Point& at) {
        imp_->DeviceText(s.c_str(), at.x, at.y);
    }
    virtual void DrawContents() = 0;

protected:
    WindowImp* imp() { return imp_.get(); }

private:
    std::unique_ptr<WindowImp> imp_;
};

Abstraction(추상부)는 Window 클래스가 담당한다. Window는 클라이언트에 노출되는 고수준 인터페이스를 정의하며, DrawRect, DrawText 같은 메서드를 통해 기능을 제공한다. 하지만 직접 그리기를 수행하지 않고, 내부에 std::unique_ptr<WindowImp>를 보관해 실제 동작을 구현부에 위임한다. 이렇게 하면 클라이언트는 Window의 API만 이용하면 되고, 저수준 동작은 구현부에서 알아서 처리된다.

Refined Abstraction

// -------- Refined Abstractions --------
class IconWindow : public Window {
public:
    IconWindow(std::unique_ptr<WindowImp> imp, std::string iconName)
        : Window(std::move(imp)), icon_(std::move(iconName)) {}
    void DrawContents() override {
        DrawText(("ICON:" + icon_), {0, 0});
        DrawRect({0, 0}, {32, 32});
    }
private:
    std::string icon_;
};

class TransientWindow : public Window {
public:
    explicit TransientWindow(std::unique_ptr<WindowImp> imp)
        : Window(std::move(imp)) {}
    void DrawContents() override {
        DrawText("Transient", {8, 16});
        DrawRect({4, 4}, {128, 64});
    }
};

IconWindow와 TransientWindow 같은 Refined Abstraction은 Window를 상속받아 고수준의 행위를 구체화한다. 예를 들어 IconWindow는 아이콘을 그리는 동작을 정의하고, TransientWindow는 임시 창을 그리는 방식을 정의한다. 하지만 이들도 직접 저수준 연산을 구현하지 않고, imp()를 통해 내부의 WindowImp에 작업을 위임한다. 이렇게 추상부는 “무엇을 할 것인지”를 정의하고, 구현부는 “어떻게 할 것인지”를 책임지게 되는 구조가 된다. 물론 나는 IconWindow 만 구현을 한 상태이다.

Client

// -------- Client --------
int main() {
    IconWindow w1(std::make_unique<XWindowImp>(), "app.png");
    TransientWindow w2(std::make_unique<PMWindowImp>());

    w1.DrawContents(); // X 플랫폼 구현으로 동작
    w2.DrawContents(); // PM 플랫폼 구현으로 동작
    return 0;
}

마지막으로 클라이언트는 실행 시점에 IconWindow나 TransientWindow를 생성하면서 원하는 구현체(XWindowImp 혹은 PMWindowImp)를 주입할 수 있다. 이렇게 런타임 조합(Runtime Composition) 을 활용하면, 기능 축(추상)과 플랫폼 축(구현)을 완전히 독립적으로 확장할 수 있으며, 기능 × 플랫폼 조합에 따라 모든 클래스를 미리 만들어야 하는 클래스 폭발 문제를 방지할 수 있다.

마무리 😘

Bridge Pattern은 추상과 구현을 분리해서 독립적으로 확장할 수 있도록 만들어주는 구조적 패턴이다. 예시에서 보았듯이, 추상화 계층과 구현 계층을 분리해두면 새로운 기능을 추가하더라도 클래스가 불필요하게 늘어나지 않고 훨씬 유연하게 확장할 수 있다. 즉, 어댑터 패턴이 기존 인터페이스의 불일치를 해결하기 위한 사후적 접근이었다면, Bridge Pattern은 처음부터 확장을 고려한 선제적 설계 방식이라고 볼 수 있다.

다음 글에서는 마찬가지로 구조 패턴 중 하나인 Composite Pattern을 다뤄볼 생각이다. Composite Pattern은 객체들을 트리 구조로 묶어서 부분-전체 계층을 표현하는 데 초점이 맞춰져 있다. 즉, 개별 객체와 객체 집합을 동일한 방식으로 다룰 수 있게 해주는 패턴인데, 이를 통해 복잡한 계층 구조도 단순하게 다룰 수 있는 장점이 있다.

[참고] Bridge Pattern

이번에는 저번 글에서 말한 것 처럼LoRA(Low Rank Adaptation) 에 대해서 알아보겠다.

「LoRA: Low-Rank Adaptation of Large Language Models (Hu et al., 2021)」

LoRA는 위의 논문 「LoRA: Low-Rank Adaptation of Large Language Models (Hu et al., 2021) 에서 제시된 기존의 Fine-tuning을 개선한 방식이다. LoRA가 제시되기 이전에는 Fine-tuning은 전체의 파라미터를 조정하는 Full Fine-Tuning으로 이루어졌다. 이름만 들어도 전체 파라미터를 조정한다는 말에서 알 수 있듯, 비용이 어마어마하게 많이 들었다. 그래서 해당 논문에서는 LoRA를 사용해 저차원 부분행렬을 통해 일부 가중치만 조정하는 기법을 소개한다.

따라서 해당 논문을 바탕으로 LoRA에 대해서 정리를 해보겠다.

📘 Introduction of LoRA

논문에서는 LoRA가 제시된 이유로 기존의 파인튜닝 방식인 Full Fine-Tuning의 단점을 먼저 이야기한다. 크게 두 가지 단점이 있었는데, 첫 번째로 엄청난 양의 연산 비용을 요구한다는 점이다. 두 번째로 테스트를 위해 각 파라미터를 조정할 때 모델을 저장하여 성능 지표를 측정해야 한다는 점이다. 이는 GPT-2와 RoBERTa와 같은 LLM이 적은 기간 내에 계속 출시되면서 파라미터 수가 급격히 증가해 점점 어려워졌다. 이를 완화하기 위해 일부 파라미터만 저장하는 Adapting이라는 기법이 있었으나, 모델의 깊이가 증가하면 성능이 떨어지는 문제가 있었다.

위 그림은 LoRA를 간단히 설명하는 그림이다. 그림을 보면 $d$ 차원의 $x$ 입력이 각각 Pretrained로 설정된 가중치 $W$와 $A$에 input으로 들어간다. 여기서 LoRA의 핵심 개념을 알 수 있는데, 바로 기존의 $W$는 freeze 시키고 입력을 새로운 layer에 입력으로 넣어 저차원 공간으로 축소(Down Projection)하는 행렬 $A \in \mathbb{R}^{r \times d}$를 거친다는 점이다. 참고로 $d$는 출력 값의 차원이고, $r$은 Down Projection 했을 때의 차원이다. 이렇게 $d$ 차원의 입력을 $r$ 차원으로 줄여낸 뒤, 다시 $B \in \mathbb{R}^{d \times r}$ 행렬을 통해 원래 출력 차원 $d$로 확장(Up Projection)한다. 결국 전체 업데이트 행렬은 $\Delta W = BA$ 형태가 된다.

$$ h = W_0 x + BAx $$

위의 식이 최종적으로 LoRA가 가중치를 구하는 방법이다. 기존의 방법인 Full Fine-Tuning은 다음과 같다.

$$ h = W_0 x $$

위 식은 가중치 전체를 조정하는 Full Fine-Tuning을 나타낸다.

이 그림은 원래 가중치 $W_0$는 동결시키고, 작은 두 개의 행렬 $A, B$만 학습해서 기존 선형 변환 결과에 보정값을 더해주는 구조를 단순하게 보여준다. 이를 통해 큰 모델 전체를 건드리지 않고도 파라미터 효율적인 학습이 가능하다는 것이 LoRA의 핵심이다.

여기서 핵심은 바로 $r$인데, 논문에서는 파라미터가 175B이고 출력 차원 수가 12,288인 GPT-3에서도 $r = 1$ 또는 $r = 2$ 정도의 매우 작은 값으로도 성능이 유지된다고 한다. 사실 이렇게 들으면, 왜 성능이 유지되는지 의문이 될 정도로 터무니없게 차이가 크다.

논문에서는 이러한 원리를 LoRA를 고안할 때 영감을 받은 「Measuring the Intrinsic Dimension of Objective Landscapes (ICLR 2018)」, 그리고 「Intrinsic Dimensionality Explains the Effectiveness of Language Model Fine-Tuning (ACL 2021)」에서 언급한 LLM 모델의 Fine-Tuning은 저차원 공간에서 이루어진다는 이유로 설명한다. 두 논문에서는 거대한 네트워크라도 학습할 때는 저차원 공간(subspace)에서만 움직여도 충분하다는 발견, 그리고 대규모 언어모델 파인튜닝에서도 실제로 필요한 변화는 낮은 intrinsic dimension 안에서 발생한다는 것을 실험적으로 입증했다고 한다. 따라서 사실상 Fine-Tuning은 학습할 입력값에 대해 전체 차원을 사용할 필요가 없다는 것이다.

LoRA는 기본적으로 기존 파인튜닝보다 더 일반화된 방식이다. 풀 파인튜닝이 전체 파라미터를 학습하거나 일부만 선택해서 학습하는 것이라면, LoRA는 한 단계 더 나아가서 가중치 행렬 업데이트가 꼭 풀랭크(full-rank)일 필요가 없다는 점에 주목한다. 즉, 모든 가중치 행렬에 LoRA를 적용하고 bias까지 학습하며, rank $r$을 원래 가중치 행렬의 랭크 수준으로 높게 잡아버리면 사실상 풀 파인튜닝과 같은 표현력을 회복할 수 있다. 다시 말해, 학습 가능한 파라미터 수를 늘릴수록 LoRA는 풀 파인튜닝에 점점 가까워진다.

📊 Results

실험 결과를 보면 LoRA가 왜 이렇게 주목받는지 바로 알 수 있다. 먼저 평가 지표에 대해서 설명하겠다.

WikiSQL은 자연어 질문을 SQL 쿼리로 바꾸는 데이터셋이다. 예를 들어 2010년에 개봉한 영화 제목 알려줘라는 문장이 들어오면 모델은 그걸 SQL 쿼리 형태로 바꿔야 한다. 그래서 단순히 언어 이해만 보는 게 아니라 데이터베이스 쿼리까지 연결하는 능력을 평가한다.

MultiNLI는 두 문장의 의미적 관계를 따지는 데이터셋이다. 나는 점심을 먹었다와 나는 밥을 안 먹었다는 모순, 나는 점심을 먹었다와 나는 음식을 먹었다는 함의, 그리고 서로 관련 없는 문장은 중립으로 분류한다. 결국 모델이 문장 간 의미를 얼마나 정확히 파악하는지를 측정한다.

SAMSum은 대화 요약 데이터셋이다. 메신저 대화처럼 짧은 대화가 주어지고, 모델은 그걸 요약해야 한다. 예를 들어 A: 오늘 뭐해? B: 영화 볼 건데. A: 같이 가자라는 대화가 있으면 A와 B가 같이 영화를 보기로 했다라고 요약하는 식이다. 짧은 대화를 읽고 핵심만 뽑아내는 능력을 평가한다. 그리고 이런 요약 과제 성능을 볼 때 쓰는 게 R1, R2, RL이다. R1은 정답 요약과 단어 단위로 얼마나 겹치는지를 보는 지표이고, R2는 연속된 두 단어 bigram이 겹친 비율을 본다. RL은 최장 공통 부분 수열(Longest Common Subsequence)을 기반으로 해서 문장 구조 자체가 비슷한지를 평가한다. 결국 R1은 단어 겹침, R2는 구 겹침, RL은 문장 구조 겹침이라고 보면 된다.

우선 WikiSQL 결과부터 보면, Full Fine-Tuning은 가장 높은 성능을 보여주지만 파라미터 수가 엄청나다. 반면에 LoRA는 훨씬 적은 파라미터만 학습했음에도 불구하고 Full Fine-Tuning에 거의 근접한 정확도를 달성했다. Adapter(H)도 LoRA와 비슷하게 좋은 성능을 보이지만, Prefix 계열(PrefixEmbed, PrefixLayer)은 상대적으로 낮은 정확도를 보인다.

MultiNLI-matched 결과는 더 극적이다. Full Fine-Tuning이 여전히 좋은 성능을 내지만, LoRA와 Adapter(H)는 보다 높은 정확도를 훨씬 더 효율적인 파라미터 사용으로 달성했다. 특히 LoRA는 실질적으로 Full Fine-Tuning 수준의 성능을 뛰어넘으면서도 필요한 파라미터 수는 압도적으로 적다.

그리고 SAMSum에서도 LoRA는 Full Fine-Tuning보다 더 높은 수준의 정확도를 보였다.

즉, LoRA는 단순히 파라미터를 줄이는 수준이 아니라, 적은 자원으로도 풀 파인튜닝급 성능을 낼 수 있다는 걸 명확히 보여준다. 이런 점에서 실제 대규모 모델을 다룰 때 LoRA가 가지는 실용성은 엄청나다고 할 수 있다.

그리고 나는 FT가 항상 좋은 줄 알았는데, 찾아보니 과적합으로 인해 오히려 FT의 성능이 안 좋아질 수도 있다고 한다. 입력 데이터가 적을 경우 FT는 과적합이 일어날 가능성이 있지만 LoRA는 데이터셋이 적어도 적절한 학습이 가능하다.

📝 마무리

오늘은 LoRA에 대해 논문과 실험 결과를 중심으로 정리해 보았다. LoRA는 단순히 파라미터 효율성을 제공하는 수준을 넘어, 실제로 Full Fine-Tuning에 맞먹거나 그 이상의 성능을 적은 자원으로 달성할 수 있음을 보여준다. 특히, 데이터셋 크기가 제한적이거나 리소스가 부족한 상황에서 매우 강력한 대안이 될 수 있다.

다음 글에서는 오늘 정리한 내용을 바탕으로 실제 코드를 통해 LoRA를 활용한 파인튜닝 방법을 자세히 살펴보겠다.

오늘은 갑자기 미니 프로젝트를 하고 싶어져서, Velog 포스트들을 백업해주는 프로그램을 만들려고 한다. 갑자기 미니 프로젝트를 하는 이유는 딱히 없다. 그냥 해보고 싶어졌다. 프로그램 목적은 사용자의 이름을 환경변수로 주면 GrphQL로 Velog 정보를 가져와서 시리즈 별 디렉토리에 포스트들을 저장하는 방식이다.

그리고 Python Package Index 를 통해 배포를 해보고 GitHub Actions 로 자동화 까지 가능하도록 구현할 생각이다.

🔍 GraphQL

내가 GitHub Pages를 만들 때, 그때도 Velog 포스트들을 가져와서 GitHub Pages에 출력 해주는 API를 만들었다. 그떄는 RSS를 사용해서 가져왔다. RSS는 근데 시리즈랑 프로필에 대한 상세한 정보가 없어서, 단순하게 내가 제목에 대괄호로 자체 태그를 만드는 걸 이용해서 포스트들의 시리즈를 구분했다.

이번 프로젝트는 다른 사람들이 전부 사용 가능하도록 GraphQL을 활용해서 시리즈를 추출할 생각이다. 참고로 GraphQL은 Facebook(현 Meta) 가 2012년 개발해서, 2015년 공개한 API 쿼리 언어라고 한다. 클라이언트가 필요한 데이터만 정확히 요청할 수 있도록 설계된 데이터 질의 언어인데, 서버와 클라이언트 간 데이터 통신을 더 유연하고 효율적으로 만들어 준다...

이번에 처음 써보는데, 클라이언트가 원하는 데이터만 응답해주는 것이 특징이다. 내가 느낀 건, GraphQL은 마치 "필요한 만큼만 담아오는 주문표" 같은 느낌이다. REST API에서는 /posts 요청하면 정해진 형식대로 모든 데이터가 쏟아지는데, GraphQL은 title이나 tags만 원하면 그것만 딱 주고, series까지 원하면 그것도 같이 준다. 그래서 불필요한 데이터 전송이 줄고, 필요한 관계형 데이터도 한 번에 가져올 수 있다. 대신 스키마랑 쿼리를 직접 설계해야 해서, 초반에는 좀 낯설고 복잡하게 느껴질 수도 있다. 하지만 익숙해지면 데이터 흐름이 훨씬 깔끔해지고, 특히 내가 이번에 시리즈 정보까지 정리해서 가져오려는 것처럼, RSS보다 훨씬 세밀하게 제어할 수 있는 게 장점이다.

import requests

ENDPOINT = "https://v2.velog.io/graphql"

def gql(query: str, variables: dict | None = None) -> dict:
    """
    GraphQL 쿼리를 실행하는 함수

    Args:
        query (str): GraphQL 쿼리 문자열
        variables (dict | None, optional): 쿼리 변수

    Returns:
        data["data"] (dict): GraphQL 응답 데이터
    """
    payload = {"query": query, "variables": variables or {}}
    res = requests.post(ENDPOINT, json=payload, timeout=15)
    res.raise_for_status()
    data = res.json()
    if "errors" in data:
        msgs = "; ".join(e.get("message", "") for e in data["errors"])
        raise RuntimeError(f"GraphQL 오류: {msgs}")
    return data["data"]

위의 코드는 Velog의 정보를 가져오는 GraphQL 실행 함수이다. 저기 payload 에 내가 원하는 데이터의 정보를 넣게 되면, 해당 정보를 응답해 준다.

QUERY

PROFILE_QUERY = """
query UserProfile($username: String!) {
    user(username: $username) {
        id
        username
        profile {
            display_name
            thumbnail
        }
    }
}
"""

LIST_QUERY = """
query Posts($username: String!, $limit: Int!, $cursor: ID) {
    posts(username: $username, limit: $limit, cursor: $cursor) {
        id
        url_slug
    }
}
"""

DETAIL_QUERY = """
query ReadPost($username: String!, $slug: String!) {
    post(username: $username, url_slug: $slug) {
        id
        url_slug
        title
        thumbnail
        tags
        series { name }
        released_at
        updated_at
        is_markdown
        body
        likes
    }
}
"""

앞에서 말한 것 처럼 GraphQL에서는 Route가 없고, 클라이언트가 무슨 payload를 보내느냐에 따라 오는 응답이 달라진다. 나는 Velog 사용자의 프로필과, 모든 포스트 정보, 그리고 각 포스트의 컨텐츠 3개가 필요하다. 프로필은 PROFILE_QUERY를 통해 요청이 가능했다. 간단하게 Velog 유저 이름을 보내면 프로필 정보를 보내준다. 다음은 LIST_QUERY를 통해서 모든 포스트 정보를 가져왔다. 해당 쿼리가 제일 복잡한데, 이유는 GraphQL은 리스트를 요청할때 한번에 요청이 가능한 한도가 정해져 있어서 cursor 와 limit로 메세지 큐를 보내는 것처럼 잘라서 받아야 한다. 그래서 cursor 와 limit 가 LIST_QUERY를 보면 설정되어 있다. 마지막으로 DETAIL_QUERY는 url_slug 라는 LIST_QUERY에서 가져온 포스트들의 url로 해당 포스트의 컨텐츠를 가져온다. 이렇게 모든 정보를 가져오면 이제 간단하다. 각 시리즈들을 폴더로 만들고, 해당 폴더 안에 시리즈에 해당하는 포스트들을 md파일로 생성하면 된다. 매우 고맙게도 GraphQL은 응답을 md파일로 해줘서 매우 편했다. RSS를 사용할때는 html형식을 md로 바꿔야해서 짜증이 났다.

⚙️ pyproject.toml

이제 해당 프로젝트를 빌드를 하고, 빌드 파일을 배포해보겠다. 파이썬은 배포 환경이 매우 잘 되어 있는데 빌드를 PyPI에 업로드 하며 우리가 흔히 파이썬 패키지를 다운 받을 때 사용하는 pip install이 가능하다.

파이썬에서 패키지를 배포할 때는 pyproject.toml 파일을 작성해야 한다. 이게 일종의 패키지 설정서 역할을 하는데, 프로젝트 이름부터 버전, 의존성, 빌드 방식까지 전부 여기에 정의한다. 내가 작성한 항목들을 하나씩 보면 이렇다:

[project]
name = "velog_sync"
version = "0.1.0"
description = "Velog 글을 Markdown으로 백업 (시리즈별 폴더) — velog_sync PyPI 패키지 실행"
readme = "README.md"
requires-python = ">=3.10"
authors = [{ name = "choi-hyk", email = "blindlchoil@gmail.com" }]
license = { file = "LICENSE" }   
classifiers = [
  "License :: OSI Approved :: MIT License",
]
dependencies = [
  "requests>=2.32.0",
  "tzdata>=2024.1"   
]

[project.scripts]
velog-sync = "velog_sync:main"

[tool.setuptools]
py-modules = ["velog_sync"]

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]

name: "velog_sync"

• PyPI에 올라갈 패키지 이름. pip install velog-sync 할 때 쓰이는 이름이다.
• 참고로 언더바 ( _ ) 는 하이픈 ( - )으로 바뀐다

  version: "0.1.0"

• 패키지 버전. SemVer(주버전.부버전.패치버전) 규칙을 따른다.

description: 패키지 간단 설명.

readme: "README.md"

• PyPI 페이지에 표시될 문서.

requires-python: ">=3.10"

• 파이썬 최소 버전. 여기서는 Python 3.10 이상만 지원하도록 했다.

authors: 작성자 정보. 이름과 이메일을 적을 수 있다.

license = { file = "LICENSE" }

• 라이선스 파일을 명시해준다.

classifiers

• 라이선스의 종류를 명시해준다.

dependencies:

• requests>=2.32.0: HTTP 요청용 라이브러리
• tzdata>=2024.1: 타임존 데이터용 라이브러리
• 패키지를 설치할 때 자동으로 같이 설치된다.

[project.scripts]

velog-sync = "velog_sync:main"

이 프로젝트가 단일 파이썬 파일(velog_sync.py)로 구성되어 있다는 걸 명시한다. 패키지 디렉토리 구조가 아니라 .py 모듈을 main 함수로 실행하면 위와 같이 적는다. 함수는 본인이 알아서 설정 가능하다.

[build-system]

requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

빌드할 때 어떤 툴을 사용할지 지정한다. setuptools와 wheel이 필요하다고 정의했고, setuptools.build_meta를 빌드 백엔드로 사용한다고 명시했다. 이 설정 덕분에 python -m build 명령으로 .tar.gz와 .whl 빌드 파일을 만들 수 있다.

여기서 중요한 건, build-system.requires에 적은 패키지들이 실제 실행 환경에 필요한 건 아니라는 점이다. 이건 어디까지나 빌드 과정에서만 필요한 도구라서, 패키지를 설치하는 사람 입장에서는 신경 쓸 필요가 없다. 그리고 setuptools.build_meta는 일종의 빌드 엔진 역할을 하는데, pip install . 같은 명령을 실행했을 때 내부적으로 build_wheel, build_sdist 같은 함수를 호출해서 배포 파일을 만들어준다.

🚀 PyPI 배포하기

배포를 하려면 PyPI에 계정을 만들고, Token을 받아서 등록을 해야 한다.

이제 해당 토큰을 자신의 로컬에 등록을 하면 된다.

이 토큰을 사용하세요.
이 API 토큰을 사용하려면:

__token__에 사용자 이름을 설정합니다
pypi- 접두사를 포함하여 비밀번호를 토큰 값으로 설정하세요
예를 들어, 프로젝트를 PyPI에 업로드하기 위해 Twine을 사용하는 경우, $HOME/.pypirc 파일을 다음과 같이 설정하세요:

[pypi]
  username = __token__
  password = TOKEN

위의 설정을 보고 로컬에 등록을 하면 로컬에서 배포가 가능하다. 먼저 빌드를 통해 코드를 배포 가능한 형태인 .tar.gz, .whl로 만들어야 한다.

1. 빌드

python -m build 를 실행하면 dist/ 디렉토리에 아래와 같은 파일이 생긴다.

• velog_sync-0.1.0.tar.gz (소스 배포본)
• velog_sync-0.1.0-py3-none-any.whl (휠 파일)

2. 업로드

이제 twine을 사용해서 PyPI에 업로드한다:

twine upload dist/*

여기서 .pypirc 파일에 등록해둔 토큰이 자동으로 사용된다. 업로드가 성공하면 PyPI 패키지 페이지에 바로 반영된다.

3. 설치 확인

업로드가 끝나면 실제로 잘 올라갔는지 pip로 설치해본다:

pip install velog-sync

설치가 잘 되고, 내가 지정한 velog-sync 명령어까지 정상 실행되면 배포 완료다.

🤖 GitHub Actions 배포

name: Publish to PyPI   # 워크플로우 이름 (GitHub Actions 탭에 표시됨)

on:
    push:
        tags: ["v*"]    # 태그가 v로 시작하는 커밋이 push될 때 실행됨 (예: v0.1.0, v1.0.0)

jobs:
    pypi-publish:
        name: Upload release to PyPI  # 잡 이름
        runs-on: ubuntu-latest        # 실행 환경: 최신 Ubuntu GitHub Runner 사용

        permissions:
            contents: read            # 리포지토리 컨텐츠 읽기 권한
            id-token: write           # OIDC(OpenID Connect) 토큰 발급 권한 → PyPI에 인증용

        steps:
            # 1. 코드 체크아웃
            - uses: actions/checkout@v4
              # GitHub Actions 런너에 현재 레포지토리 코드 가져오기

            # 2. Python 설치
            - uses: actions/setup-python@v5
              with:
                  python-version: "3.12"   # 파이썬 3.12 환경 구성

            # 3. 빌드 단계
            - name: Build
              run: |
                  python -m pip install --upgrade pip  # pip 최신화
                  pip install build                    # build 패키지 설치
                  python -m build                      # pyproject.toml 기반으로 dist/에 빌드 산출물 생성

            # 4. PyPI 업로드
            - name: Publish to PyPI
              uses: pypa/gh-action-pypi-publish@release/v1
              with:
                  skip-existing: true  # 이미 업로드된 파일이 있으면 스킵(중복 업로드 방지)

위와 같이 구성이 가능한데, 살펴볼 점은 태그랑 인증 방법이다. GitHub Actions는 태그 설정을 통해 배포 자동화가 이루어진다. 예를 들어 git tag v0.1.0 을 하게 되면, 바뀐 버전이 해당 액션으로 자동 배포가 이루어진다.

다음은 PyPI의 인증 방식인데, 기존에 로컬에서는 Token을 발급받아서, 배포를 하였는데, PyPI는 GitHub Actions와 같이 자동화 툴들을 위해 PyPI Trusted Publisher라는 방법을 제공한다. 예전처럼 .pypirc에 비밀번호 저장하는 게 아니라, GitHub OIDC(OpenID Connect) 토큰을 이용해서 PyPI Trusted Publisher로 인증한다. 즉, GitHub 저장소와 PyPI 계정을 연결해두면 비밀번호/토큰 노출 없이 안전하게 배포 가능하다. PyPI Trusted Publisher 를 사용하려면 자신의 PyPI 계정에 해당 GitHub repo를 등록하면 된다.

난 이렇게 등록을 하였다.

실행을 할때는 패치된 버전의 코드와 pyproject.toml 의 버전을 올리고 push와 push tag를 해줘야 한다. 참고로 git tag 명령어를 통해 tag를 등록하고 기존의 푸쉬 방법 처럼 git push origin v0.1.0 과 같은 방법으로 배포를 해줄 수 있다. 이때 주의할 점은 반드시 패치된 버전의 코드와 pyproject.toml 의 버전을 푸쉬해 놓은 상태여야 한다.

🔄 GitHub Actions로 velog-sync 자동화 하기

이제 로컬 배포와 GitHub Actions 배포도 구성을 하였으니, 실제로 사용자들이 쓸 수 있도록 GitHub Actions의 yml 파일을 제공하면 된다. 로컬에서 사용할 사람은 로컬에서 실행해서 백업을 진행하면 되고 나는 사용자들이 매일 03:00 시에 자동으로 Velog 포스트들을 GitHub repo에 업로드 되도록 yml 파일을 구성하였다.

name: velog-sync (daily KST 03:00)

on:
    schedule:
        - cron: "0 18 * * *" # 매일 03:00 KST
    workflow_dispatch: {}

permissions:
    contents: write

jobs:
    sync:
        runs-on: ubuntu-latest
        environment: velog_sync
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Set up Python
              uses: actions/setup-python@v5
              with:
                  python-version: "3.11"

            - name: Install velog-sync
              run: |
                  python -m pip install --upgrade pip
                  pip install velog-sync

            - name: Run velog-sync
              env:
                  VELOG_USERNAME: ${{ vars.VELOG_USERNAME }}
              run: velog-sync

            - name: Configure Git
              run: |
                  git config user.name "github-actions[bot]"
                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

            - name: Rebase with remote main
              run: |
                  git pull --rebase --autostash origin main

            - name: Commit if changed
              env:
                  TZ: Asia/Seoul
              run: |
                  if [ -n "$(git status --porcelain)" ]; then
                    DATE_KST="$(date +'%Y-%m-%d %H:%M:%S %Z')"
                    git add -A
                    git commit -m "chore: velog sync @ ${DATE_KST}"
                    git push
                  else
                    echo "No changes to commit."
                  fi

yml 파일에서는 내가 만든 패키지인 velog-sync를 다운받고 해당 패키지를 사용해서 등록한 유저 환경변수를 통해 GitHub에 업로드 해준다.

배포가 완료된 모습이다. 아래 링크에서 확인 가능하다. https://github.com/choi-hyk/Velog

🏁 마무리

오늘은 velog-sync라는 패키지를 만들고 배포까지 해보았는데, repo를 확인하고 이슈가 등록되면 개선해 나갈 생각이다. 그리고 지금은 Velog 가 조회수를 보여주는 API가 없지만, access_token을 통해 조회수를 확인 가능하다고 들었다. 그래서 해당 패키지에 access_token을 등록하여 조회수를 확인하는 기능을 넣고 싶다. 해당 패키지는 아래 링크에서 확인 가능하고, 이슈가 있으면 언제든지 등록을 해주길 바란다.

[PyPI] velog-sync [GitHub] velog-sync

이번에는 Adapter Pattern에 대해서 알아보겠다. GOF 디자인패턴 책에서는 구조패턴을 설명할 때 Adapter Pattern 을 제일 먼저 설명한다. Adapter Pattern은 말 그대로 기존의 클래스 인터페이스에 다른 라이브러리나 인터페이스를 결합하기 위해 사용하는 패턴이다. 그래서 구조는 매우 직관적이다. 기존에 우리가 사용할 인터페이스와 결합할 인터페이스를 다중 상속 받는 클래스 어댑터를 생각해 볼 수 있고, 다른 방법으로는 결합할 인터페이스를 인스턴스로 가지고 있는 객체 어댑터를 생각해 볼 수 있다

클래스의 인터페이스를 사용자가 기대하는 인터페이스 형태로 적응(변한)시킵니다. 서로 일치하지 않는 인터페이스를 갖는 클래스들을 함께 동작시킵니다.

언제 사용하나? 📌

책에서는 어댑터 패턴을 Shape라는 그래픽을 관리하는 클래스에 TextView 기능을 결합하는 예제로 설명을 한다.

위의 그림은 객체 어댑터를 표현하고 있다. 그 이유는 TextShape가 TextView를 상속하지 않고 포함(Composition) 하고 있기 때문이다. 즉, TextShape 안에 TextView 인스턴스를 멤버 변수로 두고, Shape의 인터페이스를 구현하면서 내부적으로 TextView의 기능을 호출해주는 방식이다.

반면에 클래스 어댑터 방식이라면 TextShape가 Shape를 상속함과 동시에 TextView도 상속받아야 한다. 즉, 다중 상속을 이용해서 TextView 기능을 바로 가져오는 구조이다. 하지만 이렇게 하면 유연성이 떨어지고, 언어 제약(자바는 다중 상속 불가) 때문에 현실적으로 잘 안 쓰이는 경우가 많다.

구조 🏗️

클래스 어댑터

객체 어댑터

구조는 매우 간단하다. 클래스 어댑터는 상속(Inheritance) 을 이용해서 구현하고, 객체 어댑터는 합성(Composition) 을 이용해서 구현한다. 즉, 클래스 어댑터는 이미 존재하는 클래스를 직접 상속받아 새로운 인터페이스를 맞추는 방식이고, 객체 어댑터는 기존 클래스를 멤버 변수로 두고 그 객체의 기능을 위임(delegate)하는 방식이다.

클래스 어댑터는 상속을 쓰는 만큼 기존 클래스의 세부 구현에 강하게 묶인다. 대신 성능상 조금 더 단순하고 직접적이다.

객체 어댑터는 합성을 쓰기 때문에 더 유연하고, 다른 클래스와도 쉽게 조합할 수 있다. 다형성을 활용하기에도 적합하다.

정리하면, "빠르고 단순하게"라면 클래스 어댑터, "유연하고 확장성 있게"라면 객체 어댑터를 쓰는 게 맞다.

구현 💻

#include <iostream>
#include <string>
#include <memory>

using namespace std;

struct Point { int x{}, y{}; };
struct Size  { int w{}, h{}; };
struct Rect  { int x1{}, y1{}, x2{}, y2{}; };

ostream& operator<<(ostream& os, const Rect& r) {
    return os << "Rect{(" << r.x1 << "," << r.y1 << ") ~ (" << r.x2 << "," << r.y2 << ")}";
}

class Manipulate;
class TextManipulator;

class Shape{
    public:
        ~Shape()  = default;
        virtual void boundingBox() const = 0;
        virtual unique_ptr<Manipulate> createManipulate() const = 0;
};

class Manipulate {
    public:
        Manipulate() = default;               
        virtual ~Manipulate() = default;
        virtual void manipulate() const {
            std::cout << "Shape 조작\n";
        }
};

class TextManipulator : public Manipulate
{
    public:
        void manipulate() const override {
            std::cout << "TextShape 조작\n";
        }
};

class Line : public Shape
{
    public:
        Line(Point p1, Point p2) : p1_(p1), p2_(p2) {}

        void boundingBox() const override {
            Rect r{
                min(p1_.x, p2_.x),
                min(p1_.y, p2_.y),
                max(p1_.x, p2_.x),
                max(p1_.y, p2_.y)
            };
            std::cout << "[Line] boundingBox = " << r << "\n";
        }

        unique_ptr<Manipulate> createManipulate() const override {
            return make_unique<Manipulate>();
        }

    private:
        Point p1_{}, p2_{};
};

class TextView{
    public: 
        virtual ~TextView() = default;
        Point getOrigin() const { return origin_; }
        Size  getExtent() const { return extent_; }

        virtual bool isEmpty() const = 0;

    protected:
        void setOrigin(Point p) { origin_ = p; }
        void setExtent(Size s)  { extent_ = s; }

    private:
        Point origin_{0, 0};
        Size  extent_{0, 0};
};

class TextShape : public Shape, private TextView
{
    public:
        TextShape(Point origin, Size extent, bool empty = false) : empty_(empty) {
            setOrigin(origin);
            setExtent(extent);
        }

    void boundingBox() const override {
        Point o = getOrigin();
        Size  s = getExtent();
        Rect r{o.x, o.y, o.x + s.w, o.y + s.h};
        cout << "[TextShape] origin=(" << o.x << "," << o.y
            << "), extent=(" << s.w << "," << s.h << ") -> boundingBox = "
            << r << "\n";
        }

        unique_ptr<Manipulate> createManipulate() const override {
            return make_unique<TextManipulator>();
        }

        bool isEmpty() const override {
            return empty_;
        }

    private:
        bool empty_{false};
};

int main() {
    unique_ptr<Shape> s1 = make_unique<Line>(Point{10, 5}, Point{2, 20});
    s1->boundingBox();
    s1->createManipulate()->manipulate();

    unique_ptr<Shape> s2 = make_unique<TextShape>(Point{100, 200}, Size{50, 20});
    s2->boundingBox();
    s2->createManipulate()->manipulate();

    return 0;
}

책에서 예제로 든 Shape에 TextView를 결합하는 클래스 어댑터이다. Shape 는 2개의 기능을 제공하는데 Shape를 생성하면 경계선 박스를 만드는 함수 boundingBox() 그리고 Shape를 이동시키거나 조작하는 조작기를 생성하는 createManipulate() 이 2가지의 기능을 제공한다. 이때 기존에 원래 존재하는 Line은 Shape의 기능을 그대로 상속받아 구현하고 있다. 우리는 TextShape라는 어댑터를 통해 TextView를 Shape에서 사용할 수 있도록 하는 것이 목표이다.

Adaptee

class TextView{
    public: 
        virtual ~TextView() = default;
        Point getOrigin() const { return origin_; }
        Size  getExtent() const { return extent_; }

        virtual bool isEmpty() const = 0;

    protected:
        void setOrigin(Point p) { origin_ = p; }
        void setExtent(Size s)  { extent_ = s; }

    private:
        Point origin_{0, 0};
        Size  extent_{0, 0};
};

TextView는 3개의 기능이 존재하는데, 자신의 위치와 크기를 알려주는getOrigin(), getExtent() 두가지 기능과 텍스트가 채워져 있는지 아닌지를 알려주는 isEmpty()가 있다. 따라서 Target인 Shape 가 제공하는 두가지 기능인 boundingBox() 와 createManipulator()를 연동하기 위해서 기존의 TextView의 기능을 적절히 조합해서 만들거나 아예 새로운 코드를 넣어서 기능을 연동시켜야 한다.

Adapter

class TextShape : public Shape, private TextView
{
    public:
        TextShape(Point origin, Size extent, bool empty = false) : empty_(empty) {
            setOrigin(origin);
            setExtent(extent);
        }

    void boundingBox() const override {
        Point o = getOrigin();
        Size  s = getExtent();
        Rect r{o.x, o.y, o.x + s.w, o.y + s.h};
        cout << "[TextShape] origin=(" << o.x << "," << o.y
            << "), extent=(" << s.w << "," << s.h << ") -> boundingBox = "
            << r << "\n";
        }

        unique_ptr<Manipulate> createManipulate() const override {
            return make_unique<TextManipulator>();
        }

        bool isEmpty() const override {
            return empty_;
        }

    private:
        bool empty_{false};
};

TextShape는 말한 것 처럼 다중상속을 통해 Shape 와 TextView를 받고 있다. 여기서 중요한 점이 Adaptee인 TextView는 Private로 해야 한다. 이유는 당연히 Target이 Adaptee를 Adater를 통해 사용할 때 내부의 구조를 알 필요가 없기 때문이다. boundingBox()를 보면 TextView의 getOrigin() 와 getExtent()를 사용해서 위치와 크기를 얻고 경계 박스를 구현하는 것으로 연동을 완료했다. 그런데 createManipulator()는 기존의 기능으로 연동이 불가능 하므로 새로운 TextManipulator를 생성해서 연동해야 한다.

TextManipulator

class TextManipulator : public Manipulate
{
    public:
        void manipulate() const override {
            std::cout << "TextShape 조작\n";
        }
};

이렇게 만든 TextManipulator를 통해 완벽히 연동이 되었다. 이제 클라이언트는 기존에 Shape를 이용하는 방식으로 TextView를 이용가능하다.

Client

int main() {
    unique_ptr<Shape> s1 = make_unique<Line>(Point{10, 5}, Point{2, 20});
    s1->boundingBox();
    s1->createManipulate()->manipulate();

    unique_ptr<Shape> s2 = make_unique<TextShape>(Point{100, 200}, Size{50, 20});
    s2->boundingBox();
    s2->createManipulate()->manipulate();

    return 0;
}

s1으로 Line을 만들고 boundingBox() 와 createManipulate()를 사용하고 있다. 그리고 s2로 TextShape를 만들고 똑같이 boundingBox() 와 createManipulate()를 사용하고 있다. 이렇게 완벽히 연동이 되었다.

이번에는 객체 어댑터는 어떻게 구현하는지 알아보자.

Adapter

class TextShape : public Shape{
public: 
    TextShape(shared_ptr<TextView> tv) : tv_(std::move(tv)) {}

    void boundingBox() const override {
        Point o = tv_->getOrigin();
        Size  s = tv_->getExtent();
        Rect r{o.x, o.y, o.x + s.w, o.y + s.h};
        cout << "[TextShape(ObjectAdapter)] origin=(" << o.x << "," << o.y
            << "), extent=(" << s.w << "," << s.h << ") -> boundingBox = "
            << r << "\n";
    }

    unique_ptr<Manipulate> createManipulate() const override {
        return make_unique<TextManipulator>();
    }

    bool empty() const { return tv_->isEmpty(); }

private:
    shared_ptr<TextView> tv_;
};

TextShape는 TextView를 공유 포인터로 생성하면서 생성된다. 따라서 TextView를 합성하여 인스턴스로 가지고 있다.

Client

int main() {
    unique_ptr<Shape> s1 = make_unique<Line>(Point{10, 5}, Point{2, 20});
    s1->boundingBox();
    s1->createManipulate()->manipulate();

    auto tv = make_shared<SimpleTextShape>(Point{100, 200}, Size{50, 20});
    unique_ptr<Shape> s2 = make_unique<TextShape>(tv);
    s2->boundingBox();
    s2->createManipulate()->manipulate();

    return 0;
}

따라서 먼저 TextShape를 생성한 다음 Shape에 주입을 해야 한다. 만약에 TextView 여러개의 서브클래스로 다양한 기능이 있다고 해보자.

class SimpleTextView : public TextView {
public:
    explicit SimpleTextView(Point origin, Size extent, bool empty = false)
        : empty_(empty)
    {
        setOrigin(origin);
        setExtent(extent);
    }

    bool isEmpty() const override { return empty_; }

private:
    bool empty_{false};
};

이렇게 SimpleTextView라는 TextView의 기능을 확장해주는 서브클래스를 바로 주입이 가능하다. 그러면 우리는 객체 어댑터를 통해 TextShape를 여러가지 형태로 만들 수 있을 것이다. 이것이 클래스 어댑터에는 없는 객체 어댑터의 장점이다.

마무리

어댑터 패턴은 서로 다른 인터페이스를 가진 클래스들을 연결해주는 역할을 한다고 보면 된다. 클래스 어댑터는 상속으로, 객체 어댑터는 합성으로 풀어내는데, 결국 상황에 따라 어떤 방식을 선택할지가 달라진다. 내가 글에서 보여준 것처럼, Shape와 TextView를 연동할 때도 두 가지 방식 모두 동작은 되지만, 유연성과 확장성을 생각하면 객체 어댑터 쪽이 좀 더 현실적이라고 할 수 있다.

다음 글에서는 구조 패턴 중에서 Bridge Pattern을 소개할 생각이다. 브리지 패턴은 이름처럼 추상과 구현을 분리해서 독립적으로 확장할 수 있게 만들어주는 패턴인데, 어댑터 패턴과 비교하면 더 일반화된 구조를 갖는다. 즉, 인터페이스 불일치를 해결하는 게 목적이었던 어댑터와 달리, 브리지는 애초에 확장 가능성을 열어두는 구조 설계에 초점이 맞춰져 있다

[참고] Adapter Pattern

Transformer 구조를 이해했으니, 이제 자연스럽게 "그럼 이렇게 만들어진 모델을 어떻게 내 태스크에 맞게 쓰는가?" 라는 질문이 생긴다. 바로 여기서 Fine-tuning(파인튜닝) 이라는 개념이 나온다.

LLM이나 Transformer 모델은 처음에 Corpus 로 학습된다. 이 과정에서 모델은 언어의 전반적인 패턴, 문법, 의미 관계를 배우게 되는데, 이걸 사전학습(Pre-training) 이라고 한다. 앞의 글에서 살펴본 Transformer 과정이 사전학습을 진행하는 과정이다. 하지만 이렇게 학습된 모델을 바로 특정 태스크에 쓰기는 어렵다. 그 이유는 모든 도메인 지식을 아우를 수는 없기 때문이다. Corpus를 통해 LLM들은 방대한 양의 지식을 가지고 있지만 새로 생성된 지식이나, 특정 구조에 맞춰서 입력을 만들어야하는 모델이 필요하다면, 기존의 LLM 모델들을 자신의 목적에 맞게 업그레이드(?) 하고 싶을 것이다.

그래서 하는 게 바로 Fine-tuning이다. 물론 엄밀히 말하면 업그레이드는 아니다. 원리를 간단히 말하면 이렇다.

Transformer 내부는 기본적으로 Attention, FFN, Embedding 같은 블록으로 구성되어 있고, 이 블록들 안에는 수많은 가중치(Weight) 가 들어있다. Pre-training에서 이미 이 가중치들이 언어를 잘 다룰 수 있게 학습되어 있다. Fine-tuning에서는 이렇게 이미 구성된 LLM 에 내 태스크 데이터셋을 다시 넣고, 역전파(Backpropagation) 를 통해 가중치를 조금씩 조정한다. 여기서 역전파를 많이 들어봤을텐데. 사실 Pre-training 과정에서 이미 모델은 역전파를 통해 가중치를 조정한다. 파인튜닝은 이러한 역전파를 새로운 데이터셋으로 시도하는 것이라 보면 된다. Transformer 에서 모델을 완성하기 위해 최초의 Corpus로부터 각 layer의 가중치를 업데이트 하는 것을 반복하는 것이 Pre-training에서 진행되는 과정 이고, Fine-tuning은 완성된 모델을 다시 원하는 출력을 만드는 모델로 바꾸기 위해 새로운 입력을 넣고 가중치를 업데이트 하는 것을 반복하는 것 이다. 따라서 이전 글의 Transformer의 구조만 잘 이해하고 있으면, Fine-tuning은 이해하기 쉬울 것이다. 그러므로 이번 글에서는 Fine-tuning 자체 보다는 역전파(Backpropagation) 의 과정을 설명할 생각이다.

🖇️ 역전파(Backpropagation)

사실 ** Fine-tuning이라는 개념은 Transformer가 등장하기 전부터 존재했다.** 예전에는 CNN 같은 컴퓨터 비전 모델을 학습할 때도, 대규모 데이터셋으로 학습된 모델의 가중치를 가져와 새로운 이미지 분류 작업에 맞게 일부 층만 조정하는 방식으로 활용했다. 즉, fine-tuning 자체는 오래된 개념이지만, 현대 LLM에서는 Transformer 아키텍처 위에서 이루어진다는 점이 다르다. 따라서 우리는 현대 모델들이 사용하는Transformer 구조를 기반으로 이해하면 된다.

Transformer를 기반으로 하는 Fine-tuning을 구체적으로 보면 Self-Attention, Multi-head Attention 같은 구조는 그대로 두고, 내부 가중치 행렬 $W^Q, W^K, W^V$, 그리고 Feed Forward Network(FFN)의 $W_1, W_2$ 같은 파라미터들이 다시 학습 대상이 된다. 이때 학습 과정은 Pre-training 때와 똑같이 순전파 → 손실 계산 → 역전파 → 가중치 업데이트로 돌아간다. 차이는 단지 데이터셋의 목적이다. Pre-training 때는 일반 텍스트 전체, Fine-tuning 때는 특정 태스크에 맞는 데이터라는 점이 다르다.

용어들에 대해서 헷갈릴 것 같은데, 정리를 해보겠다.

• 순전파(Forward Propagation): 입력 데이터를 모델에 넣어서 예측값을 뽑아내는 과정. Transformer라면 입력 토큰이 Self-Attention, Multi-head Attention, FFN 등을 거쳐서 최종 출력 확률로 바뀌는 걸 의미.

• 손실(Loss): 모델의 예측과 정답 사이의 차이를 수치로 나타낸 값. Cross-Entropy 같은 걸 많이 쓰고, 이 값이 클수록 모델이 정답과 멀리 있는 것.

• 역전파(Backpropagation): 손실 값을 기준으로 어떤 가중치가 얼마나 잘못했는지 를 계산해서 뒤로 흘려보내는 과정. 각 층의 $W^Q, W^K, W^V, W_1, W_2$ 같은 파라미터가 손실에 얼마나 기여했는지 기울기를 구함.

• 가중치 업데이트(Weight Update): 역전파로 구한 기울기를 바탕으로 실제 파라미터 값을 조금씩 수정하는 단계. 보통 SGD, Adam 같은 옵티마이저 가 이 역할을 담당.

손실 계산부터 어떻게 파인튜닝이 진행되는지 살펴보자

손실 계산

예측 확률 $p$와 정답 레이블 $y$를 비교해서 손실 $\ell$을 구한다.

• Cross-Entropy 손실 기준으로는 $\ell = -\sum y \log p$.

음의 로그 함수를 사용해서, 정답 클래스의 $p$를 음의 로그 스케일로 보면, 정답 확률이 0에 가까워 지면, 손실 $\ell$은 무한대로 증가하고 1에 가까워지면 $\ell$은 0에 가까워질 것이다.

오차 신호(Gradient) 계산

손실을 로짓 $z$에 대해 미분하면

$$ \frac{\partial \ell}{\partial z} = p - y $$

이 값이 나온다 (값을 도출하는 것은 논문이나 다른 글에서 확인바람...). 이게 바로 역전파로 흘러가는 오차 신호다. 로짓 $z$ 는 예측 확률 $p$ 를 소프트맥스를 하여 확률 분포로 나타내기 직전의 상태 이다. 따라서 확률 데이터가 아닌, 단순히 점수(score)로서 정답과 얼마나 가까운지를 상대적으로 보여주는 값 이라 보면 된다. 따라서 "손실률에 대해 로짓을 미분했다" 는 것은, 로짓 값이 바뀔 때 손실이 얼마나 영향을 받는지를 수치로 나타내는 것 이다.

클래스를 개(dog), 고양이(cat), 소(cow)로 두고 예시를 들어보자. 정답은 고양이라고 하자.

1. 모델이 낸 로짓 (점수)

$$ z = [2.0,; 1.0,; -0.5] $$

• 개 = 2.0
• 고양이 = 1.0
• 소 = -0.5

로짓은 아직 확률이 아니라 “점수” 같은 거라 보면 된다. 여기서는 개가 가장 높은 점수를 가지고 있다. 따라서 오차가 있는 출력 값이다.

2. 소프트맥스 → 확률 분포

$$ p = \text{softmax}(z) = [0.62,; 0.34,; 0.04] $$

• 개일 확률 = 62%
• 고양이일 확률 = 34%
• 소일 확률 = 4%

정답은 고양이인데, 모델은 개가 더 맞다고 본 상황이므로 이를 통해서 오차 신호를 계산할 수 있다.

3. 오차 신호 계산

$$ p-y = [0.62-0,; 0.34-1,; 0.04-0] = [0.62,; -0.66,; 0.04] $$

4. 해석

• 개(dog): $+0.62$ → 정답이 아닌데 너무 높게 잡았다. 점수를 내려야 한다.
• 고양이(cat): $-0.66$ → 정답인데 확률이 낮다. 점수를 올려야 한다.
• 소(cow): $+0.04$ → 정답이 아닌데 살짝 점수를 줬다. 조금 줄여야 한다.

결국 $p-y$는 단순한 차이가 아니라, 가중치를 어느 방향으로 바꿔야 하는지 알려주는 오차 신호다.

• 정답 클래스는 음수 → 점수를 올려야 한다.
• 오답 클래스는 양수 → 점수를 내려야 한다.

역전파 진행

이 오차 신호가 FFN, Multi-head Attention, Embedding까지 거꾸로 내려가면서 각 파라미터의 기울기 $\frac{\partial \ell}{\partial W}$를 계산한다.

경사하강법으로 가중치 업데이트

계산된 기울기를 바탕으로 옵티마이저가 가중치를 업데이트한다. 가장 기본적인 SGD는 다음과 같다.

$$ W \leftarrow W - \eta \cdot \frac{\partial \ell}{\partial W} $$

• $\eta$: 학습률(learning rate).
• 기울기가 양수면 가중치를 줄이고, 음수면 가중치를 늘려서 손실을 줄이는 방향으로 움직인다.

위의 예시로 다시 살펴보면 이렇게 된다.

$$ g ;=; p-y ;=; [,0.62,; -0.66,; 0.04,] $$

$$ \frac{\partial \ell}{\partial b} = g,\qquad $$

$$ W \leftarrow W - \eta,\frac{\partial \ell}{\partial W} \quad,\quad b \leftarrow b - \eta,\frac{\partial \ell}{\partial b} $$

예를 들어 $\eta=0.1$이면

$$ b' = b - 0.1,[,0.62,; -0.66,; 0.04,] = \big[b_1-0.062,; b_2+0.066,; b_3-0.004\big] $$

• 개(dog): $g_1=+0.62\Rightarrow b_1$ 감소(점수↓)
• 고양이(cat): $g_2=-0.66\Rightarrow b_2$ 증가(점수↑)
• 소(cow): $g_3=+0.04\Rightarrow b_3$ 소폭 감소(점수↓)

$g_k>0$ (오답을 과대평가) ⇒ $z_k$ 감소

$g_k<0$ (정답을 과소평가) ⇒ $z_k$ 증가

이후 $z'$에 softmax를 다시 적용하면, 고양이 확률이 올라가고 개/소는 내려가는 방향으로 조정된다.

한마디로 요약하자면

정답인데 확률을 높여야 된다!

• 로짓 $z$를 크게 만들어서 손실률을 줄여야 하므로 기울기 $g$가 음수
• 기울기가 음수 이므로 경사하강법 $W -\eta{g}$ 적용 했을 때, 가중치가 증가 함

오답인데 확률이 너무 높다!

• 로짓 $z$를 작게 만들어서 손실률을 줄여야 하므로 기울기 $g$가 양수
• 기울기가 양수이므로 경사하강법 $W -\eta{g}$ 적용 했을 때, 가중치가 감소 함

반복

이 과정을 수천~수억 번 반복하면서 모델은 점점 내 데이터셋에 맞게 적응한다. 결국 Fine-tuning은 손실을 계산하고, 그걸 역전파로 풀어내서, 경사하강법으로 가중치를 조금씩 고쳐나가는 과정이다. 새로운 모델을 처음부터 만드는 게 아니라, 이미 언어 감각을 익힌 Transformer를 내가 원하는 태스크에 맞게 조금씩 조율하는 작업이라고 보면 된다. 그리고 이러한 반복을 epoch 이라고 한다

😘 마무리

이번에는 파인튜닝의 역전파의 기본 원리에 대해 알아보았다. 다음글에서는 현대 모델에서 표준으로 자리잡은 파인튜닝 기법인 LoRA(Low-Rank Adaptation) 를 살펴보고, 실제 코드와 함께 파인튜닝 과정을 정리해보겠다.

오늘은 현대 LLM의 모델들이 활용중인 가장 중요한 요소인 Transformer에 대해서 알아보겠다. Transformer는 2017년 Google에서 발표한 「Attention is All you need」 논문에서 소개된 모델이다.

Attention is All you need

해당 논문에서는 Transformer 아키텍처가 고안된 이유를 RNN의 단점을 서술하면서 설명하고, Transformer 아키텍처의 구성 방식을 각 layer를 기준으로 설명을 한다. 내용이 너무 어려워서 여러가지 영상이랑, 해석본도 찾아보면서 최대한 정리를 해보았다...

✏️ Transformer가 고안된 이유

「Attention is All you need」 에서는 먼저 RNN의 단점을 이야기하는데, RNN은 3가지의 주요 단점이 있다.

• 순차적 처리: RNN은 단어를 순서대로 처리하는 구조 때문에 병렬 처리가 불가능하다. 이는 대규모 데이터 학습에 많은 시간이 소요되는 원인이 된다.

• 장기 의존성(Long-term Dependency) 문제: 문장이 길어질수록 초반부 단어의 정보가 점차 희미해진다. 이로 인해 문장의 앞부분에 있는 중요한 맥락 정보를 활용하기 어렵다.

• 고정된 컨텍스트 벡터: RNN은 문장 전체의 정보를 하나의 고정된 크기 벡터에 압축하는데, 이 과정에서 정보 손실이 발생하여 복잡한 문장의 의미를 온전히 담기 어렵다.

간단하게 RNN 문장이 길어질수록 성능이 떨어지고, 문장을 순서대로 처리를 해야되기 때문에, 병렬처리가 불가능하다. 또한 RNN과 더불어 CNN(Convolutional Neural Network) 이라는 신경망 기술에 대해서도 설명을 하였는데, 간단하게 CNN은 "합성곱 신경망"이라는 기술이다. CNN은 이미지 및 비디오와 같은 2차원 또는 3차원 데이터 처리에 특화된 딥러닝 모델인데, 데이터의 특징을 추출하여 분류나 탐지 같은 작업에 강점을 가진다. 하지만 CNN 또한 문장 내 단어 간의 장기적인 의존 관계 를 학습하는 데는 한계가 있었다.

즉, RNN은 순차 처리와 장기 의존성 문제, CNN은 문장의 전체 맥락을 포착하기 어렵다는 문제를 가지고 있었다.

따라서 Transformer는 에서 설명한 RNN과 CNN의 문제점인 병럴처리, 장기 의존성 그리고 다양한 문장의 표현을 고려한 모델이다.

🛠️ 구조

위의 구조를 보면 머리가 좀 아파올 것 같은데, layer 별로 나눠서 이해해보면 좀 괜찮을 것이다. 그림은 Transformer에서 사용하는 Encoder와 Decoder의 구조를 나타낸 그림이다. Encoder는 입력이 주어지면, 해당 입력을 기반으로 입력 데이터들 관의 관계를 파악하고, Decoder는 해당 입력과 Encoder에서 생성된 관계를 통해 다음 데이터를 예측한다. 이제 이 그림을 각 layer마다 살펴보겠다.

Input Embedding

제일 먼저 Encoding에서 보이는 Input Embedding 은 자연어를 Tokenizer 해서 벡터화를 한 데이터이다.
Tokenizer 와 Embedding은 추후에 다른 글로 알아보도록하고,

Embedding으로 벡터화를 하게 되면 각 토큰의 특징을 나타내는 차원이 생긴다. 예를 들어서 바나나 라는 토큰이 있으면, 해당 토큰은 여러개의 특징으로 나타낼 수 있다.

각 특징은 벡터의 한 요소로 표현되며, 예를 들어 바나나라는 단어가 4차원 벡터로 임베딩 되었다고 하면,

바나나 → [0.12, -0.87, 0.33, 0.55]

이런 식으로 수치화된다. 이 벡터의 각 값은 단순히 숫자가 아니라, 의미적인 특징을 압축한 값이다. 어떤 값은 과일과 관련된 의미를, 또 어떤 값은 음식이라는 카테고리적 의미를, 또 다른 값은 다른 단어들과의 관계 속에서 파생된 의미를 담고 있다.

이렇게 만들어진 Input Embedding은 이후 Positional Encoding 과 결합된다. Transformer는 RNN처럼 순차적으로 단어를 처리하지 않기 때문에, 단어의 순서 정보를 따로 제공해야 한다. 이때 사용하는 것이 Positional Encoding(위치 인코딩) 인데, 잠시 후에 알아보겠다.

Attention

Attention은 사실 Transformer에서 고안된 기법이 아니다. Attention은 벡터화 되어서, 각 특징들을 벡터로 나타내어진 자연어의 관계를 파악하는 기법이다. 「Neural Machine Translation by Jointly Learning to Align and Translate」이라는 2014년 논문에서 RNN을 통한 기계번역을 개선하기 위해 고안된 기술이라고 한다.

그렇다면 드는 생각이, Transformer는 기존의 딥러닝 모델들과는 무엇이 다르냐는 것이다. Attention을 적용하는 기법에서 Transformer는 Self Attention과 Multi Head Attention 이라는 발전된 기법을 사용한다.

먼저 Attention의 기본 원리에 대해서 알아보자.

$$ Attention(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$

위의 식은 「Attention is All you need」 에서 설명하는 Attention을 구하는 식이다.

Attention은 크게 세 단계로 진행된다. 먼저 입력 데이터는 Query(Q), Key(K), Value(V) 세 가지로 변환된다. 이때 Query는 현재 단어가 "무엇을 찾고 있는가" 를 나타내고, Key는 "어떤 정보를 가지고 있는가" 를, Value는 "그 정보 자체" 를 의미한다.

예를 들어서 검색창에 LLM과 관련된 논문 을 입력하면 해당 입력이 $Q$ 가 될 것이다. 그리고 검색 이후 나온 여러가지 웹 사이트와 논문들은 $K$ 가 되고 실제 논문 데이터는 $V$ 가 될 것이다.

이러한 $Query(Q)$, $Key(K)$, $Value(V)$ 를 만드는 방식이 가중치 $W$ 를 적용하는 것이다. 입력 임베딩 $X \in \mathbb{R}^{n \times d_{\text{model}}}$에 대해, 각각의 행렬은 다음과 같이 정의된다.

$$ Q = XW^Q, \quad K = XW^K, \quad V = XW^V $$

여기서 $W^Q \in \mathbb{R}^{d_{\text{model}} \times d_k}$, $W^K \in \mathbb{R}^{d_{\text{model}} \times d_k}$, $W^V \in \mathbb{R}^{d_{\text{model}} \times d_v}$ 는 모두 학습 가능한 파라미터이다.

즉, 하나의 입력 임베딩이 들어오더라도 서로 다른 가중치 행렬과 곱해지면서, 질문을 하는 벡터(Q), 조건을 제공하는 벡터(K), 실제 정보를 전달하는 벡터(V) 로 투영된다.

그리고 $W^Q \in \mathbb{R}^{d_{\text{model}} \times d_k}$, $W^K \in \mathbb{R}^{d_{\text{model}} \times d_k}$, $W^V \in \mathbb{R}^{d_{\text{model}} \times d_v}$ 에서 보통 $d_k$, $d_v$는 $\frac{d_\text{model}}h$ 로 차원을 계산하게 되는데, 이와 관련해서 왜 가중치들의 집합의 크기가 $d_{\text{model}}\times d_k$, $d_{\text{model}}\times d_v$ 가 되는지 그리고 $h$가 무엇인지 궁금할 것이다. 일단 기억만 하고 있어라, 뒤에 Multi Head Attention에서 $h$ 가 무엇이고 집합의 크기가 왜 저렇게 나오는지, 그리고 차원을 맞추는 이유가 무엇인지 설명하겠다.

$Q$, $K$, $V를 구하는$ 과정은 단순한 선형 변환으로 보일 수 있지만, 학습을 통해 $W^Q, W^K, W^V$가 점차적으로 최적화되면서, Attention이 각 단어 간의 관계를 더 정교하게 파악할 수 있도록 만드는 핵심 장치가 된다. 결국 이 단계는 "입력 임베딩을 서로 다른 관점에서 바라보는 방법"을 모델이 스스로 학습하는 과정 이라고 이해할 수 있다.

그리고 이러한 가중치들은 최종적으로 디코더를 통해 생성된 확률 분포를 기반으로 손실 계산을 수행하고, 이 손실을 줄이기 위해 역전파와 가중치 조정 과정을 거쳐 업데이트된다. 이렇게 조정된 가중치는 모델의 성능을 향상시키며, 다음 번 예측의 정확도를 높이는 데 사용된다.

새롭게 조정된 가중치로 모델은 다시 한번 입력 데이터를 받아 순전파를 시작한다. 참고로 순전파는 우리가 오늘 알아보는 Transformer의 과정이다. 인코더와 디코더는 업데이트된 가중치를 활용하여 입력 데이터의 문맥을 다시 파악하고, 디코더는 이를 기반으로 더 정확한 확률 분포를 생성한다. 이 반복적인 훈련 과정은 모델이 충분히 학습되어 손실값이 더 이상 줄어들지 않을 때까지 계속된다.

이러한 가중치를 생성 및 조정하는 방법인 역전파는 다음글인 Fine-tuning에서 심도있게 정리해보겠다. 지금은 Attention에 집중해보도록 하자.

Attention은 위 세 가지 $Query(Q)$, $Key(K)$, $Value(V)$ 의 데이터들의 관계를 파악하는 기법이다. 다시 식으로 돌아가서, 각 데이터들은 임베딩 되어서 벡터로 표현된다고 했다. 그리고 각 벡터들은 차원(특징)을 가진다 했다. 여기서 하나의 $Q$는 여러 개의 $K$를 가질 것이다. 그리고 $Q$와 $K$의 개수는 $n{\text{ (토큰의 개수)}}\times d_k{\text{ (차원의 개수)}}$ 가 된다. 그리고 하나의 $Q$는 입력 값 $X$에서 생성된 같은 차원의 모든 $K$와 내적을 수행하여 유사도를 계산하고, 그 결과를 기반으로 각 $V$에 가중치를 부여하여 최종 Attention 출력을 만든다. ${K^T}$는 전치 행렬을 의미한다. 전치 행렬로 만드는 이유는 아래의 식으로 설명하겠다.

$$ Q \in \mathbb{R}^{n \times d_k}, \quad K \in \mathbb{R}^{n \times d_k} $$

위에서 말했다 싶이 $Q$와 $K$의 개수는 $n{\text{ (토큰의 개수)}}\times d_k{\text{ (차원의 개수)}}$ 이다. 이때 내적을 하기 위해서 행렬 곱을 하게 된다. 토큰의 행렬에서 행은 $n$을 열은 $d_k$를 나타낸다. 하지만 위의 크기로는 $Q$, $K$는 행렬곱을 하지 못한다. 따라서 전치를 통해 크기를 맞춰준다.

$$ K^T \in \mathbb{R}^{d_k \times n} $$

$$ QK^T \in \mathbb{R}^{n \times n} $$

이렇게 크기가 맞춰진 $Q$ 와 $K$는 $n\times n$ 크기의 어텐션 스코어(attention score)로 변환된다.

$$ \frac{QK^T}{\sqrt{d_k}} $$

위의 식은 $Q$를 $K$와 내적을 한 값을 $\sqrt{d_k}$로 Scaling하는 것을 나타낸다.

내적 은 $Query$가 $Key$와 얼마나 잘 맞는지를 나타내는 척도이며, 일종의 유사도(similarity) 점수라고 볼 수 있다. 고등학교때 배운 내적을 생각해보자

$Q = (1, 2, 3)$ $K_1 = (2, 0, 1)$ $K_2 = (-2, -1, 1)$ $K_3 = (0, 2, 2)$

이렇게 1개의 $Q$에 3개의 $K$가 있다고 해보자. 해당 벡터는 위에서 이야기한 가중치가 적용되어 3개의 차원으로 이루어진 값이다. 즉 ${d_k}$는 3이다.

$Q \cdot K_1 = 5$ $Q \cdot K_2 = -1$ $Q \cdot K_3 = 10$

행렬로 나타낸 경우

$$ QK^T = \begin{bmatrix}1 & 2 & 3\end{bmatrix} \begin{bmatrix} 2 & -2 & 0 \ 0 & -1 & 2 \ 1 & 1 & 2 \end{bmatrix} = \begin{bmatrix}5 & -1 & 10\end{bmatrix} $$

위에서 내적의 결과를 보면, $K_3$가 10으로 $Q$ 와 가장 유사하다. 그리고 $K_2$가 -1로 가장 관련이 없다.

$\sqrt{d_k}$는 스케일링(scaling) 을 의미한다 앞에서 계산한 내적 결과는 $d_k$의 크기가 커질수록 값이 점점 커지게 된다 만약 차원이 수백 차원 이상으로 커진다면 내적 값은 지나치게 커지고 $softmax$ 함수에 넣었을 때 기울기가 매우 가팔라져 작은 차이에도 확률 분포가 한쪽으로 치우쳐 버린다

이를 방지하기 위해 내적 값을 차원의 제곱근으로 나누어 정규화(normalization) 를 해준다 예를 들어 위에서 $d_k = 3$이므로 $\sqrt{d_k} = \sqrt{3} \approx 1.73$ 이 된다

그럼 각각의 내적 값은 다음과 같이 스케일링된다

• $\frac{Q \cdot K_1}{\sqrt{3}} = \frac{5}{1.73} \approx 2.89$
• $\frac{Q \cdot K_2}{\sqrt{3}} = \frac{-1}{1.73} \approx -0.58$
• $\frac{Q \cdot K_3}{\sqrt{3}} = \frac{10}{1.73} \approx 5.77$

이 과정을 거치면 값의 크기가 안정화되어 $Softmax$에 넣었을 때 적절한 확률 분포를 얻게 된다 즉 스케일링은 내적 값이 차원 수에 비례해 과도하게 커지는 문제를 제어하는 장치라고 이해하면 된다

그러면 이제 $Q$로부터 각 3개의 $K$의 관계를 알게 되었다. 그 다음으로 적용되는 것이 $softmax$이다. $softmax$는 $\frac{QK^T}{\sqrt{d_k}}$ 에서 나온 값 들을 전부 합 하였을 때, 1로 만들어주는 함수이다. 위의 경우에서는 $K_3$가 1에서 가장 많은 비율을 차지할 것이다. 그리고 $K_2$가 가장 적은 비율을 차지할 것이다.

마지막으로 가중합을 $V$에 적용하여 최종적인 정보의 관계를 생성하게 된다.

정리하자면, 특정 Query가 여러 Key들과 얼마나 관련성이 있는지를 Softmax를 통해 확률 값으로 바꾸게 되고, 이 확률 값이 바로 Attention에서 말하는 가중치(weight) 가 된다. 그리고 이 가중치는 Value $V$ 벡터에 곱해져 최종적으로 중요한 정보는 크게, 덜 중요한 정보는 작게 반영되도록 조절한다.

결과적으로 Attention 메커니즘은 “Query와 Key의 내적으로 구한 유사도를 스케일링 후 Softmax로 정규화하여, Value에 가중합을 적용하는 과정”이라고 정리할 수 있다.

Self Attention

그렇다면 Self Attention은 무엇일까? 앞에서 예시는 검색엔진처럼 Query는 질문, Key는 문서의 제목, Value는 실제 내용으로 비유했다. 하지만 Self-Attention은 그 대상이 외부 데이터가 아니라, 같은 문장 안의 토큰들끼리 서로를 참고하는 방식이다. 사실 앞에서 이야기한 "하나의 $Q$는 입력 값 $X$에서 생성된 같은 차원의 모든 $K$와 내적을 수행하여 유사도를 계산한다" 가 바로 Self Attention을 나타내는 말이었다. 그냥 Attention은 외부 데이터에서 $Q$, $K$, $V$를 각각 생성한다.

하나의 문장 나는 학교에 간다가 있다고 하면, 각 단어가 동시에 Q, K, V의 역할을 수행한다.

"나는" → Query를 만들고, Key와 Value도 만든다 "학교에" → Query, Key, Value를 모두 가진다 "간다" → 역시 Query, Key, Value를 가진다

이렇게 되면 문장 안에서 각 단어는 다른 단어와 자신 사이의 관련성을 계산할 수 있다. 이를 통해 처음에 말한 RNN에서 실현하지 못한 장기 의존성 그리고 다양한 문장의 표현을 해결이 가능하다. 그러면 마지막 목적인 병럴처리는 어떻게 실현이 가능할까? 바로 Multi Head Attention에 그 정답이 있다.

Multi Head Attention

먼저 Multi Head Attention에 대해서 알아보려면 head가 무엇인지 알아야 한다. 처음에 나는 차원이랑 헤드가 헷갈렸는데, 차원은 위에서 이야기 한 것처럼 각 토큰의 특징을 나타낸 것이다.

$d_{model} = 512$라면, 각 단어 토큰은 512개의 숫자로 표현된다.

"바나나"라는 토큰이 들어오면 벡터

$$ (0.12, -0.33, 0.98, \dots, 0.21) \in \mathbb{R}^{512} $$

이런 식으로 512차원의 공간에서 하나의 점으로 표현된다. 즉 $\mathbb{R}^{512}$ 는 모델의 용량이 된다.

헤드는 Self-Attention을 여러 번 나눠서 병렬로 돌리는 단위이다. 예를 들어, $d_{model} = 512$이고 Head 수가 $h = 8$이라면, 각 Head는 차원을 나눠서

$$ d_{head} = \frac{d_{model}}{h} = 64 $$

의 크기로 Attention 연산을 한다. 전체 임베딩 512차원을 8개의 시각(Head)으로 쪼개서 동시에 바라본다고 이해하면 된다.

• 차원(dimension) → 토큰 벡터의 "특징 공간" 크기 (정보량)
• 헤드(head) → 그 특징 공간을 "여러 시각"으로 분할해 병렬로 학습하는 방법

즉 Multi Head Attention은 $h$번 만큼 Self Attention을 하는 것이다. 이를 통해 병렬처리를 실현 가능하다.

여기서 앞에서 이야기한 가중치의 크기와 $d_k, d_v$를 $\frac{d_{model}}{h}$로 맞추는 이유가 여기서 나온다.

$$ X \in \mathbb{R}^{n \times d_{\text{model}}} $$

위의 식처럼 입력값 $X$의 크기는 $n$개의 토큰에서 차원 ($d_{\text{model}}$)을 곱한 값이다. 그러면 각 $Q$, $K$, $V$를 생성하기 위해 가중치와 곱하게 되는데 이때 $h$개 ($d_k$, $d_v$) head로 Self Attention을 하게 된다. 그 뜻은 원래 차원 각각에 $h$개의 특징 추가시키는 것이다. 위의 예시인 경우 512개의 차원에서 8개의 특징을 추가하여 512와 8을 곱한 98,304개가 된다.

따라서 가중치들의 크기는 $d_{\text{model}}\times d_k$, $d_{\text{model}}\times d_v$

$$ Q = XW^Q, \quad K = XW^K, \quad V = XW^V $$

위에서 본 해당 식에서 각 행렬 곱을 하게 되면 $$(n \times d_{\text{model}}) \times (d_{\text{model}} \times d_k) = (n \times d_k)$$ $$(n \times d_{\text{model}}) \times (d_{\text{model}} \times d_k) = (n \times d_v)$$

위의 예시에서 Self Attention의 각 차원은 64개 일것이다. 그리고 8번의 Self Attention을 하면 총 512개의 차원이 다시 완성되는 것이다. 이렇게 해야지 다음 과정인 Residual Connection(잔차 연결) 같은 구조에서 입력($d_{model}$)과 출력($d_{model}$)을 그대로 더할 수 있고, 다음 Feed-Forward Layer도 동일한 차원에서 작동할 수 있게 된다. 이렇게 $h$로 나누는 방법으로 차원을 맞추는 것이다.

$$ MultiHead(Q, K, V) = Concat(head_1, \dots, head_h)W^O $$

$$ \text{where } head_i = Attention(QW_i^Q, KW_i^K, VW_i^V) $$

위의 식은 Self Attention 이 $head$번 만큼 일어나고 각 결과를 더해서 Multi Head Attention을 구성하는 것을 나타낸다.

Multi Head Attention까지 실행하면, 아마 입력값에 대해 모델이 충분히 이해했다고 생각할 것이다. 하지만 하나 빠트린것이 있는데, 바로 입력 값의 위치에 대한 정보이다.

Positional Encoding

자연어에서 입력값의 위치는 매우 중요하다. 그런데 위치를 고려하게 되면 RNN에서 장기 의존성(Long-term Dependency)와 같이 위치에 따른 정보 손실과 순차적 처리로 인해 병렬처리가 불가능하다. 이러한 위치에 따른 정보를 Transformer에서는 다른 기법으로 적용하였는데, 바로 Positional Encoding으로 적용을 한 것이다.

Transformer는 RNN처럼 순차적으로 단어를 처리하지 않기 때문에, 입력 토큰의 순서 정보가 사라지는 문제가 있다. 즉, "나는 학교에 간다"라는 문장이 들어와도, Transformer 입장에서는 단순히 4개의 벡터 집합일 뿐 "나는 → 학교에 → 간다"라는 순서 관계를 알 수 없다.

이를 해결하기 위해 Positional Encoding(위치 인코딩)을 추가한다. Positional Encoding은 각 토큰의 임베딩 벡터에 "해당 토큰이 문장 내 몇 번째 위치에 있는지"를 수학적으로 표현한 벡터를 더해주는 방식이다.

$$ Z = X + PE $$

$X$는 원래의 단어 임베딩, $PE$는 위치 정보를 담은 인코딩 벡터이다.

논문에서 제안한 Positional Encoding은 사인(sin)과 코사인(cos) 함수를 이용한다. 특정 위치 $pos$와 차원 $i$에 대해 다음과 같이 정의된다.

$$ PE_{(pos, 2i)} = \sin \left( \frac{pos}{10000^{2i/d_{model}}} \right) $$

$$ PE_{(pos, 2i+1)} = \cos \left( \frac{pos}{10000^{2i/d_{model}}} \right) $$

여기서

• $pos$ : 단어의 위치 (0번, 1번, 2번 …)
• $i$ : 임베딩 벡터의 차원 인덱스
• $d_{model}$ : 임베딩 벡터의 총 차원 수

즉, 짝수 차원은 사인 함수, 홀수 차원은 코사인 함수로 값을 넣어준다. 나도 정확한 원리는 모르지만 사인 코사인으로 파형을 생성해서 무한한 길이도 위치를 알아낼 수 있는 형태로 바꿔진다고 한다. 잘 모름

Feed Forward Network (FFN)

마지막으로 Multi-Head Attention과 Positional Encoding을 거친 후의 출력은 그대로 다음 레이어로 전달되지 않고, 한 번 더 Feed Forward Network(포지션별 전결합 신경망)을 거치게 된다. FFN은 모든 위치(pos)에 대해 동일하게 적용되는 두 개의 선형 변환과 비선형 활성화 함수로 구성된다.

수식으로 표현하면 다음과 같다.

$$ FFN(x) = \max(0, xW_1 + b_1)W_2 + b_2 $$

여기서 $W_1, W_2$와 $b_1, b_2$는 학습 가능한 가중치와 편향이다. 중간에 들어가는 $\max(0, \cdot)$는 ReLU 함수로, 비선형성을 부여하여 모델이 더 복잡한 패턴을 학습할 수 있게 한다.

FFN의 특징은 각 토큰 위치마다 동일한 네트워크가 독립적으로 적용된다는 것이다. 즉, 입력이 10개의 토큰이든 20개의 토큰이든, 각 토큰 벡터는 똑같은 FFN 구조를 거쳐 변환된다. 이로 인해 모델은 위치에 무관하게 동일한 변환을 수행하면서도, Attention으로 이미 반영된 단어 간의 관계를 기반으로 비선형적인 특징을 학습할 수 있다.

간단히 말해 Attention이 단어들 사이의 관계 를 학습하는 단계라면, FFN은 그 관계로부터 복잡한 패턴을 추출하고 강화하는 단계라고 볼 수 있다.

이 과정을 거친 출력은 다시 Residual Connection(잔차 연결)과 Layer Normalization을 통해 안정화되고, 다음 Encoder Layer로 전달된다. Encoder는 이런 구조를 여러 층 쌓아 올려 강력한 표현 학습 능력을 얻게 된다.

Masking

이제 Masking에 대해서 알아보겠다. 마스킹은 decoder에만 적용되는 기법이다. Decoder는 해당 입력과 Encoder에서 생성된 관계를 통해 다음 데이터를 예측한다... 라고 위에서 설명했다. 그런데 생각해보자 Encoder는 단순히 모든 입력에 관한 관계를 정의하는 것이라서, Encoder로 생성된 정보들은 전부 Self Attention 을 통해 조금이라도 각자의 정보를 가지고 있을 것이다.

하지만 Decoder는 다르다. Decoder는 순차적 예측(Autoregressive Generation) 을 수행해야 한다. 예를 들어, 나는 학교에 간다라는 문장을 생성한다고 할 때, 첫 번째 단계에서는 나는만 알고 있어야 하며, 두 번째 단계에서는 나는 학교에까지만 알고 있어야 한다. 만약 Decoder가 앞으로 나올 단어 간다를 미리 참고해버린다면, 모델은 학습 과정에서 미래 정보를 엿보는 정보 누수(Information Leakage) 가 발생하게 된다. 이를 해결해 주는 것이 Masking 기법이다.

Masking은 미래 시점의 단어를 가려서 현재 시점 이전의 단어들만 보이도록 하는 역할을 한다. 수학적으로는 Attention의 Softmax 단계에서, 미래 단어 위치에 -∞ 값을 추가하여 확률이 0이 되도록 만든다. 이렇게 하면 Decoder는 항상 앞에서 생성된 단어까지만 참고해서 다음 단어를 예측하게 된다.

Add & Norm

그림을 다시 한번 봐보자 MultiHead Attention과 Feed Forward를 하고 나서 Add & Norm이라는 과정이 있고, 화살표 하나는 MultiHead Attention과 Feed Forward를 하지 않고 Add & Norm을 향하고 있다.

MultiHead Attention과 Feed Forward를 하고 나면 원래 입력 정보 $X$가 변질 되거나 학습지 되지 않아, 아예 다른 출력이 나올 수도 있다. 또한 각 layer를 지날때마다 데이터 분포 층이 뒤틀릴 수도 있다. 이를 해결 해 주는 것이 Add & Norm이고, 따라서 각 layer를 지나고 나서 적용을 해준다.

즉, Add & Norm은 "입력 + 출력"을 합쳐서 정규화하는 과정이다.Add & Norm은 Residual Connection + Layer Normalization로 이루어진다.

먼저 Residual Connection은 레이어의 입력 $X$와 해당 레이어의 출력 $F(X)$를 더한다.

$$ Y = X + F(X) $$

이렇게 더하면, 깊은 네트워크에서도 원래 입력 정보 $X$가 손실되지 않고 그대로 흘러갈 수 있다.

그 다음에 Layer Normalization을 적용한다. 평균과 분산을 구해서 정규화하는 거다.

$$ \text{LayerNorm}(Y) = \frac{Y - \mu}{\sigma} \cdot \gamma + \beta $$

최종 출력은 이렇게 된다.

$$ \text{Output} = \text{LayerNorm}(X + F(X)) $$

BackPropagation

이제 위에서 구한 값을 통해 역전파를 진행한다. 이러한 역전파는 수천~수억번을 반복하여 모델을 최적화 하게 된다. 앞에서 말한 것처럼 역전파는 다음 글에서 알아보겠다.

Decoder

위의 그림을 보면 디코더에서는 두 가지 입력이 필요하다. 첫 번째는 아웃풋 임베딩(Output Embedding), 두 번째는 인코더의 출력값이다.

아웃풋 임베딩은 지금까지 생성한 단어들을 임베딩한 것이다. 예를 들어 번역 모델에서 이미 “I go”까지 만들었다면, 이게 디코더 입력으로 들어간다. 디코더는 이걸 바탕으로 다음 단어가 뭔지 예측한다.

인코더 출력값은 원문 문장의 의미 표현이다. 디코더는 단순히 자기 자신(아웃풋 임베딩)만 보고는 번역을 할 수 없다. 원래 문장 정보도 같이 참고해야 한다. 그래서 중간에 Cross-Attention 이라는 중간단계에서 인코더 출력값을 Key, Value로 삼고, 디코더 쪽에서 만든 Query와 결합한다. 이렇게 해야 “출력 문장이 원문을 잘 반영하도록” 만들 수 있다.

디코더만 사용하는 모델들

GPT 같은 모델은 디코더만 사용하는 구조다. 인코더-디코더 구조가 아니기 때문에, 아웃풋 임베딩만 가지고 학습한다. 방식은 다음과 같다. 디코더 모델은 입력 문장을 바로 디코더에 넣는다. 그리고 나서 마스크드 셀프 어텐션(Masked Self-Attention)으로, 앞으로 올 단어는 못 보고 과거 단어만 참고한다. 이렇게 해서 언어 모델링이 가능하다. 즉, 앞 단어가 주어졌을 때 다음 단어를 예측하는 방식이다. 따라서 디코더 생성형 모델이 사용하는 방식이다. 우리가 GPT를 통해 자연어를 입력하고 GPT가 응답을 생성하는 것이 이러한 토크나이저와 마스크드 셀프 어텐션으로 다음 단어의 확률을 통해 만드는 것이다.

😁 마무리

이번에는 Transformer에 대해서 알아보았는데, 사실 이 글을 5일에 걸쳐서 쓴것 같다. 중간에 틀린 내용도 고치고 논문 내용도 다시 살펴보느라 오래 걸렸는데, 이렇게 한번 정리하니 확실히 이해가 잘되는 것 같다. 다음에는 fine-tuning에 대해서 알아보겠다. 사실 우리가 LLM을 사용하면 이미 Transformer 가 적용된 LLM을 파인튜닝하거나 RAG, 프롬프팅을 적용하여 사용한다. 따라서 파인튜닝이야 말로 LLM을 실전에 사용할 수 있는 핵심적인 기술이다. 다음 글에서 파인튜닝에 대해서 심도있게 다뤄보겠다.

[참고] Attention/Transformer 시각화로 설명, 임커밋 (YouTube)

이전 글에 Prompt Engineering과 Chunking에 대해서 정리를 했었는데, LLM의 기초부터 Velog에 정리를 해야 할 필요를 느꼈다. LLM의 개념에 대해서는 예전에 책으로 몇 번 보고, 영상이나 강의자료로 가볍게 본 기억이 있는데, 이번에 제대로 기초부터 다시 공부해서 정리해 보려고 한다.

이번 글에서는 간단한 LLM의 역사와 기본적인 원리를 간단하게 정리해 보고, 다음 글에서 Transformer에 대해서 심도 있게 다룰 생각이다.

📜 LLM History

LLM(Large Language Model) 은 처음 들어보면, 엄청나게 복잡한 알고리즘과 원리로 동작하는 것처럼 보인다. 하지만 기본적인 원리는 엄청 간단하다고 한다. 뒷말 잇기를 생각해 보면 이해가 될 텐데, 만약 이러한 문장을 보았다고 하자.

나는 늦게 일어나서 학교까지 ~

나는 뒤에 뛰어갔다 를 넣으면 자연스러울 것 같다. 아마도 택시를 타고 갔다 도 괜찮을 것 같다. 그럼 LLM이 볼 때는 어떻게 생각을 할까? LLM은 수많은 예시를 가지고 있고, 각 예시는 확률을 가지고 있다.

만약 이러한 확률을 가지고 있다고 해보자. LLM은 아마도 이러한 확률 테이블에서 가장 적절한 후보 단어를 골라서 문장을 생성해 낼 것이다.

이것이 바로 기본적인 LLM의 동작이다. 이러한 원리는 1950년대부터 고안이 되었는데, 그 유명한 튜링 머신 테스트가 이러한 자연어 생성 메커니즘에 부합하는 기계를 찾는 테스트이다.

이후 1990년대에는 통계적 언어 모델이 등장했다. N-gram이라는 모델을 사용해 이전 단어들을 보고 다음 단어의 확률을 계산하는 방식이었다. 하지만 긴 문맥을 처리하지 못하고 데이터가 커질수록 희소성 문제가 발생했다.

2010년대 초반, RNN(Recurrent Neural Network) 과 LSTM(Long Short-Term Memory) 같은 신경망 모델이 NLP에 도입되면서 조금 더 긴 문맥을 다룰 수 있게 되었지만, 여전히 학습 속도와 긴 시퀀스 처리에서 한계가 있었다.

참고로 RNN은 순환 신경망 기술로 연쇄적인 데이터를 처리하기 위해 이전 상태를 입력으로 받아서 출력을 만들어 내는 뉴런 구조에서 착안한 기술이다.

결정적인 전환점은 2017년 Transformer의 등장이다. 「Attention is All You Need」 라는 논문에서 제안된 Transformer 구조는 병렬 처리가 가능하면서도 긴 문맥을 효과적으로 학습할 수 있게 했다. 그 이후 BERT, GPT, T5 같은 모델들이 등장하며 언어 모델의 패러다임을 완전히 바꾸었다.

🤖 BERT / GPT / T5

Transformer는 입력된 시퀀스의 모든 단어를 병렬로 처리할 수 있다. 이러한 병렬 처리를 가능하게 하는 것이 바로 멀티헤드 어텐션(MultiHead Attention)이다. 멀티헤드 어텐션은 단어들의 관계를 파악하는 기법이다.

Transformer는 크게 두 가지의 구조로 구성된다. 인코더(Encoder)와 디코더(Decoder) 두 개의 절차로 구성되는데, 이를 어떻게 사용하느냐에 따라 BERT, GPT, T5와 같은 다양한 모델이 탄생했다.

BERT (Bidirectional Encoder Representations from Transformers)

Bidirectional → 양방향

BERT는 구글에서 개발한 모델로, 인코더만으로 구성되어 있다. 양방향(Bidirectional) 으로 문맥을 학습하는 것이 특징이다. 예를 들어, 나는 늦게 일어나서 학교까지 뛰어갔다라는 문장이 있을 때, BERT는 "나는 늦게 일어나서"와 "학교까지"라는 양쪽의 문맥을 모두 고려하여 뛰어갔다라는 단어를 이해한다. 이는 문장의 의미를 이해하고 분류하는 과제(NLU, Natural Language Understanding) 에 매우 효과적이다.

GPT (Generative Pre-trained Transformer)

GPT는 OpenAI에서 개발한 모델로, 디코더만으로 구성되어 있다. GPT는 단방향(Unidirectional) 으로 학습하며, 문맥을 기반으로 다음 단어를 예측하는 방식이다. 위 예시에서, GPT는 나는 늦게 일어나서 학교까지라는 문장이 주어졌을 때, 이전 단어들만을 참고하여 뛰어갔다를 예측한다. 이 구조는 새로운 문장을 생성하는 과제(NLG, Natural Language Generation) 에 뛰어나다.

T5 (Text-to-Text Transfer Transformer)

T5는 구글에서 개발한 모델로, 인코더와 디코더를 모두 사용한다. T5의 가장 큰 특징은 모든 자연어 처리 문제를 "텍스트를 텍스트로 바꾸는(text-to-text)" 형식으로 통일했다는 점이다. 예를 들어, 문장 분류, 요약, 번역 등 모든 과제를 질문과 답변 텍스트 쌍으로 변환하여 학습한다.

자세한 원리는 다음 글인 Transformer에서 심도 있게 다뤄보도록 하겠다.

🌟 Emergence

그런데 우리가 궁금한 것은 이러한 소위 말하는 LLM 혁명이 어떻게 왔냐는 것이다. 아마 LLM에 관심이 많으면 창발적 능력이라는 말을 많이 들어봤을 텐데, 답은 여기에 있다.

창발적 능력이란 작은 모델에서는 전혀 보이지 않던 능력이, 모델의 규모가 일정 임계치를 넘었을 때 갑작스럽게 도약하듯 나타나는 현상을 의미한다.

해당 그래프는 OpenAI가 2017년에 발표한 논문 「Learning to Generate Reviews and Discovering Sentiment Neurons」 에서 나온 결과인데, LSTM(Long Short-Term Memory) 기반의 언어 모델이 갑자기 긍정/부정 감정(sentiment)을 구분하는 능력을 갖추게 된 것이다. 이것이 초기 창발적 능력의 증거라고 보는 견해가 많다.

이러한 창발적 능력은 GPT-2에서도 관찰되었다는 견해가 있지만, 실제로 놀라운 성능을 보여준 것은 GPT-3부터였다. 바로 In Context Learning이라는 Prompt Engineering의 핵심이 되는 현상이 일어난 것이다.

이때부터 Microsoft가 OpenAI에 본격적으로 눈길을 돌렸다. 이미 2019년에 Azure 클라우드를 통해 일부 협력 관계를 맺고 있었지만, 이러한 창발적 능력으로 인한 LLM의 능력 극대화는 충격적으로 다가왔을 것이다.

OpenAI의 CEO인 샘 알트먼과 연구진들은 이러한 창발적 능력을 2017년에 알게 되어 GPT-1부터 3까지 Zero-shot, Few-shot 등 여러 가지 현상을 관찰하고 개선하면서 지금에 이르렀다. 참고로 Zero-shot과 Few-shot은 각각 GPT-2와 GPT-3에서 처음 체계적으로 입증되었다고 한다.

📌 마무리

이번 글에서는 LLM의 역사와 기본 원리, 그리고 창발적 능력의 개념까지 정리해 보았다. 다음 글에서는 LLM의 핵심 구조 Transformer를 심도 있게 다룰 예정이다. 또한 LLM이 학습을 하는 방식도 다룰 생각이다.

[참고] Unsupervised sentiment neuron

오랜만에 디자인패턴 글을 써보는데, 최근에 IPP로 회사에 가서 이것저것 하고 정신이 없어서 글 쓰는 것을 잊고 있었다.

앞으로는 일주일에 한번은 디자인패턴 글을 쓸 생각이다. 어쨌든 저번 프로토타입 패턴을 마지막으로 생성패턴은 전부 정리를 완료했고, 오늘부터는 장식자 패턴을 시작으로 구조 패턴을 차례대로 정리해보겠다.

Decorator Pattern은 이름에서 알 수 있다시피, 어떤 객체를 장식을 하는 패턴이다. 참고로 장식자 패턴을 포함한 Structure Patterns는 여러 개의 객체로 이루어진 구조를 정의해주는 패턴이다. 간단하게 보편적인 설계도를 정의한 것이라 보면 된다. 따라서 코드를 작성할 때, 클래스나 함수를 정의하고 객체의 생명주기를 관리하는 방법에는 생성패턴이 사용된다면, 전체적인 구조를 정의하고, 하나의 모듈로 동작하는 기능을 구현할 때는 구조패턴을 사용할 경우가 생길 것이다.

다시 돌아가서 장식자 패턴은 객체에 동적으로 새로운 책임(기능)을 추가하는 방식으로, 상속의 대안으로 사용된다. 이 패턴은 기존 객체의 구조를 변경하지 않고 기능을 확장할 수 있다.

객체에 동적으로 새로운 책임을 추가할 수 있게 합니다. 기능을 추가하려면, 서브클래스를 생성하는 것보다 융통성 있는 방법을 제공합니다

GOF 책에서 보면 많은 패턴들이 서브클래스를 생성하는 것을 대체하고 효율적으로 기능을 추가하기 위해 고안된 것임을 알 수 있다. 그렇다면 여기서 동적은 무엇을 뜻하는 것일까?

여기서 동적은 실제로 컴퓨터공학에서 말하는 Dynamic을 의미한다. 만약 객체를 서브클래스로 기능과 책임을 만들 경우, 컴파일 타임이나 빌드 타임에 "정적"으로 기능과 책임을 담당하는 클래스를 생성해야 한다. 하지만 장식자 패턴은 동적으로 실제 런타임 환경에서 이러한 추가 기능 클래스를 추가 가능하다. 또한 장식자 패턴은 Wrapper라고도 불리는데, 객체를 감싸서 추가적인 기능이나 책임을 부여하는 구조 때문에 이렇게 불린다.

책임을 부여하는 것이 장식자 패턴에서 가장 중요한 점인데, 장식받는 객체는 자신의 기능만 신경 쓰면 되고, 나머지 장식을 하는 객체들의 구현과 기능은 신경 쓸 필요가 없다. 따라서 Decorator가 사용되는 순간 장식받는 객체는 Decorator의 멤버 변수로 들어가서 기능 호출만 받으면 된다.

언제 사용하나? 📌

책에서는 장식자 패턴을 TextView 컴포넌트를 감싸서 기능을 BorderDecorator와 ScrollDecorator로 예시를 들었다.

해당 이미지를 보면, 기존의 TextView에 BorderDecorator와 ScrollDecorator로 감싸서 컴포넌트를 이루는 것을 나타낸다.

위 사진을 보면 동적으로 어떻게 기능을 추가하는지 이해가 될 것이다. 바로 VisualComponent라는 클래스가 TextView를 서브클래스로 가지고 있는데, 해당 클래스가 Decorator라는 클래스를 서브클래싱하여 관리를 한다.

Decorator는 Draw()로 원하는 컴포넌트를 그리면 된다. 여기서 중요한 점이 있는데, TextView는 이러한 Decorator들을 알 필요가 없다. TextView를 정의하고, 만약 테두리를 그리고 싶으면 TextView를 Decorator에 넘겨주고 해당 클래스에서 장식을 해준다.

따라서 TextView는 자신의 기능인 텍스트뷰 그리기만 신경을 쓰면 된다.

구조 🏗️

ConcreteDecorator들은 Operation()으로 자신만의 기능과 함께 ConcreteComponent의 Operation()을 호출할 것이다. 이렇게 ConcreteComponent는 그저 자신의 기능만 호출하고 추가 기능 확장에 대해서는 신경 쓸 필요가 없다.

구현 💻

#include <iostream>
#include <memory>

class VisualComponent {
public:
    virtual void Draw() = 0;
    virtual ~VisualComponent() {}
};

class TextView : public VisualComponent {
public:
    void Draw() override {
        std::cout << "기본 텍스트 뷰 그리기" << std::endl;
    }
};

class Decorator : public VisualComponent {
protected:
    std::unique_ptr<VisualComponent> _component;
public:
    Decorator(std::unique_ptr<VisualComponent> component)
        : _component(std::move(component)) {} 
    void Draw() override {
        if (_component) {
            _component->Draw();
        }
    }
};

class BorderDecorator : public Decorator {
private:
    int _width;
    void DrawBorder() {
        std::cout << "테두리 그리기" << std::endl;
    }
public:
    BorderDecorator(std::unique_ptr<VisualComponent> component, int width)
        : Decorator(std::move(component)), _width(width) {}

    void Draw() override {
        Decorator::Draw();
        DrawBorder();
    }
};

class ScrollDecorator : public Decorator {
private:
    void DrawScroll() {
        std::cout << "스크롤바 그리기" << std::endl;
    }
public:
    ScrollDecorator(std::unique_ptr<VisualComponent> component)
        : Decorator(std::move(component)) {}

    void Draw() override {
        Decorator::Draw();
        DrawScroll();
    }
};

int main() {
    auto textView = std::make_unique<TextView>();
    std::cout << "\n--- 기본 TextView ---" << std::endl;
    textView->Draw();

    auto textViewWithBorder = std::make_unique<BorderDecorator>(std::move(textView), 1);
    std::cout << "\n--- 테두리 추가된 TextView ---" << std::endl;
    textViewWithBorder->Draw();

    auto textViewWithBoth = std::make_unique<ScrollDecorator>(
        std::make_unique<BorderDecorator>(
            std::make_unique<TextView>(), 1));
    std::cout << "\n--- 테두리와 스크롤 모두 추가된 TextView ---" << std::endl;
    textViewWithBoth->Draw();

    return 0;
}

위의 코드에서 중요하게 볼 점은, 바로 Decorator들이 VisualComponent* _component;로 장식할 객체인 TextView를 멤버 변수로 받는 것이다. 이를 통해서 TextView는 만약 Decorator를 사용하고 싶지 않으면, 해당 객체들을 만들 필요가 없다.

다시 상기시키자면, 장식자 패턴에서 가장 중요한 점은 바로 책임 전가이다.

마무리

Decorator 패턴은 기존 객체의 구조를 변경하지 않고, 런타임에 동적으로 새로운 기능과 책임을 부여할 수 있는 디자인 패턴이다. 상속 대신 객체를 감싸는 방식(Wrapper)을 사용하여 기능을 확장하므로, 필요할 때만 선택적으로 기능을 조합할 수 있고 클래스 폭발 문제를 피할 수 있다는 장점이 있다. 하지만 장식이 중첩될수록 구조가 복잡해지고, 디버깅이 어려워질 수 있으며, 너무 많은 데코레이터가 사용되면 유지보수 비용이 증가할 수 있다는 단점이 있다. 결국 이 패턴은 기능 확장이 빈번하고, 유연한 구조가 필요한 UI 컴포넌트나 모듈성 높은 시스템에서 특히 효과적으로 사용된다.

다음 글에서는 구조 패턴 중 Adapter Pattern에 대해 알아볼 예정이다. Adapter 패턴은 호환되지 않는 인터페이스를 가진 클래스들이 함께 동작할 수 있도록 연결하는 패턴으로, 기존 코드를 수정하지 않고 새로운 환경에 맞출 수 있다는 장점이 있다.

[참고] Decorator Pattern

이번에는 저번 Prompt Engineering에 이어서 Chunking에 대해서 알아보겠다.

청킹은 자연어를 특정 크기로 나누는 것을 의미한다. 각 나누어진 단위를 청크(chunk)라고 하며, 이러한 기법을 적용하는 도구를 텍스트 분할기(Text splitters)라고 한다. 따라서 텍스트 분할을 어떻게 하느냐에 따라서 청킹이 구성되는 방식이 달라진다. 중요한 점은 이러한 텍스트 분할은 분할을 적용하려는 자연어의 종류에 따라 나뉜다는 것이다.

텍스트 분할기 (Text Splitters) 📑

텍스트 분할은 RAG(Retrieval-Augmented Generation, 검색 증강 생성)에서 사용되는 핵심 기법이다. 긴 문서를 모델이 처리하기 쉬운 작은 단위인 청크로 나누어, 효율적인 검색과 정확한 답변 생성을 가능하게 한다.

문서를 나누는 구체적인 이유는 다음과 같다.

• 다양한 문서 길이 처리: 실제 문서들은 길이가 제각각이다. 분할을 통해 모든 문서를 일관된 크기로 처리할 수 있다.
• 모델 한계 극복: 대부분의 임베딩 모델과 언어 모델은 입력 크기 제한이 있다. 분할을 통해 이 제한을 초과하는 문서를 처리할 수 있다.
• 표현 품질 향상: 긴 문서는 임베딩 품질이 저하될 수 있다. 분할을 통해 각 섹션에 더 집중된, 정확한 표현을 생성할 수 있다.
• 검색 정확도 향상: 정보 검색 시스템에서 분할은 검색 결과의 세분성을 높여, 질의와 관련된 문서 섹션을 더 정확하게 찾아낼 수 있게 한다.
• 연산 자원 최적화: 작은 텍스트 청크로 작업하면 메모리 효율이 높아지고, 처리 작업을 병렬화하기 쉬워진다.

텍스트 분할을 구현하는 방법은 여러 가지가 있다.

길이를 기반으로 분할 (Length-based) 📝

가장 직관적인 방법으로, 정해진 길이(문자 또는 토큰 수)를 기준으로 문서를 나눈다.

• 특징: 구현이 간단하고, 청크 크기가 일관적이며, 모델의 요구사항에 맞추기 쉽다.
• 유형: 토큰 기반은 언어 모델에 유용하도록 토큰 수를 기준으로 나누고, 문자 기반은 텍스트 유형에 관계없이 일관된 문자를 기준으로 나눈다.

텍스트 구조를 기반으로 분할 (Text-structured based) ✨

문단, 문장, 단어 등 텍스트의 계층적 구조를 활용하여 자연스러운 언어 흐름을 유지하며 분할한다.

• 특징: 문맥적 일관성을 보존하고, 텍스트의 세분화 수준에 맞게 조절한다.

문서 구조를 기반으로 분할 (Document-structured based) 📚

HTML, Markdown, JSON 등 문서 자체의 내재된 구조를 활용하여 분할한다.

• 특징: 문서의 논리적 조직을 보존하고, 각 청크 내의 문맥을 유지하며, 검색이나 요약 같은 후속 작업에 더 효과적이다.
• 유형: Markdown의 헤더(#, ##), HTML의 태그, JSON의 객체나 배열 등을 기준으로 분할한다.

의미적 유사도를 기반으로 분할 (Semantic meaning based) 🤔

텍스트의 내용적 의미를 직접 분석하여 분할한다.

• 특징: 의미적 변화가 큰 지점을 찾아 분할한다. 이를 통해 의미적으로 더욱 응집된 청크를 만들고, 후속 작업의 품질을 향상시킨다.
• 예시: 슬라이딩 윈도우(Sliding Window) 방식을 사용하여 문장 그룹의 임베딩을 생성하고, 임베딩 간의 유의미한 차이를 비교하여 분할 지점을 찾는다.

참고로, 슬라이딩 윈도우는 특정 데이터를 어떠한 단위(윈도우)로 나누고, 그 데이터 단위들을 순회(슬라이딩)하며 작업을 진행하는 기법이다. 의미적 유사도 기반 분할의 경우, 특정 단위의 문장(윈도우)의 의미를 분석하여 임베딩을 하고, 다음 문장으로 넘어간 뒤(슬라이딩), 다시 해당 문장을 임베딩하여 임베딩된 문장 사이의 차이점을 알아내 분할 지점을 찾는 방식이다.

청크 (Chunk) 🧩

텍스트 분할을 진행할 때 고려해야 하는 점은 자연어를 청크로 나누는 단위인 청크 크기(Chunk Size)와, 나누어진 청크 사이의 관계인 청크 중첩(Chunk Overlap)을 유지하는 것이다. 인접한 청크 사이에 청크 중첩을 적용하여 문맥적 연속성을 유지시켜주는 작업을 진행한다.

청크 크기와 청크 중첩, 이 두 변수를 적용하여 텍스트 분할을 진행하게 되는데, 해당 변수의 크기에 따라 자연어를 분석하는 정도가 달라진다. 중요한 점은, 해당 자연어가 어떠한 종류의 자연어인지가 중요한데, 각 종류에 따라 문장의 복잡도와 구조가 다르기 때문이다.

청크 크기에 따라 좋은 성능을 보이는 문서들을 표로 정리하면 다음과 같다. 이는 문서의 구조와 내용적 특성을 기반으로 한다.

청크 크기를 결정할 때는 문서의 내용이 얼마나 독립적인지와 문맥이 얼마나 중요한지를 기준으로 판단하는 것이 중요하다. 정형화되고 독립적인 내용이 많은 문서는 작은 청크가, 문맥적 흐름과 논리적 관계가 중요한 문서는 큰 청크가 더 효율적이다.

또한, 청크 오버랩은 보통 청크 크기의 10~20% 를 사용한다. 문서 구조와 내용에 따라 적절한 청크 크기를 찾아내고 10~20% 비율 안에서 최적의 오버랩 비율을 찾아내는 것이 좋은 텍스트 분할기를 만드는 방법이라 볼 수 있겠다.

다음 시간에는 LangChain 환경에서 간단한 청킹 실습을 진행해 보겠다.

[참고] LangChain Text splitters

저번에는 LangChain을 통해서 Prompt Engineering을 적용하는 법을 알아보았는데, 사실 Prompt Engineering 최근 LLM을 구성하는데 있어서 매우 중요한 기술이다. 따라서 Prompt Engineering Guide에서 학습 한 내용을 내 나름대로 정리해 보았다.

프롬프팅 엔지니어링이란? 🤖

프롬프팅 엔지니어링은 사람이 모델의 프롬프트를 개발하는 행위를 이야기한다. 따라서 비교적 최근에 활발히 연구되고 있는 분야다. 프롬프팅 엔지니어링은 LLM(Large Language Model, 거대 언어 모델)의 역량을 향상시키고, LLM 및 기타 도구와 인터페이스를 형성할 수 있다.

또한 중요한 점은 바로 하드웨어적이 변경 없이 오직 내부의 자연어로 처리된 프롬프팅을 통해 성능을 개선한다는 점이다. 사실 지금은 크게 와 닿지는 않는다...

매개변수 (Parameters) ⚙️

매개변수는 프롬프팅 엔지니어링에서 사용하는 용어들과 더불어 성능을 조절할 수 있는 변수들이다. 프레임워크, 도구를 사용해서 프롬프팅을 할 때 이러한 변수들을 사용해서 성능과 출력 결과를 조절하게 된다.

Temperature

모델이 생성하는 텍스트의 무작위성을 조절하는 매개변수다.

• 낮은 값을 설정하면 확률이 가장 높은 단어를 선택하여 결정적이고 사실적인 응답을 생성한다. 이는 질의응답과 같은 작업에 적합하다.
• 높은 값을 설정하면 다양한 단어의 선택 가중치를 높여 다양하고 창의적인 응답을 촉진한다. 이는 시 창작과 같은 작업에 유용하다.

Top-p

온도와 유사하게 텍스트 생성의 결정성을 제어하는 매개변수다.

• 낮은 값을 설정하면 정확하고 사실적인 답변을 생성한다.
• 높은 값을 설정하면 보다 다양한 응답을 유도한다.
• 일반적으로 온도(temperature)와 Top-p 중 하나만 조정하는 것이 권장된다.

최대 길이 (Max Length)

모델이 생성할 수 있는 최대 토큰(단어) 수를 설정하는 매개변수다. 길고 불필요한 응답을 방지하고 비용을 관리하는 데 도움이 된다.

정지 시퀀스 (Stop Sequences)

모델의 텍스트 생성을 중단시키는 특정 문자열이다. 응답의 길이와 구조를 제어하는 데 사용된다.

빈도 페널티 (Frequency Penalty)

이미 생성된 단어가 다시 등장할 확률을 낮추는 매개변수다. 값이 높을수록 모델의 응답에서 단어의 반복을 방지한다.

존재 페널티 (Presence Penalty)

이미 한 번이라도 등장한 단어에 동일한 페널티를 적용하여 반복을 방지하는 매개변수다.

• 값이 높을수록 다양한 텍스트를 생성하는 데 도움이 되고, 낮은 값은 사실 기반의 집중적인 응답에 적합하다.
• 빈도 페널티와 존재 페널티 중 하나만 조정하거나 둘 다 조정하지 않는 것이 일반적인 권장 사항이다.

프롬프팅 기법 (Prompting Techniques) ✨

Zero-shot

Zero-shot은 모델에게 예시를 제공하지 않고, 질문과 지시만으로 답변을 유도하는 기법이다. 모델의 사전 학습된 지식을 활용하여 직접적인 답변을 생성한다.

텍스트를 중립, 부정 또는 긍정으로 분류합니다.
텍스트: 휴가는 괜찮을 것 같아요.
감정:

중립

이 프롬프트는 별도의 배경 정보나 예시 없이 모델에게 바로 질문을 던진다. 예제를 제시하지 않지만 모델의 사전 학습된 지식을 통해서 답변을 하게 된다. LLM은 뛰어난 제로샷 능력을 보여준다고 한다. 하지만 복잡한 작업에서는 개선이 필요하다.

Few-shot

Few-shot은 원하는 답변의 패턴을 모델에게 학습시키기 위해 질문과 함께 몇 가지 예시를 제공하는 기법이다. 이를 통해 모델은 예시의 형식을 모방하여 답변을 생성한다.

정말 멋지네요! // 긍정
이건 나쁘다! // 부정
와우 그 영화 정말 멋졌어요! // 긍정
정말 끔찍한 쇼였어! // 부정

이 프롬프트는 답변을 유도해서 정확한 출력을 하게 한다.

정말 멋지네요! // 부정
이건 나쁘다! // 긍정
와우 그 영화 정말 멋졌어요! // 긍정
정말 끔찍한 쇼였어! //

현재 대규모 모델들은 이러한 Zero-shot, Few-shot 전부 가능하며, 위와 같이 무작위로 입력된 프롬프트에 대해서도 정확한 답변을 가져올 수 있다고 한다. 하지만 Few-shot 프롬프트도 복잡한 추론 작업에서는 완벽한 기술은 아니다.

이 집합 {15, 32, 5, 13, 82, 7, 1}에서 홀수를 모두 더하면 짝수이다.
A:

네, 이 집합의 홀수를 모두 더하면 짝수인 107입니다.

만약 질의 결과가 이렇게 나왔을 때는 다른 방식으로 프롬프팅을 진행해야 한다.

이 집합 {4, 8, 9, 15, 12, 2, 1}에서 홀수의 합은 짝수입니다.
A: 답은 거짓입니다.
이 집합 {17, 10, 19, 4, 8, 12, 24}에서 홀수의 합은 짝수입니다.
A: 정답은 참입니다.
이 집합 {16, 11, 14, 4, 8, 13, 24}에서 홀수의 합은 짝수입니다.
A: 답은 참입니다.
이 집합 {17, 9, 10, 12, 13, 4, 2}에서 홀수의 합은 짝수입니다.
A: 답은 거짓입니다.
이 집합 {15, 32, 5, 13, 82, 7, 1}에서 홀수의 합은 짝수입니다.
A:

답은 참입니다.

위의 결과로 프롬프팅을 해도 안 되는 경우가 존재할 것이다. 이럴 때 필요한 것이 Chain-of-Thought다.

Chain-of-Thought (CoT) 🧠

CoT는 모델에게 "단계별로 생각하라"는 지시를 내려 복잡한 문제를 논리적인 사고 과정을 통해 해결하도록 유도하는 기법이다. 이를 통해 모델의 추론 오류를 줄이고 정확도를 높인다.

이 기법이 프롬프트 엔지니어링의 핵심이되는 추론 과정을 탑재한 기법이다.

앞으로 나오는 기법들은 해당 CoT를 활용해서 추론 과정을 바꾸고 여러가지 도구를 중간에 넣어서 성능을 향상시킨 것이다.

집합 {4, 8, 9, 15, 12, 2, 1}에서 홀수를 모두 더하면 짝수야.
답변: 홀수(9, 15, 1)를 모두 더하면 25가 돼. 위의 명제는 거짓이야.
집합 {17, 10, 19, 4, 8, 12, 24}에서 홀수를 모두 더하면 짝수야.
답변: 홀수(17, 19)를 모두 더하면 36이 돼. 위의 명제는 참이야.
집합 {16, 11, 14, 4, 8, 13, 24}에서 홀수를 모두 더하면 짝수야.
답변: 홀수(11, 13)를 모두 더하면 24가 돼. 위의 명제는 참이야.
집합 {17, 9, 10, 12, 13, 4, 2}에서 홀수를 모두 더하면 짝수야.
답변: 홀수(17, 9, 13)를 모두 더하면 39가 돼. 위의 명제는 거짓이야.
집합 {15, 32, 5, 13, 82, 7, 1}에서 홀수를 모두 더하면 짝수야.
답변:

홀수(15, 5, 13, 7, 1)를 모두 더하면 41이 돼. 위의 명제는 거짓이야.

위의 프롬프팅과 같이 추론 과정을 입력하면 모델이 훨씬 정확한 답변을 하게 된다.

Zero-shot CoT Prompting 🚀

모델의 성능이 향상되면서, Let's think step by step과 같은 질의 예시가 없는 Zero-shot이어도 모델이 추론 도출을 진행한다는 것이다.

현재의 LLM들은 이러한 제로샷 능력을 가지고 있다고 보면 된다.

나는 시장에 가서 사과 10개를 샀어. 사과 2개를 이웃에게 주고, 2개를 수리공에게 주었어. 그리고 사과 5개를 더 사서 1개는 내가 먹었어. 나는 몇 개의 사과를 가지고 있었니?

사과 11개

여기서 Zero-shot CoT Prompting을 적용하면 이렇게 구현할 수 있다.

나는 시장에 가서 사과 10개를 샀어. 나는 사과 2개를 이웃에게 주고, 2개를 수리공에게 주었어.
그리고 사과 5개를 더 사서 1개는 내가 먹었어.
사과가 몇 개나 남았니?
단계별로 생각해 보자.

먼저 사과 10개로 시작했어.
이웃에게 2개, 수리공에게 2개를 나누어 주었으므로 사과가 6개가 남았어.
그런 다음 사과 5개를 더 사서 이제 사과가 11개가 되었어.
마지막으로 사과 1개를 먹었으므로 사과 10개가 남게 된다.

Self-Consistency 🔄

Self-Consistency는 CoT를 확장한 기법으로, 같은 질문에 대해 여러 가지 다른 사고 경로를 탐색하여 다양한 답변을 생성한 뒤, 가장 일관된 답변을 최종 결과로 선택하는 방식이다.

참고로 디코딩은 LLM의 사고를 바탕으로 실제 텍스트를 선택해서 결과를 내놓는 과정이다. LLM에서 많이 쓰이는 디코딩 방식은 크게 세 가지로 요약할 수 있다. 이 방식들은 각각 속도, 품질, 다양성 측면에서 서로 다른 장단점을 가지고 있으며, 해결하고자 하는 문제의 성격에 따라 적절한 방식을 선택하여 사용한다.

탐욕 알고리즘 (Greedy Decoding)

가장 단순하고 빠른 방식으로, 매 단계에서 확률이 가장 높은 단어 하나만을 선택한다.

• 속도: 매우 빠르다.
• 결과: 매번 동일한 결과를 생성하며, 다양성이 전혀 없다.
• 장점: 계산 비용이 매우 낮아 리소스 소모가 적다.
• 단점: 지역 최적해(local optimum)에 빠져 최적의 문맥을 놓칠 수 있다.

빔 서치 (Beam Search)

매 단계에서 가장 확률이 높은 **K개의 단어(빔)**를 동시에 추적하며, 여러 가능한 경로를 탐색한다. K개의 경로 중 최종적으로 가장 높은 확률의 문장을 선택한다.

• 속도: 탐욕 알고리즘보다 느리다.
• 결과: 탐욕 알고리즘보다 더 나은 품질의 결과를 생성할 가능성이 높다.
• 장점: 탐욕 알고리즘의 한계를 보완하며, 전체적인 문맥을 고려한다.
• 단점: 계산 비용이 높고, 생성된 문장이 다소 반복적이거나 일관성이 떨어질 수 있다.

샘플링 (Sampling)

확률이 가장 높은 단어 하나만 선택하는 것이 아니라, 예측된 확률 분포에 기반하여 무작위로 단어를 선택하는 방식이다.

• 속도: 탐욕 알고리즘과 비슷하거나 조금 더 느리다.
• 결과: 매번 다른 결과물을 생성하며, 다양성과 창의성이 높다.
• 장점: 창의적인 글쓰기나 Self-Consistency와 같이 여러 다른 추론 경로를 생성하는 데 필수적이다.
• 단점: 때때로 의미 없는 문장이나 논리적이지 않은 결과물을 생성할 수 있다.

만약 탐욕 알고리즘 디코딩으로 자연어를 생성한다면, 확률이 높은 결과로 나아가는 특징이 있지만, 만약 지역 최적해에 빠지게 되면 최악의 결과를 내놓게 된다. 따라서 이를 보완한 것이 샘플링을 사용하는 Self-Consistency이다.

내가 6살이었을 때 내 여동생은 내 나이의 절반인 나이였어.
지금 나는 70살이라면 여동생은 몇 살일까?

35

위의 프롬프팅을 CoT를 적용할 수 있다.

Q: 과수원에는 15그루의 나무가 있어. 과수원의 일꾼들이 오늘 과수원에 나무를 심을 거야. 나무 심기가 끝나면 21그루의 나무가 있을 거야. 오늘 과수원 일꾼들은 몇 그루의 나무를 심었을까?
A: 15그루로 시작합니다. 나중에 나무가 21그루가 됩니다. 그 차이가 그들이 심은 나무의 수일 것입니다. 따라서 그들은 21 - 15 = 6그루의 나무를 심었어야 합니다. 정답은 6입니다.
Q: 주차장에 3대의 차량이 있고, 2대의 차량이 더 도착하면 주차장에 몇 대의 차량이 있을까?
A: 주차장에 이미 3대의 차량이 있습니다. 2대가 더 도착합니다. 이제 3 + 2 = 5대의 차량이 있습니다. 정답은 5입니다.
Q: 지호는 초콜릿을 32개, 여동생은 42개를 가지고 있었어. 둘이 35개를 먹었다면 총 몇 개가 남았을까?
A: 레아는 초콜릿 32개, 레아의 여동생은 42개를 가지고 있었습니다. 즉, 원래 32개 + 42개 = 74개의 초콜릿이 있었습니다. 35개를 먹었습니다. 따라서 총 74 - 35 = 39개의 초콜릿이 남아 있습니다. 정답은 39입니다.
Q: 선우는 막대 사탕을 20개 가지고 있었어. 그는 두리에게 막대 사탕을 몇 개 주었어. 이제 선우는 막대 사탕 12개를 가지고 있어. 선우는 두리에게 몇 개의 막대 사탕을 줬을까?
A: 선우는 막대 사탕 20개를 가지고 있었습니다. 이제 선우는 12개만 가지고 있으므로, 나머지는 두리에게 주었을 것입니다. 선우가 두리에게 준 막대 사탕의 수는 20 - 12 = 8개다. 정답은 8개다.
Q: 내가 6살이었을 때 내 여동생은 내 나이의 절반인 나이였어. 지금 나는 70살이고 내 여동생은 몇 살일까?
A:

이렇게 CoT를 진행하면 샘플링으로 여러 개의 답이 나올 것이다.

내가 6살이었을 때 여동생은 내 나이의 절반이었으므로 3살이었다. 이제 나는 70살이므로 여동생은 70 - 3 = 67살이다. 정답은 67이다.

화자가 6살이었을 때 여동생은 화자의 절반 나이인 3살이었다. 이제 화자가 70살이 되었으므로 여동생은 70 - 3 = 67살이 된다. 정답은 67이다.

내가 6살이었을 때 여동생은 내 나이의 절반이었으므로 3살이고, 이제 나는 70살이므로 여동생은 70/2 = 35살이다. 정답은 35이다.

디코딩으로 3개의 출력이 나왔고 이제 Self-Consistency는 다수결 합의를 통해 67과 35 중 더 많은 67을 선택하게 된다.

Generative knowledge prompting 💡

Generative knowledge prompting은 말 그대로 프롬프팅에 사용할 지식을 미리 생성하는 기법이다.

골프의 목적 중 하나는 다른 사람보다 더 높은 점수를 얻기 위해 노력하는 것이다.
예, 아니오?

예.

골프는 홀에 공을 넣어서, 타수가 최저가 되게 해야 한다. 이때 타수는 점수로 계산되므로, 점수가 낮도록 노력해야 된다. 따라서 해당 출력은 오답이다. 이를 개선하려면 위와 같은 형태의 질문이 들어왔을 때 해당 주제의 전반적인 지식을 지시하여 지식 수준을 높이는 프롬프팅이 가능하다.

만약 LLM에게 해당 질문을 하기 전에, 골프에 대한 지식을 알려줘라고 입력하면 골프에 대한 지식을 출력할 것이다.

Input: 그리스는 멕시코보다 크다.
Knowledge: 그리스는 약 131,957 제곱 킬로미터이고, 멕시코는 약 1,964,375 제곱 킬로미터로 멕시코가 그리스보다 1389% 더 크다.
Input: 안경은 항상 김이 서린다.
Knowledge: 안경 렌즈에는 땀, 호흡 및 주변 습도에서 나오는 수증기가 차가운 표면에 닿아 식은 다음 작은 액체 방울로 변하여 안개처럼 보이는 막을 형성할 때 응결이 발생한다. 특히 외부 공기가 차가울 때는 호흡에 비해 렌즈가 상대적으로 차가워진다.
Input: 물고기는 생각할 수 있다.
Knowledge: 물고기는 보기보다 훨씬 더 똑똑하다. 기억력과 같은 많은 영역에서 물고기의 인지 능력은 인간이 아닌 영장류를 포함한 '고등' 척추동물과 비슷하거나 그 이상이다. 물고기의 장기 기억력은 복잡한 사회적 관계를 추적하는 데 도움이 된다.
Input: 평생 담배를 피우는 것의 일반적인 결과는 폐암에 걸릴 확률이 정상보다 높다는 것입니다.
Knowledge: 평생 동안 하루 평균 담배를 한 개비 미만으로 꾸준히 피운 사람은 비흡연자보다 폐암으로 사망할 위험이 9배 높았다. 하루에 한 개비에서 열 개비 사이의 담배를 피운 사람들은 폐암으로 사망할 위험이 비흡연자보다 거의 12배 높았다.
Input: 돌은 조약돌과 같은 크기다.
Knowledge: 조약돌은 퇴적학의 우든-웬트워스 척도에 따라 입자 크기가 4~64밀리미터인 암석 덩어리다. 조약돌은 일반적으로 과립(직경 2~4밀리미터)보다는 크고 자갈(직경 64~256밀리미터)보다는 작은 것으로 간주된다.
Input: 골프의 목적 중 하나는 다른 사람보다 더 높은 점수를 얻기 위해 노력하는 것이다.
Knowledge:

위의 출력 마지막 질문에 답을 하기 전에 LLM은 골프에 대한 지식을 생성할 것이다.

# Knowledge 1
골프의 목적은 최소의 스트로크로 한 세트의 홀을 플레이하는 것이다. 골프 라운드는 일반적으로 18홀로 구성된다.
각 홀은 표준 골프 코스에서 라운드 중 한 번씩 플레이된다. 각 스트로크는 1점으로 계산되며 총 스트로크 수를 사용하여 게임의 승자를 결정한다.

# Knowledge 2
골프는 경쟁하는 선수(또는 골퍼)가 여러 종류의 클럽을 사용하여 가장 적은 수의 스트로크로 코스에 있는 한 세트의 홀에 공을 치는 정밀한 클럽 앤 볼 스포츠다.
각 홀에서 기록한 총 타수를 합산하여 계산하는 점수가 최저가 되도록 코스를 완주하는 것이 목표다.
가장 낮은 점수를 기록한 플레이어가 게임에서 승리한다.

이렇게 지식이 생성이 되면, LLM은 훨씬 쉽게 추론이 가능할 것이다.

Prompt Chaining ⛓️

프롬프트 체이닝 기법은 LLM의 작업을 하위 작업으로 나누는 것이다. 만약 하나의 작업에 대해 여러 개의 하위 작업으로 나누어지게 된다면, 각 응답을 서로 활용해서 보완이 가능하다. 이러한 연쇄적인 작용을 프롬프트 체이닝이라고 한다.

프롬프트 체이닝은 이러한 성능 개선뿐만 아니라 안전성과 작업의 직관성, 투명성을 높여줘서 사람 기준에서 디버깅과 분석을 하기에 용이하게 한다. 특히 문서 기반 자료를 분석할 때 유용한데, 아래 예시가 있다.

# Prompt 1
You are a helpful assistant. Your task is to help answer a question given a document. The first step is to extract quotes relevant to the question from the document, delimited by ####. Please output the list of quotes using <quotes></quotes>. Respond with "No relevant quotes found!" if no relevant quotes were found.
####
{{document}}
####

이렇게 인용문을 #### 기준으로 나누어서 생성해 달라고 지시할 수 있다.

Given a set of relevant quotes (delimited by <quotes></quotes>) extracted from a document and the original document (delimited by ####), please compose an answer to the question. Ensure that the answer is accurate, has a friendly tone, and sounds helpful.
####
{{document}}
####
<quotes>
- Chain-of-thought (CoT) prompting[27]
- Generated knowledge prompting[37]
- Least-to-most prompting[38]
- Self-consistency decoding[39]
- Complexity-based prompting[41]
- Self-refine[42]
- Tree-of-thought prompting[43]
- Maieutic prompting[45]
- Directional-stimulus prompting[46]
- Textual inversion and embeddings[59]
- Using gradient descent to search for prompts[61][62][63][64]
- Prompt injection[65][66][67]
</quotes>

그러면 이렇게 출력이 나오게 되면 다시 해당 인용문을 사용해서 프롬프팅할 수 있다.

The prompting techniques mentioned in the document include:
1. Chain-of-thought (CoT) prompting[27]
2. Generated knowledge prompting[37]
3. Least-to-most prompting[38]
4. Self-consistency decoding[39]
5. Complexity-based prompting[41]
6. Self-refine[42]
7. Tree-of-thought prompting[43]
8. Maieutic prompting[45]
9. Directional-stimulus prompting[46]
10. Textual inversion and embeddings[59]
11. Using gradient descent to search for prompts[61][62][63][64]
12. Prompt injection[65][66][67]
Each of these techniques employs unique strategies to enhance or specify the interactions with large language models to produce the desired outcomes.

이제 모델은 인용문과 문서를 기반으로 응답하여 훨씬 정확한 답변을 할 것이다.

Tree of Thoughts (ToT) 🌳

해당 기법은 기존의 CoT에서 여러 가지의 의견을 가진 추론 과정을 생성하는 방법을 사용한다. 입력이 들어오면 위의 그림과 같이 여러 개의 추론 과정을 생성해낸다. 이때, 추론 과정에서 생성된 생각들을 평가하여 가장 높은 확률의 생각을 판단한다.

위의 그림에서 Propose Prompt는 프롬프팅이 추론하여 생각을 생성하는 과정이다. Value prompt는 값을 평가하여 각 생각들의 정답 도달 확률을 구하게 된다.

연구 결과를 보면 ToT가 다른 기법들보다 월등히 뛰어나다고 한다. 그러나 연산이 매우 오래 걸려서 고도화된 작업이나 퍼즐 문제 등 복잡한 연산 문제를 처리하는 데 적절하다.

[참고] Prompt Engineering Guide

이번에는 저번에 이어서 대화 맥락을 유지시켜 주는 trimmer 기능에 대해서 알아보겠다. Chatbot은 지금 하는 대화와 이전에 나눈 대화도 기억해서 사용자와 대화해야 한다. 이것을 가능하게 해주는 것이 trimmer 함수이다.

✂️ trim_messages

trimmer = trim_messages(
    max_tokens=512,
    strategy="last",
    token_counter=model,
    include_system=True,
    allow_partial=False,
    start_on="human",
)

messages = [
    SystemMessage(content="you're a good assistant"),
    HumanMessage(content="hi! my name is HYK"),
    AIMessage(content="hi! HYK!"),
    HumanMessage(content="My favorite color is blue."),
    AIMessage(content="nice color!"),
    HumanMessage(content="My favorite movie is DarkKnight."),
    AIMessage(content="nice movie!"),
    HumanMessage(content="whats 2 + 2"),
    AIMessage(content="4"),
    HumanMessage(content="thanks"),
    AIMessage(content="no problem!"),
    HumanMessage(content="having fun?"),
    AIMessage(content="yes!"),
]

trimmer.invoke(messages)

위의 코드는 메시지 트리머를 정의한 코드이다. 토큰을 충분히 크게 주어서 이전 대화를 최대한 많이 기억할 수 있도록 하였다. 만약 토큰을 적게 할당하면 이전에 나눈 많은 양의 대화를 잊을 것이다. messages 변수는 Chatbot에게 메시지를 주입하기 위해 설정한 배열이다.

이를 통해 Chatbot은 해당 대화 내용을 기억하고 있게 된다.

def call_model(state: State):
    trimmed_messages = trimmer.invoke(state["messages"])
    prompt = prompt_template.invoke(
        {"messages": trimmed_messages, "language": state["language"]}
    )
    response = model.invoke(prompt)
    return {"messages": response}

이렇게 모델을 정의할 때, trimmed_messages = trimmer.invoke(state["messages"])를 삽입해 준다.

query = "What's my name?."
language = "Korean"
input_messages = messages + [HumanMessage(query)]
output = app.invoke(
    {"messages": input_messages, "language": language},
    config,
)
output["messages"][-1].pretty_print()

query = "What's my favorite color?"
language = "English"
input_messages = messages + [HumanMessage(query)]
output = app.invoke(
    {"messages": input_messages, "language": language},
    config,
)
output["messages"][-1].pretty_print()

query = "내가 가장 좋아하는 영화는?"
input_messages = messages + [HumanMessage(query)]
language = "Korean"
output = app.invoke(
    {"messages": input_messages, "language": language},
    config,
)

마지막으로 input_messages = messages + [HumanMessage(query)]를 통해 정의한 메시지를 주입해 주면 된다.

💬 answer

================================== Ai Message ==================================

당신의 이름은 HYK입니다.
================================== Ai Message ==================================

Your favorite color is blue.
================================== Ai Message ==================================

당신이 가장 좋아하는 영화는 다크 나이트입니다.

이렇게 trimmer까지 구현을 완료했고, 다음 시간에는 RAG(Retrieval Augmented Generation)의 개념에 대해서 알아보겠다.

[참고] LangChain Build a Chatbot

저번 시간에 이어서 이번에는 Chatbot을 프롬프팅해서 지시를 내리는 작업을 하겠다. 프롬프팅은 간단하다. 프롬프팅의 기능으로는 자신이 원하는 스타일의 모델을 생성 가능하도록 자연어 지시를 내리는 것이다. 또한 언어를 설정하는 기능도 존재한다.

📝 Prompting Template

import os
from typing import Sequence
from langchain_core.messages import BaseMessage
from langgraph.graph.message import add_messages
from typing_extensions import Annotated, TypedDict
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, AIMessage
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import START, MessagesState, StateGraph
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

load_dotenv()
key = os.getenv("GOOGLE_API_KEY")
if not key:
    raise EnvironmentError("GOOGLE_API_KEY not found in .env")

model = init_chat_model("gemini-2.5-flash", model_provider="google_genai")

prompt_template = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "You are a happy assistant. Answer all questions with a smile.",
        ),
        MessagesPlaceholder(variable_name="messages"),
    ]
)


class State(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]


workflow = StateGraph(state_schema=State)


def call_model(state: State):
    prompt = prompt_template.invoke(state)
    response = model.invoke(prompt)
    return {"messages": response}


workflow.add_edge(START, "model")
workflow.add_node("model", call_model)

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

config = {"configurable": {"thread_id": "abc123"}}

query = "Hi! I'm HYK."
input_messages = [HumanMessage(query)]
output = app.invoke(
    {
        "messages": input_messages,
    },
    config,
)
output["messages"][-1].pretty_print()

query = "What's my name?"
input_messages = [HumanMessage(query)]
output = app.invoke(
    {
        "messages": input_messages,
    },
    config,
)
output["messages"][-1].pretty_print()

query = "How are you today?"
input_messages = [HumanMessage(query)]
output = app.invoke(
    {
        "messages": input_messages,
    },
    config,
)
output["messages"][-1].pretty_print()

위의 코드를 살펴보자.

prompt_template = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "You are a happy assistant. Answer all questions with a smile.",
        ),
        MessagesPlaceholder(variable_name="messages"),
    ]
)

일단 나는 행복한 느낌의 답변을 생성하는 프롬프팅을 하였다.

def call_model(state: State):
    prompt = prompt_template.invoke(state)
    response = model.invoke(prompt)
    return {"messages": response}

call_model()에 prompt를 넣어서 구동을 시켜보자.

💡 Answer

================================== Ai Message ==================================

Hello HYK! It's so lovely to meet you! 😊 I'm thrilled to be your happy assistant today! How can I help you?
================================== Ai Message ==================================

Why, your name is HYK! 😄 It's a pleasure to remember! Is there anything else I can help you with, HYK?
================================== Ai Message ==================================

Oh, I'm absolutely wonderful today, thank you for asking! 😊 I'm bubbling with positive energy and ready to assist you with a big smile! How about you, HYK? I hope you're having a fantastic day too!

이렇게 억지로 이모티콘을 쓰면서 행복해하는 모델을 볼 수 있다.

🌐 Prompting Language

이제 원하는 언어를 지시해 보겠다.

prompt_template = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            "You are a happy assistant. Answer all questions with a smile and in {language}.",
        ),
        MessagesPlaceholder(variable_name="messages"),
    ]
)

이렇게 마지막에 {language}로 말해 달라고 하면 모델을 정의할 때 들어간 언어 변수로 답변을 해주게 된다.

def call_model(state: State):
    prompt = prompt_template.invoke(state)
    response = model.invoke(prompt)
    return {"messages": response}

이제 언어를 각 메시지마다 설정해 보자.

query = "Hi! I'm HYK."
language = "Korean"
input_messages = [HumanMessage(query)]
output = app.invoke(
    {"messages": input_messages, "language": language},
    config,
)
output["messages"][-1].pretty_print()

query = "What's my name?"
language = "Spanish"
input_messages = [HumanMessage(query)]
output = app.invoke(
    {"messages": input_messages, "language": language},
    config,
)
output["messages"][-1].pretty_print()

query = "How are you today?"
input_messages = [HumanMessage(query)]
language = "Japanese"
output = app.invoke(
    {"messages": input_messages, "language": language},
    config,
)

💡 Answer

================================== Ai Message ==================================

안녕하세요, HYK님! 만나 뵙게 되어 정말 반갑습니다! 😊
================================== Ai Message ==================================

¡Claro que sí, HYK! ¡Tu nombre es HYK! 😊 ¡Es un placer conocerte!
================================== Ai Message ==================================

こんにちは！私はとても元気です、ありがとうございます！😊 HYKさんもお元気ですか？

이렇게 여러 가지 언어로 답변을 해주는 것을 볼 수 있다. 다음 시간에는 trimming을 통해 성능을 향상시키는 방법을 알아보겠다.

실습 출처: Build a Chatbot

LangChain은 요즘 핫한 AI 애플리케이션 개발을 도와주는 오픈소스 라이브러리이다. 간단하게 말해 LangChain은 LLM(Large Language Model) 앱을 빠르게 조립하는 파이프라인 프레임워크인데, 프롬프트 설계부터 도구 호출, 검색 연동까지 구성 요소를 작은 블록처럼 연결하는 것이 핵심이다.

위 그림은 LangChain에서 사용하는 도구들을 나눈 것이라 생각하면 된다. 한번 역할을 간단하게 살펴보겠다.

코드 환경에서는 LangChain을 통해 개발을 진행하게 된다. 그리고 LangGraph를 통해 HIP(Human In the Loop)이라는 방법으로 고도화 작업이 가능하다고 하는데, 이 부분은 나중에 알아보도록 하자.

또한 LangSmith를 통해 품질 모니터링과 테스트 같은 활동이 가능하다.

마지막으로 LangGraph Platform은 실제 제품화를 위한 API 추출과 Assistant화를 도와준다고 한다.

나는 일단 LangChain을 통해 코드 환경에서 간단한 실습을 진행하고, 프로젝트화를 통해 기능을 넣을 생각이다.

💬 Chatbot 만들기

이제 Chatbot 실습을 진행하겠다.

langchain
langchain-core
langgraph>0.2.27
dotenv

먼저 필요한 패키지다.

pip install -qU "langchain[google-genai]"

이 명령은 google-genai를 사용하게 해주는 LangChain 키트를 설치하는 명령어다. 이 명령어는 꼭 별도로 설치해야 한다. 그렇지 않으면 의존성 오류가 발생한다.

import os
from dotenv import load_dotenv

load_dotenv()

key = os.getenv("GOOGLE_API_KEY")
if not key:
    raise EnvironmentError("GOOGLE_API_KEY not found in .env")

from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, AIMessage

model = init_chat_model("gemini-2.5-flash", model_provider="google_genai")

resp = model.invoke(
    [
        HumanMessage(content="Hello, my name is choihyeok"),
        AIMessage(content="Hello choihyeok! How can I assist you today?"),
        HumanMessage(content="What's my name?"),
    ]
)
print(resp.content)

위 코드를 보면 from langchain.chat_models import init_chat_model을 통해 Chatbot 모델 기능을 사용 가능하다. 여기에 API 키를 넣어 사용하면 되며, 여기서는 Google-Gemini 2.25-flash 모델을 사용했다.

invoke를 통해 모델에 메시지를 삽입하고, HumanMessage와 AIMessage로 사람과 AI의 대화를 구분한다. 마지막에 resp.content를 출력하면 텍스트 응답만 확인할 수 있다.

📌 실행 예시

Your name is **choihyeok**.

그런데 우리가 원하는 것은 프로세스 환경에서 실시간 대화다.

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import START, MessagesState, StateGraph

workflow = StateGraph(state_schema=MessagesState)

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": response}

workflow.add_edge(START, "model")
workflow.add_node("model", call_model)

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

config = {"configurable": {"thread_id": "abc123"}}

query = "Hi! I'm HYK."
input_messages = [HumanMessage(query)]
output = app.invoke({"messages": input_messages}, config)
output["messages"][-1].pretty_print()

query = "What's my name?"
input_messages = [HumanMessage(query)]
output = app.invoke({"messages": input_messages}, config)
output["messages"][-1].pretty_print()

call_model 메서드를 선언해 state를 설정하고, LangGraph의 State 기능을 통해 대화 상태를 기억하게 한다.

여기서 LangGraph의 강력한 기능을 알 수 있는데, 바로 State로 워크플로를 관리하는 것이다. LangGraph는 하나의 프로세스를 정의해서 해당 모델이 어떠한 상태를 가지고 있는지 정의한다.

workflow = StateGraph(state_schema=MessagesState)

해당 코드가 핵심인데, StateGraph를 MessagesState로 정의하는 워크프로를 생성한다는 의미이다. 이제 모델은 해당 워크플로안에서 유지되면서 메세지를 받게된다.

workflow.add_edge(START, "model")
workflow.add_node("model", call_model)
memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

워크플로는 노드와 엣지 형태로 모델의 시작점과 진행 사항을 연결 및 유지 해준다.

위와 같이 구현하면 모델은 대화를 메모리에 저장하며 진행한다. 다만 현재는 프로세스를 종료하면 쓰레드가 정리되어 기록이 사라진다.

config = {"configurable": {"thread_id": "abc123"}}

이 코드로 쓰레드를 설정해 대화 세션을 구분할 수 있다.

📌 실행 예시

================================== Ai Message ==================================
Hi HYK! It's nice to meet you.
How can I help you today?

================================== Ai Message ==================================
Your name is HYK! You told me that when you first introduced yourself.

================================== Ai Message ==================================
I don't know your name. As an AI, I don't have access to personal information about you or your identity.
How can I help you today?

================================== Ai Message ==================================
Your name is HYK! I remember you told me that when we first started chatting.

위 출력에서 보듯, 첫 번째 메시지에서 이름을 알려줬지만 세번째 쓰레드에서는 이름을 모른다.

기본적인 구현은 위와 같으며, 다음에는 프롬프트 엔지니어링을 알아보겠다.

[참고] LangChain Build a Chatbot

형식

ls [옵션] [경로]

주요 옵션

• -l 상세 목록

• -a 숨김 파일 포함

• -R 하위 디렉터리 재귀

• -h 사람이 읽기 쉬운 크기

예시

ls -la

• 현재 디렉터리의 숨김 파일까지 상세 정보 출력

ls -lh /var/log

• /var/log의 파일 크기를 사람이 읽기 쉬운 단위로 표시

ls -R ~/projects

• projects 아래 하위 디렉터리까지 재귀적으로 나열

2. pwd — 현재 작업 디렉터리 경로 출력 Print Working Directory

형식

pwd [옵션]

주요 옵션

• -P 실제 경로(심볼릭 링크 해제)

• -L 논리 경로(기본값)

예시

pwd

• 현재 작업 디렉터리의 논리 경로 표시

pwd -P

• 심볼릭 링크를 해제한 실제 경로 표시

cd /var && pwd

• /var로 이동 후 경로 출력

3. cd — 디렉터리 이동 Change Directory

형식

cd [경로]

주요 옵션

• .. 상위 디렉터리

• ~ 홈 디렉터리

• • 이전 디렉터리로 전환

예시

cd ..

• 상위 디렉터리로 이동

cd ~/Downloads

• 홈의 Downloads 디렉터리로 이동

cd -

• 직전 작업 디렉터리로 이동

4. mkdir — 디렉터리 생성 Make Directory

형식

mkdir [옵션] 디렉터리

주요 옵션

• -p 하위 경로까지 일괄 생성

• -m 권한 지정

• -v 생성 과정 출력

예시

mkdir project

• 현재 위치에 project 디렉터리 생성

mkdir -p a/b/c

• 중간 경로가 없어도 a/b/c까지 모두 생성

mkdir -m 755 web

• 권한 755로 web 디렉터리 생성

5. rmdir — 비어 있는 디렉터리 삭제 Remove Directory

형식

rmdir [옵션] 디렉터리

주요 옵션

• -p 상위 디렉터리 연쇄 삭제

• -v 삭제 과정 출력

예시

rmdir empty

• empty 디렉터리를 삭제(비어 있어야 함)

rmdir -p a/b/c

• c 삭제 후 비어 있으면 b, a 순서로 삭제

rmdir -v old

• 삭제 과정을 출력하며 비어 있는 old 삭제

6. rm — 파일/디렉터리 삭제 Remove

형식

rm [옵션] 파일/디렉터리

주요 옵션

• -r 디렉터리 재귀 삭제

• -f 강제 삭제(확인 없음)

• -i 삭제 전 확인

예시

rm file.txt

• 일반 파일 file.txt 삭제

rm -rf build

• build 디렉터리와 내부 모든 항목 강제 삭제

rm -i data.csv

• 삭제 전 확인 프롬프트 표시

7. cp — 파일/디렉터리 복사 Copy

형식

cp [옵션] 원본 대상

주요 옵션

• -R 디렉터리 재귀 복사

• -p 권한/타임스탬프 보존

• -i 덮어쓰기 전 확인

예시

cp a.txt b.txt

• a.txt를 b.txt로 복사

cp -R src dst

• src 디렉터리 전체를 dst로 복사

cp -p config.ini /etc/app/

• 속성을 보존하며 복사

8. mv — 파일/디렉터리 이동 또는 이름 변경 Move

형식

mv [옵션] 원본 대상

주요 옵션

• -i 덮어쓰기 전 확인

• -n 덮어쓰기 방지

• -v 작업 로그 출력

예시

mv a.txt b.txt

• a.txt의 이름을 b.txt로 변경

mv /tmp/logs ./logs_old

• /tmp/logs를 현재 위치로 이동하며 logs_old로 변경

mv *.log logs/

• 현재 디렉터리의 로그 파일을 logs로 이동

9. touch — 빈 파일 생성 또는 타임스탬프 변경

형식

touch [옵션] 파일...

주요 옵션

• -t 지정한 타임스탬프 설정

• -a 접근 시간만 변경

• -m 수정 시간만 변경

예시

touch notes.md

• 빈 파일 생성(이미 존재 시 타임스탬프 갱신)

touch -t 202501010101 file

• 지정한 시각으로 타임스탬프 설정

touch -a -m data.bin

• 접근/수정 시간을 현재 시각으로 변경

10. file — 파일 타입 식별

형식

file [옵션] 파일...

주요 옵션

• -i MIME 타입 표시

• -b 파일명 없이 결과만

• -k 가능한 추가 정보 표시

예시

file image.png

• PNG 이미지 파일로 식별

file -i report.pdf

• MIME 타입(application/pdf) 표시

file -b archive.tar.gz

• 파일명 없이 타입 정보만 출력

11. zip — ZIP 압축 생성

형식

zip [옵션] 아카이브.zip 파일들

주요 옵션

• -r 디렉터리 재귀 압축

• -9 최대 압축률

• -q 조용한 모드

예시

zip logs.zip *.log

• 현재 디렉터리의 .log 파일을 logs.zip으로 압축

zip -r site.zip ./site

• site 디렉터리 전체를 압축

zip -9 backup.zip data/*

• 최대 압축률로 data 내용을 압축

12. unzip — ZIP 압축 해제

형식

unzip [옵션] 아카이브.zip [-d 대상]

주요 옵션

• -d 대상 디렉터리 지정

• -l 목록만 보기

• -o 덮어쓰기 강제

예시

unzip logs.zip

• 현재 디렉터리에 압축 해제

unzip -d out data.zip

• out 디렉터리로 압축 해제

unzip -l site.zip

• 압축 내부 파일 목록만 출력

13. tar — 아카이브 생성/해제 Tape ARchiver

형식

tar [옵션] [아카이브] [파일/디렉터리...]

주요 옵션

• -c 생성

• -x 해제

• -t 목록

• -f 파일 지정

• -z gzip 사용

• -v 진행 표시

예시

tar -cf backup.tar folder

• folder를 backup.tar로 묶기(압축 없음)

tar -czf backup.tar.gz folder

• gzip으로 압축한 tarball 생성

tar -xzf backup.tar.gz -C /restore

• /restore에 압축 해제

14. nano — 터미널 텍스트 편집기

형식

nano [옵션] 파일

주요 옵션

• -l 줄 번호 표시

• -B 백업 파일 생성

• -m 마우스 지원

예시

nano /etc/hosts

• hosts 파일을 편집

nano -l notes.md

• 줄 번호가 표시된 상태로 편집

nano -B config.ini

• 편집 시 config.ini~ 백업 생성

15. vi — 터미널 텍스트 편집기(Vim 포함)

형식

vi [+행] 파일

주요 옵션

• +N N번째 줄에서 시작

• -R 읽기 전용 모드

• -u NONE 기본 설정 없이

예시

vi app.py

• app.py 파일 편집

vi +10 main.c

• 10번째 줄에서 편집 시작

vi -R /etc/fstab

• 읽기 전용으로 열기

16. cat — 파일 내용 출력/결합 Concatenate

형식

cat [옵션] [파일...]

주요 옵션

• -n 줄 번호 출력

• -A 제어문자 표시

• -E 줄 끝 표시

예시

cat file.txt

• 파일 내용을 표준출력으로 표시

cat a.txt b.txt > all.txt

• 두 파일을 결합해 all.txt 생성

cat -n code.c | less

• 줄 번호를 붙여 페이지 단위로 보기

17. tac — 파일을 거꾸로 출력

형식

tac [옵션] 파일

주요 옵션

• -s 구분자 지정

• -b 구분자 뒤에 출력

• -r 정규식 구분자

예시

tac file.txt

• 마지막 줄부터 첫 줄까지 역순 출력

tac -s '---' parts.txt

• 지정 구분자로 블록 단위 역순 출력

tac -b -s "," csv_parts.txt

• 구분자 뒤에 이어 붙여 역순 출력

18. grep — 패턴 매칭 검색 Global Regular Expression Print

형식

grep [옵션] 패턴 [파일...]

주요 옵션

• -i 대소문자 무시

• -n 줄 번호

• -r 디렉터리 재귀

• -E 확장 정규식

예시

grep -n 'ERROR' app.log

• ERROR 포함 라인을 라인 번호와 함께 표시

dmesg | grep -i usb

• 커널 로그에서 usb 관련 메시지 필터링

grep -r 'TODO' src/

• src 디렉터리 전체에서 TODO 검색

19. sed — 스트림 편집기 Stream EDitor

형식

sed [옵션] '스크립트' [파일]

주요 옵션

• -n 선택 출력

• -E 확장 정규식

• -i 제자리 수정(in-place)

예시

sed -n '1,10p' file.txt

• 1~10행만 출력

sed 's/red/blue/g' colors.txt

• red를 blue로 전역 치환 후 출력

sed -i 's/DEBUG=false/DEBUG=true/' .env

• 파일을 직접 수정하여 값 변경

20. head — 파일 앞부분 출력

형식

head [옵션] 파일

주요 옵션

• -n N행 출력

• -c N바이트 출력

예시

head -n 20 access.log

• 앞 20줄 출력

head -c 1K big.bin

• 앞 1024바이트 출력

head README.md

• 기본 10줄 출력

21. tail — 파일 뒷부분 출력

형식

tail [옵션] 파일

주요 옵션

• -n N행

• -f 추가 내용 실시간 추적

• -c N바이트

예시

tail -n 50 access.log

• 마지막 50줄 출력

tail -f app.log

• 로그 파일을 실시간으로 추적

tail -c 512 data.bin

• 마지막 512바이트 출력

22. awk — 패턴 스캔과 처리 언어

형식

awk [옵션] '패턴{동작}' [파일]

주요 옵션

• -F 필드 구분자 지정

• NR 현재 레코드 번호

• NF 필드 개수

• $1..$N 필드 참조

예시

awk -F: '{print $1}' /etc/passwd

• 콜론 기준 1번째 필드(계정명) 출력

awk '{sum+=$1} END{print sum}' nums.txt

• 첫 필드 합계 계산

awk '$3>100 {print $0}' data.tsv

• 3번째 필드가 100 초과인 행 출력

23. sort — 정렬

형식

sort [옵션] [파일]

주요 옵션

• -r 내림차순

• -n 숫자 정렬

• -k N 정렬 키

• -t 구분자

예시

sort names.txt

• 기본 오름차순 정렬

sort -nr scores.txt

• 숫자 기준 내림차순 정렬

sort -t, -k2 data.csv

• 쉼표 구분, 2열 기준 정렬

24. cut — 필드/문자 범위 추출

형식

cut [옵션] 파일

주요 옵션

• -d 구분자

• -f 필드 리스트

• -c 문자 범위

예시

cut -d, -f2,4 data.csv

• 2, 4열만 추출

cut -c1-8 ids.txt

• 각 행의 1~8번째 문자 추출

cut -d: -f1 /etc/passwd

• 계정명 필드만 출력

25. diff — 두 파일의 차이 비교

형식

diff [옵션] 파일1 파일2

주요 옵션

• -u 통합 형식

• -r 디렉터리 재귀

• -q 차이 유무만

예시

diff a.txt b.txt

• 두 텍스트의 라인 단위 차이 표시

diff -u old.c new.c

• 패치에 적합한 통합 형식으로 표시

diff -r src_old src_new

• 디렉터리 간 차이를 재귀적으로 비교

26. tee — 출력을 화면과 파일에 동시에 기록

형식

cmd | tee [옵션] 파일

주요 옵션

• -a 파일에 이어쓰기

• -i SIGINT 무시

예시

echo hello | tee out.txt

• hello를 화면과 out.txt에 동시에 기록

dmesg | tee -a kernel.log

• 커널 메시지를 화면+파일(추가)로 기록

ls -l | tee list.txt | wc -l

• 목록을 저장하고 행 수 계산

27. tr — 문자 변환/삭제 Translate

형식

tr [옵션] 집합1 [집합2]

주요 옵션

• -d 삭제

• -s 반복 문자 압축

예시

echo 'Hello' | tr '[:upper:]' '[:lower:]'

• 대문자를 소문자로 변환

echo 'a,,b,,,c' | tr -s ','

• 연속된 쉼표를 하나로 압축

echo 'abc123' | tr -d '0-9'

• 숫자 문자 삭제

28. chmod — 파일 권한 변경 Change Mode

형식

chmod [옵션] 모드 파일

주요 옵션

• u/g/o 사용자/그룹/기타

• +/- 권한 추가/제거

• 숫자 표기 755 등

• -R 재귀 적용

예시

chmod 644 file.txt

• 소유자 읽기/쓰기, 그 외 읽기

chmod u+x script.sh

• 소유자에 실행 권한 추가

chmod -R 755 bin/

• 디렉터리 전체에 실행 권한 부여

29. chown — 파일 소유자/그룹 변경 Change Owner

형식

chown [옵션] 소유자[:그룹] 파일

주요 옵션

• -R 재귀 적용

• --from 기존 소유자 조건

예시

sudo chown user file.txt

• file.txt의 소유자를 user로 변경

sudo chown user:staff -R www

• www 디렉터리와 내부의 소유자/그룹 변경

sudo chown :www-data app.log

• 그룹만 www-data로 변경

30. ln — 하드/심볼릭 링크 생성

형식

ln [옵션] 원본 링크명

주요 옵션

• -s 심볼릭 링크

• -f 기존 링크 덮어쓰기

• -n 심볼릭 링크 대상 처리

예시

ln file.txt file_hard

• 하드 링크 생성

ln -s /opt/app/bin/run ./run

• 실행 파일의 심볼릭 링크 생성

ln -sf new.conf current.conf

• 기존 링크를 새 대상에 강제로 갱신

31. find — 파일 검색

형식

find 경로 [조건] [동작]

주요 옵션

• -name 이름 패턴

• -type 파일 타입

• -size 크기 조건

• -exec 명령 실행

예시

find . -name '*.log'

• 현재 디렉터리에서 .log 파일 검색

find /var -type d -name 'nginx'

• /var에서 디렉터리 nginx 검색

find . -size +100M -exec rm -i {} \;

• 100MB 초과 파일을 찾아 삭제 확인

32. locate — 인덱스 기반 빠른 파일 검색

형식

locate [패턴]

주요 옵션

• -i 대소문자 무시

• -n N개 결과 제한

예시

locate ssh_config

• 시스템 DB에서 ssh_config 경로 빠르게 검색

locate -i readme

• 대소문자 무시하고 README/Readme 등 검색

locate -n 5 nginx.conf

• 최대 5개 결과만 표시

33. which — 실행 파일의 경로 표시

형식

which 프로그램

예시

which python

• python 실행 파일의 절대 경로 출력

which ls

• ls 명령의 실제 경로 확인

which node

• node가 PATH에 있는지 확인

34. whereis — 명령의 바이너리/소스/매뉴얼 위치

형식

whereis 프로그램

주요 옵션

• -b 바이너리만

• -m 매뉴얼만

• -s 소스만

예시

whereis ls

• ls의 바이너리와 매뉴얼 위치 표시

whereis -b gcc

• gcc 바이너리 위치만 표시

whereis -m bash

• bash의 man 페이지 위치 표시

35. du — 디스크 사용량 추정 Disk Usage

형식

du [옵션] [경로]

주요 옵션

• -h 사람이 읽기 쉬운 단위

• -s 총합 요약

• -d 깊이 제한

예시

du -h .

• 현재 디렉터리의 각 항목 사용량 표시

du -sh /var/log

• /var/log의 총 사용량 요약

du -h -d1 /home/user

• /home/user 하위 1단계까지 사용량 표시

36. df — 파일시스템별 여유/전체 디스크 용량

형식

df [옵션] [경로]

주요 옵션

• -h 사람이 읽기 쉬운 단위

• -T 파일시스템 타입 표시

• -i inode 정보

예시

df -h

• 모든 마운트의 용량/사용량을 사람이 읽기 쉬운 단위로 표시

df -T /

• 루트 파티션의 파일시스템 타입과 용량 표시

df -i

• inode 사용 현황 표시

37. free — 메모리/스왑 사용량

형식

free [옵션]

주요 옵션

• -h 사람이 읽기 쉬운 단위

• -m MB 단위

• -s N초마다 갱신

예시

free -h

• RAM/스왑 총량과 사용량을 보기 좋게 표시

free -m

• 메모리 정보를 MB 단위로 표시

free -h -s 5

• 5초마다 갱신하여 메모리 사용 추적

38. top — 실시간 프로세스/리소스 모니터

형식

top

주요 옵션

• -p PID 특정 프로세스만

• -u USER 사용자 필터

예시

top

• CPU/메모리 사용량 상위 프로세스 실시간 표시

top -u www-data

• 특정 사용자 프로세스만 모니터링

top -p 1234

• PID 1234의 리소스 사용만 추적

39. ps — 프로세스 스냅샷

형식

ps [옵션]

주요 옵션

• aux 모든 프로세스 상세

• -ef 표준 포맷

• -o 출력 형식 지정

예시

ps aux | grep nginx

• nginx 관련 프로세스 찾기

ps -ef --forest

• 트리 형태로 프로세스 관계 표시

ps -o pid,cmd -p 1234

• 특정 PID의 정보만 출력

40. kill — 프로세스 종료 신호 전송

형식

kill [옵션] PID

주요 옵션

• -SIGTERM 정상 종료 요청

• -9 강제 종료 SIGKILL

• -l 신호 목록

예시

kill 1234

• PID 1234에 종료 요청

kill -9 5678

• PID 5678 강제 종료

kill -HUP 1111

• PID 1111 설정 재로딩(HUP) 유도

41. pkill — 이름/조건으로 프로세스에 신호 전송

형식

pkill [옵션] 패턴

주요 옵션

• -f 전체 명령줄 매칭

• -u 사용자 필터

• -9 SIGKILL

예시

pkill nginx

• nginx라는 이름의 프로세스 종료 요청

pkill -f 'python app.py'

• 명령줄에 패턴이 포함된 프로세스 종료

pkill -u www-data nginx

• 특정 사용자 소유 nginx만 종료

42. xargs — 표준입력을 인수로 변환해 명령 실행

형식

xargs [옵션] 명령

주요 옵션

• -0 널 구분자 입력

• -n N개씩 나눠 실행

• -I{} 자리표시자 사용

예시

printf 'a\nb\nc' | xargs echo

• a b c를 인수로 전달하여 한 줄 출력

find . -name '*.log' -print0 | xargs -0 rm -f

• 널 구분자로 안전하게 삭제

cat list.txt | xargs -n 1 wget -q

• URL 목록을 한 줄씩 wget 실행

43. man — 매뉴얼 페이지 보기 Manual

형식

man [섹션] 명령

주요 옵션

• -k 키워드 검색(apropos)

• -f 간단 설명(whatis)

예시

man grep

• grep의 공식 매뉴얼 페이지 열기

man 5 crontab

• 섹션 5 포맷 문서(crontab 파일 형식) 보기

man -k archive

• 아카이브 관련 명령 검색

44. alias — 명령 별칭 설정

형식

alias 이름='명령'

예시

alias ll='ls -alF'

• ll 입력만으로 상세/형식 표시 목록

alias gs='git status'

• git status를 gs로 단축

alias rm='rm -i'

• rm 사용 시 항상 확인 받기

45. unalias — 별칭 해제

형식

unalias [옵션] 이름

주요 옵션

• -a 모든 별칭 제거

예시

unalias ll

• ll 별칭 제거

unalias -a

• 현재 셸의 모든 별칭 제거

unalias gs || true

• 없어도 에러 무시하고 진행

46. history — 명령 기록 조회/관리

형식

history [옵션]

주요 옵션

• -c 지우기

• -d N 특정 항목 삭제

예시

history | tail

• 최근 실행한 명령 몇 줄 확인

history -d 100

• 100번째 기록 삭제

history -c

• 전체 히스토리 초기화

47. env — 환경 변수 조회/실행 환경 지정

형식

env [변수=값]... [명령]

주요 옵션

• -i 빈 환경으로 실행

예시

env | sort

• 현재 환경 변수 목록 표시

env PATH=/custom/bin:$PATH mycmd

• 일시적으로 PATH를 바꿔 실행

env -i sh -c 'echo $PATH'

• 빈 환경으로 셸을 실행

48. export — 환경 변수 내보내기(자식 프로세스에 전달)

형식

export 변수=값

주요 옵션

• -p 현재 내보낸 변수 표시

예시

export JAVA_HOME=/opt/jdk

• JAVA_HOME 환경 변수 설정

export PATH=$HOME/bin:$PATH

• 사용자 bin을 PATH 앞에 추가

export -p | grep JAVA_HOME

• 내보낸 변수 목록에서 JAVA_HOME 확인

49. echo — 문자열 출력

형식

echo [옵션] 문자열

주요 옵션

• -n 끝의 개행 생략

• -e 백슬래시 이스케이프 해석

예시

echo Hello

• Hello 출력 후 개행

echo -n 'No newline'

• 개행 없이 출력

echo -e 'A\nB'

• 이스케이프를 해석해 줄바꿈 포함 출력

50. printf — 포맷 지정 출력

형식

printf 포맷 [인수...]

예시

printf '%s %d\n' user 3

• 문자열과 정수를 형식에 맞게 출력

printf '%.2f\n' 3.14159

• 소수점 둘째 자리까지 반올림 출력

printf '%-10s | %5d\n' name 42

• 좌/우 정렬 폭 지정 출력

51. date — 시각 표시/설정

형식

date [옵션] [+포맷]

주요 옵션

• -u UTC 기준

• -d 입력 시각 해석

• -s 시스템 시각 설정

예시

date '+%Y-%m-%d %H:%M:%S'

• 지정 형식으로 현재 시각 출력

date -u

• UTC 기준 현재 시각 출력

date -d '2025-01-01 12:00' '+%s'

• 해당 시각의 epoch 초 계산

52. cal — 달력 출력

형식

cal [월] [년]

주요 옵션

• -y 전체 연도 달력

• -3 이전/다음 달 포함

예시

cal

• 현재 달의 달력 출력

cal 12 2025

• 2025년 12월 달력 출력

cal -y 2026

• 2026년 1~12월 달력 출력

53. uname — 시스템 정보 출력

형식

uname [옵션]

주요 옵션

• -a 모든 정보

• -r 커널 릴리스

• -m 머신 하드웨어

예시

uname -a

• 커널/호스트/아키텍처 등 전체 정보 표시

uname -r

• 커널 버전 표시

uname -m

• 머신 아키텍처(x86_64 등) 표시

54. hostname — 호스트명 조회/설정

형식

hostname [옵션] [이름]

주요 옵션

• -I IP 주소들

• -f FQDN 전체 도메인명

예시

hostname

• 현재 호스트명 출력

hostname -I

• 호스트에 할당된 IP 리스트 출력

sudo hostname new-host

• 호스트명을 일시적으로 변경

55. ping — 네트워크 연결 확인 ICMP Echo

형식

ping [옵션] 대상

주요 옵션

• -c 횟수 지정

• -i 간격

• -W 타임아웃

예시

ping -c 4 8.8.8.8

• 구글 DNS에 4회 패킷 전송 테스트

ping -c 3 example.com

• 도메인 이름으로 연결 확인

ping -i 0.2 -c 5 1.1.1.1

• 간격 0.2초로 5회 빠르게 테스트

56. curl — URL로 데이터 전송/다운로드 Client URL

형식

curl [옵션] URL

주요 옵션

• -L 리다이렉트 따라가기

• -o 파일로 저장

• -I 헤더만 요청

• -d 데이터 POST

예시

curl https://example.com

• HTML을 표준출력으로 가져오기

curl -L -o page.html http://example.com

• 리다이렉트 따라가 파일 저장

curl -X POST -d 'a=1&b=2' https://httpbin.org/post

• 폼 데이터를 POST

57. wget — 비대화식 네트워크 다운로드 World GET

형식

wget [옵션] URL

주요 옵션

• -O 파일명 지정

• -c 이어받기

• -r 재귀 다운로드

• --no-check-certificate 인증서 무시

예시

wget https://example.com/file.zip

• 현재 디렉터리에 파일 저장

wget -O latest.html https://example.com

• 파일명을 지정해 저장

wget -c big.iso

• 중단된 다운로드를 이어서 받기

58. ssh — 원격 셸 접속 Secure Shell

형식

ssh [옵션] 사용자@호스트 [명령]

주요 옵션

• -p 포트 지정

• -i 개인키 지정

• -L 로컬 포워딩

예시

ssh user@server

• 원격 서버에 셸 접속

ssh -i ~/.ssh/id_rsa user@server

• 특정 키로 인증하여 접속

ssh -L 8080:localhost:80 user@server

• 로컬 8080을 원격 80으로 포워딩

59. scp — SSH 기반 파일 복사 Secure Copy

형식

scp [옵션] 원본 대상

주요 옵션

• -P 포트

• -i 키 파일

• -r 디렉터리 재귀

예시

scp file.txt user@server:/tmp/

• 로컬 파일을 원격 /tmp로 업로드

scp -r site/ user@server:/var/www/

• 디렉터리를 재귀 업로드

scp -P 2222 user@server:/var/log/syslog .

• 특정 포트로 원격 파일 다운로드

60. sudo — 권한 상승하여 명령 실행 Superuser Do

형식

sudo [옵션] 명령

주요 옵션

• -v 자격 갱신

• -k 자격 무효화

• -u 사용자 지정

예시

sudo apt update

• 관리자 권한이 필요한 패키지 인덱스 갱신

sudo -u www-data ls /var/www

• 다른 사용자 권한으로 명령 실행

sudo -k && sudo whoami

• 캐시 무효화 후 다시 인증 요구

일주일 동안 진행된 OJT 기간이 끝나고, 드디어 팀 선택을 통해 최종 팀 배정을 받는 시간이 찾아왔다. 팀 배정 방식은 본인이 원하는 팀과 각 팀장님이 원하는 인원을 서로 조율하여 결정하는 방식이었다. 즉, 내가 지원한 팀에서 나를 필요로 한다면, 높은 확률로 해당 팀에 배정되는 구조다.

다행히 나는 내가 가장 가고 싶었던 팀에 합류할 수 있었다. 내가 합류한 팀은 회사 제품에 새로운 기능을 더하기 위해 LLM을 파인튜닝하고 확장하는 업무를 주로 담당한다. 아직 나는 AI와 관련된 지식이 부족한 편이지만, 이번 기회를 계기로 열심히 학습하여 팀에 도움이 되고 싶다. 내가 원하는 팀에 합류했다는 점이 큰 동기부여가 되었고, 앞으로 최선을 다해 기여하겠다는 다짐을 하게 됐다.

🖥️자리 세팅

팀 배정이 끝난 후, 이제 본격적으로 자리를 세팅하는 시간이 왔다. 우연히도 내가 지난 1~2월 현장실습 때 배정받았던 자리 근처에 다시 자리를 배정받게 됐다. 그런데 한 가지 차이가 있었다. 그때는 Windows 운영체제를 사용했지만, 이번 팀에서는 Ubuntu 환경에서 작업한다고 했다.

그래서 우분투 USB 설치 파일을 준비해 직접 설치를 진행했다. 사실 리눅스를 완전히 처음 써보는 것은 아니었다. WSL(Windows Subsystem for Linux)이나 AWS EC2 환경에서 간단히 다뤄본 경험이 있고, 학교 실습 시간에 가상머신으로 우분투를 구동해본 적도 있었다. 하지만 그 외의 경험은 거의 없어서, 앞으로는 기본적인 명령어와 리눅스 환경에서의 작업 흐름을 좀 더 익혀야겠다고 느꼈다.

이번 시간에는 최종적으로 GitHub Page 구현을 마치려고 한다. 그런데 역시 끈기가 부족해서 구현하는 게 상당히 귀찮게 느껴졌다. 특히 CSS로 렌더링을 구현하는 게 짜증이 났다. 그래서 이번에는 온전히 Cursor AI를 통해 프로젝트를 분석하고 적절한 코드를 생성하려고 한다.

Vibe Coding

올해 가장 핫한 개발 트렌드는 Vibe Coding일 것이다. 학부생 수준의 개발자들은 AI를 적극적으로 활용해 개발하겠지만, 사용하면서 양심의 가책을 느낄 수도 있다(나만 그런가?). 현직 개발자들의 이야기를 들어보면, 이제 AI를 적극 활용해 업무 효율을 극대화하는 것이 매우 중요하다고 한다. 물론 나도 인턴십 경험이 겨우 2개월이라 실질적인 현업 경험은 부족하지만, 이번에 Cursor AI로 Vibe Coding과 유사한 작업물을 만들어 보려고 한다.

Cursor AI

나는 주로 VS Code IDE를 사용한다. Cursor AI는 완전히 VS Code 위에서 작동하는 AI 통합 개발 환경으로, LLM(대규모 언어 모델, Large Language Model)을 탑재했다. VS Code의 Copilot과 달리 전체 프로젝트를 분석해 더 수준 높은 코드를 생성할 수 있다.

Cursor AI는 다음과 같은 모델을 지원한다:

• OpenAI

  • o3-pro (GPT-3.5 Pro)
  • GPT-4.1 (o4)
  • GPT-4 Turbo

• Google

  • Gemini 2.5 Pro

• Anthropic

  • Claude Sonnet 4
  • Claude Opus 4

• xAI

  • Grok 3 Beta

• DeepSeek

  • DeepSeek V3.1

• Cursor 자체 모델

  • cursor-small (경량화 버전)

사용자는 자신이 보유한 API 키로 원하는 모델을 지정할 수 있다. 나는 무료 플랜에서 GPT-3.5 모델을 사용했다. Cursor AI의 강점은 전체 프로젝트 단위에서 자연어 프롬프트만으로 원하는 결과물을 얻을 수 있다는 점이다.

구현 과정

위와 같이 대략적인 프롬프트만 작성해도, 숙련된 사용자가 아니어도 매우 자연스럽고 정확한 코드를 생성해 준다. 나는 이미 구현해 둔 Velog.tsx의 스타일과 컴포넌트를 기준으로 요청하자, 거의 동일한 스타일로 코드를 받아낼 수 있었다.

최종 결과

프로젝트 내 전역 색상, 보더, 컴포넌트 스타일을 유사하게 구현한 결과를 확인할 수 있다. 앞으로는 이런 CSS 디자인 작업을 Cursor AI에 전적으로 맡길 생각이다.

다음 시간에는 GitHub Pages 중간 점검을 해 보고 잠시 쉬어갈 예정이다. 이후에는 GitHub Codespaces 서버와 개인 톡비서 같은 AI 챗봇 시스템을 구현할 계획이다. 그다음 프로젝트로는 AI와 Godot 엔진을 결합한 간단한 게임 개발을 생각 중이며, 틈틈이 AI 공부도 진행해 정리할 예정이다.