프로덕션 아키텍처와 배포 운영

데모는 모델 호출 하나로 끝나지만, 제품은 교통관제다

AI Studio에서 프롬프트를 실행하고, SDK로 generateContent를 한 번 호출하는 순간은 짜릿하다. 몇 줄의 코드로 요약, 분류, 검색 보강, 도구 호출이 움직인다. 그래서 많은 팀이 "이제 서비스에 붙이기만 하면 되겠다"고 생각한다. 하지만 실제 트래픽이 들어오는 순간 문제는 모델의 지능보다 훨씬 평범한 곳에서 터진다. 요청이 몰리고, 재시도가 겹치고, 긴 문서가 한꺼번에 들어오고, 사용자가 새로고침을 누르고, 백엔드가 같은 요청을 두 번 처리한다. 이때 준비되지 않은 Gemini 애플리케이션은 똑똑한 답변을 하기도 전에 스스로 병목이 된다.

프로덕션 시스템에서 가장 먼저 설계해야 할 대상은 "어떤 모델을 쓸 것인가"가 아니라 "모델 호출을 어디에 격리할 것인가"다. 모델 호출은 네트워크 I/O이고, 비용이 발생하는 외부 의존성이며, 지연시간의 분산이 크고, 할당량과 안전 필터의 영향을 받는다. 일반 데이터베이스 쿼리처럼 짧고 예측 가능한 작업으로 취급하면 곧 전체 웹 서비스가 모델의 응답 속도에 끌려간다.

따라서 이 장의 핵심 원칙은 단순하다. 사용자 요청을 받는 계층과 Gemini 추론을 수행하는 계층을 분리한다. 그 사이에 큐, 작업 상태, 타임아웃, 재시도 예산, 캐시, 관측성을 넣는다. 데모는 모델을 직접 부른다. 제품은 모델 호출을 통제한다.

Google의 공식 예제와 Cookbook은 Gemini API를 학습하고 작은 기능을 검증하는 데 좋은 출발점이다. Cookbook은 빠른 시작, 기능별 예제, 엔드투엔드 데모를 나누어 제공하며 Python, Node.js, Go, Java, C# 등 공식 SDK 경로를 안내한다.¹ Codelab 역시 AI Studio, SDK, 긴 컨텍스트, 도구, Live API, Cloud Run 배포 흐름을 한 번에 훑게 해 준다.² 그러나 운영 환경에서는 예제 코드 위에 "트래픽을 받아내는 구조"를 얹어야 한다. 이 장은 바로 그 얹는 법을 다룬다.

기준 아키텍처: Gateway, Orchestrator, Worker, Store

Gemini 기반 서비스를 운영할 때 가장 안전한 기본 구조는 네 개의 축으로 나누는 것이다. 첫째, 외부 요청을 받아 인증과 요청 검증을 처리하는 API Gateway가 있다. 둘째, 사용자의 의도를 해석하고 어떤 모델·도구·검색 경로를 쓸지 결정하는 Orchestrator가 있다. 셋째, 실제 Gemini API 호출을 담당하는 Inference Worker가 있다. 넷째, 세션 상태, 파일 메타데이터, RAG 검색 결과, 캐시를 관리하는 Context/Vector Store가 있다.

이 구조에서 Gateway는 "비싼 일을 하기 전에 싼 검사를 끝내는 곳"이다. 인증 토큰이 없거나, 요청 본문이 너무 크거나, 사용자가 허용된 분당 요청 수를 넘었다면 모델을 부르기 전에 거절해야 한다. Orchestrator는 "판단하는 곳"이다. 짧은 FAQ인지, RAG가 필요한 질문인지, 파일 분석인지, 도구 호출이 필요한 업무인지, 비동기 작업으로 넘겨야 하는지 결정한다. Worker는 "느리고 비싼 일을 하는 곳"이다. 이곳에서만 Gemini API 키나 Vertex AI 서비스 계정 권한을 사용하고, 재시도와 회로 차단기를 적용한다. Store는 "기억하는 곳"이다. 세션, 프롬프트 버전, 캐시 키, 검색 결과, 작업 상태, 비용 집계가 여기에 쌓인다.

초기 팀은 종종 하나의 FastAPI 또는 Express 서버 안에 라우터, 프롬프트 조립, Gemini 호출, 로그 저장, 응답 스트리밍을 모두 넣는다. 로컬에서는 잘 된다. 하지만 트래픽이 늘어나면 이 단일 서버는 세 가지 역할을 동시에 떠안는다. 사용자의 HTTP 연결을 붙잡고, 모델 응답을 기다리고, 다음 요청도 받아야 한다. 여기에 긴 컨텍스트나 멀티모달 파일 처리까지 붙으면 서버는 빠르게 포화된다. 구조를 나누는 이유는 멋진 마이크로서비스 그림을 그리기 위해서가 아니라, 장애의 전파 경로를 짧게 만들기 위해서다.

웹 요청 경로에서 모델 호출을 떼어내기

가장 먼저 피해야 할 패턴은 사용자의 웹 요청 안에서 Gemini 호출을 동기적으로 끝까지 기다리는 것이다. 물론 짧은 채팅 응답이나 스트리밍 UX에서는 웹 요청과 모델 호출이 어느 정도 연결될 수밖에 없다. 그러나 보고서 생성, 긴 PDF 분석, 동영상 요약, 대규모 RAG 질의, 복수 도구 호출처럼 시간이 길어질 수 있는 작업은 "요청 수락"과 "추론 실행"을 분리해야 한다.

사용자가 /jobs 엔드포인트에 요청을 보내면 서버는 입력을 검증하고 작업 ID를 반환한다. 실제 추론은 큐에 들어간 뒤 Worker가 처리한다. 프런트엔드는 /jobs/{job_id}를 폴링하거나 Server-Sent Events, WebSocket, 푸시 알림으로 상태를 받는다. 이렇게 하면 Gemini 호출이 느려져도 웹 서버의 요청 처리 스레드가 오래 묶이지 않는다.

# FastAPI 예시: 요청 수락 계층과 추론 계층 분리
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel
from uuid import uuid4
import time

app = FastAPI()

# 실제 운영에서는 Redis, Cloud Tasks, Pub/Sub, RabbitMQ, Kafka 등을 사용한다.
JOB_STORE = {}
JOB_QUEUE = []

class GenerateRequest(BaseModel):
    prompt: str
    model: str = "gemini-2.5-flash"
    priority: str = "normal"

@app.post("/jobs")
def create_job(req: GenerateRequest, idempotency_key: str | None = Header(default=None)):
    if len(req.prompt) > 20_000:
        raise HTTPException(status_code=413, detail="prompt too large")

    dedupe_key = idempotency_key or str(uuid4())
    if dedupe_key in JOB_STORE:
        return {"job_id": JOB_STORE[dedupe_key]["job_id"], "status": "accepted"}

    job_id = str(uuid4())
    JOB_STORE[dedupe_key] = {
        "job_id": job_id,
        "status": "queued",
        "created_at": time.time(),
        "request": req.model_dump(),
    }
    JOB_QUEUE.append((job_id, dedupe_key))
    return {"job_id": job_id, "status": "accepted"}

@app.get("/jobs/{job_id}")
def get_job(job_id: str):
    for item in JOB_STORE.values():
        if item["job_id"] == job_id:
            return item
    raise HTTPException(status_code=404, detail="job not found")

이 예제는 일부러 단순하게 썼다. 운영 환경에서는 인메모리 리스트 대신 Redis Streams, Cloud Tasks, Pub/Sub, RabbitMQ, Kafka 같은 큐를 사용한다. 중요한 것은 도구가 아니라 계약이다. 사용자의 요청은 "수락됨" 상태로 빠르게 끝나야 하고, 추론 작업은 별도의 실행 단위에서 타임아웃과 재시도 정책을 적용받아야 한다.

특히 idempotency_key는 실무에서 매우 중요하다. 사용자가 결제 버튼을 두 번 누르지 않도록 막는 것처럼, AI 생성 요청도 중복 실행을 막아야 한다. 브라우저 새로고침, 모바일 네트워크 재전송, 프록시 재시도, 배포 중 연결 끊김이 모두 같은 작업을 두 번 만들 수 있다. 긴 문서 요약 한 번이 수천 또는 수만 토큰을 소비한다면, 중복 실행은 곧 비용 사고다.

실시간 채팅처럼 즉시 응답이 필요한 경우에는 완전한 비동기 작업보다 스트리밍이 적합하다. 스트리밍은 전체 답변이 완성되기 전에 토큰을 조금씩 보내므로 사용자의 체감 지연시간을 낮춘다. 다만 스트리밍도 무제한 연결을 허용하면 안 된다. 연결당 최대 지속 시간, 사용자당 동시 스트림 수, 중간 취소 처리, 부분 응답 저장 여부를 정해야 한다. 제품 관점에서 스트리밍은 "빠른 응답" 기술이면서 동시에 "길어진 작업을 안전하게 끊는" 기술이다.

429와 5xx는 예외가 아니라 평상시 시나리오다

Gemini 기반 서비스는 외부 API에 의존한다. 외부 API에 의존한다는 말은 429, 500, 503, 504가 언젠가는 반드시 발생한다는 뜻이다. 429는 할당량이나 속도 제한에 걸렸다는 신호이고, 5xx는 서버 측 오류나 일시적 장애일 수 있으며, 504는 게이트웨이나 업스트림 대기 시간이 길어졌다는 뜻일 수 있다. 운영 설계에서는 이것을 "드문 예외"가 아니라 "정상적으로 처리해야 하는 상태"로 봐야 한다.

가장 앞단에는 요청 제어가 필요하다. 토큰 버킷은 일정 속도로 토큰이 채워지고 요청마다 토큰을 하나씩 소비하는 방식이다. 짧은 버스트를 어느 정도 허용하면서 평균 요청량을 제한할 수 있다. 리키 버킷은 물이 새듯 일정한 속도로 요청을 흘려보내 갑작스러운 폭주를 평탄화한다. 사용자별 제한, 조직별 제한, API 키별 제한, 모델별 제한을 분리하면 한 고객의 폭주가 전체 서비스를 잠식하는 일을 줄일 수 있다.

재시도는 더 조심해야 한다. 재시도는 장애를 치유하기도 하지만, 잘못 설계하면 장애를 증폭한다. 모든 서버가 1초 뒤 동시에 재시도하면 작은 장애가 거대한 파도로 변한다. 그래서 exponential backoff with jitter를 사용한다. 실패할수록 대기 시간을 늘리되, 무작위 흔들림을 넣어 재시도 시점을 분산한다.

# 재시도 예산과 jitter가 있는 단순 예시
import asyncio, random, time

class RetryBudget:
    def __init__(self, max_attempts: int, deadline_seconds: float):
        self.max_attempts = max_attempts
        self.deadline = time.monotonic() + deadline_seconds

    def can_retry(self, attempt: int) -> bool:
        return attempt < self.max_attempts and time.monotonic() < self.deadline

async def call_with_backoff(fn, budget: RetryBudget):
    attempt = 0
    while True:
        try:
            return await fn()
        except Exception as e:
            attempt += 1
            if not budget.can_retry(attempt):
                raise
            base = min(2 ** attempt, 8)
            sleep = base * 0.2 + random.uniform(0, 0.3)
            await asyncio.sleep(sleep)

여기에 retry budget을 둔다. 예를 들어 한 요청은 최대 세 번까지만 시도하고, 전체 마감 시간은 12초를 넘기지 않는 식이다. 재시도 예산은 모델별, 기능별, 리전별로 다르게 줄 수 있다. 짧은 자동완성 기능은 한 번 실패하면 바로 폴백하는 편이 낫고, 야간 배치 보고서는 몇 분 뒤 재시도해도 된다.

회로 차단기(circuit breaker)는 일정 기간 실패율이 높을 때 아예 호출을 멈추는 장치다. 전기가 과부하될 때 차단기가 내려가듯, 모델 호출 실패가 연속되면 더 이상 같은 경로로 요청을 보내지 않는다. 대신 캐시된 답변, 더 가벼운 모델, "현재 분석이 지연되고 있습니다"라는 상태 응답, 검색 결과만 제공하는 축약 모드로 graceful degradation을 수행한다. 중요한 것은 폴백도 제품 경험의 일부로 설계해야 한다는 점이다. 사용자는 "뭔가 망했다"보다 "지금은 요약 대신 원문 검색 결과를 먼저 보여드릴게요"를 훨씬 잘 받아들인다.

이 표에서 눈여겨볼 점은 "모든 실패를 재시도하지 않는다"는 것이다. 안전 필터나 정책 차단은 같은 입력으로 재시도해도 대개 해결되지 않는다. JSON 파싱 실패는 한 번 정도 복구 프롬프트를 붙여 재시도할 수 있지만, 무한 반복하면 비용만 늘어난다. 429는 더 많이 때린다고 열리는 문이 아니다. 기다리거나, 큐에 넣거나, 낮은 우선순위로 내려야 한다.

지연시간과 비용을 함께 줄이는 네 가지 캐시

캐시는 "빠르게 만들기 위한 장치"이면서 동시에 "덜 부르기 위한 장치"다. Gemini 서비스에서는 최소 네 종류의 캐시를 구분해야 한다.

첫째는 응답 캐시다. 완전히 같은 요청 또는 의미상 거의 같은 질문에 대해 이전 답변을 재사용한다. 고객지원 FAQ, 정책 설명, 제품 사양처럼 자주 반복되고 최신성 요구가 낮은 영역에 적합하다. 단, 의미 캐시는 위험할 수 있다. "환불 규정 알려줘"와 "VIP 고객 환불 예외 알려줘"는 비슷해 보여도 권한과 맥락이 다르다. 따라서 캐시 키에는 사용자 권한, 조직 ID, 언어, 프롬프트 버전, 모델 버전, 안전 설정, 데이터셋 버전을 함께 넣어야 한다.

둘째는 RAG 검색 캐시다. 같은 질문에 대해 벡터 검색 결과나 reranking 결과를 잠시 저장한다. 모델 답변 자체를 캐시하지 않더라도 검색 결과를 캐시하면 지연시간을 크게 줄일 수 있다. 문서 저장소가 자주 바뀌지 않는 서비스라면 index_version을 캐시 키에 포함해 무효화 기준을 명확히 한다.

셋째는 프롬프트 조립 캐시다. 시스템 지시, 정책 문구, 도구 설명, JSON 스키마, 긴 few-shot 예시처럼 매 요청마다 반복되는 부분을 별도 조각으로 관리한다. 이 캐시는 보통 애플리케이션 내부 캐시에 가깝다. 프롬프트 문자열을 매번 새로 만들지 않아도 되고, 버전별 비교도 쉬워진다.

넷째는 Gemini/Vertex AI의 컨텍스트 캐싱이다. 긴 문서, 오디오, 동영상, 코드 저장소처럼 큰 입력을 반복해서 참조할 때 특히 유용하다. Vertex AI 문서에 따르면 컨텍스트 캐싱은 반복 콘텐츠가 포함된 요청의 비용과 지연시간을 줄이기 위한 기능이며, 암시적 캐싱과 명시적 캐싱을 제공한다. 응답 메타데이터의 cachedContentTokenCount를 보면 입력 중 캐시된 토큰 수를 확인할 수 있고, 캐싱 요청에는 최소 토큰 수 조건이 있다.³ 명시적 캐시는 캐시할 콘텐츠를 직접 만들고 이후 요청에서 리소스 이름으로 참조하는 방식이며, 기본 만료 시간과 리전, MIME 유형, Cloud Storage 파일 사용, CMEK 같은 보안 옵션을 함께 고려해야 한다.⁴ Gemini API 쪽에서도 명시적 캐싱은 한 번 전달한 입력 토큰을 캐시한 뒤 후속 요청에서 참조하는 방식으로 설명된다.⁵

컨텍스트 캐싱은 만능이 아니다. 한 번만 묻고 끝나는 질문에는 캐시 생성 비용과 관리 비용이 더 클 수 있다. 반대로 같은 200쪽 문서를 여러 사용자가 계속 질의하거나, 같은 코드베이스를 여러 관점에서 분석하거나, 긴 회의 녹취를 여러 질문으로 탐색한다면 효과가 크다. 운영 대시보드에는 캐시 적중률뿐 아니라 "캐시 생성 비용 대비 절감된 입력 토큰"을 함께 표시해야 한다. 캐시가 많다고 좋은 것이 아니라, 돈을 아끼는 캐시가 좋은 캐시다.

긴 컨텍스트를 그대로 넣지 않는 용기

Gemini의 긴 컨텍스트는 강력하다. 그러나 긴 컨텍스트를 사용할 수 있다는 것과 매번 긴 컨텍스트를 넣어야 한다는 것은 다르다. 제품 운영에서는 "모델이 읽을 수 있는 최대치"보다 "이번 질문에 필요한 최소치"가 더 중요하다.

긴 문서 질의의 기본 전략은 세 단계로 나눈다. 먼저 문서를 청킹하고, 각 조각의 제목·위치·권한·생성일·버전 같은 메타데이터를 붙인다. 다음으로 질문에 맞는 조각을 검색하고, 필요하면 reranking으로 순서를 다시 잡는다. 마지막으로 모델에는 상위 몇 개 조각과 답변 형식, 출처 요구사항만 넣는다. 전체 문서를 넣는 방식은 "한 문서 전체를 종합적으로 분석해야 하는 작업"이나 "반복 질의가 많아 컨텍스트 캐시를 만들 가치가 있는 작업"에 남겨 둔다.

멀티모달 입력도 마찬가지다. 동영상 전체를 매번 분석하게 하는 대신, 먼저 장면 분할이나 메타데이터 추출을 수행하고, 질문에 필요한 구간만 다시 넣을 수 있다. 오디오 회의록은 전체 음성을 반복 전달하기보다 전사본, 화자 분리 결과, 주요 구간 타임스탬프를 중간 산출물로 저장한다. 이미지 다건 분석은 썸네일·OCR·객체 태그를 먼저 뽑고, 고해상도 원본은 필요한 경우에만 사용한다.

운영자는 긴 컨텍스트를 아끼는 사람이 아니라, 긴 컨텍스트가 필요한 순간을 판별하는 사람이다. 모델의 능력을 줄이는 것이 아니라, 모델이 정말 중요한 부분에 계산을 쓰도록 돕는 것이다.

배포 경로 선택: 직접 API, Cloud Run, Agent Platform

Gemini 서비스의 배포 경로는 팀의 성숙도와 요구사항에 따라 달라진다. 작은 사내 도구라면 Next.js 프런트엔드와 FastAPI 백엔드를 Cloud Run에 올리고 Gemini API를 직접 호출하는 구조로 충분하다. 엔터프라이즈 검색, 권한 기반 데이터 연결, 평가, 관측성, 거버넌스가 중요하다면 Gemini Enterprise Agent Platform 또는 Vertex AI 기반 경로가 더 적합하다.

개발·스테이징·프로덕션 환경은 반드시 분리한다. 같은 API 키, 같은 서비스 계정, 같은 모델 별칭, 같은 안전 설정을 모든 환경에서 공유하면 테스트가 곧 운영 사고가 된다. 개발 환경에서는 비용 한도를 낮게 두고, 스테이징에서는 프로덕션과 같은 모델 버전을 쓰되 샘플 데이터만 사용한다. 프로덕션에서는 승인된 모델, 승인된 도구, 승인된 데이터 저장소만 접근하도록 IAM과 네트워크 경계를 좁힌다.

모델 버전도 환경 변수처럼 다룬다. gemini-flash-latest 같은 별칭은 실험에는 편하지만, 운영 기본값에는 고정 버전이 더 안전하다. 새 모델은 먼저 오프라인 평가를 통과하고, 그다음 내부 사용자에게만 켜고, 이후 일부 트래픽에 카나리로 적용한다. 마지막에야 기본 모델로 승격한다. 모델 변경은 코드 변경만큼 위험하다.

Docker와 Cloud Run의 기본 골격

컨테이너의 목표는 "어디서 실행해도 같은 서비스"를 만드는 것이다. 다음은 FastAPI 기반 Gemini 백엔드의 최소 Dockerfile 예시다.

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV PORT=8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

requirements.txt에는 대략 다음이 들어간다.

fastapi
uvicorn[standard]
google-genai
pydantic
opentelemetry-api
opentelemetry-sdk

Node.js/Express 또는 Next.js 서버도 원칙은 같다. 빌드 시점에 비밀키를 이미지 안에 넣지 않는다. 런타임 환경 변수나 Secret Manager를 통해 주입한다. 특히 Next.js에서 NEXT_PUBLIC_ 접두사가 붙은 값은 브라우저로 노출될 수 있으므로 Gemini API 키를 절대 넣으면 안 된다. 프런트엔드는 항상 여러분의 서버 API를 호출하고, 서버가 Gemini 또는 Agent Platform과 통신해야 한다.

Cloud Run에 올릴 때는 동시성과 타임아웃을 보수적으로 시작한다. 모델 호출이 긴 서비스에서 컨테이너 하나가 너무 많은 동시 요청을 받으면 메모리와 연결 풀이 빠르게 고갈된다. 처음에는 낮은 동시성으로 안정성을 확인하고, p95 지연시간과 오류율을 보며 조정한다. 긴 작업은 HTTP 요청 안에서 끝내려 하지 말고 큐와 Worker로 넘긴다.

# 예시: 컨테이너 빌드와 배포 흐름

gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/apps/gemini-api:2026-05-13

gcloud run deploy gemini-api \
  --image REGION-docker.pkg.dev/PROJECT_ID/apps/gemini-api:2026-05-13 \
  --region REGION \
  --set-env-vars GEMINI_MODEL=gemini-2.5-flash \
  --set-secrets GEMINI_API_KEY=gemini-api-key:latest \
  --concurrency 20 \
  --timeout 60

이 명령은 개념 예시다. 실제 프로젝트에서는 Artifact Registry 리전, Secret Manager 이름, 서비스 계정, VPC 연결, 최소 인스턴스, IAM 호출 권한을 조직 정책에 맞게 조정해야 한다. 운영 배포에서는 latest 태그만 쓰지 말고 날짜나 Git SHA가 포함된 이미지 태그를 사용한다. 롤백은 "이전 이미지를 다시 배포하는 일"이어야지 "어제 코드를 기억해 내는 일"이어서는 안 된다.

관측성: 블랙박스를 유리 상자로 바꾸기

AI 시스템의 장애는 전통적인 웹 장애보다 더 미묘하다. 서버는 200을 반환했지만 답변 품질이 나빠질 수 있다. JSON은 유효하지만 필드 의미가 틀릴 수 있다. 검색은 성공했지만 엉뚱한 문서를 넣었을 수 있다. 안전 필터 차단이 늘었는데 제품팀은 단순 응답률 하락으로만 볼 수 있다. 그래서 Gemini 서비스의 관측성은 HTTP 상태 코드만으로 부족하다.

Gemini Enterprise Agent Platform의 관측성 문서는 OpenTelemetry 형식의 원격 분석을 기반으로 에이전트와 MCP 서버의 성능, 동작, 상태를 추적한다고 설명한다. 대시보드에서는 세션 수, 세션당 평균 턴 수, 에이전트 호출 수, 입력·출력 토큰 사용량, 트래픽 볼륨, p50·p95·p99 지연시간, 오류율, 모델별 호출과 할당량 실패, 도구별 지연시간과 오류율 등을 볼 수 있다.⁶ 이 관점은 직접 Gemini API를 호출하는 자체 서비스에도 그대로 적용해야 한다.

최소한 다음 지표는 릴리스별로 추적한다.

• 트래픽: 요청 수, 사용자 수, 세션 수, 작업 큐 깊이, 동시 스트림 수

• 지연시간: Gateway, Orchestrator, RAG 검색, Gemini 호출, 도구 호출, 전체 응답의 p50·p95·p99

• 비용: 입력 토큰, 출력 토큰, 캐시된 토큰, 모델별 호출 수, 사용자·조직별 비용 추정치

• 안정성: 429 비율, 5xx 비율, 504 비율, 재시도 횟수, 회로 차단기 활성화, 폴백 비율

• 품질: 구조화 출력 파싱 실패율, safety block, recitation 또는 block reason, RAG 검색 실패율, 출처 누락률

• 도구: 함수 호출 성공률, 도구별 오류율, 도구 응답 시간, 권한 거부 횟수

OpenTelemetry의 trace/span 모델을 사용하면 하나의 사용자 요청이 어떤 경로를 거쳤는지 볼 수 있다. 예를 들어 하나의 trace 안에 gateway.validate, orchestrator.plan, rag.retrieve, gemini.generate, tool.crm_lookup, response.parse 같은 span을 넣는다. 각 span에는 모델명, 프롬프트 버전, 입력 토큰, 출력 토큰, 캐시 적중 여부, 재시도 번호, 오류 코드를 속성으로 남긴다.

{
  "trace_id": "9f0a...",
  "span": "gemini.generate",
  "model": "gemini-2.5-flash",
  "prompt_version": "support_answer_v17",
  "input_tokens": 1840,
  "output_tokens": 412,
  "cached_tokens": 1024,
  "latency_ms": 1280,
  "retry_count": 1,
  "finish_reason": "STOP",
  "safety_blocked": false,
  "rag_index_version": "kb_2026_05_10"
}

Gemini CLI도 OpenTelemetry 기반 관측성을 제공하며, 로컬 파일 출력이나 Google Cloud Trace·Monitoring·Logging으로 보낼 수 있는 구성을 제공한다. 또한 프롬프트 로깅 여부를 설정할 수 있고, 세션·도구 호출·API 요청 같은 이벤트를 구조화해 남긴다.⁷ CLI의 기능을 그대로 제품 서버에 옮기라는 뜻은 아니다. 중요한 교훈은 같다. AI 호출도 일반 함수 호출처럼 추적 가능해야 하고, 프롬프트와 도구 실행도 운영 데이터의 일부로 다뤄야 한다.

다만 프롬프트와 응답 전문 로깅은 매우 조심해야 한다. Gemini Enterprise의 관측성 설정 문서는 프롬프트 입력과 답변 출력 로깅을 켜면 Cloud Logging에 전체 콘텐츠가 기록될 수 있으며, 여기에는 민감정보나 개인식별정보가 포함될 수 있다고 경고한다.⁸ 운영 기본값은 "전문을 남기지 않는다"가 안전하다. 필요한 경우에도 샘플링, 마스킹, 암호화, 접근 권한, 보관 기간을 명확히 정해야 한다. 디버깅 편의 때문에 고객 데이터를 로그에 쌓아 두면, 나중에는 그 로그 자체가 가장 위험한 데이터베이스가 된다.

릴리스와 모델 변경을 같은 수준으로 관리하기

전통적인 소프트웨어 릴리스에서는 코드 변경, 설정 변경, 데이터베이스 마이그레이션을 관리한다. Gemini 서비스에서는 여기에 모델 변경, 프롬프트 변경, 안전 설정 변경, 도구 스키마 변경, RAG 인덱스 변경이 추가된다. 답변 품질은 이 모든 요소의 곱으로 결정된다.

따라서 배포 파이프라인에는 다음 관문이 필요하다. 먼저 단위 테스트에서 프롬프트 템플릿이 정상 조립되는지, JSON 스키마가 유효한지, 도구 스키마가 깨지지 않았는지 확인한다. 다음으로 고정 평가셋을 이용해 이전 버전과 새 버전의 답변을 비교한다. 그다음 스테이징에서 실제 인프라를 통해 부하 테스트와 장애 주입을 수행한다. 마지막으로 프로덕션에서 카나리 배포를 한다.

카나리는 "운영에 몰래 올려 보는 것"이 아니다. 전체 트래픽의 1%, 내부 직원, 특정 조직, 낮은 위험 기능처럼 경계가 명확해야 한다. 카나리 기간에는 비용, 지연시간, 429/5xx, safety block, 파싱 실패율, 사용자 피드백, 자동 평가 점수를 이전 버전과 나란히 본다. 하나라도 임계치를 넘으면 자동 또는 수동으로 롤백한다.

A/B 테스트는 품질 판단에 유용하지만, AI 서비스에서는 윤리와 비용도 함께 봐야 한다. B 버전이 클릭률은 높지만 환각률이 높다면 좋은 버전이 아니다. B 버전이 답변은 조금 좋아졌지만 출력 토큰이 두 배라면 비즈니스 모델에 따라 나쁜 버전일 수 있다. 릴리스 승격 기준은 "더 똑똑해 보인다"가 아니라 "정해진 비용과 지연시간 안에서 더 안전하고 유용하다"여야 한다.

운영 저장소의 구조

운영 가능한 Gemini 프로젝트는 코드만 담고 있지 않다. 재현 가능한 최소 예제, 부하 테스트, 장애 주입, 평가셋, 배포 매니페스트가 함께 있어야 한다. 공식 Cookbook이 빠른 시작과 실전 예제를 나누어 제공하는 것처럼, 여러분의 저장소도 학습용 코드와 운영용 코드를 분리해야 한다.¹

gemini-production-app/
  apps/
    api-fastapi/
    web-nextjs/
    worker-python/
  packages/
    prompts/
    schemas/
    evals/
    telemetry/
  infra/
    cloud-run/
    terraform/
    dashboards/
    alerts/
  tests/
    unit/
    integration/
    golden/
    load/
    fault-injection/
  datasets/
    eval-public/
    synthetic/
  runbooks/
    429-rate-limit.md
    safety-block.md
    rollback-model.md
    cache-purge.md

prompts에는 프롬프트 버전과 변경 이력이 있어야 한다. schemas에는 구조화 출력 JSON 스키마와 예제가 있어야 한다. evals에는 11장에서 다룬 고정 평가셋과 채점 코드가 들어간다. dashboards에는 대시보드 정의가 코드로 관리된다. runbooks에는 장애가 났을 때 누구나 따라 할 수 있는 절차가 있어야 한다.

부하 테스트는 평균 요청량만 재현하면 안 된다. 실제 사고는 평균이 아니라 피크에서 난다. 출근 직후 10분, 마케팅 캠페인 직후, 배치 작업 시작 시각, 월말 보고서 생성일처럼 트래픽이 몰리는 순간을 시나리오로 만든다. 장애 주입 테스트에서는 Gemini 호출 타임아웃, 429 폭증, 벡터 DB 지연, 캐시 장애, 도구 API 500, 잘못된 JSON 응답, 프롬프트 버전 누락을 일부러 발생시킨다. 좋은 운영팀은 장애를 피하려고만 하지 않는다. 작은 장애를 안전한 곳에서 미리 겪어 본다.

프런트엔드 UX도 운영 설계의 일부다

운영은 백엔드만의 문제가 아니다. AI 서비스는 사용자가 기다리는 시간이 길어질 수 있으므로 프런트엔드가 상태를 잘 보여 줘야 한다. "생성 중…" 하나로 모든 상황을 가리면 사용자는 멈춘 것인지, 실패한 것인지, 오래 걸리는 것인지 알 수 없다.

좋은 UX는 작업 상태를 단계별로 보여 준다. 파일 업로드 중, 문서 분석 중, 관련 근거 검색 중, 답변 생성 중, 출처 정리 중처럼 현재 위치를 알려 준다. 긴 작업에는 취소 버튼이 있어야 한다. 취소된 작업은 Worker가 가능한 한 빨리 중단하거나, 적어도 결과 저장을 하지 않아야 한다. 사용자가 같은 요청을 다시 보냈을 때는 idempotency key로 기존 작업을 찾아 이어 보여 준다.

스트리밍 답변에서는 부분 결과와 최종 결과를 구분한다. 모델이 생성 중인 문장은 아직 검증되지 않았을 수 있다. 구조화 출력이 필요한 업무에서는 스트리밍 텍스트를 그대로 업무 시스템에 반영하지 말고, 최종 JSON 검증이 끝난 뒤 저장한다. 사람이 읽는 채팅과 시스템이 처리하는 데이터는 다른 안정성 기준을 가져야 한다.

비용 통제도 UX와 연결된다. 사용자가 500쪽 PDF를 올리면 예상 처리 시간과 비용 등급을 알려 줄 수 있다. "빠른 요약", "정밀 분석", "출처 포함 상세 분석"처럼 모드를 나누면 사용자는 품질과 비용 사이에서 선택할 수 있다. 내부 관리자 화면에는 조직별 사용량, 실패율, 캐시 절감량, 고비용 요청 목록을 보여 준다. 비용은 월말 청구서에서 처음 발견하면 이미 늦다.

프로덕션 체크리스트

Gemini 서비스를 제품으로 올리기 전, 다음 질문에 "예"라고 답할 수 있어야 한다.

• Gateway에서 인증, 요청 크기 제한, 사용자·조직별 rate limit을 적용하는가?

• 웹 요청 수락 계층과 모델 추론 계층이 큐, 작업 상태, 타임아웃으로 분리되어 있는가?

• 429, 5xx, 504에 대한 backoff, jitter, retry budget, circuit breaker가 있는가?

• 모든 재시도 요청에 idempotency key 또는 중복 방지 장치가 있는가?

• 스트리밍, 비동기 작업, 배치 작업의 사용 기준이 문서화되어 있는가?

• 응답 캐시, RAG 검색 캐시, 프롬프트 캐시, 컨텍스트 캐시의 무효화 기준이 있는가?

• 개발·스테이징·프로덕션의 API 키, 서비스 계정, 모델 버전, 안전 설정, 도구 권한이 분리되어 있는가?

• OpenTelemetry trace/span으로 Gateway부터 Gemini 호출, RAG, 도구 실행까지 연결해 볼 수 있는가?

• 입력·출력 토큰, 캐시 토큰, p50/p95/p99, 429/5xx, safety block, 파싱 실패율, 함수 호출 실패율을 대시보드에서 보는가?

• 프롬프트와 응답 전문 로깅의 민감정보 위험을 검토했고, 기본적으로 마스킹 또는 비활성화했는가?

• 새 모델, 새 프롬프트, preview 기능은 카나리와 A/B 평가를 거쳐 승격되는가?

• 롤백 가능한 이미지 태그, 배포 매니페스트, 장애 대응 runbook이 저장소에 있는가?

이 체크리스트가 길게 느껴진다면 정상이다. 프로덕션은 원래 길다. 하지만 이 길고 지루한 장치들이 있어야 사용자는 짧고 자연스러운 답변을 경험한다. 훌륭한 Gemini 서비스는 모델이 똑똑해서만 만들어지지 않는다. 모델이 실패해도 서비스가 무너지지 않도록 설계한 팀이 만든다.

다음 장으로

이제 우리는 Gemini 서비스를 실제 트래픽에서 버티게 하는 뼈대를 세웠다. Gateway로 막고, Orchestrator로 판단하고, Worker로 격리하고, Store와 Cache로 기억하고, OpenTelemetry로 관찰하고, 카나리로 조심스럽게 배포한다. 다음 장에서는 이 운영 구조가 산업별로 어떻게 다른 모양을 갖는지 살펴본다. 리테일의 검색과 추천, 미디어의 영상 분석, 금융의 규제 대응 챗봇, 보험·헬스케어의 문서 자동화, 교육의 튜터링은 모두 Gemini를 쓰지만 같은 아키텍처로 성공하지 않는다. 기술은 같아도 비즈니스 제약이 다르면 설계도 달라진다.

참고

¹Gemini API Cookbook

²개발자를 위한 Gemini Codelab

³Vertex AI 컨텍스트 캐싱 개요

⁴Vertex AI 컨텍스트 캐시 만들기

⁵Gemini API context caching

⁶Gemini Enterprise Agent Platform 관측 가능성 개요

⁷Gemini CLI Observability with OpenTelemetry

⁸Gemini Enterprise 관측 가능성 설정 관리