로컬 모델을 위한 모델 라우팅 전략

Tokios를 이용하면 여러 모델을 각각 고유한 공개 이름으로 제공할 수 있으며, 요청 시 model 필드 값만 변경함으로써 원하는 모델으로 라우팅할 수 있습니다. 엔드포인트와 API 키는 그대로 유지되며, 변경되는 것은 오직 model 값뿐입니다.

라우팅이 어떻게 작동하는지

각 배포마다 고유한 공개 이름이 존재합니다. Tokios가 요청을 수신하면 model 필드 값을 읽어 해당 이름을 가진 배포를 찾은 뒤, 그 배포의 업스트림 모델 ID로 값을 변경하여 커넥터 터널을 통해 전달합니다. 클라이언트 설정은 전혀 변경되지 않으며, 오직 model 값만 바뀌게 됩니다.

하나의 커넥터로 다양한 모델을 사용할 수 있습니다

하나의 커넥터로 여러 모델을 처리할 수 있습니다. Routes에 각 업스트림 모델 ID를 기재하고 Upstreams에 해당하는 명칭의 로컬 업스트림 모델로 매핑해주세요:

tokios-connector.json

{
  "Connector": {
    "ConnectorId": "con_...",
    "Token": "ct-...",
    "Routes": [
      { "Model": "gemma4:e4b",    "UpstreamId": "ollama" },
      { "Model": "qwen2.5-coder", "UpstreamId": "lmstudio" }
    ],
    "Upstreams": {
      "ollama":   { "BaseUrl": "http://127.0.0.1:11434/v1" },
      "lmstudio": { "BaseUrl": "http://127.0.0.1:1234/v1" }
    }
  }
}

Then register a deployment for each model in the console, giving each a public name (e.g. gemma-tunnel → gemma4:e4b, qwen-coder → qwen2.5-coder), all pointing at this connector.

각각 따로 유지하는 것을 선호하시나요? 또는 각 업스트림 모델 ID와 ConnectorId/Token, Upstream 설정을 갖춘 커넥터를 모델별로 실행하는 방법도 가능합니다. 두 방식 모두 문제없으며, 서버는 터널을 통해 오직 모델 ID만 전송할 뿐입니다.

요청 시 업스트림 모델 ID를 변경하는 방법

두 배포 환경이 모두 등록된 상태에서, model 필드만 변경하여 모델을 전환할 수 있습니다:

# Use the Gemma model
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma-tunnel", "messages": [{"role": "user", "content": "Hello"}]}'

# Use the Qwen model
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-coder", "messages": [{"role": "user", "content": "Hello"}]}'

엔드포인트와 인증 헤더, 그리고 기타 모든 매개변수는 그대로 유지됩니다. Tokios가 요청의 전송을 처리합니다.

클라이언트를 수정하지 않고도 백엔드를 교체할 수 있습니다.

클라이언트는 공개된 모델 이름만 참조하므로 업스트림 모델 ID나 커넥터 설정을 새 서버로 변경하고 동일한 공개 이름을 유지하기만 하면 기존 클라이언트 설정을 바꾸지 않고도 모델을 다른 하드웨어나 백엔드로 옮길 수 있습니다. 그러면 기존 요청들도 정상적으로 작동합니다.

라우팅 전략들

여러 로컬 모델을 운용할 때 모든 요청을 동일한 모델으로 보내면 자원이 낭비됩니다. 코딩 요청에는 120B 추론용 모델이 필요 없으며 단순 분류 작업에도 70B 대형 모델이 필요하지 않습니다. 라우팅 기능을 활용하면 각 요청을 해당 작업에 가장 적합한 모델으로 보낼 수 있어 작업 부하에 따라 속도, 품질, 비용을 최적화할 수 있습니다. 모든 작업에 1 모델 하나만 사용하는 방식은 여러 단점을 수반합니다. 대형 모델은 어떤 작업이든 잘 처리하지만 응답 속도가 느리고 VRAM 소모도 많습니다. 소형 모델은 응답 속도는 빠르지만 복잡한 추론에는 어려움을 겪습니다. 라우팅을 이용하면 두 가지 모델을 모두 활용할 수 있습니다.

속도: 간단한 질문은 빠르게 처리하는 소형 모델로, 복잡한 작업은 대형 모델로 전달됩니다.
품질: 코딩 관련 요청은 코딩 전문 모델로, 일반 대화는 범용 모델로 보내집니다.
비용: 소형 모델은 전력과 VRAM 소모가 적어 고부하 작업을 위한 여유 공간을 확보할 수 있습니다.
복원력: 기본 모델이 과부하 상태이거나 다운되었을 때 요청은 백업 모델로 자동 전달됩니다.

배포당 모델 하나만 사용하기

가장 간단한 방법은 각 모델을 별도의 Tokios 배포 항목으로 등록한 뒤 클라이언트에서 model 필드 값만 변경하여 원하는 모델을 호출하도록 설정하는 것입니다.

tokios-connector.json

{
  "Connector": {
    "Routes": [
      { "Model": "qwen3-coder", "UpstreamId": "ollama" },
      { "Model": "gemma-tunnel", "UpstreamId": "ollama" }
    ],
    "Upstreams": {
      "ollama": { "BaseUrl": "http://127.0.0.1:11434/v1" }
    }
  }
}

클라이언트가 적절한 model 값을 포함한 요청을 전송합니다:

# Code task → code model
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-coder", "messages": [{"role": "user", "content": "Write a Python function to sort a list"}]}'

# General chat → general model
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma-tunnel", "messages": [{"role": "user", "content": "Summarize this article"}]}'

사용 시점: 2부터 3까지의 모델들을 운용하며 애플리케이션에서 호출할 모델을 직접 결정하는 경우입니다. 이 방식이 가장 일반적인 시작점입니다.

작업 기반 라우팅

작업 유형에 따라 라우팅합니다. 코딩 관련 요청은 코드 전문 모델로, 일반 대화는 범용 모델로, 추론 작업은 고성능 모델로 전송하죠. 클라이언트나 미들웨어 계층이 요청 내용을 분석하여 적절한 배포 대상을 선택합니다.

작업 유형	권장되는 모델 종류	예시 배포 설정	그 이유
코드 생성 및 리팩토링	코드 전문 모델	Qwen3-Coder-30B on vLLM	코드 처리에 특화되어 훈련되었으며 구문 및 논리 처리 면에서 우수한 성능을 보입니다.
일반적인 대화 및 요약 작업	MoE (35B–122B)	Atlas 플랫폼에서 구동되는 Qwen3.5-35B-A3B 모델	빠른 처리 속도; 토큰당 3B 개의 활성 파라미터
복잡한 추론 및 수학 문제 해결	밀도가 높은 70B 이상의 구조	vLLM 환경에서 사용 가능한 Qwen3-32B 또는 70B 모델	다단계 추론 시 더 높은 품질의 결과 제공
도구 호출 및 에이전트 기능 지원	도구 활용이 가능한 모델	vLLM에서 구동되는 GLM-4.5-Air 모델	함수 호출 기능을 효과적으로 지원함
시각 및 멀티모달 기능	멀티모달 모델	vLLM 환경에서 구동되는 Qwen3-VL	이미지 입력을 기본적으로 처리할 수 있음

가장 간단한 구현 방법은 애플리케이션 코드 내에서 이루어집니다. 요청 유형을 확인한 뒤 적절한 배포 이름을 선택하시면 됩니다.

def select_model(task_type: str) -> str:
    routing = {
        "code": "qwen3-coder",
        "chat": "gemma-tunnel",
        "reasoning": "glm-4-chat",
        "vision": "qwen3-vl",
    }
    return routing.get(task_type, "gemma-tunnel")

보다 정교한 라우팅이 필요한 경우, 요청 내용을 분석하여 설정된 규칙에 따라 올바른 백엔드로 전달하는 LiteLLM이나 OpenRouter와 같은 게이트웨이를 활용하시기 바랍니다.

게이트웨이 수준의 라우팅

클라이언트와 Tokios 사이에 라우팅 프록시를 배치하세요. 이 프록시는 요청 속성, 부하 상태 또는 사용자 정의 규칙에 따라 어떤 Tokios 배포 인스턴스를 사용할지 결정합니다.LiteLLM은 여러 Tokios 배포 인스턴스 앞에 배치되어 모델 별칭에 따라 요청을 라우팅할 수 있습니다.

litellm_config.yaml

model_list:
  - model_name: gpt-4  # alias
    litellm_params:
      model: openai/qwen3-coder  # Tokios deployment
      api_base: https://api.tokios.com/v1
      api_key: sk-tok-YOUR_KEY
  - model_name: gpt-4
    litellm_params:
      model: openai/gemma-tunnel  # fallback
      api_base: https://api.tokios.com/v1
      api_key: sk-tok-YOUR_KEY

router_settings:
  routing_strategy: simple-shuffle
  num_retries: 2

클라이언트는 별칭 gpt-4을 사용해 LiteLLM 프록시로 요청을 전송하며, 프록시는 설정된 Tokios 배포 인스턴스로 해당 요청을 전달합니다.OpenRouter는 여러 제공업체 간 모델 폴백 및 부하 분산 기능을 지원합니다. Tokios 엔드포인트를 사용자 정의 제공업체로 추가한 뒤 OpenRouter 대시보드에서 라우팅 규칙을 설정하시면 됩니다.

폴백 체인 구조

Configure a primary model with 1 or more fallback models. If the primary is busy, offline, or returns an error, the request falls through to the next model in the chain.

import requests

FALLBACK_MODELS = ["qwen3-coder", "gemma-tunnel", "qwen3-32b"]

def chat_with_fallback(prompt: str) -> str:
    for model in FALLBACK_MODELS:
        try:
            response = requests.post(
                "https://api.tokios.com/v1/chat/completions",
                headers={
                    "Authorization": "Bearer sk-tok-YOUR_KEY",
                    "Content-Type": "application/json"
                },
                json={"model": model, "messages": [{"role": "user", "content": prompt}]},
                timeout=30
            )
            response.raise_for_status()
            return response.json()["choices"][0]["message"]["content"]
        except (requests.RequestException, KeyError):
            continue
    raise RuntimeError("All models failed")

Tokios 커넥터들은 자신의 상태를 게이트웨이에 보고합니다. 커넥터가 오프라인 상태가 되면 해당 커넥터에 배포된 서비스에 대한 요청은 503 응답을 반환하게 됩니다. 애플리케이션에서는 이를 감지하여 다른 배포 서비스로 재시도할 수 있으며, LiteLLM과 같은 게이트웨이를 설정해 자동으로 대체 모델을 선택하도록 할 수도 있습니다.

비용 기반 라우팅

간단하고 빈번한 요청은 크기가 작고 비용이 저렴한 모델으로 보내고, 대규모 모델은 꼭 필요한 작업에만 사용하세요.

요청 유형	라우팅 대상	이유
분류 및 추출	MoE with 3–4B active params	속도가 빠르고 토큰당 연산량이 적음
요약 작업 (간단한 경우)	7B개부터 14B개까지의 밀집형 모델 또는 MoE	충분한 품질을 유지하면서 빠른 응답 속도 제공
복잡한 추론 과제 처리 가능	32B 기반의 밀집형 구조 또는 122B MoE 방식 활용	다단계 작업에서 더 높은 품질의 결과 도출
코드 생성 기능 우수	코드 생성에 특화된 모델	토큰 사용량 대비 더 나은 결과 생성

이 전략은 전체 연산량과 전력 소비를 줄여줍니다. VRAM과 전력 공급이 제한적인 일반 사용자용 하드웨어에서 실행할 때 매우 유용합니다.

의사결정 매트릭스

전략	복잡도	가장 적합한 용도	사용 시점
배포당 단일 모델만 사용	낮음	시작하기, 2–3 모델들	애플리케이션 코드에서 호출할 모델을 직접 지정할 수 있음
작업 기반 라우팅	중간 수준	코딩 및 채팅, 추론 기능	서로 다른 작업 유형마다 각기 다른 모델이 필요함
게이트웨이 수준 라우팅	높음	여러 클라이언트가 동일한 인프라를 공유하는 경우	클라이언트 코드를 수정하지 않고도 중앙 집중식 라우팅 규칙을 적용하고 싶으신가요
폴백 체인	중간 수준	고가용성	주요 업스트림 모델 ID가 오프라인 상태가 되거나 동시 처리 한도에 도달할 수 있습니다
비용 기반 라우팅	중간 수준	대량의 다양한 유형의 워크로드	간단한 작업은 크기가 작은 모델로 전송하여 컴퓨팅 비용을 최소화하고 싶으신가요

이 전략들은 서로 배타적이지 않습니다. 실제 운영 환경에서는 작업 유형에 따른 라우팅(코드 → 코드 모델)과 게이트웨이 프록시 뒤에서의 폴백 체인(주 모델 → 백업 모델)이 함께 사용되기도 합니다

다음 단계

로컬 모델을 선택하세요

어떤 배포 환경을 등록할지 결정하기 위해 모델과 백엔드를 비교해보세요.

해당 배포 환경의 성능을 벤치마크하세요.

실제 워크로드 상황에서 라우팅 결정이 적절한지 확인하기 위해 처리량과 지연 시간을 측정해보세요.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

로컬 모델을 위한 모델 라우팅 전략

라우팅이 어떻게 작동하는지

하나의 커넥터로 다양한 모델을 사용할 수 있습니다

요청 시 업스트림 모델 ID를 변경하는 방법

클라이언트를 수정하지 않고도 백엔드를 교체할 수 있습니다.

라우팅 전략들

의사결정 매트릭스

다음 단계

로컬 모델을 선택하세요

해당 배포 환경의 성능을 벤치마크하세요.

​라우팅이 어떻게 작동하는지

​하나의 커넥터로 다양한 모델을 사용할 수 있습니다

​요청 시 업스트림 모델 ID를 변경하는 방법

​클라이언트를 수정하지 않고도 백엔드를 교체할 수 있습니다.

​라우팅 전략들

​의사결정 매트릭스

​다음 단계

로컬 모델을 선택하세요

해당 배포 환경의 성능을 벤치마크하세요.

라우팅이 어떻게 작동하는지

하나의 커넥터로 다양한 모델을 사용할 수 있습니다

요청 시 업스트림 모델 ID를 변경하는 방법

클라이언트를 수정하지 않고도 백엔드를 교체할 수 있습니다.

라우팅 전략들

의사결정 매트릭스

다음 단계