무료티어 API 키 풀 로테이션·쿨다운으로 한도 버티기

무료티어 API 키 풀 로테이션·쿨다운으로 한도 버티기

무료 LLM API 키는 분당 요청 한도가 있어서 하나로는 금방 막혔다. 키를 풀로 돌리고, 실패한 키만 잠깐 쉬게 하는 구조를 만들었다.

1. 서론 (Introduction)

• 문제/상황 (Problem): 무료 티어는 분당 요청 수 제한이 있다. 키 하나로는 금방 429 오류가 났고, 여러 키를 번갈아 쓰고 싶었다.
• 목적 (Purpose): 키 풀에서 라운드로빈으로 키를 순환시키고, 실패한 키는 쿨다운 후 자동 복귀시키는 구조를 만든다.
• 대상 (Target Audience): 무료 LLM API 한도를 늘리고 싶은 개발자.

2. 방법 및 과정 (Methods & Process)

• 배경 조사 및 데이터 (Data Collection): 키 하나만 쓸 때와 여러 키를 순환시킬 때의 차이를 정리했다.

  방식	분당 처리 가능 요청	429 발생 시
  키 1개	한도만큼	요청 중단, 수동 대기
  키 N개 라운드로빈 + 쿨다운	한도 × 활성 키 수	해당 키만 제외, 나머지로 계속

• 접근 방법 (Approach Methods):
  • [방법 1] 라운드로빈 커서: 키 리스트에 커서를 두고 순서대로 다음 키를 반환한다. 커서는 매 호출마다 한 칸씩 전진한다.
  • [방법 2] 실패 시 쿨다운: mark_failed(key) 호출 시 해당 키의 cooldown_until 타임스탬프를 현재 시각 + N초로 기록한다. 다음 선택 시 쿨다운 중인 키는 커서 순회에서 건너뛴다.
• 분석 및 해결 프로세스 (Analysis Flow):
  • 도구/기술: Python dataclass, time.time() 기반 쿨다운 타임스탬프.
  • 주요 단계: 커서 위치에서 다음 키 확인 $\rightarrow$ 쿨다운 중이면 스킵 $\rightarrow$ 활성 키면 반환·커서 전진 $\rightarrow$ 실패 보고 시 쿨다운 타임스탬프 갱신.
  • 결과 도출 및 검증: 키 3개(A/B/C)로 라운드로빈 확인 후 B를 실패 처리했다. 이후 4회 연속 선택에서 B는 한 번도 나오지 않고 A/C만 교대로 반환됐다. 쿨다운 시간(5초)이 지난 시점으로 시각을 이동시켜 재요청하면 B가 다시 선택됐다.

3. 결과 (Results)

• 분석 결과 요약: 키 3개 기준 정상 상태에서는 A→B→C 순서가 그대로 유지됐다. 키 B를 실패 처리한 직후에는 활성 키 수가 3에서 2로 줄었고, 이후 라운드는 A와 C만 순환했다. 쿨다운 시각을 지난 시점으로 넘기자 별도 조치 없이 B가 다시 순환에 포함됐다.

4. 인사이트 및 액션 (Insights & Action)

• 인사이트 (Insight): 키를 풀로 관리하면 한도가 공급자 단위가 아니라 키 단위로 쪼개진다. 실패 감지와 복귀를 자동화하면 수동 개입 없이도 한도 초과 구간을 버틸 수 있다.
• 실행 방안 (Action Plan): 쿨다운 시간을 공급자별 실제 한도 초기화 주기에 맞춰 조정한다. 너무 짧으면 아직 한도가 남지 않은 키가 다시 선택돼 실패가 반복된다.
• 한 줄 결론 (Key Takeaway): 라운드로빈 + 실패 시 쿨다운 조합으로 무료 LLM 키 풀의 처리량을 활성 키 수만큼 늘릴 수 있다. 샘플 코드
• 다음 스텝 (Next Step): 지금 구조는 실패 원인을 구분하지 않고 동일한 쿨다운을 적용한다. 실제로는 429(한도 초과)와 403(권한 문제)의 복구 시간이 전혀 다르므로, 오류 유형별로 쿨다운 길이를 다르게 주는 세분화가 필요하다.

---

연구·학습 목적. 이 글은 기법의 동작 원리를 정리한 것이다. 특정 서비스의 이용약관을 우회하거나 타인의 자원에 무단 접근하는 데 쓰지 않는다. 적용 전에 대상의 이용약관과 robots.txt를 확인한다.