Fournisseurs de modèles

Qwen Code vous permet de configurer plusieurs fournisseurs de modèles via le paramètre modelProviders dans votre settings.json. Cela vous permet de basculer entre différents modèles et fournisseurs d’IA en utilisant la commande /model.

Vue d’ensemble

Utilisez modelProviders pour déclarer des modèles par id de fournisseur entre lesquels le sélecteur /model peut basculer. Chaque clé est un id de fournisseur et sa valeur est un tableau de définitions de modèles (ModelConfig[]). Pour les fournisseurs intégrés, la clé doit être un type d’authentification valide (openai, anthropic, gemini, vertex-ai) ; un id de fournisseur personnalisé (par ex. idealab) est autorisé tant que vous le mappez à un protocole via le paramètre de niveau supérieur providerProtocol. Chaque entrée de modèle nécessite un id ; envKey est facultatif mais recommandé (lorsqu’il est omis, il revient à la clé d’environnement par défaut du type d’authentification, par ex. OPENAI_API_KEY pour openai), avec des champs facultatifs name, description, baseUrl et generationConfig. Les identifiants ne sont jamais enregistrés dans les paramètres ; le runtime les lit depuis process.env[envKey]. Les modèles Qwen OAuth restent codés en dur et ne peuvent pas être remplacés.

Routes de génération d’images

Définissez supportsImageGeneration: true lorsqu’une route peut être utilisée par l’outil intégré image_gen. Cette capacité est indépendante de la prise en charge de l’entrée d’images telle que capabilities.vision ou generationConfig.modalities.image.

Utilisez imageOnly: true lorsque la route est dédiée à la génération d’images et ne doit pas apparaître dans les sélecteurs de modèles ordinaires. Pour des raisons de rétrocompatibilité, imageOnly: true implique également la capacité de génération d’images, donc les paramètres existants n’ont pas besoin d’être migrés.

Une route à double rôle peut être sélectionnée comme modèle principal et via /model --image :

{
  "modelProviders": {
    "openai": [
      {
        "id": "omni-model",
        "envKey": "MODEL_API_KEY",
        "baseUrl": "https://gateway.example.com/model-api",
        "supportsImageGeneration": true
      }
    ]
  }
}

Une route image dédiée définit les deux champs. La forme legacy avec seulement imageOnly: true reste valide :

{
  "id": "image-model",
  "envKey": "MODEL_API_KEY",
  "baseUrl": "https://images.example.com/api/v1",
  "supportsImageGeneration": true,
  "imageOnly": true
}

La route sélectionnée doit déclarer une baseUrl HTTPS explicite et un envKey non vide. La génération d’images utilise le même endpoint et le même identifiant que la route ; si le chat et la génération d’images nécessitent des endpoints ou des identifiants différents, configurez plutôt deux routes.

Exemples de configuration par type d’authentification

Vous trouverez ci-dessous des exemples de configuration complets pour différents types d’authentification, montrant les paramètres disponibles et leurs combinaisons.

Types d’authentification pris en charge

Les clés de l’objet modelProviders doivent être des valeurs authType valides. Les types d’authentification actuellement pris en charge sont :

[!note] Les entrées Vertex AI peuvent s’authentifier avec les Application Default Credentials. Définissez GOOGLE_CLOUD_PROJECT (et facultativement GOOGLE_CLOUD_LOCATION, qui vaut global par défaut) et laissez envKey non défini, ainsi que toutes les autres sources de clé lues par le résolveur : GOOGLE_API_KEY, settings.security.auth.apiKey et les indicateurs CLI de clé. Toute valeur de clé API qui atteint une entrée Vertex bascule le SDK Google en mode Vertex Express, qui ignore le projet, la localisation et vos identifiants ADC. Une entrée déclarant un envKey n’est jamais routée vers ADC, donc une clé dont l’injection échoue continue d’échouer sur cette variable au lieu de s’authentifier silencieusement auprès d’un autre principal.

[!warning] Un id de fournisseur qui n’est ni un protocole intégré ni mappé via providerProtocol (par ex. une faute de frappe comme "openai-custom") ne peut pas être routé, donc son entrée entière est ignorée avec un avertissement — ses modèles n’apparaîtront simplement pas dans le sélecteur /model. Utilisez l’une des valeurs de type d’authentification prises en charge ci-dessus pour les fournisseurs intégrés, ou ajoutez un mapping providerProtocol pour un id personnalisé.

Ids de fournisseurs personnalisés (providerProtocol)

Les ids de fournisseurs intégrés (openai, gemini, anthropic, vertex-ai, qwen-oauth) sont routés automatiquement vers leur protocole SDK. Pour utiliser un id de fournisseur personnalisé — par exemple pour regrouper plusieurs endpoints compatibles OpenAI sous un nom plus convivial — déclarez-le sous modelProviders et mappez-le à un protocole intégré avec le paramètre de niveau supérieur providerProtocol :

{
  "modelProviders": {
    "idealab": [
      {
        "id": "my-model",
        "envKey": "IDEALAB_API_KEY",
        "baseUrl": "https://idealab.example.com/v1"
      }
    ]
  },
  "providerProtocol": {
    "idealab": "openai"
  }
}

Sans une entrée providerProtocol correspondante, un id de fournisseur personnalisé est ignoré (voir l’avertissement ci-dessus).

SDK utilisés pour les requêtes API

Qwen Code utilise les SDK officiels suivants pour envoyer des requêtes à chaque fournisseur :

Cela signifie que la baseUrl que vous configurez doit être compatible avec le format d’API attendu par le SDK correspondant. Par exemple, lors de l’utilisation du type d’authentification openai, le point de terminaison doit accepter les requêtes au format de l’API OpenAI.

Fournisseurs compatibles avec OpenAI (openai)

Ce type d’authentification prend en charge non seulement l’API officielle d’OpenAI, mais aussi tout point de terminaison compatible avec OpenAI, y compris les fournisseurs de modèles agrégés comme OpenRouter et Requesty.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here",
    "REQUESTY_API_KEY": "sk-your-actual-requesty-key-here"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "retryInitialDelayMs": 3000,
          "retryMaxDelayMs": 30000,
          "enableCacheControl": true,
          "contextWindowSize": 128000,
          "modalities": {
            "image": true
          },
          "customHeaders": {
            "X-Client-Request-ID": "req-123"
          },
          "extra_body": {
            "enable_thinking": true,
            "service_tier": "priority"
          },
          "samplingParams": {
            "temperature": 0.2,
            "top_p": 0.8,
            "max_tokens": 4096,
            "presence_penalty": 0.1,
            "frequency_penalty": 0.1
          }
        }
      },
      {
        "id": "gpt-4o-mini",
        "name": "GPT-4o Mini",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 30000,
          "samplingParams": {
            "temperature": 0.5,
            "max_tokens": 2048
          }
        }
      },
      {
        "id": "openai/gpt-4o",
        "name": "GPT-4o (via OpenRouter)",
        "envKey": "OPENROUTER_API_KEY",
        "baseUrl": "https://openrouter.ai/api/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      },
      {
        "id": "openai/gpt-4o-mini",
        "name": "GPT-4o Mini (via Requesty)",
        "envKey": "REQUESTY_API_KEY",
        "baseUrl": "https://router.requesty.ai/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      }
    ]
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "name": "Claude 3.5 Sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "contextWindowSize": 200000,
          "samplingParams": {
            "temperature": 0.7,
            "max_tokens": 8192,
            "top_p": 0.9
          }
        }
      },
      {
        "id": "claude-3-opus",
        "name": "Claude 3 Opus",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 180000,
          "samplingParams": {
            "temperature": 0.3,
            "max_tokens": 4096
          }
        }
      }
    ]
  }
}

Google Gemini (gemini)

{
  "env": {
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "modelProviders": {
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com",
        "capabilities": {
          "vision": true
        },
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "schemaCompliance": "auto",
          "samplingParams": {
            "temperature": 0.4,
            "top_p": 0.95,
            "max_tokens": 8192,
            "top_k": 40
          }
        }
      }
    ]
  }
}

Pour un modèle vision qui peut également suivre la politique normale de l’agent Qwen Code et utiliser des outils, activez le routage d’images sur le tour complet avec les deux capacités :

"capabilities": {
  "vision": true,
  "agent": true
}

Lorsqu’un primaire text-only utilise ce modèle comme fallback vision configuré, le tour complet portant l’image reste sur ce fournisseur, modèle et endpoint exact à travers les appels d’outils et les retries. Le tour indépendant suivant revient au primaire, et chaque demande de modèle ne reçoit que les modalités média prises en charge par sa cible. Omettez agent (ou définissez-le sur false) pour conserver le flux de transcription Vision Bridge plus sûr.

Modèles auto-hébergés locaux (via une API compatible OpenAI)

La plupart des serveurs d’inférence locaux (vLLM, Ollama, LM Studio, etc.) fournissent un point de terminaison d’API compatible avec OpenAI. Configurez-les en utilisant le type d’authentification openai avec une baseUrl locale :

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": {
          "timeout": 300000,
          "maxRetries": 1,
          "contextWindowSize": 32768,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 4096
          }
        }
      },
      {
        "id": "llama-3.1-8b",
        "name": "Llama 3.1 8B (vLLM)",
        "envKey": "VLLM_API_KEY",
        "baseUrl": "http://localhost:8000/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 2,
          "contextWindowSize": 128000,
          "samplingParams": {
            "temperature": 0.6,
            "max_tokens": 8192
          }
        }
      },
      {
        "id": "local-model",
        "name": "Local Model (LM Studio)",
        "envKey": "LMSTUDIO_API_KEY",
        "baseUrl": "http://localhost:1234/v1",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": {
            "temperature": 0.5
          }
        }
      }
    ]
  }
}

Pour les serveurs locaux qui ne nécessitent pas d’authentification, vous pouvez utiliser n’importe quelle valeur fictive pour la clé API :

# Pour Ollama (aucune authentification requise)
export OLLAMA_API_KEY="ollama"
 
# Pour vLLM (si aucune authentification n'est configurée)
export VLLM_API_KEY="not-needed"

Alibaba Cloud Coding Plan

Alibaba Cloud Coding Plan fournit un ensemble préconfiguré de modèles Qwen optimisés pour les tâches de codage. Cette fonctionnalité est disponible pour les utilisateurs disposant d’un accès API à Alibaba Cloud Coding Plan et offre une expérience de configuration simplifiée avec des mises à jour automatiques de la configuration des modèles.

Vue d’ensemble

Lorsque vous vous authentifiez avec une clé API Alibaba Cloud Coding Plan à l’aide de la commande /auth, Qwen Code configure automatiquement les modèles suivants :

Configuration

1. Obtenez une clé API Alibaba Cloud Coding Plan :
   • Chine : https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • International : https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. Exécutez la commande /auth dans Qwen Code
3. Sélectionnez Alibaba ModelStudio, puis choisissez Coding Plan dans le sous-menu
4. Sélectionnez votre région
5. Saisissez votre clé API lorsque vous y êtes invité

Les modèles seront automatiquement configurés et ajoutés à votre sélecteur /model.

Régions

Alibaba Cloud Coding Plan prend en charge deux régions :

La région est sélectionnée lors de l’authentification et stockée dans settings.json sous la configuration modelProviders. Pour changer de région, réexécutez la commande /auth et sélectionnez une région différente.

Stockage de la clé API

Lorsque vous configurez Coding Plan via la commande /auth, la clé API est stockée en utilisant le nom de variable d’environnement réservé BAILIAN_CODING_PLAN_API_KEY. Par défaut, elle est stockée dans le champ env de votre fichier settings.json.

# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=your-api-key-here

Mises à jour automatiques

Les configurations des modèles Coding Plan sont versionnées. Lorsque Qwen Code détecte une version plus récente du modèle de configuration, vous serez invité à effectuer la mise à jour. L’acceptation de la mise à jour permettra de :

• Remplacer les configurations existantes des modèles Coding Plan par les dernières versions
• Préserver toutes les configurations de modèles personnalisées que vous avez ajoutées manuellement
• Basculer automatiquement vers le premier modèle de la configuration mise à jour

Le processus de mise à jour garantit que vous avez toujours accès aux dernières configurations et fonctionnalités des modèles sans intervention manuelle.

Configuration manuelle (Avancé)

Si vous préférez configurer manuellement les modèles Coding Plan, vous pouvez les ajouter à votre settings.json comme n’importe quel fournisseur compatible OpenAI :

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "description": "Qwen3-Coder via Alibaba Cloud Coding Plan",
        "envKey": "YOUR_CUSTOM_ENV_KEY",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    ]
  }
}

Couches de résolution et atomicité

Les valeurs effectives d’authentification/modèle/identifiants sont choisies par champ en utilisant la priorité suivante (le premier présent l’emporte). Vous pouvez combiner --auth-type avec --model pour pointer directement vers une entrée de fournisseur ; ces indicateurs CLI s’exécutent avant les autres couches.

*Lorsqu’ils sont présents, les indicateurs d’authentification CLI remplacent les paramètres. Sinon, security.auth.selectedType ou la valeur par défaut implicite détermine le type d’authentification. Qwen OAuth et OpenAI sont les seuls types d’authentification exposés sans configuration supplémentaire.

Empilement de la configuration de génération : La couche fournisseur imperméable

La résolution de la configuration suit un modèle d’empilement strict avec une règle cruciale : la couche modelProvider est imperméable.

Fonctionnement

1. Lorsqu’un modèle modelProvider EST sélectionné (par exemple, via la commande /model en choisissant un modèle configuré par le fournisseur) :

   • L’intégralité du generationConfig du fournisseur est appliquée atomiquement
   • La couche fournisseur est complètement imperméable — les couches inférieures (CLI, env, paramètres) ne participent pas du tout à la résolution du generationConfig
   • Tous les champs définis dans modelProviders[].generationConfig utilisent les valeurs du fournisseur
   • Tous les champs non définis par le fournisseur sont définis sur undefined (non hérités des paramètres)
   • Cela garantit que les configurations du fournisseur agissent comme un « paquet scellé » complet et autonome

   Si un modèle est listé dans modelProviders, placez tous les paramètres de génération spécifiques au modèle dans l’entrée du fournisseur correspondante. Les valeurs model.generationConfig de niveau supérieur, y compris contextWindowSize, modalities, customHeaders et extra_body, sont ignorées pour les modèles du fournisseur. Configurez ces champs sous modelProviders[authType][].generationConfig pour qu’ils s’appliquent.

2. Lorsqu’AUCUN modèle modelProvider n’est sélectionné (par exemple, en utilisant --model avec un ID de modèle brut, ou en utilisant directement CLI/env/paramètres) :

   • La résolution passe aux couches inférieures
   • Les champs sont remplis depuis CLI → env → paramètres → valeurs par défaut
   • Cela crée un modèle d’exécution (voir la section suivante)

Priorité par champ pour le generationConfig

Traitement atomique des champs

Les champs suivants sont traités comme des objets atomiques : les valeurs du fournisseur remplacent complètement l’objet entier, aucune fusion n’est effectuée :

• samplingParams - Température, top_p, max_tokens, etc.
• customHeaders - En-têtes HTTP personnalisés
• extra_body - Paramètres supplémentaires du corps de la requête

Exemple

// Paramètres utilisateur (~/.qwen/settings.json)
{
  "model": {
    "generationConfig": {
      "timeout": 30000,
      "samplingParams": { "temperature": 0.5, "max_tokens": 1000 }
    }
  }
}
 
// Configuration de modelProviders
{
  "modelProviders": {
    "openai": [{
      "id": "gpt-4o",
      "envKey": "OPENAI_API_KEY",
      "generationConfig": {
        "timeout": 60000,
        "samplingParams": { "temperature": 0.2 }
      }
    }]
  }
}

Lorsque gpt-4o est sélectionné depuis modelProviders :

• timeout = 60000 (provenant du provider, écrase les paramètres)
• samplingParams.temperature = 0.2 (provenant du provider, remplace complètement l’objet settings)
• samplingParams.max_tokens = undefined (non défini dans le provider, et la couche provider n’hérite pas des paramètres — les champs sont explicitement définis sur undefined s’ils ne sont pas fournis)

Lors de l’utilisation d’un modèle brut via --model gpt-4 (ne provenant pas de modelProviders, crée un Runtime Model) :

• timeout = 30000 (provenant des paramètres)
• samplingParams.temperature = 0.5 (provenant des paramètres)
• samplingParams.max_tokens = 1000 (provenant des paramètres)

La stratégie de fusion pour modelProviders lui-même est REPLACE : l’intégralité de modelProviders provenant des paramètres du projet écrasera la section correspondante dans les paramètres utilisateur, au lieu de fusionner les deux.

Configuration du raisonnement / thinking

Le champ optionnel reasoning sous generationConfig contrôle l’intensité avec laquelle le modèle raisonne avant de répondre. Les convertisseurs Anthropic et Gemini le respectent toujours. Le pipeline compatible OpenAI le respecte sauf si generationConfig.samplingParams est défini — voir la mise en garde « Interaction avec samplingParams » ci-dessous.

{
  "modelProviders": {
    "openai": [
      {
        "id": "deepseek-v4-pro",
        "name": "DeepSeek V4 Pro",
        "baseUrl": "https://api.deepseek.com/v1",
        "envKey": "DEEPSEEK_API_KEY",
        "generationConfig": {
          // L'échelle à quatre niveaux :
          //   'low'    | 'medium' — mappé côté serveur à 'high' sur DeepSeek
          //   'high'   — intensité de raisonnement par défaut
          //   'max'    — niveau extra-fort spécifique à DeepSeek
          // Ou définir sur `false` pour désactiver complètement le raisonnement.
          "reasoning": { "effort": "max" },
        },
      },
    ],
  },
}

Comportement par provider

reasoning: false

Définir reasoning: false (le booléen littéral) désactive explicitement la réflexion sur tous les providers — utile pour les requêtes secondaires peu coûteuses qui ne bénéficient pas du raisonnement. Ceci est également respecté au niveau de la requête via request.config.thinkingConfig.includeThoughts: false pour les appels ponctuels (par ex. génération de suggestions).

Sur un baseURL api.deepseek.com, le pipeline OpenAI émet le champ explicite thinking: { type: 'disabled' } requis par DeepSeek V4+ — la valeur par défaut côté serveur est 'enabled', donc omettre simplement reasoning_effort paierait tout de même la latence/coût de la réflexion. Les backends DeepSeek auto-hébergés (sglang/vllm) et les autres serveurs compatibles OpenAI ne reçoivent pas ce champ ; si vous devez désactiver la réflexion sur ceux-ci, injectez thinking: { type: 'disabled' } (ou tout autre paramètre exposé par votre framework d’inférence) via samplingParams/extra_body.

Interaction avec samplingParams (compatible OpenAI uniquement)

budget_tokens

Vous pouvez définir un budget exact de tokens de réflexion en incluant budget_tokens à côté de effort :

"reasoning": { "effort": "high", "budget_tokens": 50000 }

Pour Anthropic, cela devient thinking.budget_tokens. Pour OpenAI/DeepSeek, le champ est conservé mais actuellement ignoré par le serveur — reasoning_effort est le paramètre déterminant.

Modèles Provider vs Modèles Runtime

Qwen Code fait la distinction entre deux types de configurations de modèle :

Modèle Provider

• Défini dans la configuration modelProviders
• Possède un package de configuration complet et atomique
• Lorsqu’il est sélectionné, sa configuration est appliquée comme une couche imperméable
• Apparaît dans la liste de commandes /model avec toutes les métadonnées (nom, description, capacités)
• Recommandé pour les workflows multi-modèles et la cohérence d’équipe

Modèle Runtime

• Créé dynamiquement lors de l’utilisation d’IDs de modèle bruts via CLI (--model), variables d’environnement ou paramètres
• Non défini dans modelProviders
• La configuration est construite en « projetant » à travers les couches de résolution (CLI → env → paramètres → défauts)
• Capturé automatiquement en tant que RuntimeModelSnapshot lorsqu’une configuration complète est détectée
• Permet la réutilisation sans ressaisir les identifiants

Cycle de vie du RuntimeModelSnapshot

Lorsque vous configurez un modèle sans utiliser modelProviders, Qwen Code crée automatiquement un RuntimeModelSnapshot pour préserver votre configuration :

# Ceci crée un RuntimeModelSnapshot avec l'ID : $runtime|openai|my-custom-model
qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url https://api.example.com/v1

Le snapshot :

• Capture l’ID du modèle, la clé API, l’URL de base et la configuration de génération
• Persiste à travers les sessions (stocké en mémoire pendant l’exécution)
• Apparaît dans la liste de commandes /model en tant qu’option runtime
• Peut être activé en utilisant /model $runtime|openai|my-custom-model

Différences clés

Quand utiliser chacun

• Utilisez les Modèles Provider lorsque : vous avez des modèles standard partagés dans une équipe, avez besoin de configurations cohérentes, ou souhaitez éviter les remplacements accidentels
• Utilisez les Modèles Runtime lorsque : vous testez rapidement un nouveau modèle, utilisez des identifiants temporaires, ou travaillez avec des points de terminaison ad hoc

Persistance de la sélection et recommandations

• /model et /auth persistent model.name (lorsque applicable) et security.auth.selectedType dans le scope inscriptible le plus proche qui définit déjà modelProviders ; sinon, ils reviennent au scope utilisateur. Cela maintient les fichiers d’espace de travail/utilisateur synchronisés avec le catalogue de providers actif.
• Sans modelProviders, le résolveur mélange les couches CLI/env/paramètres, créant des Modèles Runtime. C’est acceptable pour les configurations à provider unique, mais fastidieux lors de changements fréquents. Définissez des catalogues de providers chaque fois que les workflows multi-modèles sont courants afin que les changements restent atomiques, attribués à une source et débogables.