초보 개발자의 일기장

에이전트 시대의 AI 시스템 설계

토오오끼 — Sun, 24 May 2026 22:55:59 +0900

"한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬받아 작성된 서평입니다."

https://www.hanbit.co.kr/store/books/look.php?p_code=B4205161590

책의 핵심 메시지

"그럴듯한 프로토타입은 누구나 만든다. 하지만 무너지지 않는 서비스는 '설계'에서 갈린다."

이 책은 LLM API를 붙여 데모를 만드는 시대를 지나, 그 데모를 실제 사용자에게 내보내는 '프로덕션'의 문턱에서 모두가 부딪히는 골짜기-환각, 매번 달라지는 응답, 지식 공백-를 정면으로 다룬다.

저자는 이 문제들을 "프롬프트를 더 잘 쓰면 된다"는 식으로 넘기지 않는다.

대신 시스템 설계의 문제로 격상시킨 뒤, 현업에서 반복적으로 마주치는 32가지 상황을 문제 정의 → 해결 방식 → 코드 예제 → 트레이드오프라는 일관된 형식의 '패턴'으로 정리한다.

이 책이 좋은 이유

1. '패턴'이라는 형식의 힘 — GoF의 AI 버전

오래전 개발자들이 손에 들고 다니던 GoF 디자인 패턴서를 떠올리면 가장 가깝다.

모든 패턴이 동일한 구조로 서술되어, 정답을 외우는 게 아니라 판단의 좌표계를 얻게 된다. 덕분에 설계 회의에서 "지금 우리 RAG는 검색 품질 검증 단계가 비었으니 CRAG 패턴을 넣을지 보자"고 말할 팀 공용 언어가 생긴다.

2. RAG를 '검색 붙이기'에서 '아키텍처'로 끌어올린다

분량으로 보나 깊이로 보나 이 책의 심장은 RAG다.

"임베딩 + 벡터DB"라는 흔한 한 줄 요약을 넘어, CRAG(검색된 문서 품질을 재검증), Self-RAG(모델이 스스로 근거가 충분한지 점검)까지 단계적으로 분화시킨다. 검색 결과 하나만 잘못 들어와도 답변 전체가 무너지던 고질병을 아키텍처로 푸는 방법을 보여준다.

3. "모델은 틀릴 수 있다"를 전제로 설계한다

심판형 LLM(LLM-as-a-Judge)과 성찰(Reflection) 패턴은 AI가 낸 답을 또 다른 AI가 평가하고 스스로 고치게 만든다. 그 밑에 깔린 "AI도 테스트의 대상"이라는 관점이 인상적이다.

기존 소프트웨어의 단위 테스트처럼, 생성형 AI를 검증 가능한 엔지니어링 안으로 끌어들인다.

4. 특정 모델·프레임워크에 종속되지 않는다

GPT든 클로드든 제미나이든, 랭체인이든 무엇이든 가리지 않는다.

무게중심을 구현이 아니라 설계 사고에 두었기 때문에, 코드 예제는 낡아도 패턴은 살아남는다. 변화 속도가 빠른 AI 환경에서 비교적 오래 참고할 수 있다는 게 가장 영리한 선택이다.

5. 가장 가려운 곳 — 신뢰성·안전·비용까지 챙긴다

후반부에서는 프롬프트 인젝션 방어, 행동 제한, 자체점검을 다루며 "에이전트가 외부 도구를 쓰는 순간 보안은 곧 설계 문제가 된다"는 걸 체감시킨다.

소규모 언어 모델(SLM), 프롬프트 캐싱, 인퍼런스 최적화로 비용과 지연시간이라는 현실적 제약까지 놓치지 않는다.

이런 사람에게 추천

LLM API는 이미 붙여봤고, 이제 진짜 서비스 구조를 고민하기 시작한 개발자
RAG를 단순 검색이 아니라 운영 수준의 아키텍처로 이해하고 싶은 엔지니어
환각·비결정적 응답이 무서워 배포 직전에 멈춰 서본 적 있는 사람
모델과 도구가 바뀌어도 오래 통하는 설계 원칙을 손에 쥐고 싶은 사람
AI 도입의 방향을 판단해야 하는 아키텍트·기술 리더·PM·CTO
AI 에이전트 트렌드를 흥분이 아니라 견고한 시스템 설계 역량으로 바꾸고 싶은 사람

이런 사람에게는 조금 어려움

LLM을 한 번도 다뤄본 적 없는 완전 입문자 (1장 '서론'부터 Temperature·LoRA·RLHF가 빠르게 지나간다. 사실상 압축된 AI 개론이라 초반 진입 장벽이 높다)
코딩 없이 'AI 활용법'만 알고 싶은 라이트 유저 (이 책은 활용서가 아니라 명백히 개발, 설계자를 위한 설계서다)
책의 코드를 그대로 베껴 바로 돌아가길 기대하는 사람 (MCP, 에이전트 프레임워크는 변화가 빨라 예제는 금세 낡는다. 깃허브 저장소 병행이 사실상 필수다)
"버튼만 누르면 끝"인 A-Z 완성형 튜토리얼을 기대하는 사람 (어디까지나 방향성과 인사이트가 핵심인 책이다)

✍ 총평

이 책의은 AI를 써보는 단계에서 AI로 시스템을 설계하는 단계로 데려다 준다.

시중의 AI 책 상당수가 "이런 게 가능해요!"에서 멈추는 반면, 이 책은 출력 형식 제어부터 RAG 고도화, 신뢰성 검증, 다중 에이전트 협업, 비용 최적화, 가드레일까지 프로덕션을 떠받치는 전 과정을 촘촘히 안내한다.

특히 인상 깊었던 건 두 가지다.

첫째, 관점의 전환.

"모델은 틀릴 수 있다"를 전제로 시스템을 설계한다는 한 문장이, 배포를 망설이던 마음의 매듭을 풀어줬다.

둘째, 레퍼런스로서의 가치.

쉽게 읽히는 책은 아니다. 하지만 생성형 AI 정보가 사방에 흩어진 지금, 책상 옆에 꽂아두고 설계 회의 전에 꺼내 보게 될 그런 책이다.

앞으로의 경쟁력은 "얼마나 큰 모델을 쓰느냐"가 아니라 "그 모델을 얼마나 신뢰할 수 있는 시스템으로 엮어내느냐"에서 갈린다. AI 도구에 어느 정도 익숙해진 분이라면, 이 책으로 분명히 한 단계 더 나아갈 수 있다.

Tailscale | tailescale 사용법, tailscale 사용하여 ssh 접속, tailscale 사용 원격 접속

토오오끼 — Mon, 18 May 2026 09:52:55 +0900

tailscale이란?

WireGuard 프로토콜을 기반으로 한 메시(mesh) VPN 서비스이다.

전통적인 VPN과 가장 다른 점은 "중앙 서버를 거치지 않고" 디바이스끼리 직접 암호화된 연결을 맺는다는 것이다.

일반 VPN(예: 회사 VPN)은 모든 트래픽이 게이트웨이 서버 한 곳을 통과하다보니 그래서 속도 병목이 생기고, 서버가 다운되면 다 끊기는 문제가 있다.

Tailscale은 대신 각 디바이스에 가상의 사설 IP(예: 100.x.x.x 대역)를 부여하고, 디바이스들끼리 직접 peer-to-peer로 연결한다. 마치 모든 기기가 같은 LAN 안에 있는 것처럼 동작하게 된다.

중앙 서버는 "Coordination Server"라는 게 있긴 하지만 이 서버는 트래픽을 중계하는 게 아니라, 누가 누구랑 연결할 수 있는지에 대한 키 교환과 라우팅 정보만 관리한다.

주요 사용 사례:

집에 있는 NAS나 홈서버에 외부에서 안전하게 접속
여러 클라우드 서버를 한 네트워크처럼 묶기
소규모 팀의 사내망 대용 (포트포워딩, 방화벽 설정 없이)
출장 중 회사 리소스 접근

또, 설정이 굉장히 쉽다는 장점이 있다.

각 디바이스에 클라이언트 설치하고 Google/Microsoft/GitHub 계정으로 로그인하면 끝이다. 포트 열 필요도, 공인 IP 받을 필요도 없다.

개인 사용은 보통 무료 플랜으로 충분하고(디바이스 100대까지), 팀/기업용 유료 플랜이 따로 있다.

1. tailscale 설치 / 기존 로그인 해제

나의 경우엔 맥북에서 우분투 pc에 ssh로 연결, 접속을 하고자 한 상황이다.

우분투 tailescale 설치

curl -fsSL https://tailscale.com/install.sh | sh

만약 기존에 tailscale이 설치 되어 있다면 기존 로그인을 해제해야 한다.

기존 우분투 pc에 이미 tailscale이 설치 되어 있어서 로그아웃 부터 해 주었다.

sudo tailscale logout

로그아웃 되었는지 확인

tailscale status

→ Logged out 같은 메세지가 뜨면 정상

→ tailscale logout은 이 우분투의 연결만 끊는다.

이전 계정 자체나 그 계정에 등록된 다른 기기들엔 영향 없지만 그 계정 소유자가 자기 관리 페이지에서 우분투를 완전히 제거하지 않으면 "비활성 기기"로 남아있을 수 있다.

2. tailscale 계정 만들기

https://tailscale.com

Tailscale | Secure Connectivity for AI, IoT & Multi-Cloud

The connectivity platform for devs, IT, and security teams. Zero Trust identity-based access that deploys in minutes and scales to every resource. Start free.

tailscale.com

위 링크에 접속하면 우측 상단에서 “Get started” 또는 “sign up” 클릭 → 가입하고 나면 빈 admin 페이지가 보일 것이다.

아직 연결 된 기기가 없기 때문에 빈 박스로 보인다.

3. 우분투에서 본인 계정으로 tailscale 로그인

우분투 터미널에서

sudo tailscale up

하면

To authenticate, visit:
    https://login.tailscale.com/a/xxxxxxxxxxxx

이렇게 메세지가 뜰 것이다.

이 URL을 연결하고자 하는 pc 브라우저에서 열면 된다. 이때 위에서 만든 본인 계정으로 로그인된 상태여야 한다.

그러면 URL dufaus “Connes [device name] to your tailnet?” 같은 페이지가 뜨고 이 때 “Connect” 클릭 후 성공하면 우분투 터미널에서 자동으로 프롬프트가 돌아오게 된다.

tailscale status

→ 이후 본인 기기가 제대로 연결되었는지 확인하고

tailscale ip -4

→ 우분투 pc에서 할당된 IP를 확인할 수 있다.

4. 연결하고자 하는 pc에 tailscale 설치

맥북 기준 터미널에서 설치 가능하다.

brew install --cask tailscale

없으면 https://tailscale.com/download/mac 에서 다운로드 하면 된다.

5. pc에서 같은 계정으로 tailscale 로그인

설치 후 메뉴바 Tailscale 아이콘 클릭 → "Log in..." → 2단계에서 만든 본인 계정으로 로그인하면된다.

이때 vpn 허용을 해 줘야만 기기가 등록이 된다.

→ 우분투 pc와 맥북 모두 등록 된 걸 확인할 수 있다.

6. 맥북 터미널에서 우분투 ssh 접속

ssh username@IP

→ 우분투의 username과 tailscale ip -4 로 확인한 ip를 입력 해 주면 ssh로 우분투 터미널에 접속이 된다.

이렇게 설정 해 두면 두 기기가 어느 네트워크에 있든 상관없이 서로 연결된다!!

7. vscode ssh 연결

vscode에서 ctrl+shift+p를 눌러서 Remote - SSH: Editing Configuration Files 해당 파일에 내용을 추가 해 주면 vscode에서 해당 우분투를 연결해서 사용할 수 있다.

Host ubuntu-pc
    HostName IP
    User username

이렇게 입력 해 주면 vscoded에서도 ssh로 연결해서 작업이 가능하다.

Aircloud | Aircloud란? Aircloud 컨테이너 생성, Aircloud SSH 접속, Aircloud VScode remote 연결

토오오끼 — Mon, 11 May 2026 16:54:52 +0900

대학원에 다니면서 졸업 논문을 준비하는 입장에서 가장 큰 벽 중 하나가 GPU다. 모델 하나 학습 돌리려면 최소 RTX 3090 정도는 필요한데, 개인 장비가 없으면 실험 자체가 막힌다. 학교 공용 서버는 대기열이 길고, AWS 같은 메이저 클라우드는 가격이 무섭다. 그렇다고 Colab 무료 티어로 졸업 논문 실험을 돌리기엔 세션 끊기는 문제부터 메모리 한계까지 어느 것 하나 만만치 않다.

그래서 한동안은 학습 데이터를 줄이거나 모델을 작게 잡는 식으로 우회했다. 하지만 졸업 논문 실험은 결국 정공법이 필요했고, 그 과정에서 알게 된 게 AirCloud(AIEEV의 분산형 GPU 클라우드)다. 직접 써보니 같은 처지의 대학원생들에게 공유할 만한 가치가 있다 싶어 후기를 남긴다.

https://www.aieev.com/

AIEEV Air Cloud Demo | AIEEV inc – Distributed GPU Solutions

Discover AIEEV inc's aieev air cloud demo, offering cutting-edge distributed GPU solutions for AI scaling and deployment.

www.aieev.com

aircloud란 전 세계의 유휴 GPU를 연결해 에너지 효율성과 확장성 문제를 해결하는 분산형 AI 클라우드 서비스이다.

aircloud는 분산된 크라우드소싱 GPU 인프라를 통해 최저 가격을 제공하고, aircloud+는 AIEEV가 직접 운영하는 자체 GPU 장비로 가동시간·성능·가용성을 보장한다.

주요 제품 라인은 Air Container(AWS·GitHub·Docker Hub·Google 등 공개/비공개 저장소에서 컨테이너 배포), Air Model(2025년 3분기 예정, 서버리스·초당 과금 기반 AI 추론), Air API(Whisper·LLaMA 3.3 8B·Solar Mini 같은 오픈소스 모델용 OpenAI 호환 REST API)으로 구성된다.

1. workspace 생성

aircloud에서 회원가입을 한 후 콘솔 창으로 접속하면 워크스페이스를 생성할 수 있다.

2. 컨테이너 생성

기존 템플릿을 선택하여 컨테이너를 만들게 되면 따로 docker 이미지 만들 필요 없고, 레지스트리 계정 만들 필요도 없으며 토큰 발급받을 필요도 없다.

도커 허브에 공개 되어 있는 이미지를 사용하여 컨테이너를 만들고 싶다면 템플릿을 별도로 선택하지 않고 다음을 클릭 해 이미지 정보를 입력하면 된다.

예를 들어, pytorch/pytorch:2.3.1-cuda12.1-cudnn8-devel ← 이 도커 이미지를 사용한다면

컨테이너 이미지 URL에 “pytorch/pytorch:2.3.1-cuda12.1-cudnn8-devel “ 이걸 입력하면 공급자가 자동으로 docker_hub로 설정이 된다.

이렇게 직접 도커 이미지를 입력하고 띄울 수도 있다.

컨테이너 정보 입력을 다 했다면 리소스를 선택해야 한다.

필요한 자원으로 선택 해 준 후에

볼륨까지 선택 해 주면 된다.

영구 볼륨은 한마디로 "컨테이너가 꺼지거나 재시작돼도 사라지지 않는 저장공간"이다.

컨테이너 안 다른 경로에 저장한 파일은 종료하면 다 날아가지만, 마운트된 경로(ex. /workspace)에 저장한 건 보존된다.

/workspace 경로 = 영구 디스크 영역 컨테이너 내부에서 보면 그냥 폴더 하나지만, 실제로는 30GB짜리 별도 저장소가 그 경로에 연결돼 있는 구조
컨테이너 라이프사이클과 분리됨
- 엔드포인트 중지/재시작 → /workspace 내용 그대로 유지 ✅
- 컨테이너 이미지 업데이트 → /workspace 내용 그대로 유지 ✅
- 볼륨 자체 삭제 → 그때 비로소 데이터 손실 ❌
컨테이너 내 다른 경로 (/, /tmp, /root 등) → 종료 시 휘발됨. 영구 볼륨 밖이라는 점이 핵심.

볼륨 소스 두 옵션의 차이

새 볼륨 만들기

: 이 엔드포인트 전용 새 30GB 볼륨을 생성한다. 다른 컨테이너에서는 접근 불가로 처음 사용한다면 이걸 선택하면 된다.

기존 볼륨 연결

: 이미 만들어둔 볼륨을 다른 엔드포인트에서 마운트하는 방식이다.

→ 사용 시나리오:

한 컨테이너에서 학습한 모델을 → 다른 추론 전용 컨테이너에 연결
무거운 데이터셋을 여러 실험 환경이 공유
학습용/추론용 컨테이너를 분리하되 같은 데이터 사용

자원 설정까지 마쳤다면 시작 명령, 포트 등의 옵션을 설정 해 주고 실행을 해 주면 된다.

이렇게 생성된 컨테이너에서 API 키 관리를 클릭해서 새 시크릿 키를 생성해야 한다.

시크릿 키 이름과 액세스 할 엔드포인트를 선택 해주면 된다.

api key를 생성했다면 이후는 aircloud CLI를 설치해서 사용해야 한다.

3. aircloud CLI 설치

맥북 기준 aircloud CLI 설치 방법은 아래와 같다.

brew install pipx
pipx install aircloud-cli

aircloud —help 명령어로 제대로 설치 되었는지 확인까지 해 주면 된다.

aircloud config set api-base-url https://external.aieev.cloud:5007
aircloud config set api-key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
aircloud config list

위 명령어들을 통해 위에서 생성했던 api key를 등록 해 줘야 한다.

sk-xxxx ← 이 부분에 아까 발급했던 시크릿 키를 입력 해 주면 된다.

aircloud whoami

위 명령어들을 통해 api가 제대로 등록된 것을 확인할 수 있다.

4. SSH 연결

생성한 컨테이너에 ssh를 연결하기 위해서는 먼저 호스트 pc에서 ssh 키를 발급 받아야 한다.

# 키 쌍 생성
ssh-keygen -t ed25519 -C "your-email@example.com"

# 공개키 출력해서 복사
cat ~/.ssh/id_ed25519.pub

이렇게 생성한 공개키를 aircloud 왼쪽 메뉴바의 SSH 키 메뉴에서 “SSH 키”를 선택하고 추가 해 주면 된다.

생성한 SSH 키를 붙여 넣고 해당 ssh키를 주입할 엔드포인트를 선택해서 추가 해 주면 된다.

이후 생성했던 컨테이너를 시작한 후

aircloud ssh <endpoint_id>

위 명령어로 ssh 접속을 하면 된다.

5. vscode ssh 연결

ssh 접속을 위해 터미널에서 터널을 먼저 열어 줘야 한다.

aircloud ssh <endpoint_id> --tunnel-only

이 명령을 실행하면 로컬 어느 포트(예: localhost:2222)에 SSH 터널이 열렸다는 메시지가 출력될텐데 이 터미널 창은 닫지 말고 그대로 둬야 한다. 닫으면 터널이 끊김…

이후 ssh config에 호스트 정보를 추가 해 준다.

vscode에서 ctl+shift+p 눌러서 ssh config 파일 수정을 선택 한 후

Host aircloud-jupyter
    HostName localhost
    Port 2222
    User root
    IdentityFile ~/.ssh/id_ed25519
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

StrictHostKeyChecking no와 UserKnownHostsFile /dev/null은 컨테이너 재시작 시 호스트 키가 바뀌어도 매번 경고 안 뜨게 하는 옵션

위와 같이 내용을 추가 해 주면 vscode remote에서 airclouod 컨테이너로 연결이 가능하다.

누구에게 추천하는가

GPU 없이 졸업·학위 논문 실험을 해야 하는 대학원생
AWS는 부담스럽고 Colab 무료 티어로는 부족한 사람
LLM 파인튜닝, Diffusion 모델 실험, 강화학습 등 GPU가 본격적으로 필요한 사이드 프로젝트 진행자
학교 공용 GPU 서버 대기열에 지친 연구자

특히 대학원생이라면 학생/연구생 프로모션을 꼭 확인해볼 것을 권한다. 가격 차이만으로도 실험 횟수가 두세 배는 늘어난다. 실험을 더 많이 돌릴 수 있다는 건 곧 졸업 논문의 완성도가 올라간다는 뜻이다.

처음엔 "분산형 GPU 클라우드"라는 컨셉이 낯설었지만, 막상 써보니 본질은 같다.

빠르게 GPU에 붙어서 실험하고, 결과 보고, 다음 실험을 돌리는 사이클. 그 사이클을 AWS보다 훨씬 가벼운 비용으로, IDE까지 풀로 활용하면서 돌릴 수 있다는 게 학생 입장에서는 정말 고마운 선택지다.

Benchmark | MSR-VTT Dataset이란?

토오오끼 — Sun, 3 May 2026 23:50:47 +0900

비디오와 언어를 다루는 논문을 한 편이라도 읽어본 사람이라면 거의 무조건 마주치는 이름이 있다. MSR-VTT.

CLIP4Clip이든, X-CLIP이든, 최근의 InternVideo든, 성능 비교표 어딘가에는 항상 MSR-VTT의 R@1, R@5, R@10 숫자가 박혀 있다.

이 데이터셋은 처음부터 검색(retrieval)용으로 만들어진 게 아니라 영상을 보고 자연어로 설명을 만들어내는 task인 비디오 캡셔닝(video captioning) 데이터셋이었다.

MSR-VTT란?

MSR-VTT(Microsoft Research Video to Text)는 2016년 CVPR에서 Microsoft Research가 공개한 비디오-언어 데이터셋이다. 이름 그대로 "비디오와 텍스트를 잇는 다리"를 만들기 위해 설계됐다.

기본 스펙은 다음과 같다.

10,000개의 웹 비디오 클립, 총 41.2시간 분량
200,000개의 clip-sentence pair (클립당 평균 20개의 캡션)
20개 카테고리 (음악, 스포츠, 게임, 뉴스, 요리, TV쇼 등)
클립 길이는 10~32초, 짧고 명확한 단일 장면 위주
1,327명의 Amazon Mechanical Turk 워커가 캡션 작성
영상뿐 아니라 오디오까지 포함 (당시로서는 드물었음)

숫자만 보면 평범한 데이터셋 같지만, 진짜 흥미로운 건 만들어진 방식이다.

MSR-VTT 제작팀은 무작위로 비디오를 모은 게 아니라, 상용 비디오 검색엔진의 인기 쿼리 257개에서 출발했다. 각 쿼리당 118개의 비디오를 모아 총 30,404개의 후보를 만들고, 중복과 저품질 영상을 거른 뒤 최종적으로 10,000개를 큐레이션했다.

이 과정이 왜 중요한가? 데이터 분포 자체가 실제 사용자의 검색 패턴과 닮아있게 된다는 뜻이기 때문이다.

사람들이 실제로 비디오를 찾을 때 어떤 단어를 쓰는지, 어떤 카테고리에 트래픽이 몰리는지가 데이터셋에 자연스럽게 반영됐다. 결과적으로 captioning 용으로 만들어진 데이터셋이 retrieval에 더 잘 맞는 묘한 상황이 만들어졌다.

여기에 추가적인 설계 결정들이 retrieval에 잘 들어맞았다.

20개 카테고리로 구조화 → 카테고리별 성능 분석이 가능
클립당 20개의 다양한 캡션 → 같은 영상에 대한 여러 표현을 학습/평가 가능
10~32초의 짧은 클립 → 단일 장면에 가까워서 "비디오 단위 매칭"이 의미 있음

만약 클립이 30분짜리 방송이었다면 "이 영상이 쿼리와 매칭된다"는 말 자체가 모호해졌을 것이다. 어디 부분이 매칭됐다는 건지 알 수 없으니까.

데이터셋이 좋다고 다 표준이 되는 건 아니다.

MSR-VTT가 retrieval 분야에서 못박힌 표준이 된 데에는 몇 가지 결정적 사건이 있었다.

1. 등장 시점

2016년은 비디오-언어 분야에서 딥러닝이 본격화되던 시점이었다. 이전 데이터셋들은 모두 한계가 명확했다.

MSVD(2011)는 2K 비디오로 너무 작았고, YouCook이나 TACoS는 요리 영상에만 한정됐으며, LSMDC는 영화에만 묶여 있었다. 그 와중에 "10K개·다양한 도메인·풍부한 캡션"이라는 조합으로 등장한 첫 데이터셋이 MSR-VTT였다.

2. JSFusion의 1k-A split

2018년 JSFusion 논문(Yu et al., ECCV)이 MSR-VTT에 multiple-choice와 retrieval annotation을 추가하면서 1k-A split(train 9K / test 1K)을 정의했다.

벤치마크가 표준이 되려면 split이 통일되어야 하는데 그전에는 논문마다 split이 달라서 숫자를 직접 비교할 수 없었다. JSFusion이 깔끔한 1K test set을 제공하자 후속 논문들이 일제히 이 split을 채택했고, 한 번 critical mass가 형성되니 R@1/R@5/R@10이라는 단순한 지표 + 1K라는 적당한 평가 비용 덕분에 빠르게 굳어졌다.

3. 평가 비용

10K 비디오는 feature 추출이 며칠 안에 가능하고, 1K test set으로 dual-encoder retrieval 평가를 돌리면 수 분 안에 끝난다. 반면 HowTo100M(136M clips)이나 WebVid-10M은 평가셋으로 쓰기엔 너무 크다.

학계 입장에서 "GPU 몇 장으로 일주일 안에 ablation 한 사이클을 돌릴 수 있는 사이즈"라는 건 채택률에 결정적이다.

4. 네트워크 효과

영향력 있는 후속 논문들이 모두 MSR-VTT 숫자를 보고하기 시작했다.

HowTo100M(2019), ClipBERT(2021), Frozen-in-Time(2021), 그리고 결정적으로 CLIP4Clip(2021) 이후 "CLIP을 비디오에 옮기면 얼마나 잘 되나"를 검증하는 표준 시험장이 되면서 한 번 더 못이 박혔다.

이후 비교 대상 SOTA 모델들이 전부 MSR-VTT 숫자만 보고했기 때문에 새 논문 입장에서는 선택의 여지가 없었다.

Captioning과 Retrieval

같은 데이터셋이 두 task에 모두 쓰인다는 것은 입력과 출력이 정반대라는 것이다.

Video Captioning은 영상 → 텍스트를 생성하는 task다.

입력: video_001
출력: "A man is playing guitar on stage"

모델은 비디오를 인코딩한 뒤 디코더가 한 단어씩 만들어낸다. Encoder-Decoder 구조이고, S2VT나 GIT, BLIP-2 같은 모델이 여기에 속한다.

Text-to-Video Retrieval은 텍스트 → 영상을 검색하는 task다.

입력: "guitar on stage" + 비디오 후보 1,000개
출력: 후보 풀에서의 매칭 순위 (top-K)

모델은 텍스트와 비디오를 각각 임베딩 공간으로 보낸 뒤 유사도만 계산한다.

Dual Encoder 구조가 일반적이고, CLIP4Clip이나 X-CLIP이 대표적이다.

같은 (video, caption) pair를 어떻게 쓰느냐만 다르다.

Captioning: video를 입력으로, caption을 생성 target으로 사용
Retrieval: (video, caption)을 positive pair로, 다른 조합을 negative로 두고 contrastive learning

평가 지표도 완전히 다르다

Captioning은 생성된 문장이 정답 문장과 얼마나 비슷한지를 측정한다. BLEU, METEOR, ROUGE-L, CIDEr 같은 텍스트 유사도 지표를 쓴다.

Retrieval은 정답 비디오를 몇 위로 올렸는지를 본다. R@1, R@5, R@10 (Recall at K), MdR (Median Rank) 같은 순위 지표를 쓴다.

Captioning = 시험의 서술형 답안: 빈 종이에 답을 써야 한다
Retrieval = 시험의 객관식 문제: 1,000개 보기 중 정답을 고른다

서술형은 답안의 품질을 평가하기가 본질적으로 어렵고, 객관식은 보기 수가 늘어날수록 어려워진다.

그래서 BLEU 같은 지표는 "이 답이 정말 맞는 답인가"를 잘 못 잡는 반면, retrieval은 채점은 명확하지만 후보가 많아질수록 빠르게 어려워진다.

MSR-VTT가 captioning용으로 만들어졌음에도 retrieval에서 더 활발하게 쓰이고 있다.

이유를 정리하면 이렇다.

평가의 객관성: BLEU의 한계 vs Recall@K의 명확함
확장성: dual encoder는 한 번 임베딩하면 수백만 후보 검색이 빠름
시기의 일치: CLIP의 등장이 contrastive learning + dual encoder 패러다임을 폭발시킴
실용성: 검색 시스템이 캡션 생성보다 산업적 수요가 더 큼

10년 가까이 표준 자리를 지켜왔지만, MSR-VTT에 대한 비판도 점점 늘고 있다.

False negative 문제

MSR-VTT는 한 캡션당 정답 비디오가 1개라고 가정한다. 그런데 실제로는 한 캡션이 여러 비디오에 매칭되는 경우가 흔하다. "A man is playing guitar"라는 캡션은 데이터셋 안의 수십 개 비디오와 다 맞는다. 모델이 그런 비디오들을 위로 올리면 점수에서 손해를 본다. 최근 연구에 따르면 이 false negative를 보정하면 SOTA 모델 점수가 무려 25 recall point까지 올라간다. 즉 우리가 보고 있는 숫자가 진짜 모델 성능보다 한참 낮다는 뜻이다.

벤치마크 포화

R@10 기준으로는 거의 saturation 상태다. 새 모델을 만들어도 차이가 1~2 포인트 안에서 다투는 수준이다.

캡션이 짧고 단순함

평균적으로 한 문장짜리 일반 묘사라, 실제 사용자 쿼리(긴 질문, 멀티턴, 도메인 특화)와 거리가 있다.

Whole-video matching

이게 가장 본질적인 한계이다. MSR-VTT는 영상 단위 매칭이라 "영상 내 특정 장면" 매핑은 다루지 않는다. 이건 DiDeMo, Charades-STA, TVR 같은 moment retrieval 데이터셋의 영역이다.

여전히 표준이긴 하지만 후계자들이 등장하고 있다.

MomentSeeker, RVMS-Bench 같은 새 벤치마크가 long-video moment retrieval, 멀티모달 쿼리 같은 더 현실적인 시나리오를 다루고 있다.

다만 표준 교체는 보통 5~10년이 걸리고, MSR-VTT를 직접적으로 대체할 명확한 후계자는 아직 없는 상태다. 당분간은 MSR-VTT 1k-A로 baseline 비교 + 자체 도메인 셋으로 실제 성능 검증이라는 이중 평가 구조가 학계와 산업계의 표준 관행으로 남을 것 같다.

MSR-VTT 이야기는 결국 "어떻게 어떤 데이터셋이 분야의 표준이 되는가"에 대한 사례 연구다. 절묘한 타이밍, 검색 친화적인 설계 결정, 합리적인 평가 비용, 그리고 split을 통일한 후속 논문 — 이런 요소들이 맞물려야 하나의 데이터셋이 못박힌 표준이 된다.

참고

원 논문: Xu, Mei, Yao, Rui, "MSR-VTT: A Large Video Description Dataset for Bridging Video and Language", CVPR 2016
1k-A split: Yu et al., "A Joint Sequence Fusion Model for Video Question Answering and Retrieval (JSFusion)", ECCV 2018
False negative 분석: "Fighting FIRe with FIRE: Assessing the Validity of Text-to-Video Retrieval Benchmarks", 2022

오픈클로 with GPT, 제미나이, 클로드

토오오끼 — Sun, 26 Apr 2026 19:35:46 +0900

"한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬받아 작성된 서평입니다."

https://www.hanbit.co.kr/store/books/look.php?p_code=B6319455015

책의 핵심 메시지

"AI는 더 이상 '대화 상대'가 아니라, 내 컴퓨터에 상주하며 직접 일하는 '동료'다."

이 책은 챗봇과 대화하던 시기를 지나, AI 에이전트가 직접 파일을 만들고 웹을 검색하고 이메일을 보내는 시대로 넘어가는 흐름의 한가운데서, 오픈소스 프로젝트 오픈클로(OpenClaw) 를 활용해 누구나 자기만의 'AI 집사'를 만들 수 있다는 메시지를 전한다.

저자는 단순히 "AI에게 질문하는 법"을 가르치지 않는다. 대신 에이전트에게 이름을 짓고, 성격을 부여하고, 일을 맡기고, 자동화를 거는 과정을 마치 새 팀원을 온보딩하듯이 단계별로 안내한다. 책을 덮을 때쯤이면 매일 아침 브리핑을 건네는 AI 집사 한 명이 내 컴퓨터 안에서 일하고 있게 된다.

이 책이 좋은 이유

1. 정리가 잘 되어 있고, 따라 하기 쉽다

설치 → 보안·비용 설정 → 첫 업무 지시 → 자동화 예약 → 외부 서비스 연동 → 멀티 에이전트 구성까지, 한 단계가 끝나면 자연스럽게 다음 단계로 넘어가는 흐름이 매끄럽다. "여기서 막히겠는데?" 싶은 지점마다 어김없이 친절한 안내가 따라붙는다.

2. 사례가 정말 다양하다

책의 가장 큰 매력은 풍부한 실전 사례다. 회의가 끝나면 노션에 자동 정리, 구글 문서로 보고서 초안 작성·공유, 지메일·슬랙·캘린더 연동, 심지어 스포티파이로 음악을 켜는 것까지. 다른 사람들은 이 도구를 어떻게 쓰고 있는지 한눈에 파악할 수 있어서, 단순한 따라 하기 학습서를 넘어 "내 업무엔 이렇게 응용할 수 있겠다"는 영감을 준다.

3. 모델 선택의 자유를 끝까지 챙긴다

GPT, 제미나이, 클로드를 상황에 맞게 골라 쓰는 법까지 다룬다. 특정 회사에 종속되지 않는 '오픈'의 장점을 책 전체에서 일관되게 강조한다.

4. 가장 가려운 곳을 긁어준다 — 비용과 보안

오픈클로를 직접 써본 사람들이 공통적으로 호소하는 두 가지 고민, 토큰 종량제 비용과 보안 이슈를 챕터 차원에서 다룬다. 깃허브 코파일럿 연동으로 비용을 아끼는 전략, 스킬 보안 등 실무적인 부분을 놓치지 않은 점이 인상적이다.

5. 진입 장벽을 낮추려는 배려

터미널을 한 번도 열어본 적 없는 사람을 위해 브라우저에서 바로 시작하는 방법까지 소개한다. "비개발자도 쓸 수 있다"는 말이 빈말이 아니다.

이런 사람에게 추천

매일 반복되는 뉴스 수집, 이메일 정리, 보고서 초안 작성을 누군가에게 떠넘기고 싶은 직장인
챗GPT, 제미나이, 클로드를 따로따로 써봤지만 "하나로 묶어 더 똑똑하게" 쓰고 싶은 사람
회사 데이터를 외부 서버로 보내기 찜찜해서 로컬에서 돌아가는 AI 비서를 원하는 사람
"AI에게 질문하는 단계"를 넘어 "AI에게 일을 시키는 단계" 로 넘어가고 싶은 사람
노션·슬랙·구글 캘린더·지메일을 자동화 한 줄로 묶어버리고 싶은 사람
AI 에이전트 트렌드를 단순한 흥분이 아니라 내 워크플로에 실제로 들여놓고 싶은 사람

이런 사람에게는 조금 어려움

명령어 한 번 쳐본 적 없고, 새로운 도구 설치 자체가 큰 부담인 사람
- (책에서도 "이 책에서 가장 어려운 건 설치"라고 솔직하게 인정한다)
API 토큰 종량제 비용에 거부감이 큰 사람
- (월 구독료가 아니라 쓴 만큼 청구되는 방식이라, 설정을 잘못하면 비용이 슬금슬금 새기 쉽다)
"버튼만 누르면 다 해주는" 완성형 서비스를 기대하는 사람
- (오픈클로는 신입사원처럼, 처음엔 못하다가 알려주면서 같이 똑똑해지는 도구다)
단순 챗봇 사용으로 충분하고 자동화, 연동까지는 필요 없는 라이트 유저

✍ 총평

이 책의 미덕은 "실제로 작동하는 AI 비서를 내 컴퓨터에 들여놓는 데까지 데려다 준다" 는 점이다.

시중의 AI 책 상당수가 "이런 게 가능해요!"에서 끝나는 반면, 이 책은 설치 한 줄에서부터 멀티 에이전트 운영까지 에이전트의 탄생부터 독립까지의 전 과정을 빠짐없이 안내한다.

특히 인상 깊었던 건 두 가지다.

첫째, 정리의 밀도. 흐름이 깔끔해서 어디에 와 있는지를 잃지 않는다.

둘째, 사례의 다양성. "다른 사람들은 이걸 이렇게 쓰는구나" 하는 발견이 책장을 넘기는 동력이 된다.

AI에게 단순히 질문하는 시대를 지나, AI를 내 컴퓨터에 상주시키고 일을 맡기는 시대로 넘어가는 지금, 이 책은 그 전환의 입구에서 가장 든든한 가이드 역할을 해준다. AI 도구에 어느 정도 익숙해진 분이라면, 이 책으로 한 단계 더 나아갈 수 있다.

Runpod | runpod ssh로 vscode에 연결, runpod 터미널에서 claude 인증

토오오끼 — Sun, 12 Apr 2026 19:22:36 +0900

https://console.runpod.io/

console.runpod.io

runpod란 비싼 gpu를 직접 구매하지 않고 필요할 때만 빌려 쓸 수 있는 서비스로 클라우드 gpu 렌탈 플랫폼이다.

저렴한 gpu 비용과 다양한 선택지가 있다는 장점이 있다.

이 플랫폼의 또 다른 장점으로는 생성한 파드를 ssh를 통해서 접속하고 vscode에 연결해서 사용할 수 도 있다.

runpod vscode ssh 연결하기

먼저 위 페이지에서 회원가입, 선불 크레딧 결제를 한 후 ssh 연결을 위해 public key를 등록 해 줘야 한다.

우선 ssh로 접속을 하려는 pc의 터미널에서 ssh key를 발급을 받아야 한다.

ssh-keygen

해당 명령어를 사용해 ssh key를 발급 받으면 된다. 키 파일 생성할 경로와 비밀번호를 물어보는데 그냥 엔터를 입력하면 ssh key가 생성됐다는 화면이 뜰 것이다.

runpod에서 Settings-SSH public keys를 클릭해서 발급 받은 key를 붙여넣고 Update public key를 클릭 해 주면 된다.

이후 pod를 클릭해 사용하고자 하는 클라우드의 스펙을 선택한다.

여기서 ssh terminal access를 체크 해 준 후에 Deploy On-Demand를 해 주면 파드가 생성이 된다.

생성된 후에 파드 정보를 통해서 접속할 ssh 주소와 포트 번호를 알 수 있다.

ssh로 접속을 하려는 pc의 터미널에서 위 ssh 주소를 사용해서 접속을 해서 known_host 파일이 생성 되도록 해 줘야 vscode에서 접속해도 오류가 발생하지 않는다.

ssh root@IP -p port -i ~/.ssh/id_ed25519

터미널에서 제대로 접속이 된다면 vscode에서 ssh 접속을 위해 config 파일을 생성 해야 한다.

그 전에 vscode에서 extension에서 Remote-SSH를 설치 해 주고

ctrl+shitf+p를 눌러서 ssh configuration file을 열어준다.

위 사진처럼 HostName과 User, Port까지 입력 해주고 IdentityFile을 입력 해 주고 저장하면 왼쪽에 생성된 remote로 접속이 가능 해 진다.

runpod 연결 vscode에서 claude extension 인증하기

vscode extension에서 claude를 설치 해 준 후 위 화면에서 Claude.ai Subscription을 선택 해 준다.

그때 외부 브라우저로 연결되는 걸 허용하면 보통은 바로 인증이 되지만 runpod는 vm이기 때문에 인증이 바로 되지 않는다. 때문에 연결된 외부 브라우저는 끄고.

이렇게 제공되는 링크를 직접 외부 브라우저에 붙여 넣어주면 추가로 인증이 가능한 홈페이지로 연결 된다.

연결된 사이트에서 익스텐션 화면에 붙여 넣을 코드가 생성된다.

이 키를 익스텐션 화면에서 붙여 넣어주면 로그인 및 인증이 완료 된다.

Render | render custom domain, render에서 custom domain으로 배포하기

토오오끼 — Sun, 5 Apr 2026 23:05:10 +0900

https://iambeginnerdeveloper.tistory.com/354

Render | render로 fastapi 배포하기, render fastapi deploy

사이드 프로젝트로 기능 개발을 하면서 localhost:8000로 화면을 확인하고 동작을 확인해 왔지만 기능 개발이 어느정도 된 것 같아 배포를 해 보고자 했다.가장 좋은 건 fastapi가 항상 구동되는 서버

iambeginnerdeveloper.tistory.com

이전에 사이드 프로젝트를 무료 툴인 렌더를 통해서 배포를 했었고
https://www.talk-report.com/

톡리포트 — KakaoTalk Chat Analyzer

www.talk-report.com

해당 사이트는 이전에 https://iambeginnerdeveloper.tistory.com/341 cloudflare를 통해서 구매한 개인 도메인을 연결해서 배포를 했었다.

배포를 했던 프로젝트의 설정 화면에서 custom domains 부분에서 설정을 할 수 있다.

cloudflare에서 구매했던 도메인을 추가 해 주면 갈색 네모창 처럼 인증에러가 뜬다. 이 인증 에러를 클릭하면

이렇게 추가한 도메인에 대해 인증을 하는 화면이 뜬다.

해당 정보들은 도메인 구매처인 cloudflare에서 설정을 먼저 해 주어야 한다.

cloudflare에 접속해서

Domains를 클릭하면 구매한 도메인을 볼 수 있으며 해당 도메인을 클릭한 후

DNS - Records를 클릭해서 추가 설정을 해 줘야 한다.

여기서 기본으로 설정 되어 있는(느낌표 표시가 있는) 설정에서 Type을 CNAME으로, Name을 구매한 도메인 이름으로, Targetdms Render에서 설정 해 준 도메인으로 설정 해 준다.

그리고 Add record를 클릭한 후 Type은 CNAME으로, Name은 www, Target은 Render에서 설정 해 준 도메인으로 설정 해 준 후 저장 해 주면 된다.

두 설정 모두 Proxy status를 해제 해 줘야 한다.

이렇게 설정 해 주면

Render에서 몇분 후에 자동으로 인증이 완료 되었다고 표시가 뜬다.

이전 글에서도 말했지만 Render가 무료 툴이라 좋지만 가장 큰 단점이 최초 접속과 15분 동안 무반응이었다가 다시 접속하게 되면 인스턴스가 종료되었다가 다시 시작되기 때문에 1분정도 접속 대기 화면을 봐야 한다는 것이다.

그래도 공부용으로는 무료 툴인 render 만한 도구를 아직까진 발견 못했기 때문에 앞으로도 애용할 것 같다.

AI 게임 개발 with 코덱스

토오오끼 — Sat, 28 Mar 2026 15:22:09 +0900

한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다.

https://www.hanbit.co.kr/store/books/look.php?p_code=B9338848964

요즘 AI로 뭔가를 만들어보고 싶다는 욕구가 부쩍 늘었다. 코딩을 몰라도 게임을 만들 수 있다는 말, 솔깃하지 않을 수 없다.

이 책은 그 욕구를 슬쩍 건드린다.

10년 차 게임 기획자가 AI 도구들을 팀원 삼아 혼자서 뱀서라이크 게임을 완성하는 과정을 보여주는 책이다.

책의 핵심 메시지

AI를 팀원처럼 활용해, 게임 개발을 해 보지 않은 사람도 게임 하나를 처음부터 끝까지 완성한다.

챗GPT로 캐릭터 에셋을 만들고, 코덱스로 복잡한 시스템을 코딩하고, Lami.ai로 음원을 뽑아내는 분업 구조가 특징이다.

다루는 주요 흐름은 다음과 같다.

게임 기획 및 콘셉트 설정
AI 도구별 역할 분담 (챗GPT / 코덱스 / Lami)
유니티(Unity)로 게임 구현
빌드, 배포, 수익화

단순히 "AI로 이런 게 된다"를 보여주는 것을 넘어, 기획부터 출시까지 전체 흐름을 한 권에 담으려 한 야심찬 시도다.

아쉬운 점

기대가 컸던 만큼, 실제로 따라가다 보면 막히는 지점이 적지 않다.

1️⃣ 초보자에게는 설명이 충분하지 않다.

책의 타깃은 분명 비개발자와 주니어 개발자인데, 설명의 밀도는 그 타깃을 따라가지 못한다. 처음 접하는 툴 앞에서 "어디를 클릭하고, 무엇을 어떻게 설정하라"는 구체적인 안내가 부족해 막막함을 느끼기 쉽다.

2️⃣ 프롬프트 예시가 실제와 다른 결과를 낸다.

책에서 제시하는 프롬프트를 그대로 따라 해도 예시 이미지와 다른 결과가 나오는 경우가 많다. 잘못된 프롬프트가 포함된 것으로 보이는 경우도 있어 초보 독자 입장에서는 내가 틀린 건지 책이 틀린 건지 판단하기도 어렵다.

3️⃣ 유료 툴 없이는 진도를 나갈 수 없다.

중간에 결제가 필요한 유료 프로그램이 등장하는데 이 부분을 건너뛰면 이후 내용을 따라갈 수 없는 구조다. 무료 대안이나 사전 안내가 충분했다면 훨씬 나았을 것이다.

이런 분께 추천

✔ 게임 개발의 전체 흐름을 한눈에 파악하고 싶은 사람

✔ AI 도구를 어떻게 조합해서 쓸 수 있는지 아이디어가 필요한 사람

✔ 유니티 경험이 어느 정도 있는 주니어 개발자

❌ 이런 분께는 아쉬울 수 있어요

코딩·개발 경험이 전혀 없는 완전 입문자
툴 설치부터 설정까지 하나하나 친절한 안내를 기대하는 분
유료 툴 결제 없이 끝까지 실습하고 싶은 분

총평

이 책이 담으려 한 비전은 분명히 가치 있다. 혼자서도 AI와 함께 게임 하나를 완성할 수 있다는 가능성을 보여주려 한 시도 자체는 흥미롭다.

다만 방대한 내용을 한 권에 압축하는 과정에서 디테일이 빠졌고, 그 빈자리가 고스란히 독자의 부담으로 돌아온다.

"AI로 게임을 만들 수 있다"는 영감을 얻는 책으로는 충분하지만, 그 영감을 실제로 구현하기까지는 책 밖에서 더 많은 시간을 써야 했다.

Render | render로 fastapi 배포하기, render fastapi deploy

토오오끼 — Thu, 26 Mar 2026 00:11:47 +0900

사이드 프로젝트로 기능 개발을 하면서 localhost:8000로 화면을 확인하고 동작을 확인해 왔지만 기능 개발이 어느정도 된 것 같아 배포를 해 보고자 했다.

가장 좋은 건 fastapi가 항상 구동되는 서버가 있을 때 해당 서버를 사용해서 배포하는 거지만 쉽지 않기 때문에 보통은 aws같은 도구를 사용한다. aws도 서버를 사용하려면 당연히 비용을 지불해야 하기 때문에 비용 부담을 덜고자 무료 툴을 알아봤다.

그러다가 알게 된 게 Render이다.

Render는 github 레포지토리와 연동해서 코드를 자동으로 빌드하고 배포해 주는 클라우드 플랫폼이다.

별도의 복잡한 서버 관리 없이 코드만 github에 push 하면 된다. 그러면 별도의 도커 설정 없이 python 환경을 사용해 fastapi를 배포할 수 있다.

이러한 장점으로 Render는 학습용 백엔드 배포 플랫폼으로 사용되고 있다.

Render 사용하기 전에 두가지를 먼저 해 줘야 한다.

1. github 원격 레포지토리에 코드 push 하기

- render는 github에서 코드를 가져오기 때문에 배포하고자 하는 소스 코드를 github에 push 해 줘야 한다.

2. requirements.txt 생성 후 소스코드가 저장되어 있는 동일 레포지토리에 push 하기

- render가 해당 파일을 읽어서 패키지를 설치하기 때문에 필요한 패키지를 모두 포함 시켜서 작성 및 저장, push 해 줘야 한다.

pip freeze > requirements.txt

위 명령어를 실행하면 pip로 설치된 모든 패키지 정보를 requirements.txt로 생성하게 된다.

3. render 가입하기

https://render.com/

Render | The cloud for builders

Deploy and scale any app or agent from your first user to your billionth. Build faster on intuitive cloud infrastructure for the modern web.

render.com

위 링크에 접속해서 "Get Started for Free" 버튼을 클릭해서 github 계정으로 가입 해 주면 된다. github 연동을 허용 해 주면 별도의 인증 없이 대시보드에 접근할 수 있다

4. 서비스 생성

대시보드에서 Web Services → New Web Service 순으로 클릭하면 어디서 코드를 가져올지 선택할 수 있다.

github를 선택 해 주면 github에서 render를 설치하고 어떤 레포를 가져올지 선택할 수 있다.

모든 레포가 아닌 선택한 레포만 사용할 수 있도록 Only select repositories를 선택 해 주고 배포 레포를 선택 해 주면 된다.

설치 후 선택한 레포를 클릭 해 주면 fastapi 연결 설정을 할 수 있다.

source code가 선택한 레포가 맞는지 확인 해 준 후 서비스 이름을 Name에 작성 해 준다.

언어는 python3, region은 가장 가까운 싱가포르로 선택 해 주면 된다.

여기서 가장 주용한 건 build command와 start command인데

build command는 pip install -r requirements.txt 로 2번에서 생성 해 준 requirements.txt를 참고해서 패키지를 설치할 수 있도록 해 준다.

start command는 api 실행 커멘트로 uvicorn app.main:app --reload --host 0.0.0.0 --port 10000 으로 설정 해 주면 된다. port는 8000이 아니라 10000으로 해 주면 문제 없이 빌드가 된다.

그리고 instance type을 Free로 선택 해 주면 무료로도 render를 사용할 수 있다.

이렇게 설정 해 준 후 deploy web service를 클릭하면 render가 배포를 시작한다.

log 페이지를 가면 아래처럼 설치 및 배포 과정을 확인 할 수 있다.

빌드를 하다가 에러가 발생하면 아래처럼 에러 로그도 확인할 수 있다.

해당 에러 로그를 보고 코드를 수정하고 다시 push 해 주면 render가 변경 된 push를 자동으로 감지하고 재배포를 하게 된다.

render가 github 레포의 변경 된 push를 자동으로 감지하도록 하려면 Pull Request Previews에서 Off를 Automatic으로 설정 해 주면 된다.

수정 된 코드에서 에러가 해결이 됐다면 render가 배포에 성공하게 되고 이 모든 이력들은 events라는 탭에서 확인할 수 있다.

이렇게 배포가 성공적으로 끝나면 모자이크 처리 된 링크를 통해 외부에서도 접속이 가능 해 진다.

보통 https://Name.onrender.com 형태로 링크가 생성이 된다.

render를 무료 플랜으로 사용하게 되면 가장 큰 단점이 있는데 15분 동안 웹 사이트에서 아무런 반응이 없다면 인스턴스가 종료 된다. 생성된 링크로 초기 접속 또는 15분 뒤 재접속을 하게 되면 50초~60초 정도 대기 시간이 발생한다.

위 화면이 인스턴스 재시작 및 접속 대기 화면인데 해당 화면에서 이런 과정들을 간단하게 로그 형태로 확인할 수 있다.

이렇게 배포한 사이트가 아래 뉴스봇이다.

네이버 뉴스에서 카테고리 별 주요 뉴스 5개의 헤드라인을 크롤링 해 오고 기사의 원문 보기를 클릭하면 해당 기사로 연결되는 간단한 기능의 웹 사이트이다.

https://news-bot-wipz.onrender.com/

https://github.com/YOOHYOJEONG/News-Bot

GitHub - YOOHYOJEONG/News-Bot

Contribute to YOOHYOJEONG/News-Bot development by creating an account on GitHub.

github.com

현재는 금융, 부동산, 경제, 정치, 사회, IT/과학, 세계 카테고리에서 주요 뉴스의 헤드라인을 가져오고 있다.

또 다른 하나는 카카오톡 대화 분석 사이트이다.

https://www.talk-report.com/

오픈채팅방에서 운영진으로 활동하면서 회원들의 채팅수가 몇개인지 분석하면서 활동이 저조한 회원들은 정리하고 있는데 해당 기능의 어플은 유료이거나 특정 os만 지원하길래 웹사이트로 만들었다.

아직 아이폰에서 내보낸 txt 파일과 윈도우에서 낸 txt 파일만 분석이 되지만 추후 맥, 안드로이드에서 내보낸 txt 파일도 분석 되도록 기능을 추가할 예정이다.

https://github.com/YOOHYOJEONG/Talk-Report

GitHub - YOOHYOJEONG/Talk-Report

Contribute to YOOHYOJEONG/Talk-Report development by creating an account on GitHub.

github.com

해당 링크는 render에서 제공한 기본 도메인이 아닌데 이전에 cloudeflare에서 구매한 개인 도메인을 render에 연결했다.

https://iambeginnerdeveloper.tistory.com/341

Cloudflare | Cloudflare Personal Domain 구매하기, 클라우드플레어에서 개인 도메인 구매하기

최근에 사이드프로젝트를 진행하면서 내 pc를 서버로 해서 배포를 해 보려고 했는데 개인 pc ip 주소와 포트를 공개해야 한다는 부담이 있어서 방법을 찾던 중 cloudflare로 배포가 가능하다는 것을

iambeginnerdeveloper.tistory.com

위 포스팅 때 구매했던 도메인을 render에 연결하는 과정은 다음 포스팅에서 다룰 예정이다.

Embedding | 딥러닝 임베딩에서 Cosine Similarity를 사용하는 이유(with FaceNet, ArcFace )

토오오끼 — Sun, 22 Mar 2026 15:30:15 +0900

딥러닝 기반 얼굴 인식이나 텍스트/이미지 임베딩을 다루다 보면 거의 항상 등장하는 개념이 있다.

바로 Cosine Similarity(코사인 유사도)다.

FaceNet, ArcFace 같은 얼굴 인식 모델뿐 아니라 CLIP, SBERT 같은 최신 임베딩 모델들도 대부분 코사인 기반으로 유사도를 계산한다. 단순히 “벡터 유사도 계산 방법 중 하나”라서 사용하는 것이 아니라, 딥러닝 임베딩 공간의 구조와 매우 잘 맞기 때문에 사실상 표준처럼 사용된다.

왜 딥러닝에서 코사인 유사도가 많이 사용되는지, 그리고 FaceNet과 ArcFace가 왜 cosine 기반 loss를 사용하는지까지 딥러닝 관점에서 자세히 정리해 보려고 한다.

먼저 딥러닝 모델이 얼굴이나 문장을 어떻게 표현하는지부터 이해할 필요가 있다.

얼굴 인식 모델은 입력 이미지를 그대로 비교하지 않는다. 대신 CNN이나 Transformer를 통해 고차원 임베딩 벡터(embedding vector)를 생성한다. 예를 들어 얼굴 이미지를 모델에 넣으면 다음과 같은 512차원 벡터가 나온다.

[0.12, -0.44, 0.87, ..., 0.31]

이 벡터는 해당 얼굴의 특징을 표현하는 수치 표현이다.

얼굴 인식 시스템은 이렇게 생성된 벡터를 데이터베이스에 저장하고, 새로운 얼굴이 들어왔을 때 벡터 간 유사도를 계산해 같은 사람인지 판단한다.

두 벡터가 얼마나 비슷한지 측정하는 방법은 대표적으로 두가지가 있다.

Euclidean Distance (유클리드 거리)
Cosine Similarity (코사인 유사도)

유클리드 거리는 distance(x, y) = ||x - y|| 익숙한 거리 개념이다.

반면에 코사인 유사도는 cos(θ) = (x · y) / (||x|| ||y||) 두 벡터 사이의 각도를 이용해 유사도를 계산한다. 값의 범위는 -1에서 1 사이이며, 1에 가까울수록 두 벡터의 방향이 비슷하다.

딥러닝 임베딩에서는 보통 벡터의 크기보다 방향이 더 중요한 의미를 갖는다.

예를 들어 같은 사람의 얼굴 두 장이 있다고 하자. 조명이나 해상도 때문에 모델이 생성한 임베딩 벡터의 크기는 달라질 수 있다.

x = [0.2, 0.4, 0.1]
y = [0.4, 0.8, 0.2]

이 두 벡터는 사실상 같은 방향을 가리키고 있다. 단지 스케일만 다르다. 이런 경우 유클리드 거리로 보면 두 벡터는 꽤 멀어 보일 수 있다. 하지만 코사인 유사도를 계산하면 거의 1에 가까운 값이 나온다. 즉 코사인 유사도는 벡터의 방향을 기준으로 유사도를 측정한다.

딥러닝 임베딩에서는 바로 이 특성이 중요하다. 모델이 학습하는 것은 절대적인 숫자가 아니라 특징 패턴의 방향이기 때문이다.

실제로 많은 얼굴 인식 모델은 임베딩 벡터를 생성한 뒤 다음과 같은 L2 normalization을 수행한다.

x = x / ||x||

이렇게 하면 모든 임베딩 벡터의 길이가 1이 된다. 즉 모든 벡터가 단위 구면(unit hypersphere) 위에 존재하게 된다.

이 상태에서는 벡터 간 관계가 사실상 각도(angle) 로 표현된다. 벡터의 길이는 모두 동일하므로 두 벡터가 얼마나 비슷한지는 각도가 얼마나 작은지로 결정된다.

이때 유클리드 거리와 코사인 유사도의 관계를 살펴보면 흥미로운 사실이 나온다. 두 벡터가 정규화되어 있다고 가정하면

||x|| = 1
||y|| = 1

이때 유클리드 거리 제곱은 다음과 같이 전개된다.

||x - y||² = ||x||² + ||y||² - 2x·y
= 1 + 1 - 2x·y
= 2 - 2cos(θ)

즉 L2 normalization을 하면 유클리드 거리와 코사인 유사도는 사실상 같은 정보를 표현하게 된다. 단지 표현 방식만 다를 뿐이다. 이 때문에 딥러닝 임베딩에서는 보통 해석이 직관적인 코사인 유사도를 사용하는 경우가 많다.

FaceNet은 얼굴 인식 분야에서 큰 영향을 준 모델이다. 이 모델은 Triplet Loss라는 방식을 사용해 임베딩을 학습한다.

Triplet Loss는 세 개의 샘플을 사용한다.

Anchor (기준 얼굴)
Positive (같은 사람의 다른 사진)
Negative (다른 사람의 얼굴)

학습 목표는 다음과 같다.

distance(anchor, positive) + margin < distance(anchor, negative)

같은 사람의 얼굴은 더 가깝게, 다른 사람은 더 멀어지도록 학습한다.

FaceNet 역시 임베딩을 정규화하기 때문에 결국 각도 기반으로 얼굴을 구분하는 구조가 된다.

하지만 Triplet Loss는 학습 효율이 좋지 않았다는 문제가 있다. 어떤 triplet을 선택하느냐에 따라 학습 성능이 크게 달라지기 때문이다. 그래서 이후 연구에서는 classification 방식과 metric learning을 결합한 새로운 방법들이 등장했다.

대표적인 것이 ArcFace다.

ArcFace는 일반적인 softmax 분류 구조를 기반으로 한다. 원래 softmax classifier는 다음과 같은 형태로 동작한다.

logit = W · x

여기서 W는 classifier weight이고 x는 feature vector다.

하지만 이 방식에는 문제가 있다. 모델이 분류 성능을 높이기 위해 벡터의 크기를 키워버릴 수 있다.

즉 임베딩 공간이 “유사도 기반 구조”가 아니라 단순히 분류 정확도를 높이는 방향으로 왜곡될 수 있다.

그래서 ArcFace는 두 가지 제약을 추가한다.

첫째, feature vector normalization이다.

||x|| = 1

둘째, classifier weight normalization이다.

||W|| = 1

이렇게 하면 분류 score가 다음과 같이 바뀐다.

W · x = cos(θ)

즉 classifier 자체가 각도 기반 분류기가 된다. 얼굴 인식 문제를 “각도 분리 문제”로 바꾸는 것이다.

하지만 여기서 또 하나의 문제가 있다. 같은 사람의 얼굴이라도 decision boundary 근처에 위치할 수 있다. 즉 intra-class 분포가 충분히 compact하지 않을 수 있다. 이를 해결하기 위해 등장한 개념이 margin이다.

CosFace는 다음과 같은 margin을 사용한다.

cos(θ) - m

즉 cosine 값에서 일정 값을 빼서 decision boundary를 조정한다.

ArcFace는 여기서 한 단계 더 나아간다. ArcFace는 cosine 값에 margin을 빼는 대신 각도 자체에 margin을 추가한다.

cos(θ + m)

이 방식이 중요한 이유는 기하학적으로 더 자연스럽기 때문이다.

임베딩 공간이 단위 구면 위에 존재하므로 실제 분리는 각도 기준으로 이루어져야 한다. ArcFace는 바로 이 각도 기준 margin을 직접 적용한다.

이렇게 하면 같은 사람의 얼굴은 더 작은 각도로 모이게 되고, 다른 사람은 더 멀어지게 되어 아래와 같은 효과가 생긴다.

intra-class compactness 증가
inter-class separability 증가

결과적으로 임베딩 공간이 다음과 같이 변한다.

기존 softmax에서는 클래스 분포가 서로 겹칠 수 있지만 ArcFace를 적용하면 각 클래스가 구면 위에서 명확하게 분리된 클러스터를 형성하게 된다. 이러한 구조 덕분에 ArcFace는 LFW, MegaFace 같은 얼굴 인식 벤치마크에서 매우 높은 성능을 기록했다.

지금까지 내용을 정리해보면 딥러닝 임베딩에서 코사인 유사도가 널리 사용되는 이유는 크게 세 가지다.

첫째, 딥러닝 임베딩에서는 벡터의 크기보다 방향이 의미를 담는 경우가 많다.

둘째, L2 normalization을 적용하면 임베딩 벡터가 unit hypersphere 위에 존재하게 되고 유사도는 각도로 표현된다.

셋째, ArcFace 같은 최신 얼굴 인식 모델은 angular margin을 통해 임베딩 공간을 더욱 명확하게 분리한다.

이러한 이유 때문에 얼굴 인식뿐 아니라 텍스트 임베딩, 이미지 검색, 추천 시스템 등 다양한 분야에서 “Embedding + Cosine Similarity” 구조가 사실상 표준처럼 사용되고 있다.