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

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" }
    }
  }
}

그런 다음 콘솔에서 각 모델에 대한 deployment를 등록하고, 각 모델에 공개 이름(예: gemma-tunnel → gemma4:e4b, qwen-coder → qwen2.5-coder)을 부여하여 모두 이 커넥터를 가리키도록 설정합니다.

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

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

클라이언트는 공개된 모델 이름만 참조하므로, 어떤 클라이언트 설정도 변경하지 않고도 모델을 다른 하드웨어나 백엔드로 옮길 수 있습니다. 배포(또는 커넥터의 업스트림)가 새 서버를 가리키도록 업데이트하고 동일한 공개 이름을 유지하면 기존 요청이 계속 작동합니다.

라우팅 전략

여러 로컬 모델을 운용할 때 모든 요청을 동일한 모델로 보내면 자원이 낭비됩니다. 코딩 요청에 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)	Qwen3.5-35B-A3B on Atlas	빠른 처리 속도; 토큰당 3B 활성 파라미터
복잡한 추론, 수학	밀집형 70B+	Qwen3-32B or 70B on vLLM	다단계 추론에서 더 높은 품질
도구 호출, 에이전트	도구 지원 모델	GLM-4.5-Air on vLLM	강력한 함수 호출 지원
비전, 멀티모달	멀티모달 모델	Qwen3-VL on vLLM	이미지 입력을 네이티브로 처리

가장 간단한 구현은 애플리케이션 코드 내에서 이루어집니다. 요청 유형을 검사하고 배포 이름을 선택합니다:

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 대시보드에서 라우팅 규칙을 구성하세요.

폴백 체인

기본 모델과 1개 이상의 폴백 모델을 구성합니다. 기본 모델이 사용 중이거나 오프라인 상태이거나 오류를 반환하면 요청이 체인의 다음 모델로 전달됩니다.

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 dense or MoE	충분한 품질; 빠른 응답
복잡한 추론	32B+ dense or 122B MoE	다단계 작업에서 더 높은 품질
코드 생성	코드 전문 모델	토큰 예산 대비 더 나은 출력

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

의사결정 매트릭스

전략	복잡도	적합 대상	사용 시점
배포당 단일 모델	낮음	시작하기, 2-3개 모델	애플리케이션 코드에서 호출할 모델을 직접 제어
작업 기반 라우팅	중간	코딩 + 채팅 + 추론	작업 유형마다 다른 모델이 필요한 경우
게이트웨이 수준 라우팅	높음	다중 클라이언트, 공유 인프라	클라이언트 코드를 변경하지 않고 중앙 집중식 라우팅 규칙을 적용하려는 경우
폴백 체인	중간	고가용성	기본 모델이 오프라인 상태가 되거나 동시성 한도에 도달할 수 있는 경우
비용 기반 라우팅	중간	고부피, 혼합 워크로드	간단한 작업을 작은 모델로 보내어 연산 비용을 최소화하려는 경우

이 전략들은 서로 배타적이지 않습니다. 일반적인 운영 패턴은 작업 기반 라우팅(코드 → 코드 모델)과 폴백 체인(기본 → 백업)을 게이트웨이 프록시 뒤에서 결합합니다.

다음 단계

로컬 모델 선택

어떤 배포를 등록할지 결정하기 위해 모델과 백엔드를 비교합니다.

배포 테스트

실제 워크로드에서 라우팅 결정을 검증하기 위해 처리량과 지연 시간을 측정합니다.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

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

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

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

요청 시 모델 전환하기

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

라우팅 전략

의사결정 매트릭스

다음 단계

로컬 모델 선택

배포 테스트

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

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

​요청 시 모델 전환하기

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

​라우팅 전략

​의사결정 매트릭스

​다음 단계

로컬 모델 선택

배포 테스트

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

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

요청 시 모델 전환하기

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

라우팅 전략

의사결정 매트릭스

다음 단계