본문으로 건너뛰기

API Key 풀

API 키 풀링을 사용하면 같은 제공업체에 여러 API 키를 구성할 수 있습니다. 요청은 가중 라운드 로빈으로 분산되며, 속도 제한이나 장애가 발생하면 시스템이 자동으로 사용 가능한 다른 키로 전환합니다.

사용 시점​

  • 높은 동시성 시나리오: 단일 키의 속도 제한이 부족할 때 여러 키가 트래픽 부하를 분담합니다
  • 팀 공유: 각 팀원이 자신의 키 할당량을 사용하여 비용을 분담합니다
  • 무료 티어 중첩: 여러 무료 계정의 키를 순환해서 사용합니다
  • 고가용성: 한 키가 실패하면 시스템이 자동으로 다른 키로 전환하여 중단을 방지합니다
  • 테스트/프로덕션 분리: 서로 다른 가중치를 사용해 프로덕션 키와 테스트 키로 가는 요청 비율을 제어합니다

사용 방법 가이드​

API Key 추가​

  1. Settings → Provider Management를 엽니다
  2. 대상 제공업체를 선택합니다(예: OpenAI)
  3. API Key Pool 섹션을 찾습니다
  1. Add Key 버튼을 클릭합니다
  2. 정보를 입력합니다:
필드필수설명
API Key예키 값 또는 환경 변수 참조($ 접두사)
Label아니요쉽게 식별하기 위한 이름입니다. 예: "Production Key #1" 또는 "Test Key"
Weight아니요1–100, 기본값은 1입니다. 값이 높을수록 선택될 확률이 높아집니다
  1. Confirm을 클릭해 추가합니다

가중치 설정​

  1. API 키 목록에서 대상 키를 찾습니다
  2. Weight 값을 수정합니다(1–100)
  3. 가중치는 해당 키가 선택될 상대적 확률을 결정합니다

개별 키 활성화 / 비활성화​

  1. API 키 목록에서 대상 키를 찾습니다
  2. Enabled 스위치를 전환합니다
  3. 비활성화된 키는 순환에서 제외되지만 구성은 유지됩니다

키 삭제​

  1. API 키 목록에서 대상 키를 찾습니다
  2. Delete 버튼을 클릭합니다
  3. 삭제를 확인합니다(이 작업은 되돌릴 수 없습니다)

구성 참조​

설정유형기본값범위설명
API KeyString(비어 있음)--키 값 또는 $ENV_VAR 참조
LabelString(비어 있음)--키를 구분하기 위한 메모 이름
WeightInteger11–100가중 라운드 로빈에 사용할 가중치
EnabledBooleantrue--이 키가 순환에 참여하는지 여부
OrderInteger0--목록의 표시 순서

동작 참고 사항​

가중 라운드 로빈​

풀의 각 키는 가중치에 비례하는 수의 "슬롯"을 차지합니다. Elftia는 고정된 순서로 이 슬롯들을 순환하며 가중치 비율에 따라 요청을 분산합니다.

가중치 분포 예시:

가중치가 각각 3, 2, 1인 키 3개가 있다고 가정합니다(총 가중치 = 6):

키가중치비율6번의 요청당 선택 횟수
Key A350%3
Key B233%2
Key C117%1

순환 순서: A → A → A → B → B → C → A → A → A → B → ...

동일 가중치 예시:

키 3개의 가중치가 모두 1이면(총 가중치 = 3), 다음처럼 엄격하게 순환합니다: A → B → C → A → B → C → ...

세션 어피니티​

같은 채팅 세션 내의 모든 요청은 같은 API 키에 바인딩됩니다. 이 설계에는 두 가지 중요한 이유가 있습니다:

  1. 프롬프트 캐싱: 일부 제공업체(예: Anthropic)는 프롬프트 캐싱을 지원합니다. 같은 키를 사용하는 연속 요청은 캐시에 적중할 수 있어 지연 시간과 비용을 크게 줄입니다
  2. 일관성: 같은 대화 안에서 키를 자주 전환할 때 발생하는 속도 제한 카운터 초기화를 방지합니다

세션 바인딩은 다음 상황에서 다시 할당됩니다:

  • 현재 바인딩된 키가 비활성화되거나 삭제된 경우
  • 현재 바인딩된 키가 오류로 인해 쿨다운 기간에 들어간 경우
  • 세션이 종료된 경우(닫힘 또는 삭제됨)

자동 장애 조치​

요청에서 오류가 발생하면 키 풀은 오류 유형에 따라 서로 다른 전략을 적용합니다:

속도 제한(429/529)​

HTTP 429(속도 제한) 또는 529(서비스 과부하) 응답을 받으면:

  1. 현재 키가 쿨다운 기간에 들어갑니다
  2. 시스템이 풀에서 다음으로 사용 가능한 키로 자동 전환합니다
  3. 새 키로 요청을 재시도합니다

쿨다운 메커니즘:

연속 실패 횟수쿨다운 기간공식
1번째60초60s × 2^0
2번째120초60s × 2^1
3번째240초60s × 2^2
4번째480초60s × 2^3
5번째 이상900초(상한)min(60s × 2^(n-1), 900s)

쿨다운 기간 동안 해당 키는 순환에서 제외되며, 기간이 만료되면 자동으로 다시 사용할 수 있게 됩니다. 성공한 요청은 해당 키의 연속 실패 카운터를 초기화합니다.

인증 실패(401/403)​

HTTP 401(Unauthorized) 또는 403(Forbidden) 응답을 받으면:

  1. 해당 키가 영구적으로 비활성화됩니다(데이터베이스에서 비활성화로 표시됨)
  2. 시스템이 사용 가능한 다음 키로 자동 전환합니다
  3. 설정 UI에서 해당 키는 비활성화된 상태로 표시됩니다

이는 인증 오류가 일반적으로 키 자체가 유효하지 않게 되었음을 의미하기 때문입니다(만료, 취소 또는 할당량 소진). 기다린다고 복구될 가능성이 낮습니다.

장애 조치 흐름도​

Request sent
    |
    v
Use session-bound key
    |
    +---> Success ---> Reset cooldown counter ---> Return response
    |
    +---> 429/529 (rate limited)
    |         |
    |         v
    |     Current key enters cooldown
    |     (starts at 60s, exponential backoff, cap at 15 minutes)
    |         |
    |         v
    |     Any other available keys in the pool?
    |         |           |
    |        Yes          No
    |         |           |
    |         v           v
    |     Switch to new key    Request fails, return error
    |     Rebind session        (all keys unavailable)
    |         |
    |         v
    |     Retry with new key
    |
    +---> 401/403 (authentication failure)
              |
              v
          Permanently disable this key
              |
              v
          Any other available keys in the pool?
              |           |
             Yes          No
              |           |
              v           v
          Switch to new key    Request fails, return error
          Rebind session

키 풀과 제공업체 수준 API Key의 관계​

  • 제공업체에 제공업체 수준 API 키(Provider 구성의 api_key 필드)와 키 풀이 모두 구성되어 있으면 키 풀이 우선합니다
  • 키 풀이 비어 있으면(항목이 없으면) 제공업체 수준 API 키가 사용됩니다
  • 로드 밸런싱과 장애 조치 기능을 위해 제공업체 수준 API 키 대신 키 풀을 사용하는 것을 권장합니다

문제 해결​

문제가능한 원인해결 방법
모든 키가 쿨다운 중이라 요청이 실패함모든 키가 동시에 속도 제한에 걸림쿨다운이 만료될 때까지 기다리거나(최대 15분), 풀 용량을 늘리기 위해 키를 더 추가합니다
특정 키가 전혀 선택되지 않음가중치가 0이거나 다른 키의 가중치가 훨씬 높음가중치 설정을 확인하고 가중치가 최소 1인지 확인합니다
키가 자동으로 비활성화됨401/403 인증 오류를 받음키가 만료되었거나 취소되었는지 확인합니다. 제공업체 웹사이트에서 키 상태를 확인한 뒤 문제를 해결하고 수동으로 다시 활성화합니다
풀이 올바르게 구성되었지만 요청이 여전히 이전 키를 사용함세션 어피니티가 이전 키에 바인딩되어 있음새 채팅 세션을 시작하거나, 이전 키가 쿨다운 기간에 들어가 시스템이 자동으로 다시 바인딩할 때까지 기다립니다
추가한 키가 즉시 적용되지 않음키 캐시가 새로 고쳐지지 않음구성을 저장하고 다시 시도합니다. 시스템이 캐시를 자동으로 새로 고칩니다
환경 변수 키를 확인할 수 없음변수 이름이 잘못되었거나 설정되지 않음$ 뒤의 변수 이름이 시스템에 설정된 이름과 대소문자까지 정확히 일치하는지 확인합니다
쿨다운이 너무 김여러 번 연속으로 속도 제한에 걸려 지수 백오프가 적용됨요청 빈도를 줄이거나 키를 더 추가해 부하를 분산합니다. 쿨다운 상한은 15분입니다
같은 세션 안에서 키가 전환됨원래 바인딩된 키가 쿨다운에 들어갔거나 비활성화됨이는 예상된 동작입니다. 시스템은 사용 가능한 최적의 키를 자동으로 선택합니다

관련 페이지​