Skip to main content

​
OpenRouter

OpenRouter는 여러 모델 공급자를 단일 API 패턴으로 다룰 수 있게 해줍니다. 핵심은 “호출 편의성”이 아니라 “라우팅 정책과 비용 통제”입니다.

​
학습 목표

  • 모델 라우팅과 fallback 개념을 이해합니다.
  • 비용/지연시간/품질 균형으로 모델 선택 정책을 세울 수 있습니다.
  • 운영 중 모델 교체/장애 대응 절차를 설계할 수 있습니다.

​
왜 OpenRouter인가

직접 각 모델 공급자(OpenAI, Anthropic, Google 등)를 따로 호출할 수도 있지만, 모델이 3개 이상이 되면 다음 문제가 발생합니다.
  • API 키 관리가 분산됩니다.
  • 장애 발생 시 수동으로 코드를 바꿔야 합니다.
  • 비용 추적이 공급자별로 파편화됩니다.
OpenRouter는 단일 엔드포인트로 이 문제를 해결합니다.

​
기본 호출 구조

OpenAI SDK 호환 API를 사용하므로, 기존 코드에서 base_url과 api_key만 교체하면 됩니다. 
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-..."  # 환경변수로 관리
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "HTTP-Referer": "https://your-app.com",
        "X-Title": "Your App Name"
    }
)
print(response.choices[0].message.content)
API 키는 절대 코드에 하드코딩하지 마세요. .env 파일이나 시크릿 매니저를 사용하세요.

​
기본 운영 모델

  • 기본 모델(primary): 평시 요청 처리
  • 대체 모델(fallback): 장애/제한 시 자동 전환
  • 태스크별 모델 정책: 요약, 추출, 코드 생성 등 목적별 분리

​
라우팅 전략 설계

​
태스크별 모델 매핑 예시

태스크Primary 모델Fallback 모델선택 기준
코드 생성anthropic/claude-sonnet-4openai/gpt-4o정확도 우선
요약/추출openai/gpt-4o-minigoogle/gemini-flash-2.0비용 우선
임베딩openai/text-embedding-3-small—단일 모델
한국어 특화anthropic/claude-sonnet-4openai/gpt-4o한국어 품질

​
Fallback 조건 정의

fallback_policy:
  triggers:
    - status_code: [429, 500, 502, 503]
    - timeout_ms: 30000
    - rate_limit_remaining: 0
  max_retries: 2
  retry_delay_ms: 1000
  fallback_order:
    - "anthropic/claude-sonnet-4"
    - "openai/gpt-4o"
    - "google/gemini-2.0-flash"

​
비용 관리

​
비용 구조

OpenRouter 비용 = 모델 원가 + OpenRouter 마진(일부 모델은 무마진) 
# 비용 조회 예시
import httpx

resp = httpx.get("https://openrouter.ai/api/v1/models")
for model in resp.json()["data"]:
    pricing = model.get("pricing", {})
    print(f"{model['id']}: prompt=${pricing.get('prompt', 'N/A')}/1K, "
          f"completion=${pricing.get('completion', 'N/A')}/1K")

​
비용 통제 체크리스트

  1. 일일 예산 설정: OpenRouter 대시보드에서 일일/월간 한도를 설정합니다.
  2. 사용량 경보: 예산의 70%, 90% 도달 시 알림을 받습니다.
  3. 토큰 추적: 요청별 usage.prompt_tokens, usage.completion_tokens를 로깅합니다.
  4. 모델별 비용 집계: 일간 단위로 모델별 비용을 리포팅합니다.

​
정책 설계 포인트

  1. 요청 타입별 모델 우선순위를 정의합니다.
  2. 실패 기준(타임아웃, 5xx, rate limit)을 정의합니다.
  3. fallback 전환 조건을 명시합니다.
  4. 비용 상한과 일일 사용량 경보를 설정합니다.
  5. 프롬프트 버전과 응답 품질 지표를 함께 추적합니다.

​
실무 지표

지표설명목표 기준
요청 성공률2xx 응답 비율> 99%
p95 지연시간95번째 백분위 응답 시간< 5s (생성 태스크)
토큰 사용량/비용일간 토큰 소비와 비용예산 내
fallback 발생 비율대체 모델 전환 횟수< 5%
모델별 품질 지표업무별 정확도/만족도태스크별 정의

​
모델 교체 프로세스

1

샘플셋 평가

기존 모델과 신규 모델을 동일한 테스트셋(최소 50건)으로 비교합니다.
2

Shadow 모드 운영

실제 트래픽의 10%를 신규 모델로 동시 전송하고 응답을 비교합니다.
3

단계적 전환

품질 확인 후 10% → 50% → 100%로 단계적으로 전환합니다.
4

롤백 준비

전환 후 24시간은 기존 모델을 즉시 복원 가능한 상태로 유지합니다.
모델 변경은 회귀 테스트 없이 바로 반영하면 품질 저하를 발견하기 어렵습니다. 샘플셋 평가 + 단계적 트래픽 전환으로 반영하세요.
fallback 비율이 오르면 기본 모델 안정성, 레이트 리밋, 네트워크 지연을 함께 점검해야 합니다. 단순히 대체 모델 품질 문제로 단정하지 마세요.
프롬프트는 코드처럼 버전 관리하고, 실험 결과(지표/샘플)를 같이 기록하세요.
OpenAI는 TPM(토큰/분), Anthropic은 RPM(요청/분) 기준이 다릅니다. OpenRouter가 통합하지만, 원 공급자의 제한을 알아야 fallback 원인을 진단할 수 있습니다.

​
체크리스트

  • 모델 라우팅 정책이 문서화되어 있나요?
  • fallback 조건과 우선순위가 정의됐나요?
  • 비용 상한과 알림이 설정됐나요?
  • 모델 교체 시 회귀 평가 프로세스가 있나요?
  • API 키가 환경변수로 관리되고 있나요?
  • 토큰 사용량/비용 로깅이 활성화됐나요?