Sevity Blog

snowflake

sevity — Mon, 23 Jun 2025 20:09:53 +0900

글로벌하게 유니키한 키를 만들어야 할때, 보통은 uuid를 떠올리지만 snowflake방식을 선택하면 아래와 같은 장점이 있다.

비교 항목	UUIDv4	Snowflake
크기(Storage)	128 bit (16 바이트)	64 bit (8 바이트)
인덱스 단편화	완전 랜덤 삽입 → B-tree 인덱스 단편화↑	시간순으로 순차적 증가 → 단편화↓
순차성(Time-sortable)	불가능	상위 비트에 밀리초 타임스탬프 내장 → 정렬 가능
생성 비용	랜덤 엔트로피 생성 → CPU & 메모리 부하 다소 높음	단순 비트 연산 + 시퀀스 → 매우 경량
메타데이터 내장	없음	타임스탬프·데이터센터ID·노드ID·시퀀스 정보 포함
충돌 위험	충돌 확률 극히 낮으나 완전히 배제 불가	노드ID+시퀀스 조합으로 충돌 사실상 0 (전제: 노드ID 관리)
디버깅·추적 편의성	ID만으로 “언제 생성됐는지” 파악 불가	ID만으로 생성 시각·생성 주체(노드) 추적 가능

언제 UUID를 쓰고, 언제 Snowflake를 쓰나?

UUIDv4
- 단순 분산 식별자(ID)만 필요하고, 시간순 정렬·인덱스 단편화 이슈가 크지 않은 애플리케이션
- 예: 각종 리소스(사용자·세션·토큰) 식별 등
Snowflake
- 고TPS 분산 시스템에서 시간순 처리·인덱스 효율·멱등 ID가 중요할 때
- 예: 이벤트 로깅, 메시징 시스템, 주문·트랜잭션 ID

OIDC(Open ID Connect)

sevity — Wed, 18 Jun 2025 01:50:19 +0900

OAuth2.0위에서 추가로 설계된 스펙으로 기존 엑세스토큰, 리프레시토큰과 더불어 ID Token을 발행하여 “인증(Authentication)” 기능을 추가한 표준 프로토콜입니다.

OAuth 2.0이 “리소스 접근 권한(Authorization)”을 다룬다면,
OIDC는 “사용자 인증(Authentication)”을 다룹니다.

필수 클레임(iss, sub, aud, exp 등) + 요청한 소수의 추가 클레임(예: email, name)

ID Token에 담기는 필드 예시

{
  "iss": "https://auth.gangnamunni.com/",     // 토큰 발급자(Identity Provider)  
  "sub": "248289761001",                       // 사용자 고유 식별자  
  "aud": "points-service-prod",                // 토큰 대상(클라이언트 ID)  
  "exp": 1718865600,                           // 토큰 만료 시각 (Unix timestamp)  
  "iat": 1718862000,                           // 토큰 발급 시각  
  "auth_time": 1718861990,                     // 사용자가 실제 인증한 시각  
  "nonce": "n-0S6_WzA2Mj",                      // 리플레이 공격 방지용 값  
  "email": "janedoe@example.com",              // 요청한 추가 클레임: 이메일  
  "email_verified": true,                      // 이메일 검증 여부  
  "name": "Jane Doe",                          // 요청한 추가 클레임: 이름  
  "preferred_username": "j.doe"                // 요청한 추가 클레임: 사용자명
}

하지만 아래 이유로..

정적 정보: 발급 시점의 정보만 담겨, 사용자가 프로필을 변경해도 토큰에는 반영되지 않음
사이즈 한계: 너무 많은 필드를 넣으면 JWT가 커져 네트워크/성능 부담 ↑
보안 고려: 민감 정보(주소, 휴대폰 등)를 토큰에 영구 저장하면 위험

UserInfo Endpoint 추가

자세한건 다시 api찔러서 확인

서비스 특성에 따라

ID 토큰만,
UserInfo만,
혹은 둘 다 쓰는 패턴을 자유롭게 선택하시면 됩니다.

UserInfo Endpoint를 왜 추가했나?

목적: “로그인한 사용자에 대한 동적·확장 프로필”을 안전하게 조회”
동작 방식:
1. 클라이언트가 access_token을 이용해 /userinfo 호출
2. 서버가 현재 스코프(scope)·권한에 맞는 최신 프로필(JSON) 반환
장점:
- 최신성: 호출 시점의 유저 정보를 그대로 반영
- 선택적 노출: scope(email profile phone 등)에 따라 필요한 정보만 제공
- 토큰 경량화: 민감·대용량 데이터는 토큰이 아니라 API로 분리

/userinfo라는 엔드포인트 이름 자체도 OIDC Core 1.0 사양(섹션 5.3)에 명시된 표준 필드(userinfo_endpoint)입니다. 클라이언트는 .well-known/openid-configuration에서 이 URL을 동적으로 조회(discovery)하도록 되어 있고, 실제 경로는 /userinfo가 아니어도 메타데이터에 정의된 대로 호출하면 됩니다. 즉, /userinfo는 OIDC 스펙에 포함된 공식 기능이며, “스펙 확장”이 아니라 인증과 프로필 조회를 분리하기 위해 설계된 표준입니다

outbox 패턴

sevity — Mon, 16 Jun 2025 23:17:44 +0900

“아웃박스 패턴은 분산 트랜잭션을 쓰지 않고도 데이터베이스 업데이트와 외부 시스템(Kafka나 REST API 등) 호출을 사실상 하나의 트랜잭션처럼 보이게 하는 기법입니다.

비즈니스 로직 DB 쓰기와 동일한 DB 트랜잭션에서 ‘Outbox’ 테이블에 이벤트 메시지를 append(INSERT)
트랜잭션 커밋 시점에 비즈니스 데이터와 Outbox INSERT가 함께 커밋됨
별도 프로세스(Outbox Poller)가 이 테이블을 폴링해서 메시지를 읽고 Kafka 프로듀서나 외부 API를 호출
호출 성공 시 Outbox 레코드의 status=PROCESSED(또는 sent_at) 같은 플래그를 업데이트”

“Outbox 패턴으로 비즈니스 데이터와 이벤트 기록을 하나의 DB 트랜잭션에 묶어 최소-Once 전송을 확보합니다.
이후 Outbox Poller가 Kafka에 이벤트를 보낼 때는 Idempotent Producer(enable.idempotence=true)와 Kafka Transaction API를 활용해, ‘메시지 전송 + 소비 오프셋 커밋’을 하나의 카프카 트랜잭션으로 처리합니다.
마지막으로, 소비 측에서 claimId를 키로 사용하는 idempotent 처리 로직을 적용하면, 네트워크 오류나 재시도 상황에서도 정확히 한 번만 downstream에 반영되는 구조를 완성할 수 있습니다.”

vector db

sevity — Sat, 14 Jun 2025 22:40:09 +0900

특성	pgvector	FAISS	Pinecone
설정 난이도	● 중간 – PostgreSQL 설치 및 CREATE EXTENSION vector 필요	● 낮음 – pip install faiss-cpu 로 즉시 사용 가능	● 낮음 – 라이브러리 설치 후 API 키 설정 필요
메타데이터 필터링	● 강력 – SQL WHERE·JOIN으로 사전 필터링 가능	● 제한적 – 검색 후 애플리케이션 레벨 후처리 필요	● 지원 – 쿼리 시 메타데이터 필터 인수로 사용 가능
비용	● 무료 오픈소스 – 인프라(서버) 비용 별도	● 무료 오픈소스	● 유료 매니지드 서비스 – 사용량 기반 과금
네트워크 의존도	● 로컬/사내 네트워크 – DB 서버 필요(실습시로컬도 가능)	● 오프라인 지원 – 완전 로컬 실행 가능	● 원격 호출 필수 – 네트워크 레이턴시 존재
운영·모니터링	● 기존 Postgres 툴 (PgAdmin, Datadog 등) 활용	● 별도 구축 필요 – 모니터링·백업 전략 직접 수립	● 관리형 대시보드·모니터링 제공
저장공간	● Postgres 테이블 내에 벡터∙메타데이터 저장 – DB 크기에 비례 – 백업/압축 툴 활용 가능	● 기본은 메모리 인덱스 – save_local() 시 로컬 파일(index.faiss) 생성 – 디스크 사용량 ≈ 4바이트×dim×N + 인덱스 오버헤드 – PQ 등 압축 옵션 가능	● 매니지드 스토리지 – 사용량 기반 과금에 스토리지 포함 – 자동 복제·압축 옵션 제공 – 백업·고가용성 내장

Pinecone

sevity — Fri, 13 Jun 2025 21:57:36 +0900

순서

먼저 https://app.pinecone.io/ 방문해서 api-key를 생성한다.

vs pgvector

pgvector
- 이미 PostgreSQL 기반 인프라가 있고, 자체 호스팅을 선호할 때
- SQL과 벡터를 한 곳에서 관리하며, 커스터마이징·확장성을 직접 책임지고 싶을 때
Pinecone
- “운영 부담 없이” 곧바로 대규모 서비스 전환이 필요할 때
- 메타데이터·하이브리드 검색·자동 스케일링 같은 고급 기능을 즉시 활용

실습

#!/usr/bin/env python3
"""
demo_pinecone.py ─ Pinecone 4.x + OpenAI 임베딩 실습
"""

import os, sys, time, logging
from dotenv import load_dotenv
import openai
from pinecone import Pinecone, ServerlessSpec      # ⬅️ 새 방식

# ──────── 로그 설정 ────────
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    datefmt="%H:%M:%S",
)
log = logging.getLogger(__name__)

# ──────── 환경 변수 읽기 ────────
load_dotenv()
try:
    OPENAI_API_KEY  = os.environ["OPENAI_API_KEY"]
    PINECONE_API_KEY = os.environ["PINECONE_API_KEY"]
    PINECONE_ENV     = os.environ["PINECONE_ENV"]    # ex) us-east-1-aws
except KeyError as e:
    log.error("환경변수 %s 가 없습니다 (.env 확인)", e.args[0]); sys.exit(1)

openai.api_key = OPENAI_API_KEY

# Pinecone 인스턴스 생성
pc = Pinecone(api_key=PINECONE_API_KEY)

# env 문자열을 region / cloud 로 분해 (us-east-1-aws → us-east-1 + aws)
*region, cloud = PINECONE_ENV.split("-")
REGION = "-".join(region)   # us-east-1
CLOUD  = cloud              # aws

INDEX  = "demo-index"
DIM    = 1536

# ──────── 인덱스 생성 / 재사용 ────────
def wait_ready(name):
    while True:
        state = pc.describe_index(name).status.state
        if state == "Ready":
            return
        log.info("   ↳ index status = %s … 대기 중", state)
        time.sleep(2)

if INDEX not in pc.list_indexes().names():
    log.info("새 인덱스 생성: %s", INDEX)
    pc.create_index(
        name=INDEX,
        dimension=DIM,
        metric="cosine",
        spec=ServerlessSpec(cloud=CLOUD, region=REGION),
    )
    wait_ready(INDEX)
else:
    log.info("기존 인덱스 재사용: %s", INDEX)

index = pc.Index(INDEX)

# ──────── 데이터 업서트 ────────
DOCS = [
    "쿠팡은 한국 최대의 전자상거래 기업이다.",
    "파인콘은 벡터 데이터베이스 서비스다.",
    "오픈AI는 GPT-4o 모델을 발표했다.",
    "서울의 여름은 덥고 습하다.",
    "벡터 검색은 의미 기반 유사도를 계산한다.",
]

def embed(texts):
    resp = openai.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [d.embedding for d in resp.data]

log.info("문서 %d개 임베딩 → Pinecone 업서트", len(DOCS))
vecs = embed(DOCS)
index.upsert(
    vectors=[(f"id-{i}", v, {"text": DOCS[i]}) for i, v in enumerate(vecs)]
)

# ──────── 질의 ────────
QUESTION = "유사도 검색을 위한 데이터베이스"
log.info("쿼리: “%s”", QUESTION)
q_vec = embed([QUESTION])[0]

res = index.query(vector=q_vec, top_k=3, include_metadata=True)
log.info("결과 (Top-3):")
for rnk, m in enumerate(res.matches, 1):
    log.info(" %d. %s (score=%.4f)", rnk, m.metadata["text"], m.score)

log.info("완료 ✅")

LangChain/LangGraph

sevity — Fri, 13 Jun 2025 21:51:34 +0900

LangChain 개요

LangChain은 단순한 “추론(inference) 엔진”을 넘어 LLM 애플리케이션을 짜는 데 필요한 거의 모든 구성 요소를 모아놓은 프레임워크입니다.

추론 파이프라인을 단계별로 나눠(입력→검색→결합→생성→후처리) 관리하기 쉽게 해 줍니다.
벡터 DB 통합도 플러그인처럼 끼워 쓰는 수준으로 제공해, FAISS·Pinecone·Weaviate·pgvector 등과 바로 연결할 수 있습니다.

사용자 규모 (GitHub Stars 기준)

LangChain: 109,000+ stars github.com
vLLM: 49,500+ stars github.com
SGLang: 15,100+ stars github.com
TensorRT-LLM: 10,700+ stars github.com

vLLM과의 차이점

vLLM이 “고성능 텍스트 생성”에 집중한 반면, LangChain은 그 앞단·옆단을 모두 지원해 줍니다.

벡터 DB(RAG)·도구 호출·에이전트 지원

vLLM은 "성성만" 잘함

langChain은 오히려 자체 추론엔진 없음(백엔드에 vLLM·OpenAI·LLama·TensorRT 등 연결)

Transformer + FastAPI와의 차이점

Transformer+FastAPI:
- 모델 불러오고, POST /generate 엔드포인트 만들어서, 분절된 코드를 직접 연결해야 함.
- 검색(RAG)·메모리·툴 호출 같은 부가 기능은 모두 “맨땅에 헤딩”으로 처음부터 구현.
LangChain:
- PromptTemplate, Retriever, Chain, Agent 클래스로 “블록 쌓듯” 조합만 하면 끝.
- 코드량 절감과 유지보수성이 월등히 높아집니다.

주요장점

Prompt 템플릿 관리
- 변수 바인딩, 다국어, 조건부 로직 처리까지 내장
체인(Chain) 단위 워크플로우
- 검색(Retrieval) → 요약(Summarization) → 생성(Generation) 과정을 모듈화
벡터 DB 통합
- FAISS·Pinecone·Weaviate·pgvector 등과 커넥터 제공
- 유사도 검색 결과를 자동으로 프롬프트에 결합
에이전트(Agent) 프레임워크
- 외부 API 호출, 계산 툴, 웹 스크래핑까지 “도구(tool)”로 래핑
- 모델이 상황에 따라 적절한 도구를 호출하도록 제어
메모리·대화 관리
- 대화형 챗봇에 필요한 세션 관리, 요약, 장기 메모리 등 지원
로깅·디버깅·모니터링
- 실행 트레이스, 토큰 사용량, 체인 단계별 출력 로그
플러그인 에코시스템
- 커스텀 컴포넌트, UI 통합, 클라우드 배포 옵션 등 풍부

LangChain이 없으면 불편한점

반복 코드: prompt 작성·변경할 때마다 엔드투엔드 코드 전부 수정
유사도 검색: 벡터 DB 연결·검색→프롬프트 결합 로직 직접 구현
도구 호출 관리: OpenAI 함수 호출, 외부 API 체계적인 에러 핸들링 모두 수작업
메모리 관리: 대화 컨텍스트 쌓기·요약·회수 로직 직접 구현
디버깅 어려움: 어느 단계에서 뭘 잘못했는지 추적하기 어려움

→ 결과적으로 개발 속도 저하, 유지보수 부담 증가, 기능 확장 난이도 상승이라는 비용을 치러야 합니다.

LangGraph

langChain이 일종의 직선적인 체인구조라면 LangGraph는 Airflow처럼 Dag으로 분기/관리해줄 수 있게 해줌

langChain회사에서 2023년말 2024년초에 발표

TensorRT-LLM

sevity — Fri, 13 Jun 2025 21:46:21 +0900

특징

TensorRT-LLM은 NVIDIA가 공식으로 오픈소스화한 프로젝트입니다.

오직 NVIDIA GPU + TensorRT 런타임 환경에서만 동작합니다.

장점

최고 수준의 추론 성능
- 낮은 지연(latency)·높은 처리량(throughput)
퀀타이제이션·메모리 최적화
- FP16, INT8 변환으로 VRAM 사용량 절감
상용 GPU 활용 극대화
- NVIDIA 드라이버·TensorRT 직접 제어

단점

vLLM은 pip install vllm만으로 시작할 수 있고, GPU가 없어도 CPU 모드로 바로 돌려볼 수 있습니다.
TensorRT-LLM은 CUDA, TensorRT SDK 버전 호환성, 빌드·변환 스크립트 디버깅 등을 거쳐야 합니다.
- 모델변환도 한번 해줘야함
vLLM은 동적 배칭(dynamic batching), 토크나이저 변경, 파이프라인 훅(hook) 삽입 등 개발 중에 코드 수정만으로 바로 반영됩니다.
TensorRT-LLM은 변환된 엔진(.plan)이 고정 그래프(graph) 형태라, 모델 구조나 토크나이저를 바꾸면 다시 변환해야 합니다.
TensorRT-LLM 전용
- 오직 NVIDIA GPU + TensorRT 런타임 환경에서만 동작합니다.
vLLM은 범용
- NVIDIA GPU는 물론, AMD GPU (ROCm), 심지어 CPU만 있어도 구동 가능합니다.
- 다양한 환경에서 “동작 여부 확인” → “간단 성능 테스트” → “프로덕션 전환” 워크플로우를 지원합니다.

따라서

vLLM으로 빠르게 기능 개발하고,
안정화되면 TensorRT-LLM으로 전환해 최종 성능을 극대화

실습해본 경험

TensorRT-LLM설치

설치하는것 자체가 c++ compiler, NVCC, MPI등 여러 의존성설치 문제가 있었고 쉽지 않았다.

설치후에는 라마7b모델 받아서 모델변환하고 엔진빌드하고 서버띄운다음에 테스트하면 됐다.

모델변환은 아마 허깅페이스의 저장포맷(체크포인트)을 TensorRT용으로 바꾸는거고

엔진빌드는 커널단위로 컴파일하는걸 포함해서 빌드하는걸 말하는듯하다.

라마7b모델받기

이거 받을때도 허깅페이스에서 권한요청해서 메일로 승인받고서야 git clone으로 받을수 있었다. 승인은 1시간내로 금방 되긴함

mkdir -p ~/models && cd ~/models
git lfs install
git clone https://huggingface.co/meta-llama/Llama-2-7b-hf

모델변환

cd ~/workspace/TensorRT-LLM/examples/models/core/llama

python3 convert_checkpoint.py \
  --model_dir ~/models/Llama-2-7b-hf \
  --output_dir ~/workspace/TensorRT-LLM/trt_llama2_7b_ckpt_int8 \
  --dtype float16 \
  --use_weight_only \
  --weight_only_precision int8 \
  --per_channel \
  --calib_dataset wikitext \
  --calib_size 100

내 그래픽카드가 8GB짜리라서 int8로 추가로 줄이는 작업이 들어갔다.

엔진빌드

trtllm-build \
  --checkpoint_dir trt_llama2_7b_ckpt_int8 \
  --gemm_plugin auto \
  --output_dir trt_llama2_7b_engine_int8_small \
  --max_seq_len 2048 \
  --max_batch_size 1 \
  --paged_state enable

추론서버 띄우기

trtllm-serve serve trt_llama2_7b_engine_int8_small \
  --tokenizer ~/models/Llama-2-7b-hf \
  --host 0.0.0.0 \
  --port 8002 \
  --max_batch_size 1 \
  --max_seq_len 1024

테스트

curl http://localhost:8002/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "trt_llama2_7b_engine_int8_small",
    "prompt": "안녕, 너 이름이 뭐야?",
    "max_tokens": 128
  }'

SGLang

sevity — Fri, 13 Jun 2025 16:23:54 +0900

개요

sglang은 왜써요?

- vLLM은 기본적으로 local Hugging face모델을 위한 인퍼런스 엔진

- SGLang은 --providoer openai같은 옵션 한줄로 바로 OpenAI API엔드포인트를 띄울 수 있음

-- 로컬모델/OpenAI등을 동시에 서빙하거나 조건부로 라우팅하는것도 CLI/설정만으로 처리가능

실습

도커로 추론엔진 실행

docker run --gpus all \
  -p 8001:8001 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --ipc=host \
  lmsysorg/sglang:latest \
  python3 -m sglang.launch_server \
    --model-path gpt2 \
    --host 0.0.0.0 \
    --port 8001 \
    --device cuda

동작테스트

curl -X POST http://localhost:8001/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"테스트 중입니다:","max_new_tokens":20}'

결과

sevity@DESKTOP-7500F:~$ curl -X POST http://localhost:8001/generate \
  -H "Content-Type: application/json" \
  -d '{"text":"테스트 중입니다:","sampling_params":{"max_new_tokens":20}}'
  
{"text":"더 고 중입니다. �","meta_info":{"id":"e01db0f5a42f48d99e02e9d2bcf29216","finish_reason":{"type":"length","length":20},"prompt_tokens":20,"completion_tokens":20,"cached_tokens":0,"e2e_latency":0.3301219940185547}}
sevity@DESKTOP-7500F:~$

트랜스포머

sevity — Thu, 12 Jun 2025 22:52:43 +0900

트랜스포머 레이어 =

Multi-Head Attention (특수 레이어)
Residual + Layer Norm
Feed-Forward (일반 Dense Layer)
Residual + Layer Norm

vLLM

sevity — Thu, 12 Jun 2025 22:15:45 +0900

서론

요청량이 많지 않고, 단순히 “모델 하나 띄워서 한두 개의 요청만 처리”한다면 transformers + FastAPI(또는 Flask) 정도면 충분

여기서 “모델 띄워주는 역할”은 Hugging Face의 transformers 라이브러리가 담당

예시

# main.py
from fastapi import FastAPI
from transformers import pipeline

app = FastAPI()

# 1) transformers 파이프라인으로 모델 로드
generator = pipeline(
    "text-generation",
    model="gpt2",            # 원하는 모델 지정
    device=0                  # GPU가 있다면 0, CPU만 있으면 -1
)

@app.post("/generate")
async def generate(payload: dict):
    prompt = payload["prompt"]
    # 2) transformers로 텍스트 생성
    outputs = generator(prompt, max_new_tokens=50)
    return {"choices": outputs}

또는 OpenAI 등 외부 API 사용 시:

자체 GPU 없이 “OpenAI API”나 “Anthropic API”처럼 원격으로 모델을 호출한다면 vLLM은 필요 없다.

vLLM

vLLM이 빛을 발하는 순간:
1. 자체 GPU를 보유하고 있고,
2. 높은 동시 처리량(수십·수백 TPS)과
3. 낮은 지연(Latency)이 요구될 때
4. 동적 배칭, 요청 스케줄링, 스트리밍 같은 최적화 로직을
  직접 구현하지 않고 바로 활용하고 싶을 때

이런 조건이 모두 맞아떨어질 때 vLLM이 “생산(Production)급”으로 가치를 발휘합니다.