제미나이 무료 API, 응답 캐시, 요청 큐, 프로젝트 분리 | 사이드 앱을 무료로 버티는 실습은?

앱별 환경 변수 분리 (.env 예시, 깃 제외)
# .env.demo  | 데모 앱 전용 프로젝트 키
GEMINI_API_KEY=demo_project_key_here
GEMINI_MODEL=gemini-2.5-flash
SOFT_RPM=8
SOFT_RPD=800
APP_NAME=demo

# .env.bot  | 봇/워커 전용 프로젝트 키 (별도 프로젝트)
# GEMINI_API_KEY=bot_project_key_here
# SOFT_RPM=10
# SOFT_RPD=1200
# APP_NAME=bot

# 셸에서 앱 하나 로드 (zsh/bash)
set -a; source .env.demo; set +a
echo "app=$APP_NAME key_len=${#GEMINI_API_KEY}"

# 저장소에 키 문자열이 남았는지 확인 (출력되면 즉시 폐기·재발급)
git grep -nE 'AIza[0-9A-Za-z_-]{20,}' || echo "no key string in repo (good)"

패키지 설치 + 스모크 호출
mkdir gemini-cache-lab && cd gemini-cache-lab
npm init -y
npm install @google/genai dotenv
# package.json 에 "type": "module" 권장

# smoke.mjs
import 'dotenv/config'
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY })
const model = process.env.GEMINI_MODEL || 'gemini-2.5-flash'

const res = await ai.models.generateContent({
  model,
  contents: '한 줄로 인사만. 무료 티어 스모크.',
  config: { maxOutputTokens: 64, temperature: 0.2 },
})
console.log({
  model,
  text: (res.text || '').slice(0, 120),
  usage: res.usageMetadata || null,
})

limits.snapshot.md 템플릿 (배포 전 채우기)
# limits.snapshot.md  | git 에 숫자만, 키는 넣지 말 것
# 캡처 시각(KST): 2026-08-09
# 출처: https://aistudio.google.com/rate-limit

project_id: your-gcp-project-id
tier: Free
model: gemini-2.5-flash

# 화면 숫자로 덮어쓰기 (아래는 자리표시)
RPM:  ___
TPM:  ___
RPD:  ___

# 소프트 캡 = 실한도 * 0.75 근처
SOFT_RPM: ___
SOFT_RPD: ___

# 리셋 참고: RPD 는 태평양 시간 자정 (공식 Rate limits 문서)

response-cache.mjs | TTL 캐시 + 호출 래퍼
import crypto from 'node:crypto'
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY })
const model = process.env.GEMINI_MODEL || 'gemini-2.5-flash'
const TTL_MS = Number(process.env.CACHE_TTL_MS || 15 * 60 * 1000)

// 단일 인스턴스 전제. 서버리스면 Redis/Upstash 로 교체
const store = new Map()

function cacheKey(prompt, opts = {}) {
  const raw = JSON.stringify({
    model,
    prompt: String(prompt).trim(),
    temperature: opts.temperature ?? 0.2,
    maxOutputTokens: opts.maxOutputTokens ?? 256,
  })
  return crypto.createHash('sha256').update(raw).digest('hex')
}

export async function generateCached(prompt, opts = {}) {
  const key = cacheKey(prompt, opts)
  const now = Date.now()
  const hit = store.get(key)
  if (hit && hit.expireAt > now) {
    return { text: hit.text, usage: hit.usage, cache: 'hit', key }
  }

  const res = await ai.models.generateContent({
    model,
    contents: prompt,
    config: {
      temperature: opts.temperature ?? 0.2,
      maxOutputTokens: opts.maxOutputTokens ?? 256,
    },
  })
  const text = res.text || ''
  const usage = res.usageMetadata || null
  store.set(key, { text, usage, expireAt: now + TTL_MS })
  return { text, usage, cache: 'miss', key }
}

// CLI: node response-cache.mjs
if (import.meta.url === `file://${process.argv[1]}`) {
  const q = process.argv[2] || '무료 티어 한도를 한 문장으로.'
  console.log(await generateCached(q))
  console.log(await generateCached(q)) // 2회차는 cache:hit 이어야 함
}

rpm-queue.mjs | 분당 상한 큐
const softRpm = Number(process.env.SOFT_RPM || 8)

let windowStart = Date.now()
let windowCount = 0
const waiters = []

function sleep(ms) {
  return new Promise((r) => setTimeout(r, ms))
}

async function acquireSlot() {
  for (;;) {
    const now = Date.now()
    if (now - windowStart >= 60_000) {
      windowStart = now
      windowCount = 0
    }
    if (windowCount < softRpm) {
      windowCount += 1
      return { rpmUsed: windowCount, softRpm }
    }
    const wait = 60_000 - (now - windowStart) + 50
    await sleep(Math.min(wait, 2000))
  }
}

export async function runWithRpmLimit(fn) {
  const slot = await acquireSlot()
  try {
    const result = await fn()
    return { result, slot }
  } catch (e) {
    // 업스트림 실패 시 슬롯을 돌려줄지 정책 선택.
    // 보수적으로는 반환하지 않아 재버스트를 막음.
    throw e
  }
}

// 사용 예
// const { result } = await runWithRpmLimit(() => generateCached(prompt))

server-route.mjs | 캐시 + 큐 합친 최소 핸들러
import 'dotenv/config'
import { generateCached } from './response-cache.mjs'
import { runWithRpmLimit } from './rpm-queue.mjs'

export async function handleAsk(userText) {
  const prompt = String(userText || '').trim().slice(0, 2000)
  if (!prompt) {
    const err = new Error('empty_prompt')
    err.status = 400
    throw err
  }

  // 캐시 히트면 업스트림·RPM 슬롯을 거의 쓰지 않음
  // (generateCached 내부 miss 시에만 API 호출)
  const { result, slot } = await runWithRpmLimit(() => generateCached(prompt))
  return {
    text: result.text,
    cache: result.cache,
    usage: result.usage,
    slot,
  }
}

// CLI 부하 흉내: 같은 질문 5번
if (import.meta.url === `file://${process.argv[1]}`) {
  const q = '사이드 프로젝트 무료 한도를 두 문장으로.'
  for (let i = 0; i < 5; i++) {
    const out = await handleAsk(q)
    console.log(i + 1, out.cache, out.slot)
  }
}

usage-log.mjs | CSV 한 줄 append
import fs from 'node:fs'
import path from 'node:path'

const LOG = process.env.USAGE_LOG || path.join(process.cwd(), 'usage.csv')

function nowKst() {
  return new Date().toLocaleString('sv-SE', { timeZone: 'Asia/Seoul' }).replace(' ', 'T')
}

export function appendUsage(row) {
  const header = 'ts_kst,app,cache,upstream,in_tok,out_tok,status\n'
  if (!fs.existsSync(LOG)) fs.writeFileSync(LOG, header, 'utf8')
  const line = [
    nowKst(),
    row.app || process.env.APP_NAME || 'app',
    row.cache || 'n/a',
    row.upstream ? 1 : 0,
    row.inTok ?? '',
    row.outTok ?? '',
    row.status || 'ok',
  ].join(',')
  fs.appendFileSync(LOG, line + '\n', 'utf8')
}

// handleAsk 성공/실패 후:
// appendUsage({
//   cache: out.cache,
//   upstream: out.cache === 'miss',
//   inTok: out.usage?.promptTokenCount,
//   outTok: out.usage?.candidatesTokenCount,
//   status: 'ok',
// })

day-report.mjs | 오늘 소진·히트율 요약
import fs from 'node:fs'

const LOG = process.env.USAGE_LOG || './usage.csv'
const softRpd = Number(process.env.SOFT_RPD || 800)
const today = new Date().toLocaleString('sv-SE', { timeZone: 'Asia/Seoul' }).slice(0, 10)

const lines = fs.existsSync(LOG) ? fs.readFileSync(LOG, 'utf8').trim().split('\n').slice(1) : []
let upstream = 0
let hits = 0
let total = 0
for (const line of lines) {
  // ts_kst 가 YYYY-MM-DD 로 시작
  if (!line.startsWith(today)) continue
  total += 1
  const cols = line.split(',')
  if (cols[2] === 'hit') hits += 1
  if (cols[3] === '1') upstream += 1
}

const hitRate = total ? ((hits / total) * 100).toFixed(1) : '0.0'
const rpdUsedPct = softRpd ? ((upstream / softRpd) * 100).toFixed(1) : 'n/a'
console.log({
  today,
  total_requests: total,
  upstream_calls: upstream,
  cache_hit_rate_pct: hitRate,
  soft_rpd: softRpd,
  soft_rpd_used_pct: rpdUsedPct,
  action:
    Number(rpdUsedPct) >= 80
      ? 'soft_rpd 80%+ → 캐시 TTL 연장·기능 제한·청구 검토'
      : '여유 있음 → 관측 유지',
})

cost-estimate.mjs | 연습용 원화·부가세 계산
// 단가·환율은 배포 전 공식 Pricing·시장 환율로 덮어쓰기
const USD_KRW = Number(process.env.USD_KRW || 1380) // 연습 환율
const VAT = 0.10

// 연습용 Flash 급 단가 (USD / 1M tokens) | 공식 표로 교체
const priceInPerM = Number(process.env.PRICE_IN_PER_M || 0.1)
const priceOutPerM = Number(process.env.PRICE_OUT_PER_M || 0.4)

const dailyUpstream = Number(process.env.DAILY_UPSTREAM || 500)
const avgInTok = Number(process.env.AVG_IN_TOK || 800)
const avgOutTok = Number(process.env.AVG_OUT_TOK || 300)
const days = Number(process.env.DAYS || 30)

const inTok = dailyUpstream * avgInTok * days
const outTok = dailyUpstream * avgOutTok * days
const usd =
  (inTok / 1_000_000) * priceInPerM + (outTok / 1_000_000) * priceOutPerM
const krw = usd * USD_KRW
const krwVat = krw * (1 + VAT)

console.log({
  dailyUpstream,
  month_in_tokens: inTok,
  month_out_tokens: outTok,
  usd: Number(usd.toFixed(4)),
  krw_ex_vat: Math.round(krw),
  krw_incl_vat_10pct: Math.round(krwVat),
  note: '무료 티어면 usd=0. 청구 연동 후에만 의미 있음. 공식 단가로 교체할 것.',
})