llm-failover: 자동 페일오버와 쿨다운 회전을 지원하는 회복 탄력적 LLM 키 풀 라이브러리

핵심 요약

LLM 기반 서비스를 운영할 때 특정 API 키의 속도 제한(Rate Limit)이나 일시적인 장애로 인해 전체 시스템이 중단되는 문제가 빈번하게 발생합니다. llm-failover는 이러한 문제를 해결하기 위해 여러 제공업체의 API 키를 하나의 풀(Pool)로 관리하고, 장애 발생 시 자동으로 다른 키로 전환하는 기능을 제공합니다. 특히 단순한 교체를 넘어 지수 백오프(Exponential Backoff) 기반의 쿨다운 시스템을 적용하여 에러 유형에 따라 복구 시간을 차등 관리합니다. 이를 통해 개발자는 인프라 복잡성 없이 TypeScript 환경에서 안정적인 LLM 추론 환경을 구축할 수 있습니다.

배경

TypeScript/JavaScript, LLM API(OpenAI, Anthropic 등) 사용 경험, 비동기 프로그래밍

대상 독자

TypeScript 기반으로 LLM 에이전트나 서비스를 개발하는 엔지니어

의미 / 영향

이 라이브러리는 LLM 서비스의 신뢰성을 높이는 데 필요한 복잡한 로직을 추상화하여 제공합니다. 특히 멀티 모델 전략을 사용하는 팀에게 인프라 관리 부담을 줄여주며, 비용 효율적인 API 키 관리를 가능하게 합니다.

섹션별 상세

llm-failover는 Anthropic, OpenAI, Gemini 등 다양한 제공업체의 API 키를 프로필 단위로 관리합니다. 특정 키에서 에러가 발생하면 라이브러리가 이를 감지하고 즉시 가용한 다른 키로 요청을 전달하며, 모든 키가 소진될 경우 미리 설정된 대체 모델(Fallback Models)로 전환하여 서비스 연속성을 보장합니다. 이는 수동으로 키를 교체해야 하는 번거로움을 없애고 시스템의 회복 탄력성을 크게 향상시킵니다.

에러의 성격에 따라 복구 대기 시간을 다르게 설정하는 지능형 쿨다운 시스템을 갖추고 있습니다. 속도 제한(Rate Limit)이나 일시적 에러의 경우 1분에서 시작해 최대 1시간까지 지수적으로 늘어나는 쿨다운을 적용하며, 결제 문제나 인증 오류 같은 영구적 에러는 5시간에서 최대 24시간까지 긴 대기 시간을 할당합니다. 이러한 차등적 접근은 불필요한 API 호출을 방지하고 시스템이 안정적으로 복구될 시간을 확보해 줍니다.

정교한 에러 분류 및 상태 관리 기능을 제공하여 운영의 편의성을 높였습니다. classifyError 헬퍼를 통해 HTTP 상태 코드와 메시지 패턴을 분석하여 에러를 8가지 유형으로 자동 분류하며, storagePath 설정을 통해 프로세스가 재시작되어도 쿨다운 상태를 유지할 수 있도록 파일 기반의 원자적(Atomic) 상태 저장을 지원합니다. 이를 통해 개발자는 복잡한 에러 처리 로직을 직접 작성하지 않고도 안정적인 상태 관리를 구현할 수 있습니다.

별도의 프록시 서버 인프라가 필요한 LiteLLM과 달리, llm-failover는 의존성이 없는 순수 TypeScript 라이브러리로 동작하여 도입 비용이 매우 낮습니다. ESM을 지원하며 복잡한 데이터베이스 없이도 파일 시스템을 통해 상태를 영속화할 수 있어 소규모 에이전트 시스템부터 프로덕션 게이트웨이까지 폭넓게 적용 가능합니다. 인프라 오버헤드 없이 타입 안전성(Type Safety)을 유지하며 LLM 키 풀을 관리하고자 하는 팀에게 최적의 선택지입니다.

</> 코드 예제 포함

실무 Takeaway

여러 개의 API 키를 풀로 구성하여 특정 키의 속도 제한(Rate Limit) 문제에 즉각 대응할 수 있습니다.
에러 유형별로 차등화된 쿨다운 전략을 통해 API 제공업체에 가해지는 부하를 줄이고 복구 효율을 높입니다.
별도의 서버 구축 없이 라이브러리 추가만으로 프로덕션 수준의 LLM 가용성을 확보할 수 있습니다.