초보 개발자의 일기장

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

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

요즘 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” 구조가 사실상 표준처럼 사용되고 있다.

Antigravity | google antigravity install, 구글 안티그래비티 설치 및 사용하기

토오오끼 — Mon, 9 Mar 2026 16:40:01 +0900

요즘 개발 환경이 빠르게 바뀌면서 단순히 코드를 자동완성 해 주는 수준을 넘어 이제는 AI가 직접 개발 작업을 수행하는 Agent 기반 개발 도구들이 등장하고 있다. 클로드 코드, 코덱스 등등 유명한 것이 많지만 구글에서 출시한 Antigravity라는 도구를 사용 해 보려고 한다.

antigravity는 프롬프트로 프로젝트를 설명하면 AI Agent가 코드 생성, 실행, 테스트까지 수행해 준다. 실제로 간단한 백엔트 프로젝트 정도는 몇분도 안돼서 생성이 되는 것을 확인할 수 있다.

이런 툴 사용도 요즘엔 당연히 요구되는 역량이기 때문에 이번에 antigravity를 설치해서 사용 해 봤다.

1. 설치

https://antigravity.google/download

Google Antigravity

Google Antigravity - Build the new way

antigravity.google

위 링크에서 환경에 맞는 파일을 다운로드 후 설치 해 주면 된다.

윈도우의 경우 환경 변수 자동 설정을 체크했다면 설치 후 pc 재시작을 해 줘야 한다.

2. 환경 셋팅

파일 설치를 해 준 후 실행을 하면 안티그래비티의 IDE 환경을 선택하는 화면이 나온다.

보통 3가지 옵션 중 원하는 옵션을 선택할 수 있다고 하는데 나는 커서를 사용하지 않고 있어서 그런지 리스트에 없다.

Start fresh: 기존 설정 없이 처음부터 시작
Import from VS Code: VS Code에서 사용하던 익스텐션, 단축키, 테마 등의 설정을 그대로 사용 가능
Import from Cursor: Cursor 사용자라면 기존 커서 환경을 그대로 사용 가능

IDE 환경을 선택하고 나서 테마까지 고른 후에는 에이전트 운용 방법을 선택할 수 있다.

에이전트 운용 방법 옵션

Strict Mode: 에이전트 실행에 엄격한 제한을 두는 방식
Review-driven development: 에이전트가 작업 전 사용자 검토를 요청하는 방식 → 기본 권장 옵션
Agent-driven development: 에이전트가 자율적으로 작업을 수행하는 방식 → 원치 않은 파일을 지울 위험이 있음
Custom configuration: 사용자가 직접 세부 설정을 구성하는 방식

Review-driven development를 선택하면 코드를 짜거나 터미널 명령어를 입력할 때 실행하기 전에 사용자에게 실행해도 되는지 확인을 받게 된다. 그럴 때 마다 동의 버튼을 눌러줘야 하지만 안티그래비티가 실수하는 일을 방지할 수 있기 때문에 해당 방법을 선택하는 게 권장된다.

오른쪽에는 터미널 실행 정책, 검토 정책, JavaScript 실행 정책 등 세부 옵션을 고를 수 있도록 되어 있다.

이후 에디터 세부 설정에서 단축키는 어떻게 설정할지 익스텐션은 어떻게 할지 설정할 수 있다.

Keybindings: 키 입력 방식을 Normal과 vim 중에서 선택할 수 있다. Normal은 VS Code처럼 마우스 클릭과 익숙한 단축키를 사용하는 일반적인 방식이며 vim은 키보드만으로 모든 편집 작업을 수행하는 방식이다. 리눅스 환경에 익숙하다면 vim을, 익숙하지 않다면 Normal을 선택하는 것이 좋다.
Extensions: 언어 확장 프로그램 설치 방식 설정으로 권장 익스텐션을 자동으로 설치하는 Recommended와 직접 구성하는 Configure 중에서 선택할 수 있다. 자동으로 설치되는 게 상관없다면 기본으로 변경 없이 설정해 주면 된다.

설정이 끝났다면 구글 로그인을 해 주고 동의까지 해 주면 설정이 끝난다.

3. 사용

설정을 모두 마치면 메인 화면이 아래처럼 나타난다.

메인 화면이 2가지로 나눠져 있는데 왼쪽은 시작 화면으로 폴더를 열거나 레포지토리를 클론하고, 최근 작업한 워크스페이스 목록을 확인할 수 있다.

오른쪽은 AI 모델 선택 화면으로, Gemini 3 Pro부터 Claude Sonnet, GPT-OSS 모델 중 선택해 사용할 수 있다.

익스텐션에서 한국어 패치를 설치하면 영어가 아니라 한국어로 안티그래비티를 사용할 수도 있다.

이후 open folder를 통해 작업할 폴더를 선택 해 주면 보안 확인 팝업이 나타나며, 권한을 허용하면 안티그래비티를 본격적으로 사용 가능하다.

4. agent한테 일 시키기

오른쪽 창의 Agent한테 구체적으로 역할, 목표, 개발하고자 하는 기능, 필요한 라이브러리, 프로젝트 이름, 각 파일들의 역할, 프로젝트 구조, 최종 산출물 등을 자세히 알려주면

이렇게 Task와 Implementation Plan을 만들어 준다.

Antigravity Agent는 보통 3단계로 작업한다.

1) Implementation Plan 생성

2) Task 분해

3) 코드 생성 및 파일 생성

현재 상태는 아직 코드가 생성된 것이 아니라 Agent가 작업 계획을 만든 단계이다.

Task와 Implementation Plan이 만들어져있다면 agent 창에서는 이렇게 되어 있을텐데 Open을 클릭해서 각각 파일을 확인할 수 있다. agent가 만들어준 내용이 적합하다고 판단된다면 채팅으로 “Approve and execute the plan.”을 입력 해 주면 agent가 다음 작업을 시작하게 된다.

1) 폴더 생성

2) 파일 생성

3) 코드 작성

4) requirements 작성

이때 생성되는 코드들마다 accept를 할건지 물어보는데 자동으로 작성된 코드를 보고 문제가 없다고 판단된다면 accept를 해 주면 파일이 저장이 된다.

산출물은 코드 뿐 만 아니라 처음 agent에 입력할 때 지정한 대로 생성되기 때문에 agent에 어떻게 입력하느냐에 따라 산출물이 달라진다.

5. 사용 후기

사용하기 전에는 딸깍 한번으로 모든 게 자동으로 생성되고 동작하는 줄 알았으나 전혀 아니었다.

agent한테 일을 시킬 때 어떤 환경에서 어떤 기능을 어떻게 동작시킬 것인지 등등 정말 하나하나 구체적으로 알려줘야만 제대로 된 결과물을 빠르게 얻을 수 있다. 러프하게 알려주면 agent도 어떻게 일을 해야 할지 갈팡지팡하면서 제대로 된 코드를 작성 해 주지 못한다.

그리고 사용 후기에 다른 툴에 비해 느리다는 단점이 있다고 했는데 처음에 사용할 땐 느리다는 느낌을 못 받았으나 디테일한 요소들이 늘어나고 시키는 범위가 늘어나니 agent가 생각하는 시간이 늘어나고 산출물을 생성하는데 약간 시간이 걸리긴 하더라.

이건 다른 툴을 써서 비교 해 봐야 할 것 같아서 다음은 코덱스로 비슷한 작업을 해 볼 예정이다.

Airflow | Airflow DockerOperator 사용 시 Permission denied 해결 방법

토오오끼 — Tue, 3 Mar 2026 11:53:25 +0900

Airflow에서 DockerOperator를 사용해 외부 Docker 컨테이너를 실행하려고 할 때, 다음과 같은 에러를 만날 수 있다.

PermissionError(13, 'Permission denied') Failed to establish connection to Docker host unix://var/run/docker.sock

여기서 핵심은 docker_url="unix://var/run/docker.sock" 즉, Airflow 컨테이너 내부에서 호스트의 Docker 소켓에 접근해야 한다.

Airflow는 DockerOperator를 통해 호스트의 Docker 데몬과 통신한다.

일반적으로 다음과 같이 설정한다.

DockerOperator(
    task_id="run_container",
    image="my_image:latest",
    command="bash -c 'echo hello'",
    docker_url="unix://var/run/docker.sock",
)

DockerOperator는 내부적으로 다음을 수행한다:

Docker 소켓(/var/run/docker.sock)을 통해
호스트 Docker 데몬에 연결
새로운 컨테이너 생성 및 실행

즉, Airflow 컨테이너가 Docker를 실행하는 구조 이기 때문에, Docker 소켓 접근 권한이 반드시 필요하다.

그런데 기본 docker-compose 환경에서 Airflow는 일반 사용자 권한으로 실행되며, var/run/docker.sock 파일은 보통 root 또는 docker 그룹만 접근 가능하다.

따라서 다음과 같은 에러가 발생한다.

PermissionError(13, 'Permission denied') Failed to establish connection to Docker host unix://var/run/docker.sock

docker-compose.yaml 파일에서 airflow-worker 서비스에 user: "0:0" 설정을 추가하면 간단하게 해결 가능하다.

airflow-worker:
  user: "0:0"

user: "0:0"는 root 권한 실행을 의미한다.

ex)

services:
  airflow-worker:
    image: apache/airflow:2.x.x
    user: "0:0"
    volumes:
      - ./dags:/opt/airflow/dags
      - /var/run/docker.sock:/var/run/docker.sock

이 설정은 다음과 같은 의미를 가진다:

Airflow worker가 root 권한을 가진다
컨테이너 탈출 시 위험성 증가

따라서 운영 환경에서는 다음 대안을 고려할 수 있다.

대안 1: docker 그룹 권한 사용

: 호스트의 docker 그룹 GID를 맞춰서 실행

대안 2: Docker Remote API + TLS 사용

: docker_url="tcp://host:2376" 방식

대안 3: KubernetesPodOperator 사용

: k8s 환경에서는 더 안전한 구조 가능

컨텍스트 엔지니어링으로 완성하는 AI 에이전트

토오오끼 — Tue, 24 Feb 2026 16:36:40 +0900

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

요즘 LLM을 활용한 서비스가 정말 많아졌다. ChatGPT를 쓰는 것을 넘어, RAG를 붙이고, 메모리를 설계하고, 에이전트를 만들고, 운영까지 고민하는 단계로 넘어가고 있다.
이 책은 바로 그 지점에서 등장한다.
이 책은 프롬프트를 잘 쓰는 법이 아니라, LLM이 제대로 사고하도록 “환경”을 설계하는 방법을 다루는 책이다.

책의 핵심 메시지

이 책의 중심은 하나다.
모델이 올바르게 사고하도록 ‘환경’을 설계하는 것

프롬프트 엔지니어링이 질문을 다듬는 기술이라면, 컨텍스트 엔지니어링은 모델이 사고할 수 있는 환경을 설계하는 기술에 가깝다.
다루는 주요 내용은 다음과 같다.

RAG (검색 증강 생성)
CoT (Chain of Thought)
단기·장기 메모리 전략
AI 에이전트 설계 패턴
품질 평가 및 디버깅
프롬프트 인젝션 등 보안 이슈

단순히 “이렇게 만들 수 있다”가 아니라
“왜 이렇게 설계해야 하는가”를 구조적으로 설명한다는 점이 특징이다.

이 책이 좋은 이유

1️⃣ 이론서가 아니라 설계서다

트랜스포머 수식이나 어텐션 구조를 깊게 파는 책은 아니다.
대신 이걸 실제 서비스로 만들려면 구조를 어떻게 잡아야 하지? 등을 물으며 LLM 아키텍처 관점에서 사고를 정리해준다.

2️⃣ RAG를 한 번이라도 삽질해본 사람에게 특히 좋다

이 책은 완전 입문자보다는 이런 사람에게 잘 맞는다.

RAG를 붙여봤는데 성능이 들쭉날쭉했던 사람
메모리를 붙였는데도 맥락을 잃는 경험을 한 사람
데모는 되는데 운영은 불안했던 사람

3️⃣ LLMOps 관점까지 확장한다

많은 책이 “만드는 법”까지만 다루는데, 이 책은 “운영과 평가”까지 간다.

어떻게 품질을 측정할 것인가?
오류를 어떻게 디버깅할 것인가?
프롬프트 인젝션은 어떻게 막을 것인가?

이런 사람에게 추천

✔ LLM API를 이미 써본 개발자
✔ LangChain/RAG를 조금이라도 다뤄본 사람
✔ 사내 AI 도입을 고민하는 PM/테크 리더
✔ 챗봇을 넘어 에이전트를 설계하고 싶은 사람
✔ LLM을 “기능”이 아니라 “시스템”으로 만들고 싶은 사람

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

완전 비개발자
LLM을 한 번도 안 써본 입문자
모델 내부 수학 이론을 깊게 배우고 싶은 사람

이 책은 기초 개념서라기보다는 실전 설계 가이드에 가깝다.

총평

이 책은 프롬프트를 잘 쓰는 법을 알려주는 책이 아니다.
LLM을 단순한 도구가 아니라 하나의 아키텍처로 다루고 싶다면 충분히 읽어볼 가치가 있다. 이미 RAG나 에이전트를 구현해본 경험이 있다면, 이 책은 설계를 한 단계 정리해줄 것이다.

Timezone | docker container timezone 변경, 도커 컨테이너 시스템 시간 변경

토오오끼 — Mon, 16 Feb 2026 20:23:36 +0900

Docker 컨테이너에서 로그를 확인하다 보면 시간이 UC T기준으로 찍히는 경우가 많은데 운영 환경이 한국(KST) 기준이라면 로그 분석 시 매번 시간 변환을 해야 해서 변경을 해 줘야만 한다.

먼저 컨테이너 내부에서 tzdata를 설치 해 줘야 한다.

apt-get update && apt-get install -y tzdata

위 명령어를 통해 설치를 하게 되면

타임존을 선택할 수 있는 창이 뜬다. 여기서 사용하고자 하는 타임존 나라, 도시를 선택하면 설치가 완료 된다.

ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime

이후 위 명령어로 위에서 선택한 시간대 파일을 시스템 기본 시간 설정 파일로 연결해 주면 컨테이너 시스템 시간을 위에서 설정한 시간 기준으로 동작하게 된다.

추가적으로 사용하는 스크립트 상단에 tZ 환경 변수를 지정해 줄 수도 있다

export TZ=Asia/Seoul

만약 컨테이너 시스템 시간은 그대로 두고 로그를 출력하는 시점에만 원하는 시간대로 지정하고 싶다면 bash 스크립트에서 로그함수를 별도로 정의해 주면 된다.

log() {
    echo "[$(TZ=Asia/Seoul date '+%F %T')] $1" | tee -a "$LOG_FILE"
}

이렇게 하면 시스템 전체 시간은 변경하지 않으며 로그 포맷만 KST로 맞추고 싶을 때 사용할 수 있고 간단한 스크립트 기반 운영 환경에서 유용하다.

rsync | rsync란?, crontab + rsync 사용해서 주기적으로 파일 백업하기

토오오끼 — Fri, 13 Feb 2026 14:12:28 +0900

rsync란

Remote Sync(원격 동기화)의 약자로 이름처럼 한 위치(로컬/원격) 의 파일을 다른 위치로 동기화하는 데 쓰인다.
로컬 시스템끼리 동기화하거나, 네트워크를 통해 원격 서버와 동기화할 수 있다.
단순 복사가 아니라, 이미 있는 파일과 비교해서 변화된 부분만 전송하는 효율적인 방식이라 빠르고 대역폭 절약에 유리하다.

rsync 장점

존에 있는 파일과 비교해서 변경된 부분만 보내므로 전체를 매번 다시 복사하지 않는다
로컬 ↔ 원격 어디든 사용 가능하다
SSH 등 보안 연결로 파일 전송이 가능하다

rsync를 crontab에 등록하여 주기적으로 실행되도록 설정함으로써, 변경된 파일만 증분 전송하는 효율적인 백업 자동화 환경을 구축할 수 있다.

1. cron, rsync 설치 및 실행

sudo apt update && sudo apt install -y cron
sudo apt-get install -y rsync

service cron start

cron을 시작 해 줘야 등록된 스케줄에 맞춰서 동작을 하게 된다.

2. 쉘 스크립트 작성

#!/bin/bash

# ======================================================
# Track new files from server using rsync
# - cron friendly
# - new files only
# ======================================================

set -euo pipefail  # -e : 명령 하나라도 실패 시 즉시 종료 / -o pipefail : 파이프 중간에 실패 시 실패로 간주

# config
SRC_USER='user name'
SRC_HOST='IP 또는 domain 주소'
SRC_BASE='소스 경로'  # source directory
DST_BASE='백업해 둘 경로'

LOG_DIR='/var/log/rsync'
LOG_FILE="${LOG_DIR}/track_$(date +%F).log"

RSYNC_BIN="/usr/bin/rsync"
SSH_BIN="/usr/bin/ssh"

mkdir -p "$DST_BASE"
mkdir -p "$LOG_DIR"

log() {
    echo "[$(date '+%F %T')] $1" | tee -a "$LOG_FILE"
}

log "==== rsync check start ===="

# -a : 권한, 시간, 심볼릭 링크 유지 / -z : 전송 중 압축 
# --ignore-existing : 이미 존재하는 파일은 덮어쓰지 않음
# --partial : 전송 중 끊겨도 받던 파일 유지, 다음 실행 시 이어받기
# --timeout=600 : 10분 간 응답 없으면 실패 처리
# --human-readable : 저장되는 파일의 용량을 읽기 쉽도록 로그에 기록 해 줌
# --itemize-changes : 진행 상태 로그에 표시
# -e "$SSH_BIN" : rsync transport로 ssh 사용, 포트 변경, 옵션 확장 가능
$RSYNC_BIN -az \
    --ignore-existing \
    --partial \
    --timeout=600 \
    --human-readable \
    --itemize-changes \
    -e "$SSH_BIN" \
    "${SRC_USER}@${SRC_HOST}:${SRC_BASE}/" \
    "${DST_BASE}/" >> "$LOG_FILE" 2>&1

# 중간에 죽었으면 이 로그 없을 것 → 장애 판단 기준
log "==== rsync pull finished ===="

위 스크립트처럼 동작 스크립트를 작성 한 후 해당 스크립트를 cron에 등록 해 주면 된다.

위 스크립트는 특정 경로에 새로운 파일이 생겼는지 확인 후 새로운 파일이 감지가 됐을 때 해당 파일만 별도 경로로 이동 시키는 스크립트이다.

3. ssh 키 인증

rsync transport로 ssh 사용할 것이기 때문에 ssh 키 인증을 사전에 해 줘야 한다.

cron을 동작 시킬 곳에서 ssh 키 인증을 해 주면 된다.

sudo -i
ssh-keygen -t ed25519

엔터 3번 치면 키가 생성되고 이때 생성된 키의 경로를 저장 해 둔다.

ssh-copy-id user@외부 pc ip

위 명령어를 통해 공개키를 외부 pc에 등록을 하고 마지막으로 비밀번호를 입력 해 주면 된다.

이후 cron을 설정할 서버에서 새로운 파일이 생기는 서버로 ssh 접속 했을 때 비밀번호를 물어보지 않고 연결 된다면 제대로 설정 된 것이다.

4. host key 자동 승인 yes/no 제거

한번만 수동으로 ssh 접속 후 “Are you sure you want to continue connecting?” 뜨면 yes 입력 해 주면 이후 절대 안 물어본다.

이때 ssh 접속 정보가 /root/.ssh/known_hosts에 저장되는데 이 파일을 cron에서 그대로 사용한다.

5. 스크립트 동작

스크립트에 구문 오류가 없는지 확인 위해 단독 실행을 해 보는 것이 좋다.

# 스크립트 권한 부여
sudo chmod +x /workspace/script.sh

# 스크립트 실행
bash -x /workspace/script.sh

스크립트에 권한을 부여 후 실행을 하면 되는데 crontab 실행 시에도 스크립트의 파일명이 아니라 위처럼 꼭 pull path를 적어줘야 한다.

단독 실행 시 오류 없이 동작 한다면 cron에 일정 등록을 하면 된다.

6. cron에 일정 등록

# cron 편집기 열기
crontab -e

위 명령어를 입력하면 편집기 선택을 할 수 있는데 nano / vim 중에 편한 걸로 에디터를 선택 해 주고 사용하면 된다.

cron의 일정 포맷 기본은 분 시 일 월 요일 실행할_명령 이렇게 되어 있다.

ex)

매분, 매시간, 매일, 매월 ⇒ 1분마다 /home/ubuntu/start.sh 파일을 실행 : * * * * * /home/ubuntu/start.sh

매일 3시에 /home/ubuntu/start.sh 파일을 실행 : 0 3 * * * /home/ubuntu/start.sh

10분 마다 실행 : */10 * * * * /usr/local/bin/track_new_mp4.sh

10분 간격, 4시, 매일, 매월, 매일, 즉 매일 4시, 4시 10분, 4시 20분, 4시 30분 /home/ubuntu/start.sh파일을 실행 : */10 4 * * * /home/ubuntu/start.sh

6시간마다 /home/ubuntu/start.sh 파일을 실행 : 0 */6 * * * /home/ubuntu/start.sh

1시간 마다 실행 : 0 * * * * /usr/local/bin/script.sh

평일(월요일~금요일) 3시에 /home/ubuntu/start.sh 파일을 실행 : 0 3 * * 1-5 /home/ubuntu/start.sh

주말(일요일, 토요일) 3시에 /home/ubuntu/start.sh 파일을 실행 : 0 3 * * 0,6 /home/ubuntu/start.sh

매일 새벽 5시에 재부팅하기 : 0 5 * * * /sbin/shutdown -r now

⇒ 해당 포맷에 맞춰서 원하는 일정, 명령어를 cron 편집기에서 하단에 추가 해 주면 된다.

7. cron 등록 확인

crontab -l

해당 명령어를 입력했을 때 추가한 일정이 뜨면 제대로 등록이 된 것이다.

8. cron 동작 확인

등록한 일정대로 스크립트가 동작하는지 확인 하면 된다.

만약 10분 마다 실행하도록 했다면 매 시간 10분 단위로 실행이 됨. cron 등록 시간이 15시 03분이라면 첫 실행이 13분에 실행되는 게 아니라 15시 10분에 첫 실행이 됨. 다음 실행 시간은 15시 20분이 된다. 동일하게 1시간 마다 실행하도록 했다면 매 시간 정각에 실행 됨. cron 등록 시간이 15시 02분이라면 첫 실행은 16시 정각에 실행된다.