멀티모델 AI 앱 구축: 라우팅과 폴백

프로덕션 AI 앱이라면 모델 장애가 나도 아무도 한밤중에 깨우지 않고 버텨야 합니다. 거기까지 데려다주는 패턴은 지루하지만 확실합니다. OpenAI 호환 클라이언트 하나, 우선순위가 매겨진 모델 목록, 저렴하면서도 건강한 프로바이더를 우선하는 라우팅 규칙, 그리고 엄격한 가격 상한입니다.

이 튜토리얼에서 만들 것:

• 문자열 하나만 바꿔서 GPT, Claude, Gemini, DeepSeek 등을 호출할 수 있는 단일 클라이언트

• 자동 폴백 — 기본 모델이 오류를 내거나 타임아웃되면 목록의 다음 모델로 요청을 재시도

• 비용 관리 — 최저가 우선 라우팅과 max_price 상한으로 트래픽 급증이 예산을 태워버리지 못하게 차단

• 지출 가시성 — 로그로 남기고 알림을 걸 수 있는 요청 단위 비용 집계

아래 내용은 모두 OpenRouter를 라우팅 계층으로 사용합니다. 같은 아키텍처는 OpenAI 호환 게이트웨이라면 어디서든 동작하며, 같은 앱에서 이미지·비디오·오디오 모델이 필요할 때는 APIMart에서도 그대로 쓸 수 있습니다.

멀티모델이 단일 모델을 이기는 이유

장애는 '만약'이 아니라 '언제'의 문제

주요 프로바이더는 모두 눈에 보이는 장애를 겪습니다. 앱이 한 벤더를 하드코딩하고 있다면 그 장애 하나하나가 곧 당신의 장애입니다. 폴백 체인은 "프로바이더 다운"을 잠깐의 지연 증가로 바꿔 줍니다.

모델마다 잘하는 영역이 다르다

싸고 빠른 모델은 분류와 추출을 맡고, 프런티어 모델은 추론이 많이 필요한 생성을 맡습니다. 작업별로 티어를 섞어 쓰는 것만으로 추론 비용이 절반 이하로 줄어드는 일이 흔합니다.

가격은 매달 바뀐다

모델 가격은 끊임없이 내려갑니다. 모델 교체가 한 줄 수정으로 끝난다면, 마이그레이션 프로젝트 없이도 분기마다 최고의 가격 대비 성능을 좇을 수 있습니다.

1단계: 클라이언트 하나, 모델 여러 개

공식 OpenAI SDK를 게이트웨이로 향하게 하면 됩니다. 커스텀 HTTP 코드는 필요 없습니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-..."
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Summarize this contract clause..."}],
)
print(resp.choices[0].message.content)

deepseek/deepseek-chat이나 google/gemini-2.5-pro로 바꾸는 것은 그저 다른 model 문자열일 뿐입니다. 모델 이름은 코드가 아니라 설정에 두세요.

TypeScript 버전

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Classify this ticket: ..." }],
});

흩어진 문자열이 아닌 모델 레지스트리

작업 → 모델 티어 매핑은 한 곳에 모아 둡니다.

{
  "extract": "deepseek/deepseek-chat",
  "chat": "anthropic/claude-sonnet-4.5",
  "reason": "openai/gpt-5.2"
}

2단계: 자동으로 발동하는 폴백

models 배열

기본 모델이 오류를 내거나, 레이트 리밋에 걸리거나, 타임아웃되면 OpenRouter가 서버 측에서 우선순위 목록을 따라 요청을 재시도합니다 ^[1].

{
  "model": "openai/gpt-5.2",
  "models": ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"],
  "messages": [{ "role": "user", "content": "..." }]
}

응답에는 실제로 어떤 모델이 요청을 처리했는지가 담겨 있습니다. 반드시 로그로 남기세요.

프로바이더 수준 페일오버

모델 폴백 아래 계층에서는 각 모델이 여러 프로바이더를 통해 제공될 수 있습니다. 라우팅 설정으로 특정 업스트림을 고정하거나 제외할 수 있습니다 ^[2].

{
  "model": "meta-llama/llama-3.3-70b-instruct",
  "provider": {
    "order": ["deepinfra", "together"],
    "allow_fallbacks": true
  }
}

클라이언트 측 최후의 보루

라우터 자체에 접근할 수 없는 드문 경우를 대비해, 다른 게이트웨이(또는 캐시된 응답)로 향하는 단 한 번의 재시도로 호출을 감싸세요. 재시도는 한 번으로 제한해야 합니다. 재시도 폭풍은 스스로 만든 장애입니다.

3단계: 우회할 수 없는 비용 관리

최저가 우선 라우팅

지연 시간이 부차적일 때는 프로바이더를 가격순으로 정렬하세요. 요청 단위로는 ("provider": {"sort": "price"}), 배치 작업에는 모델 접미사 :floor를 사용합니다.

엄격한 가격 상한

max_price는 상한(100만 토큰당 달러)을 넘는 견적을 낸 프로바이더를 모두 거부합니다.

{
  "model": "openai/gpt-5.2",
  "max_price": { "prompt": 1.5, "completion": 10 },
  "messages": [{ "role": "user", "content": "..." }]
}

이것은 선호가 아니라 보장입니다. 상한 안에서 처리할 수 없는 요청은 조용히 더 비싸지는 대신 즉시 실패합니다.

요청별 비용 추적

응답에는 usage가 포함됩니다. 실제 처리한 모델의 단가를 곱해 메트릭으로 내보내세요. 총지출만이 아니라 작업당 비용 드리프트에 알림을 걸어야 합니다. 더 비싼 모델로의 조용한 폴백은 바로 드리프트로 드러나기 때문입니다.

텍스트 너머로: 이미지·비디오·오디오에도 같은 패턴을

LLM 라우터는 언어 모델에서 멈춥니다. 실제 제품은 이미지, 비디오, 음성도 생성합니다. 그런데 벤더 SDK 다섯 개를 더 떠안으면 방금 해결한 문제가 그대로 되살아납니다.

모든 모달리티를 하나의 게이트웨이로

APIMart는 500개 이상의 모델 — 챗은 물론 GPT-Image-2, Sora 2, Kling, Veo, Suno — 를 하나의 OpenAI 호환 API와 하나의 잔액 뒤에서 제공합니다.

익숙한 통합 방식, 할인된 요금

클라이언트 설정은 base URL만 다를 뿐 1단계와 동일하며, 모델별 가격은 공식 정가보다 약 20% 낮습니다. 정확한 모델별 요금은 가격 페이지에서 확인하세요.

라우터를 섞어 써도 괜찮다

흔한 프로덕션 구성은 이렇습니다. 텍스트는 OpenRouter나 직접 API, 미디어 생성은 APIMart — 둘 다 코드에서는 같은 추상화 뒤에 있고, 둘 다 설정만으로 교체할 수 있습니다.

프로덕션 체크리스트

다섯 가지를 모두 갖추고 배포하세요. 설정 기반 모델 레지스트리, 서버 측 폴백 체인, 지연 시간이 허용하는 곳에서의 최저가 우선 라우팅, 모든 호출에 대한 max_price 상한, 드리프트 알림이 붙은 요청별 비용 메트릭. 이 조합이야말로 두 명뿐인 팀이 전담 온콜 없이 멀티모델 앱을 운영할 수 있게 해 주는 비결입니다.