llm-failover: 자동 회전 및 페일오버 기능을 갖춘 회복 탄력적 LLM 키 풀 라이브러리

섹션별 상세

llm-failover는 여러 API 키를 프로필 단위로 관리하며, 요청 실패 시 자동으로 가용한 다른 키나 모델로 페일오버를 수행한다. 사용자는 단일 엔드포인트를 사용하는 것처럼 코드를 작성하되 내부적으로는 여러 프로바이더의 자원을 유연하게 활용할 수 있다.

typescript

import { LlmKeyPool } from "llm-failover";

const pool = new LlmKeyPool({
  profiles: [
    { id: "anthropic-1", provider: "anthropic", apiKey: process.env.ANTHROPIC_KEY_1! },
    { id: "openai-1", provider: "openai", apiKey: process.env.OPENAI_KEY_1! },
  ],
  fallbackModels: [
    { provider: "openai", model: "gpt-4o" },
  ],
});

await pool.init();

const result = await pool.run(
  async (ctx) => {
    const response = await callYourLlm(ctx);
    return response;
  },
  { model: "claude-sonnet-4-20250514", provider: "anthropic" },
);

llm-failover 라이브러리를 사용하여 키 풀을 설정하고 페일오버 로직을 실행하는 기본 예시

오류 유형에 따라 차별화된 지수 백오프 쿨다운 스케줄을 적용한다. 속도 제한이나 일시적 오류는 1분부터 시작하여 최대 1시간까지 간격을 늘리며, 결제나 인증 관련 영구적 오류는 5시간부터 시작하여 최대 24시간까지 키 사용을 중단시킨다.

classifyError 헬퍼를 통해 HTTP 상태 코드(401, 402, 429 등)와 에러 메시지 패턴을 분석하여 오류 원인을 자동으로 분류한다. 이를 통해 단순 네트워크 타임아웃과 계정 차단 문제를 구분하여 적절한 대응 전략을 선택한다.

typescript

import { classifyError } from "llm-failover";

const reason = classifyError(error);
// 결과: "rate_limit" | "auth" | "auth_permanent" | "billing" | "timeout" | "model_not_found" | "format" | "unknown"

HTTP 상태 코드와 메시지 패턴을 분석하여 오류 원인을 분류하는 헬퍼 함수 사용법

상태 지속성(Persistence) 기능을 제공하여 프로세스 재시작 후에도 키의 쿨다운 상태를 유지할 수 있다. 원자적 파일 쓰기와 파일 잠금 메커니즘을 사용하여 여러 프로세스가 동일한 상태 파일을 공유하더라도 데이터 무결성을 보장한다.

LiteLLM과 같은 기존 솔루션과 비교했을 때, 별도의 프록시 서버 인프라가 필요 없는 TypeScript 네이티브 라이브러리라는 점이 강점이다. 의존성이 없고 번들 크기가 작아 서버리스 환경이나 가벼운 애플리케이션에 적합하다.

용어 해설

속도 제한(Rate Limiting): — API 서비스 제공업체가 특정 시간 동안 허용하는 요청의 수를 제한하는 메커니즘이다. 할당량을 초과하면 요청이 거부되며, 이는 LLM 기반 서비스의 안정성을 해치는 주요 원인이 된다.
지수 백오프(Exponential Backoff): — 요청 실패 시 재시도 간격을 지수적으로 늘려가는 알고리즘이다. 네트워크 과부하를 방지하고 실패한 서버가 회복할 시간을 충분히 제공하기 위해 사용된다.
페일오버(Failover): — 시스템의 한 구성 요소가 실패했을 때 자동으로 예비 구성 요소로 전환하여 서비스 중단을 방지하는 기능이다. 이 라이브러리에서는 실패한 API 키를 다른 가용한 키로 교체하는 것을 의미한다.
ECMAScript 모듈(ESM): — JavaScript의 표준 모듈 시스템으로, import 및 export 구문을 사용하여 코드를 모듈화한다. 현대적인 Node.js 및 브라우저 환경에서 권장되는 방식이다.

기술

TypeScript
Node.js
OpenAI API
Anthropic API
Gemini API

활용 사례

멀티 에이전트 시스템 운영
고가용성 LLM 게이트웨이 구축
서버리스 환경의 LLM API 관리

언급된 리소스

GitHubllm-failover GitHub Repository