Stratégies de routage pour les modèles locaux

Tokios vous permet d’exposer plusieurs modèles — chacun sous son propre nom public — et de router entre eux en modifiant le champ model dans votre requête. Le point de terminaison et la clé API restent identiques ; seule la valeur de model change.

How routing works

Chaque déploiement a un nom public unique. Lorsque Tokios reçoit une requête, il lit le champ model, trouve le déploiement correspondant, le réécrit en l’ID de modèle amont de ce déploiement, et le transmet via le tunnel du connecteur. La configuration de votre client ne change jamais — seule la valeur de model change.

One connector, many models

Un seul connecteur peut servir plusieurs modèles. Listez chaque ID de modèle amont dans Routes et mappez-le à un upstream local nommé dans 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" }
    }
  }
}

Ensuite, enregistrez un deployment pour chaque modèle dans la console, en donnant à chacun un nom public (par ex. gemma-tunnel → gemma4:e4b, qwen-coder → qwen2.5-coder), tous pointant vers ce connecteur.

Vous préférez les garder séparés ? Vous pouvez aussi lancer un connecteur par modèle, chacun avec son propre ConnectorId/Token et Upstream. Les deux approches fonctionnent — le serveur n’envoie que l’ID de modèle dans le tunnel.

Switching models in requests

Une fois les deux déploiements enregistrés, changez de modèle en modifiant uniquement le champ 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"}]}'

Le point de terminaison, l’en-tête d’authentification et tous les autres paramètres restent identiques. Tokios gère la distribution.

Swap the backend without touching clients

Comme les clients ne référencent que le nom public, vous pouvez déplacer un modèle vers du matériel différent ou un backend différent sans modifier la configuration client : mettez à jour le déploiement (ou l’upstream du connecteur) pour pointer vers le nouveau serveur, gardez le même nom public, et les requêtes existantes continuent de fonctionner.

Routing strategies

Lorsque vous faites tourner plusieurs modèles locaux, envoyer chaque requête au même modèle gaspille des ressources. Une requête de code n’a pas besoin d’un modèle de raisonnement 120B, et une tâche de classification simple n’a pas besoin d’un modèle dense 70B. Le routage vous permet de diriger chaque requête vers le modèle le mieux adapté à la tâche — optimisant la vitesse, la qualité ou le coût selon la charge de travail. Faire tourner 1 modèle pour tout oblige à un compromis. Un grand modèle gère bien chaque tâche mais répond lentement et consomme plus de VRAM. Un petit modèle répond vite mais peine avec le raisonnement complexe. Le routage vous permet d’avoir les deux :

Speed : les requêtes simples vont à un petit modèle rapide ; les tâches complexes vont à un grand modèle
Quality : les tâches de code vont à un modèle spécialisé en code ; le chat général va à un généraliste
Cost : les petits modèles consomment moins d’énergie et de VRAM, laissant de la marge pour les tâches exigeantes
Resilience : si votre modèle principal est occupé ou indisponible, les requêtes basculent vers un secours

Single model per deployment

L’approche la plus simple — enregistrez chaque modèle comme son propre déploiement Tokios et laissez le client choisir lequel appeler en changeant le champ 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" }
    }
  }
}

Votre client envoie des requêtes avec la valeur model appropriée :

# 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"}]}'

When to use : vous faites tourner 2–3 modèles et votre application contrôle lequel appeler. C’est le point de départ le plus courant.

Task-based routing

Routez par type de tâche — envoyez les requêtes de code à un modèle spécialisé en code, le chat à un généraliste, et le raisonnement à un modèle dense. Le client ou une couche intermédiaire inspecte la requête et choisit le déploiement.

Task type	Recommended model class	Example deployment	Why
Code generation, refactoring	Code-specialized	Qwen3-Coder-30B on vLLM	Trained specifically for code; better at syntax and logic
General chat, summarization	MoE (35B–122B)	Qwen3.5-35B-A3B on Atlas	Fast throughput; 3B active params per token
Complex reasoning, math	Dense 70B+	Qwen3-32B or 70B on vLLM	Higher quality on multi-step reasoning
Tool calling, agents	Tool-capable model	GLM-4.5-Air on vLLM	Strong function-calling support
Vision, multimodal	Multimodal model	Qwen3-VL on vLLM	Handles image input natively

L’implémentation la plus simple se fait dans le code de votre application — inspectez le type de requête et sélectionnez le nom du déploiement :

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

Pour un routage plus sophistiqué, utilisez une passerelle comme LiteLLM ou OpenRouter qui inspecte les requêtes et les transmet au bon backend selon des règles configurables.

Gateway-level routing

Placez un proxy de routage entre vos clients et Tokios. Le proxy décide quel déploiement Tokios utiliser en fonction des attributs de la requête, de la charge ou de règles personnalisées.LiteLLM peut se placer devant plusieurs déploiements Tokios et router selon des alias de modèles :

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

Les clients envoient leurs requêtes au proxy LiteLLM en utilisant l’alias gpt-4, et le proxy route vers le déploiement Tokios que vous avez configuré.OpenRouter prend en charge le fallback de modèles et l’équilibrage de charge entre plusieurs fournisseurs. Ajoutez votre point de terminaison Tokios comme fournisseur personnalisé et configurez les règles de routage dans le tableau de bord OpenRouter.

Fallback chains

Configurez un modèle principal avec 1 ou plusieurs modèles de secours. Si le principal est occupé, hors ligne ou renvoie une erreur, la requête bascule vers le modèle suivant dans la chaîne.

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

Les connecteurs Tokios signalent leur statut au gateway. Si un connecteur passe hors ligne, les requêtes vers des déploiements sur ce connecteur renvoient 503. Votre application peut capturer cela et réessayer avec un déploiement différent, ou vous pouvez configurer une passerelle comme LiteLLM pour gérer le fallback automatiquement.

Cost-based routing

Routez les requêtes simples et à haut volume vers un modèle plus petit et moins coûteux, et réservez le grand modèle aux tâches qui en ont besoin.

Request type	Route to	Reason
Classification, extraction	MoE with 3–4B active params	Fast; low compute per token
Summarization (short)	7B–14B dense or MoE	Adequate quality; fast response
Complex reasoning	32B+ dense or 122B MoE	Higher quality on multi-step tasks
Code generation	Code-specialized model	Better output for the token budget

Cette stratégie réduit le calcul total et la consommation d’énergie — important lorsque vous tournez sur du matériel grand public où la VRAM et le wattage sont limités.

Decision matrix

Strategy	Complexity	Best for	When to use
Single model per deployment	Low	Getting started, 2–3 models	You control which model to call in application code
Task-based routing	Medium	Coding + chat + reasoning	You need different models for different task types
Gateway-level routing	High	Multiple clients, shared infrastructure	You want centralized routing rules without changing client code
Fallback chains	Medium	High availability	Your primary model may go offline or hit concurrency limits
Cost-based routing	Medium	High-volume, mixed workloads	You want to minimize compute cost by sending simple tasks to smaller models

Ces stratégies ne sont pas mutuellement exclusives. Un pattern de production courant combine le routage par tâche (code → modèle de code) avec des chaînes de fallback (principal → secours) derrière un proxy de passerelle.

Next steps

Choose a local model

Comparez les modèles et les backends pour décider quels déploiements enregistrer.

Test your deployment

Mesurez le débit et la latence pour valider vos décisions de routage sous des charges réelles.

Matériel et compatibilité

Servir et connecter votre runtime

Connecter un client ou une app

Comparer

Stratégies de routage pour les modèles locaux

How routing works

One connector, many models

Switching models in requests

Swap the backend without touching clients

Routing strategies

Decision matrix

Next steps

Choose a local model

Test your deployment

​How routing works

​One connector, many models

​Switching models in requests

​Swap the backend without touching clients

​Routing strategies

​Decision matrix

​Next steps

Choose a local model

Test your deployment

How routing works

One connector, many models

Switching models in requests

Swap the backend without touching clients

Routing strategies

Decision matrix

Next steps