AI API Circuit Breaker Pattern 마이그레이션 플레이북

AI API를 활용한 프로덕션 시스템에서 서비스 장애는 치명적입니다. 이번 플레이북에서는 Circuit Breaker 패턴을 구현하여 AI API 장애 시 자동 복구机制을 구축하고, HolySheep AI로 마이그레이션하는 전 과정을 다룹니다.

1. 마이그레이션 배경과 목적

1.1 기존 API 문제 분석

저는 지난 2년간 여러 AI API를 프로덕션에 적용하면서 다음과 같은 문제들을 경험했습니다:

• 예측 불가능한 지연 시간: 피크 타임에 30초 이상 응답 지연 발생
• 영구적 장애 전파: 단일 API 장애 시 전체 시스템 마비
• 비용 폭탄: 재시도 로직 부재로 불필요한 API 호출 증가
• 다중 모델 관리 복잡성: 각 모델별 에러 핸들링 코드 중복

1.2 HolySheep AI 선택 이유

HolySheep AI는 글로벌 AI API 게이트웨이로서 다음과 같은 이점을 제공합니다:

# HolySheep AI 가격 비교 (2024년 기준)
GPT-4.1:           $8.00/MTok
Claude Sonnet 4.5:  $15.00/MTok
Gemini 2.5 Flash:  $2.50/MTok
DeepSeek V3.2:      $0.42/MTok

기존 Direct API 대비 30-50% 비용 절감
단일 API 키로 모든 모델 통합 관리
로컬 결제 지원 (해외 신용카드 불필요)

2. Circuit Breaker Pattern 핵심 개념

2.1 세 가지 상태 이해

상태 다이어그램:
┌─────────┐     성공     ┌─────────┐     실패 횟수 초과     ┌─────────┐
│  CLOSED │ ─────────▶ │  OPEN   │ ──────────────────▶ │ HALF-OPEN │
└─────────┘             └─────────┘                      └─────────┘
     ▲                       │                                 │
     │                       │_TIMEOUT                         │성공
     │                       ▼                                 │
     └───────────────────────────────────────────────────────────┘

• CLOSED: 정상 작동, 모든 요청이 API로 전달됨
• OPEN: 장애 감지, 모든 요청이 즉시 실패 (fail-fast)
• HALF-OPEN: 복구 시도, 제한된 요청만 허용하여 회복 테스트

3. HolySheep AI 기반 Circuit Breaker 구현

3.1 Python 구현 (가장 범용적)

import time
import threading
from enum import Enum
from dataclasses import dataclass, field
from typing import Callable, Optional, Dict, Any
import httpx

class CircuitState(Enum):
    CLOSED = "closed"
    OPEN = "open"
    HALF_OPEN = "half_open"

@dataclass
class CircuitBreakerConfig:
    failure_threshold: int = 5        # OPEN 상태로 전환되는 실패 횟수
    success_threshold: int = 3        # CLOSED로 복구所需的 성공 횟수
    timeout: float = 30.0             # OPEN → HALF_OPEN 전환 시간(초)
    half_open_max_calls: int = 3      # HALF_OPEN 상태에서 허용되는 호출 수

class CircuitBreaker:
    def __init__(self, config: CircuitBreakerConfig):
        self.config = config
        self.state = CircuitState.CLOSED
        self.failure_count = 0
        self.success_count = 0
        self.last_failure_time: Optional[float] = None
        self.half_open_calls = 0
        self._lock = threading.RLock()
    
    def call(self, func: Callable, *args, **kwargs) -> Any:
        with self._lock:
            # 상태 전이 로직
            if self.state == CircuitState.OPEN:
                if self._should_transition_to_half_open():
                    self._transition_to_half_open()
                else:
                    raise CircuitBreakerOpenError(
                        f"Circuit breaker is OPEN. Retry after "
                        f"{self.config.timeout - (time.time() - self.last_failure_time):.1f}s"
                    )
            
            if self.state == CircuitState.HALF_OPEN:
                if self.half_open_calls >= self.config.half_open_max_calls:
                    raise CircuitBreakerOpenError(
                        "Circuit breaker is HALF-OPEN. Max calls reached."
                    )
                self.half_open_calls += 1
        
        # 실제 API 호출
        try:
            result = func(*args, **kwargs)
            self._on_success()
            return result
        except Exception as e:
            self._on_failure()
            raise
    
    def _should_transition_to_half_open(self) -> bool:
        if self.last_failure_time is None:
            return True
        return (time.time() - self.last_failure_time) >= self.config.timeout
    
    def _transition_to_half_open(self):
        self.state = CircuitState.HALF_OPEN
        self.half_open_calls = 1
        self.success_count = 0
    
    def _on_success(self):
        with self._lock:
            if self.state == CircuitState.HALF_OPEN:
                self.success_count += 1
                if self.success_count >= self.config.success_threshold:
                    self._transition_to_closed()
            self.failure_count = 0
    
    def _on_failure(self):
        with self._lock:
            self.failure_count += 1
            self.last_failure_time = time.time()
            
            if self.state == CircuitState.HALF_OPEN:
                self._transition_to_open()
            elif self.failure_count >= self.config.failure_threshold:
                self._transition_to_open()
    
    def _transition_to_open(self):
        self.state = CircuitState.OPEN
        self.half_open_calls = 0
    
    def _transition_to_closed(self):
        self.state = CircuitState.CLOSED
        self.failure_count = 0
        self.success_count = 0
        self.half_open_calls = 0

class CircuitBreakerOpenError(Exception):
    pass

3.2 HolySheep AI API 호출 통합

import os
from circuit_breaker import CircuitBreaker, CircuitBreakerConfig, CircuitState

HolySheep AI 설정
HOLYSHEEP_API_KEY = os.getenv("YOUR_HOLYSHEEP_API_KEY")
HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"

class HolySheepAIClient:
    def __init__(self, api_key: str, model: str = "gpt-4.1"):
        self.api_key = api_key
        self.base_url = HOLYSHEEP_BASE_URL
        self.model = model
        
        # 모델별 Circuit Breaker 인스턴스
        self.circuit_breakers: Dict[str, CircuitBreaker] = {
            "gpt-4.1": CircuitBreaker(CircuitBreakerConfig(
                failure_threshold=5,
                success_threshold=3,
                timeout=30.0,
                half_open_max_calls=3
            )),
            "claude-sonnet-4.5": CircuitBreaker(CircuitBreakerConfig(
                failure_threshold=5,
                success_threshold=3,
                timeout=30.0,
                half_open_max_calls=3
            )),
            "gemini-2.5-flash": CircuitBreaker(CircuitBreakerConfig(
                failure_threshold=7,  # Gemini는 좀 더 관대하게 설정
                success_threshold=2,
                timeout=20.0,
                half_open_max_calls=5
            )),
            "deepseek-v3.2": CircuitBreaker(CircuitBreakerConfig(
                failure_threshold=5,
                success_threshold=3,
                timeout=30.0,
                half_open_max_calls=3
            )),
        }
    
    def chat_completion(self, messages: list, model: str = None) -> dict:
        model = model or self.model
        cb = self.circuit_breakers.get(model)
        
        if cb is None:
            raise ValueError(f"Unknown model: {model}")
        
        def _make_request():
            return self._request_chat_completion(messages, model)
        
        return cb.call(_make_request)
    
    def _request_chat_completion(self, messages: list, model: str) -> dict:
        import httpx
        
        with httpx.Client(timeout=60.0) as client:
            response = client.post(
                f"{self.base_url}/chat/completions",
                headers={
                    "Authorization": f"Bearer {self.api_key}",
                    "Content-Type": "application/json"
                },
                json={
                    "model": model,
                    "messages": messages,
                    "temperature": 0.7,
                    "max_tokens": 2000
                }
            )
            response.raise_for_status()
            return response.json()
    
    def get_circuit_status(self) -> Dict[str, str]:
        return {
            model: cb.state.value 
            for model, cb in self.circuit_breakers.items()
        }

사용 예시
if __name__ == "__main__":
    client = HolySheepAIClient(
        api_key=HOLYSHEEP_API_KEY,
        model="gpt-4.1"
    )
    
    try:
        response = client.chat_completion([
            {"role": "user", "content": "안녕하세요!"}
        ])
        print(f"Response: {response['choices'][0]['message']['content']}")
        print(f"Circuit Status: {client.get_circuit_status()}")
    except Exception as e:
        print(f"Error: {e}")
        print(f"Circuit Status: {client.get_circuit_status()}")

3.3 Spring Boot (Java) 구현

// CircuitBreaker.java
package com.holysheep.ai.config;

import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
import java.time.Instant;

public class CircuitBreaker {
    private final int failureThreshold;
    private final int successThreshold;
    private final long timeoutMillis;
    private final int halfOpenMaxCalls;
    
    private volatile State state = State.CLOSED;
    private AtomicInteger failureCount = new AtomicInteger(0);
    private AtomicInteger successCount = new AtomicInteger(0);
    private AtomicInteger halfOpenCalls = new AtomicInteger(0);
    private volatile long lastFailureTime = 0;
    
    public enum State { CLOSED, OPEN, HALF_OPEN }
    
    public CircuitBreaker(int failureThreshold, int successThreshold, 
                          long timeoutSeconds, int halfOpenMaxCalls) {
        this.failureThreshold = failureThreshold;
        this.successThreshold = successThreshold;
        this.timeoutMillis = timeoutSeconds * 1000;
        this.halfOpenMaxCalls = halfOpenMaxCalls;
    }
    
    public synchronized Object execute(Callable