여러 개의 LLM 제공업체(provider)를 사용하여 무언가를 구축해 본 경험이 있다면 그 어려움을 알고 있을 것입니다. 여기는 OpenAI의 SDK가 있고, 저기는 Anthropic의 SDK가 있으며, 이들을 비슷하게 보이게 만드는 래퍼(wrapper)가 필요하고, 새벽 2시에 작성하여 완전히 신뢰하지 못하는 재시도 로직(retry logic)을 구현해야 합니다. LLM 게이트웨이(LLM gateway)는 이러한 문제를 해결해 주어야 합니다. 즉, 단일 엔드포인트(endpoint)로 어떤 모델이든 사용할 수 있게 하고 복잡한 연결 구조(plumbing)를 대신 처리해 주는 것입니다.
Respan Gateway는 Rust로 작성되었으며 10월부터 공개된 새로운 오픈 소스 프로젝트입니다. 저는 이 게이트웨이를 제 Windows PC에 설치하고, Gemini를 대상으로 지정한 다음, 의도적으로 한 제공업체를 고장 내보고 실제로 작동하는지 확인해 보았습니다. 아래 내용은 그 실행 과정에서 얻은 모든 정보입니다: 실제 명령어, 실제 타이밍, 실제 스크린샷.
Respan Gateway란 무엇인가
Respan Gateway는 사용자의 코드와 AI API 사이에 위치하는 단일 바이너리(single binary)입니다. 이미 사용하고 있는 SDK(OpenAI, Anthropic 또는 Gemini)를 이 게이트웨이를 향하도록 지정하면, 어떤 모델을 요청하든 상관없이 해당 모델 제공업체가 이해할 수 있는 형식으로 요청을 변환해 줍니다.
제가 이 게이트웨이를 실행하기 전에 눈에 띈 점들은 다음과 같습니다:
- 모든 것이 플러그인(plugin)입니다. 제공업체, 라우팅(routing), 가격 책정(pricing), MCP 및 트레이싱(tracing) 기능이 모두 동일한 공개 Rust API를 기반으로 구축되어 있어 사용자가 직접 기능을 추가할 수 있습니다.
- 16개의 제공업체가 내장되어 있습니다. OpenAI, Anthropic, Gemini, xAI, DeepSeek, Mistral, Groq, OpenRouter, Ollama, vLLM을 포함하며, 모든 OpenAI와 호환되는 엔드포인트도 지원합니다.
- MIT 또는 Apache-2.0 라이선스를 따르며, 자체 호스팅(self-hosted)이 가능하고 무료입니다.
- 실시간 요청 로그, 플레이그라운드(playground), 라우트 디버거(route debugger)가 있는 내장 웹 UI를 제공합니다.
Windows에 설치하기
Respan의 문서는 네 가지 설치 방법을 나열합니다: pip install respan-gateway (컴파일된 바이너리를 포함하고 Windows를 지원함), cargo install, 릴리스 zip 파일, 또는 Docker입니다. Linux 환경에서는 pip install이 약 3초가 걸렸습니다.
내 설정
별도의 설정 없이 시작할 수 있습니다. 제공자 키(provider key)를 내보내고 respan-gateway를 실행하기만 하면 됩니다. 이번 테스트에서는 의도적으로 고장 낼 수 있는 폴백 경로(fallback route)가 필요했기 때문에, 작은 gateway.toml 파일을 작성했습니다. 이 파일은 실제 제공자로 Gemini를 사용하며, 아무것도 수신하지 않는 로컬 포트를 가리키는 down이라는 이름의 제공자도 포함하고 있습니다:
[providers.gemini]
vendor = "gemini"
key = "env:GEMINI_API_KEY"
# 포트 9에서는 아무것도 수신하지 않음: 이 제공자는 의도적으로 "다운" 상태임
[providers.down]
formats = ["openai-chat"]
base_url = "http://127.0.0.1:9/v1"
# 아무런 설정이 없는 "gemini-*" 모델은 먼저 죽은 제공자를 시도하고, 그 다음 Gemini를 사용함
[routes."gemini-*"]
to = ["down/{model}", "gemini/{model}"]
tries = 2
backoff = "200ms"
키는 설정 파일 옆의 .env 파일에 위치하며, 게이트웨이는 시작 시 이 파일을 읽습니다. 시작하기 전에 respan-gateway check는 해당 파일을 검증하고 제공자(providers), 엔드포인트(endpoints), 경로(routes), 그리고 인증 여부(auth) 등 실제로 어떤 것을 제공할지 정확하게 출력합니다. 덕분에 추측하며 재시작하는 반복 과정을 줄일 수 있었습니다. 포트에 대한 참고 사항: 게이트웨이의 기본값은 8080입니다. 제가 최종적으로 실행했을 때는 이전 테스트가 아직 8080을 사용하고 있었기 때문에 --listen 127.0.0.1:8081로 시작했습니다. 따라서 스크린샷에는 8081이 표시됩니다. 이 글의 코드는 기본값인 8080을 사용합니다.
동일한 설정이 비밀 정보가 숨겨진 웹 UI에서도 표시됩니다:
제가 마음에 들었던 기본 기능 중 하나는, 클라이언트 키가 설정되지 않은 경우 게이트웨이가 루프백(loopback) 주소에서만 응답하고 공용 주소에서는 시작을 거부한다는 점입니다. 설정을 잊어버려서 실수로 제공자 키를 노출하는 일이 발생하지 않습니다.
모든 SDK, 모든 모델
이 기능이 핵심 기능이라 가장 먼저 테스트해 보았습니다. 동일한 프롬프트를 gemini/gemini-3.5-flash-lite에 두 번 전송했습니다: 한 번은 Anthropic Messages 형식(POST /v1/messages)으로, 다른 한 번은 OpenAI Chat 형식(POST /v1/chat/completions)으로 보냈습니다. 둘 다 각각 1.03초와 1.52초 만에 올바르게 응답했습니다.
[ ]
게이트웨이는 Anthropic 형식의 요청을 Gemini 호출로 변환하고, 응답을 다시 Anthropic 형태(input_tokens, output_tokens)에 맞춰 번역했습니다. UI의 요청 상세 정보에서 이를 명확히 확인할 수 있습니다: format anthropic-messages, provider gemini.
[ ]
Playground에서는 이 부분이 더욱 눈에 띕니다. 저는 Anthropic Messages API와 Gemini 모델을 선택했고, 응답에는 "gemini가 제공함(served by gemini)" 및 "Anthropic Messages에서 번역됨(translated from Anthropic Messages)"이라는 레이블이 붙었습니다:
[ ]
코드로 보면 핵심은 간단합니다. 클라이언트를 유지하고, 기본 URL만 변경하며, 모델 문자열만 바꾸면 됩니다.
from anthropic import Anthropic
client = Anthropic(base_url="[http://localhost:8080](http://localhost:8080)", api_key="unused")
reply = client.messages.create(
model="gemini/gemini-3.5-flash-lite",
max_tokens=1024,
messages=[{"role": "user", "content": "In one sentence, what does an LLM gateway do?"}],
)
과정에서 제가 마주친 두 가지 문제는 게이트웨이의 잘못은 아니었습니다:
- Google이 모델을 단종시켰습니다. 제가 처음 선택한 gemini-2.5-flash가 신규 사용자에게 폐쇄되었습니다. 게이트웨이는 Google 자체의 404 메시지를 그대로 전달했기 때문에 무엇을 변경해야 할지 명확했습니다.
- 사고(Thinking) 토큰이 예산을 많이 소모합니다. Gemini 3.5 Flash를 사용하고 max_tokens=150으로 설정했을 때, 모델은 사고에 140개의 토큰을 사용했고 잘린 답변을 반환했습니다. 게이트웨이는 이를 사용량(thinking_tokens: 140)에 정직하게 보고했습니다. 예산을 늘리고 Flash Lite를 사용하자 문제가 해결되었고, 응답 시간은 약 1초로 줄었습니다.
폴백 (Fallback): 의도적으로 제공자 장애 발생시키기
제가 가장 중요하게 테스트한 부분입니다. 저는 gemini-* 경로와 일치하는 순수 모델 이름인 gemini-3.5-flash-lite를 요청했습니다. 게이트웨이는 먼저 다운(down)을 시도하고, 실패하며 재시도(retries)한 후, Gemini로 폴백합니다. 이 과정을 세 번 실행했습니다:
모든 호출은 올바른 답변과 함께 200으로 반환되었습니다. 클라이언트는 실패를 전혀 감지하지 못했습니다. 흥미로운 부분은 세 번째 호출입니다: 네 번의 실패 후, 게이트웨이는 쿨다운(cooldown) 상태에 들어가서 해당 요청을 건너뛰었고, 그 결과 요청이 0.79초 만에 바로 Gemini로 전달되었습니다.
첫 두 번의 호출은 각각 약 5초가 걸렸습니다. 이 시간 대부분은 아마도 Windows가 연결되지 않은 로컬 포트로 재시도(tries = 2로 배수 증가)하다가 결국 실패하는 과정일 것입니다. 빠르게 오류를 반환하는 제공자가 훨씬 더 빨리 장애 전환을 할 수 있습니다. 어느 쪽이든, 사용자의 환경에 맞춰 tries와 backoff 설정을 조정할 가치가 있습니다.
게이트웨이 자체 로그도 같은 이야기를 합니다. 세 번째 줄은 순수 모델 이름이 gemini로 라우팅된 것을 보여줍니다:
[ ]
제가 가장 좋아하는 디버깅 기능은 Routes 페이지에 있습니다. "Try a model"에 모델 이름을 입력하면 요청이 어디로 가고 왜 그렇게 되는지 보여줍니다. 여기서는 아무것도 보내지 않았음에도 불구하고 100% 오류율과 Gemini가 682ms라는 것을 보여줍니다:
[ ]
실패 후(failed-over) 요청 중 하나에 대한 상세 보기에서는 전체 4.97초가 걸렸으며 Gemini가 이를 처리했음을 보여줍니다:
[ ]
Routes는 단순한 폴백(fallback) 이상의 기능을 수행할 수 있습니다. 가장 저렴하거나, 가장 빠르거나, 가중치 기반 또는 무작위로 **선택(pick)**할 수 있고, 느린 호출을 두 번째 제공업체와 **헤지(hedge)**할 수 있습니다 (헤지 = "200ms"). needs = ["tools"]를 사용하여 필터링하거나, 제가 사용한 것과 같은 글로브(globs)를 일치시킬 수 있습니다. 설정 변경은 재시작 없이 다시 로드됩니다 (--watch 또는 SIGHUP).
웹 UI (Web UI)
http://localhost:8080/ui/를 열면 사후에 추가된 것이 아니라 제대로 된 대시보드를 얻을 수 있습니다. 제가 깨끗하게 실행한 결과: 5개의 요청, 0% 오류율, 입력 및 출력 토큰, 그리고 제공업체별 통계가 표시됩니다.
[ ]
요청(Requests) 페이지는 모델, 엔드포인트, 제공업체, 상태, 지연 시간(latency), 토큰 등 모든 호출에 대한 실시간 로그를 제공하며, 필터 및 내보내기 기능도 포함합니다:
제공자(Providers) 섹션은 각 업스트림(upstream)이 무엇을 제공하는지, 그리고 어떤 형식들(formats)을 지원하는지를 보여줍니다: