로컬 우선 라우팅

이 서비스를 단순 프록시와 다르게 만드는 규칙이 이것입니다. 모델이 우리 GPU 에 있으면 어떤 외부 provider 보다 그 슬롯을 먼저 시도합니다. 기본 동작이고, 모든 요청에 적용되며, 따로 요청할 필요가 없습니다.

규칙

모델과 그 모델을 서빙할 수 있는 자리 사이의 매핑에는 우선순위 숫자가 붙습니다. 작을수록 먼저입니다.

요청의 체인을 만드는 일은 결국 정렬입니다. 요청한 모델을 각각 엔드포인트로 전개하고, priority 오름차순으로 늘어놓고, 앞에서부터 시도합니다. 로컬은 0 이니 앞에 섭니다. 기본 경로에서 이 순서를 뒤집는 것은 없습니다.

예로 따라가 보기

google/gemma-4-26b-a4b 는 우리 GPU 슬롯과 외부 provider 한 곳에서, lgai/exaone-4.0-32b 는 우리 GPU 슬롯에서만 서빙된다고 합시다. 이 요청은

{ "models": ["google/gemma-4-26b-a4b", "lgai/exaone-4.0-32b"] }

다음 체인이 됩니다.

1. local-gpu   google/gemma-4-26b-a4b     (priority 0)
2. <외부>      google/gemma-4-26b-a4b     (priority 50)
3. local-gpu   lgai/exaone-4.0-32b        (priority 0)

3번을 보세요. priority 정렬은 요청한 모델 안에서 일어나지 목록 전체를 가로질러 일어나지 않습니다. models[] 의 순서가 바깥 루프이고 priority 가 안쪽 루프입니다. 외부 Gemma 보다 로컬 EXAONE 을 먼저 쓰고 싶다면 models[] 에서 EXAONE 을 앞에 두세요.

왜 이것이 기본인가

비용. 로컬 단가는 provider 의 USD 요금에서 유도하지 않고 원화로 직접 정합니다. 그래서 환율을 따라 움직이지 않습니다. 공개된 두 모델은 입력 ₩30 / 1M 토큰, 출력 ₩150 / 1M 토큰입니다.

국지성. 로컬 엔드포인트에는 업스트림 provider 자체가 없습니다. 프롬프트는 우리가 운영하는 하드웨어에서 처리되고 제3자에게 전송되지 않습니다. 이 성질이 선호가 아니라 요구사항이라면 아래처럼 고정하세요 — 기본값은 어디까지나 선호라서 상황에 따라 넘어갑니다.

독립성. 로컬 슬롯은 제3자의 rate limit, 쿼터 정책 변경, 모델 폐기에 영향받지 않습니다.

로컬이 지는 경우

로컬 후보가 1순위에서 밀리거나 체인에서 아예 빠지는 경우는 다섯 가지입니다. 이 목록이 이 문서의 알맹이입니다.

1. 프롬프트가 안 들어간다

로컬 슬롯의 컨텍스트 창은 고정입니다(공개된 두 모델 모두 32,768 토큰). 추정 프롬프트가 그보다 크면 로컬 후보를 보내기 전에 체인에서 제거합니다. 어차피 실패할 요청에 콜드스타트를 쓰지 않으려는 것입니다.

그 결과, 짧았으면 로컬이 처리했을 요청이 길다는 이유로 외부 provider 로 갈 수 있습니다. 국지성이 중요하면 프롬프트를 창 안에 유지하거나 only 로 고정하세요.

이 검사에 쓰는 추정치는 일부러 넉넉합니다 — 적게 세는 쪽보다 많이 세는 쪽이 낫기 때문입니다. 콜드스타트를 날리는 비용이 후보 하나를 잃는 비용보다 큽니다. 이 추정치는 과금에 쓰지 않습니다. 과금은 언제나 업스트림이 보고한 토큰 수를 씁니다.

2. 슬롯이 자고 있고 제때 못 깨어난다

로컬 모델이 전부 동시에 상주하지는 않습니다. 슬롯이 떠 있지 않으면 기동한 뒤 응답할 때까지, 또는 그 슬롯의 대기 예산이 끝날 때까지 폴링합니다. 예산을 넘기면 이 후보를 건너뛰고 체인을 계속합니다.

다음 후보가 없으면 Retry-After 와 함께 503 model_loading 이 돌아옵니다. 자세한 내용과 코드는 로컬 GPU 모델 에 있습니다.

3. 슬롯이 쿨다운 중이다

업스트림 실패가 3회 연속이면 그 엔드포인트는 60초 쿨다운에 들어가고, 그동안 체인은 시도조차 하지 않고 건너뜁니다. 한 번 성공하면 카운터는 즉시 초기화됩니다.

4. 여러분이 그렇게 시켰다

provider.ignore, provider.only, provider.order, provider.sort 는 전부 기본 순서를 덮어씁니다. 특히 "sort": "price" 는 전체를 가격순으로 다시 정렬하므로, 어떤 모델에서 외부 provider 가 더 싸다면 그쪽이 앞에 옵니다. Provider 라우팅 을 보세요.

5. 애초에 로컬 슬롯이 없는 모델이다

카탈로그의 대부분 모델은 외부 전용입니다. 로컬 우선은 동점일 때의 규칙이지, 모든 것이 로컬에서 돈다는 약속이 아닙니다.

명시적으로 정하기

로컬 아니면 안 된다

{
  "model": "google/gemma-4-26b-a4b",
  "provider": { "only": ["local-gpu"] },
  "messages": [{ "role": "user", "content": "내부 문서 요약" }]
}

이제 넘어갈 곳이 없습니다. 슬롯이 제때 못 올라오면 503 model_loading, 매핑이 꺼져 있으면 404 no_endpoints_found 입니다. 국지성이 요구사항일 때 쓰세요.

로컬은 절대 안 쓴다

{ "provider": { "ignore": ["local-gpu"] } }

콜드스타트 위험을 감수하느니 돈을 더 내겠다는, 지연에 민감한 경로에 유용합니다.

로컬 먼저, 다만 무한정 기다리진 않는다

체인에 갈 곳을 만들어 주세요.

{ "models": ["lgai/exaone-4.0-32b", "google/gemma-4-26b-a4b"] }

둘 다 로컬이고 GPU 노드는 한 번에 하나만 붙잡습니다 — 그래서 지금 상주 중인 쪽이 즉시 응답하고, 대부분의 경우 기동을 기다리지 않게 됩니다.

무슨 일이 있었는지 확인하기

모든 응답이 누가 처리했는지 말해 줍니다.

X-MyIP-Provider: MyIP Local GPU
X-MyIP-Model: google/gemma-4-26b-a4b
X-MyIP-Generation-Id: gen-01JD8Q2K7M4X9N

시도했다가 건너뛴 후보까지 전부 보려면:

curl "https://openrouter.myip.co.kr/api/v1/generation?id=gen-01JD8Q2K7M4X9N" \
  -H "Authorization: Bearer $MYIP_API_KEY"

provider_responses 에 각 시도와 상태가 남습니다. 건너뛴 로컬 슬롯은 HTTP 코드가 아니라 슬롯 관련 상태로 기록되는데, 그것이 "GPU 가 바빴다"와 "모델이 오류를 냈다"를 가르는 표시입니다.

본 작업 전에 준비 상태를 확인하려면:

curl -s https://openrouter.myip.co.kr/api/v1/models/google/gemma-4-26b-a4b/endpoints \
  | grep -o '"status":[^,]*'

로컬 엔드포인트의 "status":0 이면 슬롯이 떠 있다는 뜻입니다.

이 위에 서비스를 얹을 때의 체크리스트

1. 모델별로 묶어서 처리하세요. GPU 노드는 한 번에 한 모델만 붙잡습니다. 요청마다 로컬 모델 둘을 번갈아 쓰면 매번 적재 비용을 냅니다.
2. 몰아치기 전에 깨워 두세요. max_tokens: 1 요청 하나면 비용은 1원의 몇 분의 1이고, 그 뒤 수백 건이 따뜻한 요청이 됩니다.
3. X-MyIP-Provider 를 늘 읽으세요. 비용 정산이든 데이터 취급이든, 로컬/외부의 차이가 애플리케이션에 의미가 있다면 반드시요.
4. 요구사항이라면 only 로 고정하세요. 기본값은 선호이고 넘어갈 수 있습니다. only: ["local-gpu"] 는 조용히 넘어가는 대신 크게 실패하는 버전입니다.

요금에 미치는 영향

로컬 모델의 단가는 어떤 provider 요금과도 무관하게 정해지므로 환율이 바뀌어도 그대로입니다. 반면 외부 후보의 단가는 provider 의 USD 요금을 현재 환율로 환산하고 마진을 붙여 정합니다 — 그래서 같은 모델이라도 어느 엔드포인트가 응답했느냐에 따라 금액이 다를 수 있습니다.

X-MyIP-Model 과 X-MyIP-Provider 를 읽어야 하는 이유가 하나 더 있는 셈입니다. usage.cost 는 여러분이 요청한 모델이 아니라 실제로 응답한 엔드포인트의 비용입니다. 요금 계산 방식 을 보세요.