저는 매일 수많은 모델을 테스트하며, 원하는 하네스(harness)로 테스트하고 싶은 모델 제공업체마다 별도의 API 키를 가지게 되는 상황을 반복해 왔습니다. 그래서 이를 실제로 해결할 수 있을지 확인하기 위해 로컬 머신에 Bifrost를 설치해 보기로 했습니다.

Bifrost는 Go 언어로 구축된 고성능 오픈 소스 AI 게이트웨이 (open-source AI gateway)입니다. 이 도구는 여러 AI 제공업체를 단일 OpenAI 호환 API 뒤에 배치하며, 초저지연 (ultra-low latency), 자동 장애 조치 (automatic failover), 부하 분산 (load balancing), 그리고 엔터프라이즈 거버넌스 (enterprise governance) 기능이 내장되어 있습니다.

이전에 LiteLLM을 사용해 보셨다면 이론적으로는 익숙하게 들릴 수 있지만, 실제 경험은 상당히 다릅니다. LiteLLM은 사용자가 직접 구성하고 실행해야 하는 Python 라이브러리 및 프록시 (proxy)인 반면, Bifrost는 전체 웹 대시보드가 내장된 독립형 Go 바이너리 (standalone Go binary)로 제공됩니다. 따라서 요청에 실제로 어떤 일이 일어나고 있는지 확인하기 위해 별도의 관측성 스택 (observability stack)을 구축할 필요가 없습니다. 아래에서 확인하시겠지만, 결과적으로 그 대시보드를 가장 많이 사용하게 되었습니다.

저는 이를 Claude Code 및 Codex와 유사한 오픈 소스 코딩 하네스(coding harness)인 OpenCode에 연결했습니다. 저는 OpenCode Zen 키와 Gemini 키를 사용하고 있으며, 이 둘을 통해 각 제공업체의 별도 대시보드를 건드리지 않고도 여러 SOTA (State-of-the-Art) 모델에 무료로 접근할 수 있습니다.

설치 및 설정

설치 및 설정은 매우 간단하고 빨랐습니다.

먼저, 다음 명령어를 사용하여 Bifrost CLI를 설치했습니다:

npx -y @maximhq/bifrost

참고: 이 명령어를 실행하려면 머신에 Node와 NPM이 설치되어 있어야 합니다. 그렇지 않으면 작동하지 않습니다. Node 버전을 설치하고 관리하는 방법을 알고 싶다면, 제가 이전에 작성한 이 블로그를 참고하세요.

이제 Bifrost를 실행할 차례입니다! 저는 디렉토리 수준에서 실행하고 있지만, 원한다면 시스템 수준에서도 실행할 수 있습니다. 이를 위해서는 Bifrost 문서 (Bifrost documentation)를 쉽게 따라 할 수 있습니다.

npx -y @maximhq/bifrost -app-dir ./my-bifrost-data

저는 작업 디렉토리에서 이 명령어를 실행했으며, 이를 통해 SQLite를 사용하여 설정 파일과 로그 데이터베이스 (logs db)가 생성됩니다.

또한, 이 명령은 8080 포트에서 대시보드를 노출하며, 그곳에서 API 키를 쉽게 설정하고 애플리케이션에서 사용할 수 있습니다. 이에 대한 자세한 내용은 이 블로그의 뒷부분에서 다루겠습니다.

제공자 (Providers) 연결하기

이제 API 키를 가져와 Bifrost에 연결할 차례입니다.

앞서 언급했듯이, 저는 Zen과 Gemini를 사용할 것입니다. 두 서비스 모두 관대한 무료 티어 (free tiers)를 제공하며, API 키를 발급받는 데 신용카드 정보가 필요하지 않습니다.

위의 스크린샷에서 볼 수 있듯이, 키를 추가하는 방법은 매우 간단합니다. 제공자 (provider)를 선택하고 키에 이름을 할당하기만 하면 준비가 끝납니다!

추가적으로, 특정 키에 허용된 모델 (allowed models)을 추가할 수도 있습니다. 대부분의 키는 매우 많은 사용 가능한 모델을 포함하고 있는데, 만약 이 모델들을 모두 사용하고 싶지 않거나 사용 가능한 풀 (pool)을 제한하고 싶다면 여기서 설정할 수 있습니다.

OpenCode와 통합하기

이제 제공자 (providers)를 Bifrost에 연결했고 Bifrost가 이미 실행 중이므로, 이제 Bifrost와 이 모델들을 OpenCode에 직접 통합할 수 있습니다.

Bifrost와 같은 연결을 추가하려면 설정 파일을 수동으로 편집해야 합니다. 사용 중인 운영 체제 (operating system)에 따라 설정 파일의 위치가 다를 수 있습니다. 이에 대한 더 자세한 정보는 OpenCode의 공식 문서에서 확인할 수 있습니다.

우리가 편집해야 할 파일은 opencode.json입니다. 제공자 (provider) 블록에 다음과 유사한 내용을 추가해야 합니다:

"bifrost-local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Bifrost Local",
...

참고: Bifrost의 공식 문서에 나와 있는 방식처럼 OpenCode의 내장 openai 프로바이더 (provider)를 단순히 Bifrost로 지정하는 대신, 저는 별도의 bifrost-local 프로바이더 (provider) 블록을 할당했습니다. 그 이유는 나중에 동일한 설정 파일에 실제 OpenAI 키를 연결하게 될 경우를 대비하여, 모델 선택기 (model selector)에서 어떤 모델이 Bifrost를 거치고 어떤 모델이 프로바이더 (provider)에 직접 연결되는지 시각적으로 명확하게 구분하고 싶었기 때문입니다. 두 방식 모두 기능적으로는 작동하지만, 저는 이처럼 분리해 두는 방식을 선호합니다.

이제 이 부분은 선택한 모델과 프로바이더 (provider)에 따라 달라질 수 있습니다. Bifrost 문서 자체에서 직접 확인하는 것이 가장 좋습니다.

이제 연결이 완료되었으므로, 터미널(또는 앱)에서 OpenCode를 실행할 수 있으며, 모델 선택기 (model selector)에서 다음과 같은 모습을 볼 수 있습니다:

이제 이 모델을 선택하여 OpenCode에서 작업을 수행할 수 있습니다.

하지만 잠시만요, 지금까지는 Bifrost가 모델 프로바이더 (provider)와 사용 도구 (harness) 사이에서 어떻게 위치하는지만 설명했습니다. 이제 핵심으로 들어가서 Bifrost로 무엇을 더 할 수 있는지 알아봅시다!

모니터링 및 LLM 로그 (Monitoring and LLM Logs)

Bifrost는 모델이 어떻게 성능을 내고 있는지, 토큰 (tokens) 소비량은 얼마인지, 지연 시간 (latency)과 비용은 어느 정도인지에 대해 명확한 이해를 제공합니다.

아래 스크린샷에서 Bifrost가 이를 어떻게 수행하는지 확인할 수 있습니다:

상세한 로그 (logs) 또한 확인하고 점검할 수 있습니다.

모든 데이터는 로컬 (locally)에 저장되며, 모델 프로바이더 (provider)로 전송하는 메시지(이는 당연한 부분입니다) 외에는 클라우드 (cloud)로 아무것도 전송되지 않습니다. 모든 것은 에어갭 (air-gaped) 상태로 유지됩니다.

자동 폴백을 이용한 모델 라우팅 (Model Routing using Automatic Fallback)

이제 가장 흥미로운 부분입니다. 모델을 어떻게 자동으로 라우팅 (route)할 수 있을까요?

운영 (production) 중에는 하나의 모델이 응답에 실패할 수 있으며, 이는 꽤 흔한 일입니다. 따라서 그러한 시나리오를 위해 다음과 같은 규칙을 설정할 수 있습니다.

모델 A를 사용할 수 없다면, 모델 B를 사용한다.

하지만 이것은 가장 단순한 버전입니다. CEL 표현식 (CEL expressions)을 사용하면 우리가 원하는 거의 모든 것에 대해 커스텀 라우팅 규칙 (custom routing rules)을 생성할 수 있습니다.

모델들을 사용할 수 있고 우리가 염두에 둔 특정 로직이 있다면, Bifrost에서 이를 쉽게 구현할 수 있습니다.

그러니 지금은 다음과 같은 간단한 규칙을 만들어 보겠습니다: 만약 Gemini 모델들을 사용할 수 없다면, 대신 Zen 모델을 통해 트래픽을 라우팅 (route)한다.

위 스크린샷에서 볼 수 있듯이, 저는 최대 우선순위 (maximum priority)를 가진 글로벌 규칙 (global rule)을 생성했습니다. 즉, 제공자 (provider)가 gemini이고 모델이 gemini-2.5-flash이며 사용자가 이를 구체적으로 사용하고 있다면, 대신 opencode-zen/big-pickle로 폴백 (fall back)하도록 설정했습니다.

이제 규칙이 설정되고 적용되었으므로, 어떤 일이 일어나는지 확인하기 위해 gemini 서비스를 일시적으로 비활성화하겠습니다.

OpenCode로 가서 "hi"라고 입력하고 어떤 일이 발생하는지 살펴보겠습니다.

보시다시피, 사용자는 어떠한 중단도 겪지 않았습니다. 실제로 여기서 어떤 일이 일어났는지 확인하기 위해 로그 (logs)를 살펴보겠습니다.

확인할 수 있듯이, gemini 모델이 에러를 발생시켰고, 자동으로 big-pickle로 폴백 (fall back)하여 저에게 응답을 주었습니다.

이것이 바로 Bifrost의 마법입니다.

복잡성 라우터 (The Complexity Router)

모델 라우팅 (Model Routing)에 대해 이해했으니, 이제 어떤 종류의 요청이 어떤 종류의 모델로 가야 하는지 어떻게 결정하고 설정할 수 있는지 알아보겠습니다.

예를 들어, 사소한 쿼리 (trivial queries)는 저렴한 모델로 라우팅하는 반면, 어려운 작업에는 비용이 많이 드는 모델을 아껴둘 수 있습니다.

아이디어는 간단합니다. 들어오는 요청을 단순 (simple), 중간 (medium), 복잡 (complex), 추론 (reasoning)의 네 가지 단계 (tiers)로 나누는 것입니다.

저는 저의 복잡성 라우팅 프로필 (complexity routing profile)을 구성했으며, 여러분도 각자의 요구 사항에 따라 쉽게 구성할 수 있습니다. 제 프로필은 다음과 같습니다:

단순 및 중간 단계의 쿼리에 대해서는 gemini 모델이 처리하도록 하고, 복잡 및 추론 기반의 쿼리에 대해서는 big-pickle로 가도록 하고 싶습니다.

이제 이를 위해 커스텀 라우팅 규칙 (custom routing rules)을 생성해야 합니다.

규칙이 생성되었으니, 이제 이를 테스트하고 LLM 로그를 확인해 보겠습니다. OpenCode에서 두 가지 쿼리를 보내보겠습니다:

• Hello, briefly define REST API. (gemini로 전달될 것으로 예상)
• How to debug an async API authentication failure step by step, explain the root cause, and recommend an architecture fix. (big-pickle로 전달될 것으로 예상)

위 스크린샷에서 볼 수 있듯이, 우리가 의도한 대로 정확하게 작동했습니다.

Bifrost는 훨씬 더 많은 것을 할 수 있습니다