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

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

LLM 에이전트나 서비스를 운영할 때 특정 API 키의 속도 제한(Rate Limit)으로 인해 시스템이 중단되는 문제를 해결하기 위한 라이브러리이다. Anthropic, OpenAI, Gemini 등 다양한 프로바이더의 키를 하나의 풀로 관리하며, 오류 발생 시 자동으로 다음 키로 전환한다. 지수 백오프(Exponential Backoff)를 적용한 쿨다운 시스템을 통해 회복 중인 엔드포인트에 과부하를 주지 않도록 설계되었다. TypeScript 기반의 네이티브 라이브러리로 별도의 프록시 서버 없이 가볍게 도입할 수 있는 것이 특징이다.

배경

TypeScript/JavaScript 기초 지식, LLM API(OpenAI, Anthropic 등) 사용 경험, Node.js 환경에서의 환경 변수 관리

대상 독자

프로덕션 환경에서 LLM 에이전트나 서비스를 운영하며 API 안정성을 확보하려는 TypeScript/JavaScript 개발자

의미 / 영향

이 라이브러리는 LLM 서비스의 안정성을 높이기 위해 복잡한 프록시 서버를 구축하던 비용을 줄여준다. 특히 소규모 팀이나 서버리스 환경에서 API 키 관리와 페일오버 로직을 간단하게 구현할 수 있게 하여 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 네이티브 라이브러리라는 점이 강점이다. 의존성이 없고 번들 크기가 작아 서버리스 환경이나 가벼운 애플리케이션에 적합하다.

실무 Takeaway

다양한 LLM 프로바이더의 API 키를 하나의 풀로 묶어 관리함으로써 단일 키의 속도 제한 리스크를 제거하고 서비스 가용성을 높일 수 있다.
오류의 성격(일시적 vs 영구적)에 따라 쿨다운 시간을 다르게 설정하여 시스템의 재시도 로직을 최적화하고 불필요한 API 호출을 방지할 수 있다.
TypeScript 환경에서 별도의 인프라 구축 없이 라이브러리 추가만으로 안정적인 LLM 추론 파이프라인을 구축할 수 있다.

언급된 리소스

GitHubllm-failover GitHub Repository