Apppublic

groothaha/tokensaver-api

sourceHugging Faceupdated 6mo agoView on Hugging Face

0likes

App README

TokenSaver

LLM API 비용을 자동으로 절감하는 프록시 서버. 시맨틱 캐싱, 프롬프트 압축, 스마트 라우팅을 통해 OpenAI, Anthropic, Google Gemini API 호출 비용을 줄여줍니다.

기존 코드 한 줄 수정 없이 API Base URL만 변경하면 즉시 적용됩니다.

핵심 기능

시맨틱 캐싱

동일하거나 유사한 요청을 자동으로 캐싱합니다. Redis로 정확 매칭, Qdrant 벡터 DB로 의미 기반 유사도 검색을 수행하는 2계층 구조입니다.

—정확히 같은 프롬프트 -> Redis 해시 매칭 (즉시 응답)
—의미적으로 비슷한 프롬프트 -> Qdrant 벡터 검색 (유사도 임계값 설정 가능)
—TTL, 유사도 임계값 등 사용자별 설정 가능

프롬프트 압축

불필요한 토큰을 제거하여 입력 비용을 줄입니다.

레벨	설명
`none`	압축 없음
`minimal`	공백 정리
`moderate`	공백 정리 + 중복 메시지 제거
`aggressive`	위 전부 + 시스템 프롬프트 요약

스마트 라우팅

요청의 복잡도를 분석하여 비용 대비 효율이 좋은 모델로 자동 라우팅합니다.

복잡도	라우팅 대상
SIMPLE (0.0-0.3)	gpt-4o-mini, claude-haiku-4, gemini-2.0-flash
MODERATE (0.3-0.7)	gpt-4o, claude-sonnet-4, gemini-2.5-flash
COMPLEX (0.7-1.0)	원래 요청한 모델 유지

지원 모델

Provider	모델	Input / Output (per 1M tokens)
OpenAI	gpt-4o	$2.50 / $10.00
OpenAI	gpt-4o-mini	$0.15 / $0.60
Anthropic	claude-opus-4	$15.00 / $75.00
Anthropic	claude-sonnet-4	$3.00 / $15.00
Anthropic	claude-haiku-4	$0.80 / $4.00
Google	gemini-2.5-pro	$1.25 / $10.00
Google	gemini-2.5-flash	$0.15 / $3.50
Google	gemini-2.0-flash	$0.10 / $0.40

빠른 시작

1. 서버 실행

bash

git clone https://github.com/groothaha/tokensaver.git
cd tokensaver
cp .env.example .env
# .env 파일에서 DATABASE_URL, REDIS_URL, JWT_SECRET, ENCRYPTION_KEY 설정

docker-compose up

서버가 http://localhost:8000 에서 시작됩니다.

2. 계정 생성 및 API 키 발급

bash

# 회원가입
curl -X POST http://localhost:8000/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

# 로그인 (access_token 획득)
curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

# API 키 생성
curl -X POST http://localhost:8000/v1/api-keys \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key"}'

3. LLM API 키 등록

사용하려는 LLM 프로바이더의 API 키를 등록합니다.

bash

# OpenAI 키 등록
curl -X POST http://localhost:8000/v1/auth/llm-credentials \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "api_key": "sk-..."}'

# Anthropic 키 등록
curl -X POST http://localhost:8000/v1/auth/llm-credentials \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-..."}'

# Google 키 등록
curl -X POST http://localhost:8000/v1/auth/llm-credentials \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"provider": "google", "api_key": "AIza..."}'

4. API 호출

기존 LLM SDK에서 Base URL만 변경하면 됩니다.

bash

# OpenAI 호환 엔드포인트
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer ts-{api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

CLI 도구 연동

자동 설정 스크립트

bash

# 모든 CLI 도구 한번에 설정 (Claude Code + OpenAI + Gemini)
python scripts/setup_claude_code.py \
  --api-key ts-{your_api_key} \
  --server-url http://localhost:8000

# 특정 도구만 설정
python scripts/setup_claude_code.py --api-key ts-xxx --tools claude
python scripts/setup_claude_code.py --api-key ts-xxx --tools openai
python scripts/setup_claude_code.py --api-key ts-xxx --tools gemini

# 설정 되돌리기
python scripts/setup_claude_code.py --revert

Claude Code

~/.claude/settings.json 에 아래 내용이 추가됩니다:

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8000",
    "ANTHROPIC_API_KEY": "ts-{your_api_key}"
  }
}

OpenAI CLI / ChatGPT

셸 환경변수가 설정됩니다:

bash

export OPENAI_BASE_URL="http://localhost:8000/v1"
export OPENAI_API_KEY="ts-{your_api_key}"

Gemini CLI

bash

export GEMINI_API_KEY="ts-{your_api_key}"
export GOOGLE_GENAI_BASE_URL="http://localhost:8000"

SDK 사용법

Python SDK

bash

pip install tokensaver

python

from tokensaver import Client

client = Client(
    api_key="ts-...",
    base_url="http://localhost:8000/v1",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    cache_enabled=True,
    compression_level="moderate",
    routing_enabled=True,
)

print(response.choices[0].message.content)

비동기 클라이언트:

python

from tokensaver import AsyncClient

async with AsyncClient(api_key="ts-...", base_url="http://localhost:8000/v1") as client:
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )

API 엔드포인트

인증

Method	Endpoint	설명
POST	`/v1/auth/signup`	회원가입
POST	`/v1/auth/login`	로그인
POST	`/v1/auth/refresh`	토큰 갱신
POST	`/v1/auth/logout`	로그아웃
GET	`/v1/auth/me`	내 정보
POST	`/v1/auth/change-password`	비밀번호 변경
POST	`/v1/auth/forgot-password`	비밀번호 찾기
POST	`/v1/auth/reset-password`	비밀번호 재설정
POST	`/v1/auth/llm-credentials`	LLM API 키 등록

API 키 관리

Method	Endpoint	설명
POST	`/v1/api-keys`	API 키 생성
GET	`/v1/api-keys`	API 키 목록
DELETE	`/v1/api-keys/{key_id}`	API 키 삭제

LLM 프록시

Method	Endpoint	용도
POST	`/v1/chat/completions`	OpenAI 호환 (스트리밍 지원)
POST	`/v1/messages`	Anthropic Messages API (스트리밍 지원)
POST	`/v1beta/models/{model}:generateContent`	Gemini API
POST	`/v1beta/models/{model}:streamGenerateContent`	Gemini 스트리밍

채팅

Method	Endpoint	설명
POST	`/v1/chat`	웹 채팅 (JWT 인증)
GET	`/v1/chat/models`	사용 가능한 모델 목록

채팅 히스토리

Method	Endpoint	설명
POST	`/v1/chat/history`	세션 생성
GET	`/v1/chat/history`	세션 목록
GET	`/v1/chat/history/{id}/messages`	메시지 조회
POST	`/v1/chat/history/{id}/messages`	메시지 저장
PATCH	`/v1/chat/history/{id}`	세션 이름 변경
DELETE	`/v1/chat/history/{id}`	세션 삭제

분석/설정

Method	Endpoint	설명
GET	`/v1/analytics`	사용량 통계 (기간 설정 가능)
GET	`/v1/cache/stats`	캐시 적중률, 항목 수
DELETE	`/v1/cache`	캐시 초기화
GET	`/v1/settings`	최적화 설정 조회
PATCH	`/v1/settings`	최적화 설정 변경
GET	`/v1/billing`	요금/사용량 조회

헬스체크

GET /health → {"status": "ok"}

최적화 설정

사용자별로 최적화 기능을 세부 조정할 수 있습니다.

bash

curl -X PATCH http://localhost:8000/v1/settings \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_enabled": true,
    "cache_threshold": 0.92,
    "cache_ttl_seconds": 3600,
    "compression_enabled": true,
    "compression_level": "moderate",
    "routing_enabled": true
  }'

설정	기본값	설명
`cache_enabled`	`true`	시맨틱 캐싱 사용 여부
`cache_threshold`	`0.92`	벡터 유사도 임계값 (0.0~1.0)
`cache_ttl_seconds`	`3600`	캐시 유효 시간 (초)
`compression_enabled`	`true`	프롬프트 압축 사용 여부
`compression_level`	`moderate`	압축 수준 (none/minimal/moderate/aggressive)
`routing_enabled`	`true`	스마트 라우팅 사용 여부
`translation_enabled`	`true`	다국어 최적화 사용 여부
`translation_min_tokens`	`50`	번역 최적화 최소 토큰 수

요청 처리 흐름

클라이언트 요청
    │
    ├─ 1. 인증 (API Key 또는 JWT)
    │
    ├─ 2. 캐시 조회
    │     ├─ Redis 정확 매칭 → 캐시 히트 시 즉시 반환
    │     └─ Qdrant 유사도 검색 → 임계값 초과 시 반환
    │
    ├─ 3. 프롬프트 압축
    │     └─ 설정된 레벨에 따라 토큰 수 절감
    │
    ├─ 4. 스마트 라우팅
    │     └─ 복잡도 분석 후 최적 모델 선택
    │
    ├─ 5. LLM API 호출
    │     └─ 실제 프로바이더에 요청 전달
    │
    ├─ 6. 응답 캐싱
    │     └─ Redis + Qdrant에 저장
    │
    └─ 7. 사용량 기록 및 응답 반환

배포

Docker Compose (로컬 개발)

bash

cp .env.example .env
# .env 수정 후
docker-compose up

PostgreSQL, Redis, Qdrant, 백엔드 API, 백그라운드 워커가 함께 실행됩니다.

Railway

Railway에 연결하면 Git push 시 자동 배포됩니다. railway.json 설정이 포함되어 있으며 헬스체크(/health)와 자동 DB 마이그레이션이 구성되어 있습니다.

필요한 환경변수를 Railway 대시보드에서 설정하세요.

수동 Docker 빌드

bash

docker build -t tokensaver .
docker run -p 8000:8000 --env-file .env tokensaver

컨테이너 시작 시 Alembic 마이그레이션이 자동 실행된 후 Uvicorn 서버가 시작됩니다.

환경변수

bash

# 앱
APP_NAME=TokenSaver
DEBUG=false
BASE_URL=https://yourdomain.com

# 데이터베이스
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/tokensaver

# Redis
REDIS_URL=redis://localhost:6379/0

# Qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=                         # Qdrant Cloud 사용 시
QDRANT_COLLECTION=tokensaver_cache

# 보안 (프로덕션에서 반드시 변경)
JWT_SECRET=<64자 랜덤 문자열>
JWT_EXPIRE_MINUTES=1440
ENCRYPTION_KEY=<32자 랜덤 문자열>

# CORS
CORS_ORIGINS=https://yourdomain.com

# Rate Limiting
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_BURST=20

# 이메일 (smtp / resend / console 중 택1)
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=SG.xxx
EMAIL_FROM=noreply@yourdomain.com

# 결제 - Lemon Squeezy
LEMONSQUEEZY_API_KEY=
LEMONSQUEEZY_STORE_ID=
LEMONSQUEEZY_WEBHOOK_SECRET=

기술 스택

분류	기술
Backend	Python 3.11+, FastAPI, SQLAlchemy, Alembic
Database	PostgreSQL 16, Redis 7, Qdrant
Frontend	Next.js 15, React 19, Tailwind CSS 4
Auth	JWT (access + refresh), API Key (HMAC)
Background	ARQ (Redis 기반 작업 큐)
Billing	Lemon Squeezy
Embedding	all-MiniLM-L6-v2 (384차원)
Deployment	Docker, Railway

라이선스

MIT