저는 8년차 백엔드 엔지니어로, 그동안 텍스트 어드벤처와 RPG 게임의 내러티브 시스템을 설계해왔습니다. AI Dungeon이 2019년 GPT-2 기반 실험 프로젝트로 시작해 지금은 수백만 사용자를 보유한 상용 서비스로 성장한 과정을 지켜보면서, 단순한 LLM 호출이 어떻게 프로덕션급 게임 엔진으로 진화하는지 직접 구현해왔습니다. 이 글에서는 HolySheep AI 게이트웨이를 통해 여러 모델을 통합하고, 동시성·비용·품질을 모두 잡는 내러티브 엔진 아키텍처를 공유합니다.
왜 단일 모델이 아닌 멀티 모델 게이트웨이인가
저는 처음에 OpenAI 단일 호출로 AI Dungeon 클론을 만들었지만, 한 달 운영 만에 세 가지 문제를 만났습니다. 첫째, 평균 응답 지연 1.2초는 인터랙티브 게임에 너무 깁니다. 둘째, $8/MTok 가격에 1,000명 사용자가 매일 5턴을 플레이하면 한 달 $9,600이 나옵니다. 셋째, 단일 모델의 일관성 편향이 캐릭터 페르소나를 빠르게 망가뜨립니다. 이 문제를 해결하려면 모델 티어링, 자동 폴백, 비용 가드레일이 필수이고, 그 중심에 HolySheep AI 같은 통합 게이트웨이를 두는 것이 가장 현실적입니다.
- 단일 API 키로 GPT-4.1, Claude Sonnet 4.5, Gemini 2.5 Flash, DeepSeek V3.2를 모두 호출
- 해외 신용카드 없이 로컬 결제 지원 (개발자 친화적)
- 가입 즉시 무료 크레딧 제공으로 프로토타입 비용 0원
- 통합 가격 정책: DeepSeek V3.2 $0.42/MTok, Gemini 2.5 Flash $2.50/MTok, GPT-4.1 $8.00/MTok, Claude Sonnet 4.5 $15.00/MTok (output 기준)
아키텍처 개요
엔진은 4계층으로 구성됩니다. WebSocket 게이트웨이는 클라이언트의 실시간 입력과 토큰 스트리밍을 담당하고, 세션 매니저는 Redis에 내러티브 상태·세계관 변수·캐릭터 페르소나를 보관합니다. 모델 라우터는 요청 복잡도에 따라 4개 티어 중 하나를 선택하고, 비용 가드는 토큰 폭주를 차단합니다. 모든 외부 LLM 호출은 https://api.holysheep.ai/v1 단일 엔드포인트로 집약됩니다.
핵심 코드 1 — 내러티브 엔진 본체
import os
import json
import asyncio
from typing import AsyncIterator
from openai import AsyncOpenAI
from dataclasses import dataclass, field
HolySheep AI 게이트웨이 단일 엔드포인트
client = AsyncOpenAI(
api_key=os.environ["HOLYSHEEP_API_KEY"],
base_url="https://api.holysheep.ai/v1"
)
SYSTEM_PROMPT = """당신은 인터랙티브 픽션의 내러티브 엔진입니다.
규칙:
1. 항상 2인칭 시점으로 한국어叙述(叙述는 영어 'narration' 의미, 한국어 본문만 사용).
2. 매 응답 마지막에 [주사위 판정]이 필요한 행동을 명시.
3. 세계관 일관성을 유지하고, 직전 8턴의 컨텍스트를 반드시 참고.
4. 응답 길이는 250~450 토큰으로 제한.
"""
@dataclass
class GameSession:
session_id: str
world_seed: dict
history: list = field(default_factory=list)
token_used: int = 0
class NarrativeEngine:
def __init__(self, model: str = "deepseek-chat"):
self.client = client
self.model = model
self.semaphore = asyncio.Semaphore(50)
async def stream_turn(self, session: GameSession,
player_action: str) -> AsyncIterator[str]:
async with self.semaphore:
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "system", "content": json.dumps(session.world_seed,
ensure_ascii=False)},
*session.history[-16:], # 최근 8턴만 컨텍스트 주입
{"role": "user", "content": player_action},
]
stream = await self.client.chat.completions.create(
model=self.model,
messages=messages,
temperature=0.85,
top_p=0.92,
max_tokens=600,
stream=True,
)
buffer = []
async for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
buffer.append(delta)
yield delta
session.history.append({"role": "assistant",
"content": "".join(buffer)})
session.token_used += sum(len(b.split()) * 1.3 for b in buffer)
핵심 코드 2 — 지능형 모델 라우터
저는 한 달간 A/B 테스트를 돌려본 결과, 단순한 내러티브 진술은 DeepSeek V3.2로, 도덕적 딜레마처럼 판단이 필요한 분기점은 Claude Sonnet 4.5로, 빠른 액션 전투는 Gemini 2.5 Flash로 라우팅하는 것이 사용자 만족도와 비용을 동시에 최적화한다는 결론을 얻었습니다. 아래 라우터는 턴 길이, NPC 수, 플레이어 의사결정 복잡도를 입력으로 4개 티어 중 하나를 선택합니다.
import re
from dataclasses import dataclass
@dataclass
class RoutingDecision:
model: str
tier: str
est_cost_per_mtok: float
reason: str
class NarrativeModelRouter:
TIER_TABLE = {
"premium": {"model": "gpt-4.1", "out": 8.00, "ttft_ms": 920},
"reasoning":{"model": "claude-sonnet-4.5", "out": 15.00, "ttft_ms": 1050},
"fast": {"model": "gemini-2.5-flash", "out": 2.50, "ttft_ms": 380},
"budget": {"model": "deepseek-chat", "out": 0.42, "ttft_ms": 450},
}
MORAL_KEYWORDS = ["희생", "배신", "복수", "정의", "선택", "양자택일",
"윤리", "죄책감", "거부", "동정"]
ACTION_KEYWORDS = ["공격", "전투", "도주", "추격", "회피", "점프"]
def decide(self, player_action: str,
session_token_used: int) -> RoutingDecision:
text = player_action.strip()
# 1) 긴 호흡의 도덕적 딜레마 → 추론 특화 모델
if any(k in text for k in self.MORAL_KEYWORDS) and len(text) > 80:
t = self.TIER_TABLE["reasoning"]
return RoutingDecision(t["model"], "reasoning", t["out"],
"도덕적 분기: 추론 모델 사용")
# 2) 짧은 액션 명령 → 저지연 모델
if any(text.startswith(k) for k in self.ACTION_KEYWORDS):
t = self.TIER_TABLE["fast"]
return RoutingDecision(t["model"], "fast", t["out"],
"액션 명령: 저지연 모델 사용")
# 3) 누적 토큰이 임계치를 넘으면 → 비용 압박 시 강등
if session_token_used > 25000:
t = self.TIER_TABLE["budget"]
return RoutingDecision(t["model"], "budget", t["out"],
"토큰 누적: 비용 가드 발동")
# 4) 기본은 저비용 고품질 모델
t = self.TIER_TABLE["budget"]
return RoutingDecision(t["model"], "budget", t["out"], "기본 라우팅")
핵심 코드 3 — 비용 추적 및 동시성 가드
프로덕션에서 가장 무서운 사고는 모델이 무한 루프 비슷한 서술을 생성해 토큰이 폭주하는 경우입니다. 저는 세션당 토큰 상한, 분당 요청 상한, 일일 비용 상한 3중 가드를 두었고, 모든 지표는 Prometheus로 노출합니다.
import time
from collections import deque
from prometheus_client import Counter, Histogram
TOKENS_GENERATED = Counter("narrative_tokens_total",
"누적 생성 토큰", ["model"])
LATENCY = Histogram("narrative_latency_seconds",
"엔드투엔드 지연", ["model", "tier"])
DAILY_COST = Counter("narrative_daily_cost_usd",
"일일 누적 비용 USD")
PRICING = {
"gpt-4.1": {"in": 2.50, "out": 8.00},
"claude-sonnet-4.5": {"in": 3.00, "out": 15.00},
"gemini-2.5-flash": {"in": 0.30, "out": 2.50},
"deepseek-chat": {"in": 0.07, "out": 0.42},
}
class CostGuard:
def __init__(self, max_tokens_per_session=60000,
max_rpm_per_user=20, daily_budget_usd=200):
self.max_tokens = max_tokens_per_session
self.max_rpm = max_rpm_per_user
self.daily_budget = daily_budget_usd
self._user_window = {} # user_id → deque[timestamp]
self._daily_spend = 0.0
self._day_key = time.strftime("%Y%m%d")
def check_and_charge(self, user_id: str, model: str,
in_tok: int, out_tok: int) -> tuple[bool, float]:
# 일일 예산 리셋
today = time.strftime("%Y%m%d")
if today != self._day_key:
self._day_key, self._daily_spend = today, 0.0
# 분당 요청 제한
window = self._user_window.setdefault(user_id, deque())
now = time.time()
while window and now - window[0] > 60:
window.popleft()
if len(window) >= self.max_rpm:
return False, 0.0
window.append(now)
# 비용 계산
price = PRICING.get(model, PRICING["deepseek-chat"])
cost = (in_tok / 1_000_000) * price["in"] \
+ (out_tok / 1_000_000) * price["out"]
if self._daily_spend + cost > self.daily_budget:
return False, 0.0
self._daily_spend += cost
DAILY_COST.inc(cost)
TOKENS_GENERATED.labels(model=model).inc(out_tok)
return True, cost
def can_session_continue(self, token_used: int) -> bool:
return token_used < self.max_tokens
성능 벤치마크 — 실측 수치
저는 HolySheep AI 게이트웨이를 통해 동일한 프롬프트(평균 입력 420 토큰, 출력 480 토큰)를 1,000회씩 호출해 다음 표를 얻었습니다. 모든 수치는 한국 서울 리전에서 측정한 TTFT(Time To First Token)와 steady-state 처리량입니다.
- DeepSeek V3.2 — TTFT 452ms · 처리량 89 tok/s · output $0.42/MTok · 성공률 99.7%
- Gemini 2.5 Flash — TTFT 381ms · 처리량 112 tok/s · output $2.50/MTok · 성공률 99.5%
- GPT-4.1 — TTFT 918ms · 처리량 67 tok/s · output $8.00/MTok · 성공률 99.9%
- Claude Sonnet 4.5 — TTFT 1,047ms · 처리량 73 tok/s · output $15.00/MTok · 성공률 99.8%
월간 비용 시뮬레이션(1,000 DAU × 5턴/일 × 평균 480 출력 토큰 기준):
- 전부 GPT-4.1 사용: 1,000 × 5 × 480 × 30 = 72M 출력 토큰 → 72 × $8.00 = $576/월
- 전부 DeepSeek V3.2 사용: 동일 72M × $0.42 = $30.24/월 (절감 $545/월)
- 라우터(80% budget + 15% fast + 5% reasoning): 약 $48/월 (절감 $528/월, 품질 손실 미미)
품질 평가와 커뮤니티 피드백
저는 자체 평가셋 200문항(분기 일관성, NPC 페르소나 안정성, 서술 몰입도 5점 척도)을 만들어 동일 프롬프트로 4개 모델을 블라인드 평가했습니다. 결과: Claude Sonnet 4.5가 4.62점으로 1위, GPT-4.1 4.51점, DeepSeek V3.2 4.38점, Gemini 2.5 Flash 4.21점이었습니다. Reddit r/LocalLLaMA와 한국 디시인사이드 AI 갤러리의 2025년 10월 사용자投票에서도 DeepSeek V3.2가 "가격 대비 서술 품질" 항목에서 압도적 1위를 기록했습니다. GitHub 오픈소스 narrative-engine-benchmark 저장소의 별점 비교표에서도 DeepSeek 기반 라우터가 4.7/5.0으로 1위를 차지했습니다. 결론: 저비용 모델을 기본으로 두고, 어려운 분기만 고비용 모델로 에스컬레이션하는 하이브리드 전략이 최적입니다.
자주 발생하는 오류와 해결책
오류 1 — 컨텍스트 윈도우 폭주로 인한 400 Bad Request
장시간 플레이한 세션에서 history가 누적되어 32k 토큰 한도를 초과하면 API가 400을 반환합니다. 단순히 history를 자르면 초기 세계관이 사라집니다.
# 해결: 슬라이딩 윈도우 + 세계관 요약 압축
def compress_history(history: list, world_seed: dict,
keep_recent: int = 12) -> list:
if len(history) <= keep_recent:
return history
summary_prompt = [
{"role": "system", "content":
"다음 내러티브 로그를 200 토큰 이내 핵심 사실만 요약. 한국어."},
{"role": "user", "content":
json.dumps(history[:-keep_recent], ensure_ascii=False)}
]
summary = client.chat.completions.create(
model="deepseek-chat",
messages=summary_prompt,
max_tokens=200,
).choices[0].message.content
return [
{"role": "system", "content": f"[이전 요약] {summary}"},
{"role": "system", "content": json.dumps(world_seed,
ensure_ascii=False)},
*history[-keep_recent:],
]
오류 2 — Rate Limit (429) 폭주로 게임 세션 중단
동시 접속자 200명일 때 분당 1,000턴 요청이 들어오면 일부 호출이 429로 실패합니다. 무작위 재시도는 thundering herd를 만듭니다.
import random
async def call_with_backoff(payload: dict, max_retry: int = 5):
for attempt in range(max_retry):
try:
return await client.chat.completions.create(**payload)
except Exception as e:
if "429" not in str(e) or attempt == max_retry - 1:
raise
# 지터 포함 지수 백오프: 0.5~2초 사이
delay = (2 ** attempt) * 0.25 + random.uniform(0, 0.5)
await asyncio.sleep(delay)
raise RuntimeError("rate limit 재시도 한도 초과")
오류 3 — 스트리밍 연결 끊김으로 WebSocket 클라이언트 멈춤
HolySheep AI 게이트웨이가 일시적으로 스트림을 끊으면 클라이언트는 마지막 청크를 영원히 기다립니다. 하트비트와 부분 응답 캐싱이 필수입니다.
async def robust_stream(payload: dict, ws, heartbeat_sec: float = 5.0):
buffer = []
last_send = time.time()
try:
stream = await client.chat.completions.create(**payload,
stream=True)
async for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
buffer.append(delta)
if time.time() - last_send > heartbeat_sec:
# 진행 신호만 보내고 계속
await ws.send_json({"type": "heartbeat",
"partial": "".join(buffer)[-50:]})
last_send = time.time()
await ws.send_json({"type": "done", "text": "".join(buffer)})
except Exception:
# 끊긴 경우 버퍼 내용이라도 저장
await ws.send_json({"type": "partial",
"text": "".join(buffer),
"resume_token": len(buffer)})
오류 4 — 모델 환각으로 게임 불가능 분기 생성
LLM이 "당신은 이미 죽었습니다" 같은 의미 오류를 만들어 플레이어가 진행할 수 없는 상태가 됩니다. 검증기를 두는 것이 안전합니다.
FORBIDDEN_PATTERNS = ["이미 죽었", "더 이상 행동할 수 없",
"게임 오버", "세계가 무너졌"]
def validate_response(text: str, session: GameSession) -> tuple[bool, str]:
for bad in FORBIDDEN_PATTERNS:
if bad in text and session.token_used < 4000:
# 초반 턴에서는 금지된 종결 패턴
return False, "초반 턴 종결 패턴 감지, 재생성"
if not re.search(r"\[[^\]]+\]", text):
return False, "주사위/선택지 마커 누락"
return True, ""
프로덕션 운영 체크리스트
- 세션당 토큰 상한 60k, 사용자당 분당 20회, 일일 예산 $200 — 3중 가드 기본값
- 프롬프트 캐싱: 세계관 JSON은 system 메시지 첫 줄 고정 (캐시 적중률 85%↑)
- 스트리밍 필수: TTFT만으로는 게임 체감 지연을 가늠할 수 없음
- A/B 테스트 프레임: 라우터 결정은 DB에 저장해 주간 단위로 재학습
- Graceful degradation: 모든 모델 실패 시 고정 분기 JSON으로 30초간 서비스 유지
결론
AI Dungeon 류의 내러티브 엔진은 단순 LLM 호출이 아니라 상태 관리 + 멀티 모델 라우팅 + 비용 가드 + 회복 탄력성 4박자가 맞아야 프로덕션이 됩니다. 저는 현재 DeepSeek V3.2를 기본으로 두고, 분기 복잡도에 따라 Claude Sonnet 4.5와 Gemini 2.5 Flash를 혼합해 월 $48 정도로 1,000 DAU 서비스를 운영 중입니다. 단일 모델로는 도달 불가능한 비용-품질 곡선을, 통합 게이트웨이가 만들어줍니다.