Provider 라우팅

한 모델을 서빙하는 곳은 여러 군데일 수 있습니다 — 우리 GPU 의 슬롯, 외부 provider, 때로는 양쪽 다. 요청 본문의 provider 객체로 그중 무엇을 받아들일지, 어떤 순서로 시도할지 지정합니다.

{
  "model": "google/gemma-4-26b-a4b",
  "provider": { "only": ["local-gpu"], "sort": "price" },
  "messages": [{ "role": "user", "content": "…" }]
}

provider 객체가 아예 없으면 후보는 priority 순으로 정렬되고, 그 결과 로컬 GPU 슬롯이 맨 앞에 옵니다. 로컬 우선 라우팅 을 보세요.

Provider slug

order, only, ignore 에 넣는 값은 provider slug 입니다. 목록은 이렇게 봅니다.

curl https://openrouter.myip.co.kr/api/v1/providers

{
  "data": [
    { "name": "MyIP Local GPU", "slug": "local-gpu", "model_count": 4,
      "privacy_policy_url": null, "terms_of_service_url": null, "status_page_url": null }
  ]
}

local-gpu 가 우리 하드웨어의 slug 입니다. 어떤 외부 provider 가 있는지는 운영자가 등록한 바에 따라 달라지므로, 코드에 박아 두지 말고 목록을 읽으세요.

특정 모델을 어떤 provider 가 어떤 컨텍스트·양자화로 서빙하는지 보려면:

curl https://openrouter.myip.co.kr/api/v1/models/google/gemma-4-26b-a4b/endpoints

필드

적용 순서

필드는 고정된 순서로 적용되고, 그 순서가 결과를 바꿉니다.

order → only → ignore → sort → allow_fallbacks → max_price → require_parameters → 메타 필터 → 쿨다운

기억해 둘 두 가지가 있습니다.

• sort 가 order 를 덮습니다. 둘 다 주면 정렬이 나중에 돌면서 전체를 다시 늘어놓습니다. 정렬은 안정 정렬이라 동률인 후보는 이전 순서를 유지하는데, 여러분의 order 가 살아남는 곳은 딱 거기뿐입니다.
• allow_fallbacks: false 는 가격·파라미터 필터보다 먼저 돕니다. 체인이 먼저 후보 하나로 잘리고, 그 후보가 max_price 나 require_parameters 에 걸려 제거되면 더 싼 대안이 아니라 404 no_endpoints_found 가 돌아옵니다.

쿨다운은 마지막에 적용됩니다. 3회 연속 실패한 후보는 여러분의 조건과 무관하게 60초 동안 건너뜁니다.

예제

# 로컬 GPU 만 — 이 프롬프트를 외부 provider 가 보지 못하게 한다
curl https://openrouter.myip.co.kr/api/v1/chat/completions \
  -H "Authorization: Bearer $MYIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-26b-a4b",
    "provider": { "only": ["local-gpu"] },
    "messages": [{ "role": "user", "content": "사내 문서를 요약해 줘." }]
  }'

models[] 와의 관계

models[] 는 모델을 고르고, provider{} 는 그 모델들의 엔드포인트를 한꺼번에 거르고 정렬합니다. provider 객체는 모델별이 아니라 이어 붙인 체인 전체에 적용됩니다. 특히 allow_fallbacks: false 는 "모델마다 하나"가 아니라 전체에서 하나로 자릅니다. 모델 폴백 을 보세요.

결과 확인

X-MyIP-Provider: MyIP Local GPU
X-MyIP-Model: google/gemma-4-26b-a4b

기대한 provider 가 아니었다면 GET /api/v1/generation?id=… 의 provider_responses 에 시도한 것과 지나친 이유가 남아 있습니다.

우리에게 없는 것

다른 게이트웨이에는 있지만 우리는 일부러 두지 않은 것들입니다.

• 오토 라우팅·프론티어 선택. 모델을 대신 고르는 메타 모델도, 파레토·융합 라우터도 없습니다. 라우팅은 여러분의 체인이 전부입니다.
• 모델 변종. :nitro, :floor, :free 접미사가 없습니다. 대신 sort: "throughput" 이나 sort: "price" 를 쓰세요 — 그 접미사들이 축약하던 것이 바로 이것입니다.
• 프리셋. 서버에 저장해 두는 라우팅 설정이 없습니다. 요청마다 provider 객체를 보내거나, 여러분 쪽 클라이언트로 감싸세요.
• BYOK. 여러분의 provider 자격증명을 붙일 수 없습니다. 키 응답의 byok_* 필드는 언제나 0 입니다.

해당 기능의 엔드포인트는 404 not_supported 입니다. 지원하지 않는 엔드포인트 를 보세요.