모든 LLM API에는 상태가 나쁜 순간이 있습니다. 503, 타임아웃, 연속된 429. 대체 경로(fallback)가 있으면 그 순간이 앱 장애로 번지지 않습니다. 이 글에서는 OpenAI 호환 제공업체 간 페일오버를 직접 작성한 코드로 구현하는 방법을 보여 드립니다. 어떤 오류에서 전환해야 하는지, 서킷 브레이커로 어떻게 빠르게 유지하는지, 사용자가 전환을 눈치채지 못하려면 제공업체 간에 무엇이 같아야 하는지 다룹니다.
먼저 한 가지: BroadNet Inference는 제공업체 간 라우팅이나 페일오버를 대신해 주지 않으며, BroadRouter도 마찬가지입니다. BroadRouter는 BroadNet의 웹사이트이지 라우터가 아닙니다. 대체 경로는 아래처럼 클라이언트에 직접 구축하거나 LiteLLM 같은 게이트웨이에 구축해야 합니다.
대체 제공업체를 왜 두어야 하나요?
대부분의 셀프서비스 API는 가동 시간에 대해 아무것도 약속하지 않기 때문입니다. BroadNet 약관 7.4항은 “self-serve has no availability commitment”(번역: 셀프서비스에는 가용성 약정이 없음)라고 분명히 밝히며, 서비스 수준은 별도의 서면 계약에서만 정해집니다(2026년 11월 15일 확인). 다른 제공업체가 무엇을 약정하는지는 LLM API SLA 비교에서 다룹니다. 기능이 계속 살아 있어야 한다면, SLA 내용과 상관없이 두 번째 제공업체가 현실적인 보험입니다.
두 번째 이유는 속도 제한입니다. BroadNet 종량제 키는 분당 요청 30개, 동시 요청 4개까지 허용합니다. 이를 넘는 트래픽 급증은 429를 반환하며, 용량을 늘리는 동안 두 번째 제공업체가 넘치는 요청을 받아 줄 수 있습니다.
어떤 오류에서 페일오버해야 하나요?
오류를 두 그룹으로 나누세요. 일부는 제공업체 쪽 문제라 다른 곳에서는 성공할 수 있습니다. 나머지는 내 쪽 문제라 어디서든 실패합니다.
| 오류 | 페일오버? | 이유 |
|---|---|---|
| 연결 오류, 타임아웃 | 예, 재시도 후 | 제공업체나 네트워크에 연결할 수 없음 |
| 500, 502, 503, 504 | 예, 재시도 후 | BroadNet 문서는 먼저 “retry with bounded exponential backoff”(번역: 상한을 둔 지수 백오프로 재시도)하라고 안내 |
| 429, 속도 또는 동시 처리 한도 | 예, 백오프 후 | 이 제공업체의 용량 문제이지 잘못된 요청이 아님 |
| 429, 지출 한도 | 아니요 | 페일오버하면 일부러 정한 예산을 우회하게 됨 |
| 400, 422 | 아니요 | 요청이 잘못되었으므로 다음 제공업체에서도 실패함 |
| 401, 402 | 아니요 | 키, 허용량 또는 잔액 문제. BroadNet에서 401은 종량제 허용량 소진도 포함하므로, 페일오버하면 결제 문제가 가려짐 |
| 403, 413 | 아니요 | 정책이나 크기 문제이므로 요청을 수정 |
BroadNet API 레퍼런스에 따르면 429는 “a rate, concurrency, token-rate or spending limit was reached”(번역: 속도, 동시 처리, 토큰 속도 또는 지출 한도에 도달함)를 뜻하며, “use response details and bounded backoff”(번역: 응답 세부 정보와 상한을 둔 백오프를 사용)하라고 안내합니다. 페일오버하기 전에 이 세부 정보를 읽어서, 지출 한도 429라면 요청을 다른 곳으로 옮기지 말고 중단하세요. 모든 상태 코드는 오류 코드 가이드에 정리되어 있습니다.
페일오버 전에 먼저 재시도하세요. OpenAI Python SDK는 연결 오류, 408, 409, 429, 5xx 응답을 이미 “2 times by default, with a short exponential backoff”(번역: 기본적으로 짧은 지수 백오프로 2회) 재시도하며, 기본 타임아웃은 10분입니다(README, 2026년 11월 15일 확인). 페일오버 전에 10분을 기다리는 것은 너무 깁니다. 클라이언트마다 timeout을 설정하세요. 지터를 둔 백오프는 429 처리 글에서 다룹니다.
Python으로 페일오버를 구현하면 어떤 모습인가요?
클라이언트 두 개, 순서가 있는 목록, 작은 서킷 브레이커 하나입니다. 기본 제공업체는 BroadNet의 GLM 5.3이고, 백업은 DeepInfra의 같은 오픈 웨이트 모델입니다. DeepInfra 문서에 나온 base URL은 https://api.deepinfra.com/v1/openai입니다(2026년 11월 15일 확인).
import os
import time
from openai import (OpenAI, APIConnectionError, APITimeoutError,
RateLimitError, InternalServerError)
PROVIDERS = [
{"name": "broadnet", "model": "broadnet/glm-5.3",
"client": OpenAI(base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
max_retries=2, timeout=60)},
{"name": "deepinfra", "model": "zai-org/GLM-5.3",
"client": OpenAI(base_url="https://api.deepinfra.com/v1/openai",
api_key=os.environ["DEEPINFRA_API_KEY"],
max_retries=2, timeout=60)},
]
# Provider-side failures only. 400, 401, 402, 403 and 422 raise straight through.
FAILOVER_ON = (APIConnectionError, APITimeoutError, RateLimitError, InternalServerError)
TRIP_AFTER = 3 # consecutive failures before the breaker opens
COOLDOWN = 30 # seconds to skip a provider once its breaker is open
state = {p["name"]: {"fails": 0, "open_until": 0.0} for p in PROVIDERS}
def chat(messages, **kwargs):
last_error = None
for p in PROVIDERS:
s = state[p["name"]]
if time.monotonic() < s["open_until"]:
continue # breaker open: don't wait on a provider that is down
try:
reply = p["client"].chat.completions.create(
model=p["model"], messages=messages, **kwargs)
s["fails"] = 0
return p["name"], reply
except FAILOVER_ON as err:
last_error = err
s["fails"] += 1
if s["fails"] >= TRIP_AFTER:
s["open_until"] = time.monotonic() + COOLDOWN
raise RuntimeError("every provider failed") from last_error
served_by, reply = chat([{"role": "user", "content": "Reply with one short sentence."}],
max_tokens=1000)
print(served_by, reply.model, reply.choices[0].message.content)
중요한 세부 사항 네 가지:
- 예외 클래스. SDK는 429에
RateLimitError, 500 이상에InternalServerError, 연결할 수 없을 때APIConnectionError(하위 클래스로APITimeoutError)를 발생시킵니다. 나머지는 일부러 잡지 않습니다. 지출 한도 429를 제외하려면 계속 진행하기 전에err.response를 확인하세요. - 서킷 브레이커. 이것이 없으면 기본 제공업체가 죽어 있을 때 모든 요청이 다음으로 넘어가기 전에 타임아웃 전체를 기다립니다. 연속 세 번 실패하면 기본 제공업체를 30초 동안 건너뜁니다. 그 뒤 다음 요청이 다시 시험합니다.
- 누가 응답했는지 기록하기. 제공업체 이름을 반환하고
reply.model을 보관하세요. 품질이 달라졌을 때 어느 제공업체가 답했는지 알아야 합니다. - 추론 예산. GLM 5.3은 답하기 전에 추론합니다. BroadNet 문서에 따르면 추론은
max_tokens에 포함되므로, 모든 제공업체에서 1,000 이상을 남겨 두세요.
제공업체 간 모델 ID는 어떻게 매핑하나요?
같은 오픈 웨이트 모델이라도 호스트마다 ID가 다르고, 각 호스트가 명시하는 기능도 다를 수 있습니다. 2026년 11월 15일 기준 GLM 5.3:
| BroadNet Inference | DeepInfra | Fireworks AI | |
|---|---|---|---|
| 모델 ID | broadnet/glm-5.3 |
zai-org/GLM-5.3 |
accounts/fireworks/models/glm-5p3 |
| 컨텍스트 | 1,048,576토큰 | 1,048,576토큰 | “1040k” 토큰 |
| 도구 | 문서화됨 | “Function” 표시 | 지원 |
| 구조화된 출력 | 문서화됨 | “JSON” 표시 | 확인하지 않음 |
여기서 규칙 두 가지가 나옵니다. 첫째, 매핑은 코드 곳곳에 흩어 두지 말고 설정에 두세요. 둘째, 대체 경로를 요청이 쓰는 기능에 맞추세요. BroadNet에서 도구와 구조화된 출력이 문서화된 모델은 GLM 5.3과 Qwen3.8 27B뿐입니다. 도구 호출 에이전트는 GLM 5.3에서 다른 곳의 GLM 5.3으로 페일오버할 수 있지만, 도구를 문서화하지 않은 모델로는 안전하게 페일오버할 수 없습니다. 백업의 컨텍스트 윈도우가 더 작다면 프롬프트를 줄이거나, 긴 요청에서는 그 백업을 건너뛰세요. 제공업체 14곳의 base URL은 base URL 레퍼런스에 있습니다.
전환 후에도 답변 품질을 비슷하게 유지하려면 어떻게 하나요?
같은 가중치라도 호스트 두 곳에서 다르게 답할 수 있습니다. 호스트마다 정밀도, 채팅 템플릿, 기본 파라미터가 다를 수 있기 때문입니다. 다른 모델이라면 확실히 다르게 답합니다.
- 기본 제공업체뿐 아니라 목록의 모든 항목에 대해 평가 세트를 실행하세요.
- 요청마다
temperature,max_tokens, 시스템 프롬프트를 고정해서 제공업체 기본값이 출력을 바꾸지 못하게 하세요. - 모든 경로에서 구조화된 출력을 같은 방식으로 검증하세요. 복구 후 재시도 루프는 잘못된 JSON 고치기에서 다룹니다.
- 같은 호스트의 다른 모델보다 다른 곳의 같은 모델을 우선하세요. 사용자는 몇 초의 지연보다 문체 변화를 더 쉽게 알아챕니다.
스트리밍과 도구 호출은 어떻게 하나요?
스트림은 중간에 실패할 수 있습니다. BroadNet 문서에 따르면 data: [DONE] 전에 끝난 스트림은 불완전한 것으로 취급해야 합니다. X-Request-ID를 기록하고, 애플리케이션이 새 요청을 안전하게 보낼 수 있는지 판단하세요.
- 첫 토큰 전: 자유롭게 페일오버하세요. 사용자는 아직 아무것도 보지 못했습니다.
- 토큰이 이미 표시된 후: 백업에서 다시 시작해 부분 답변을 교체하거나, 재시도 버튼과 함께 오류를 보여 주세요. 두 제공업체의 반쪽 답변을 이어 붙이면 읽기 어색합니다.
- 부수 효과가 있는 도구 호출: 모델 호출이 실패했다는 이유만으로 이메일 전송, 카드 결제, 데이터베이스 쓰기 단계를 다시 실행하지 마세요. 각 동작에 멱등성 키를 부여하세요. 체크포인트는 장시간 실행 에이전트에서 다룹니다.
일찍 끝난 스트림을 감지하는 방법은 SSE 스트리밍에서 설명합니다.
페일오버에는 어떤 비용이 드나요?
- 중복 작업. 내 쪽에서 타임아웃이 났다고 해서 제공업체가 멈췄다는 보장은 없습니다. 토큰당 과금에서는 재시도할 때마다 새로운 추론이므로, 일부 요청에는 두 번 비용을 낸다고 예상하세요.
- 다른 가격. 백업은 자체 단가로 과금합니다. DeepInfra는 2026년 11월 15일에 GLM-5.3을 프로모션 가격으로 올려 두었으므로, 예산을 잡기 전에 다시 확인하세요. BroadNet은 100만 토큰당 입력 $0.78, 캐시된 입력 $0.173, 출력 $3.46 요금입니다.
- 차가운 캐시. 캐시된 입력은 제공업체 간에 옮겨지지 않습니다. 백업의 첫 요청들은 기본 제공업체에서 캐시되어 있던 접두부에 대해 전체 입력 가격을 냅니다. 캐시된 입력 토큰을 참고하세요.
- 헤징. 모든 요청을 두 제공업체에 동시에 보내고 먼저 온 답을 쓰면 꼬리 지연이 줄지만, 청구액은 대략 두 배가 됩니다. 지연 시간이 그만한 가치가 있는 곳에서만 쓰세요.
대체 제공업체도 같은 데이터 조건을 충족하나요?
대체 제공업체는 같은 프롬프트를 받는 또 하나의 처리자입니다. 고객에게 데이터에 관해 약속한 것이 있다면, 그 약속은 목록의 모든 항목에서 지켜져야 합니다.
BroadNet 개인정보 처리 방침은 “We do not retain prompts, audio, images, answers or transcripts”(번역: 프롬프트, 오디오, 이미지, 답변, 전사본을 보관하지 않습니다)라고 밝힙니다. 추론 콘텐츠는 보관되지 않으며, 필요한 계정·결제·보안 메타데이터는 방침에 설명된 대로 보관됩니다. 또한 추론 데이터를 모델 학습, 파인튜닝, 평가에 사용하지 않는다고 밝힙니다. 방침에 따르면 호스팅 모델은 “run on BroadNet-owned or leased hardware in the United States, with partner capacity as backup”(번역: 미국 내 BroadNet 소유 또는 임차 하드웨어에서 실행되며, 파트너 용량을 백업으로 사용)하며, DeepSeek V4.1 Flash는 파트너가 호스팅합니다. 데이터 상주 요건이 있는 데이터라면, 약관(7.3a항)은 보내기 전에 처리 위치를 합의하라고 안내합니다. 백업에 대해서도 같은 항목을 확인하세요. 보관, 학습 사용, 위치, 하위 처리자입니다. 미흡하다면 민감한 요청은 대체 경로에서 제외하고 실패 시 차단(fail closed)하세요. 확인할 질문은 데이터 비보관 체크리스트에 정리되어 있습니다.
LiteLLM 같은 게이트웨이를 대신 쓰는 게 나을까요?
여러 서비스에 같은 대체 규칙이 필요하다면 게이트웨이를 쓰세요. LiteLLM 프록시는 순서대로 시도하는 fallbacks 목록을 받습니다. num_retries는 대체 경로로 넘어가기 전에 모델 그룹을 재시도합니다. allowed_fails와 cooldown_time은 실패하는 배포를 잠시 제외하므로 서킷 브레이커 역할을 합니다. 별도의 context_window_fallbacks와 content_policy_fallbacks가 해당 오류 유형을 처리합니다(LiteLLM 문서, 2026년 11월 15일 확인).
model_list:
- model_name: glm
litellm_params:
model: openai/broadnet/glm-5.3
api_base: https://inference.broadnet.ai/v1
api_key: os.environ/BROADNET_API_KEY
- model_name: glm-backup
litellm_params:
model: openai/zai-org/GLM-5.3
api_base: https://api.deepinfra.com/v1/openai
api_key: os.environ/DEEPINFRA_API_KEY
router_settings:
fallbacks: [{"glm": ["glm-backup"]}]
allowed_fails: 3
cooldown_time: 30
litellm_settings:
num_retries: 2
request_timeout: 60
BroadNet 항목 전체는 LiteLLM 프록시 가이드에 있습니다. 두 항목 모두 LiteLLM의 범용 openai/ 접두사와 api_base를 쓰며, 가이드와 같은 패턴입니다. 게이트웨이는 홉을 하나 늘리고, 계속 운영해야 할 대상을 하나 더 만듭니다. 앱 하나라면 위처럼 클라이언트 코드 40줄 정도로 충분합니다.
필요해지기 전에 페일오버를 어떻게 테스트하나요?
- 테스트 설정에서 기본 제공업체를 연결할 수 없는 호스트로 지정하고, 요청이 백업으로 가는지 확인하세요.
- 일부러 잘못된 요청을 보내고, 페일오버가 일어나지 않는지 확인하세요.
- 잘못된 기본 키를 쓰고, 401이 조용한 전환이 아니라 오류로 드러나는지 확인하세요.
- 브레이커를 지켜보세요. 세 번 실패한 뒤에는 타임아웃을 기다리지 않고 기본 제공업체를 건너뛰어야 합니다.
- 백업이 트래픽의 작은 비율 이상을 처리하면 알림을 보내세요. 조용한 페일오버는 고장 난 기본 제공업체를 며칠씩 가릴 수 있습니다.
LiteLLM의 Router는 직접 테스트에서 mock_testing_fallbacks=True를 받아 대체 경로를 강제로 실행합니다.
BroadNet Inference는 어디에 적합한가요?
BroadRouter는 BroadNet의 웹사이트이며, BroadNet Inference는 목록의 어느 자리에든 들어갈 수 있습니다. 기본 제공업체로 쓰면 도구와 구조화된 출력이 문서화된 GLM 5.3과 Qwen3.8 27B, 그리고 Gemma 4 VL 26B와 DeepSeek V4.1 Flash를 콘텐츠 보관 없이 하나의 base URL로 제공합니다. 백업으로 쓰면 목록에 추가할 OpenAI 호환 엔드포인트가 하나 더 생깁니다. 어느 쪽이든 페일오버 로직은 직접 만들어야 합니다. BroadNet은 제공업체 간 라우팅을 하지 않으며, 셀프서비스에는 SLA가 없습니다. 계약된 서비스 수준이 필요하다면 별도의 서면 계약으로만 가능합니다. 모델을 비교하거나, 계정을 만들고 $5 금액의 초기 크레딧으로 Gemma 4 VL 26B에서 페일오버 체인을 시험해 보세요. GLM 5.3과 Qwen3.8 27B는 충전이 필요합니다.
