Comment exécuter n'importe quel modèle dans DeepSeek Harness ?

DeepSeek Harness (dsh) est livré avec les propres modèles de DeepSeek intégrés, mais vous n'êtes pas lié à ceux-ci. Le harnais traite les fournisseurs de modèles comme une configuration : pointez un bloc de fournisseur vers n'importe quel point de terminaison compatible OpenAI, donnez-lui une référence d'identifiant, et vos sessions d'agent s'exécuteront sur le modèle situé derrière cette URL. Une instance Ollama locale, une passerelle d'entreprise, Qwen via le mode compatible de DashScope, ou les grands fournisseurs de catalogues comme Anthropic et OpenAI se connectent tous au même bloc.

Ce guide explique ce bloc clé par clé, puis propose trois recettes fonctionnelles : un modèle local, un point de terminaison hébergé compatible OpenAI et les fournisseurs de catalogue intégrés. Tout ce qui est cité ici provient du guide des fournisseurs officiel sur la branche master, récupéré le 20 août 2026. Une mise en garde d'emblée : dsh est une préversion développeur, et le README avertit en majuscules qu'il y aura des changements incompatibles. Vérifiez la documentation par rapport à votre version installée avant de copier quoi que ce soit en production.

Si vous découvrez le harnais, commencez par ce qu'est DeepSeek Harness et comment il fonctionne, puis revenez ici pour le câblage des fournisseurs.

Pourquoi échanger des modèles dans un harnais d'agent ?

Un harnais d'agent est une boucle : le modèle planifie, appelle des outils, lit les résultats et répète. Le harnais possède la boucle ; le modèle est un ingrédient. Trois raisons pour lesquelles vous changeriez l'ingrédient :

Coût. Les sessions d'agent consomment rapidement des jetons car chaque résultat d'outil est réinjecté dans le contexte. Acheminer les sessions de routine vers un modèle moins cher, ou vers DeepSeek V4-Flash au lieu de V4-Pro, modifie votre facture sans modifier votre flux de travail. Vous pouvez conserver un modèle de pointe coûteux configuré pour les sessions qui en ont besoin.

Localisation des données. Certaines bases de code ne peuvent pas quitter le bâtiment. Un bloc de fournisseur pointant vers un modèle fonctionnant sur votre propre matériel signifie que les invites, le contenu des fichiers et les sorties d'outils ne traversent jamais le réseau. Même harnais, même interface utilisateur, zéro sortie de données.

Développement local. Lorsque vous créez des plugins ou testez le comportement d'un agent, vous ne voulez pas que chaque itération coûte des crédits d'API ou dépende de votre réseau. Un petit modèle local répond assez rapidement pour tester la boucle, et vous remettez le vrai modèle en place lorsque le comportement est important.

La conception découle de l'architecture de dsh : tout dans le harnais est un plugin, et l'adaptateur de modèle est l'une des pièces remplaçables. Les routes de fournisseur sont détenues par le plugin dsh-llm-pi-ai, qui est documenté dans le catalogue de configuration des plugins du dépôt comme détenant « les routes de fournisseur que cette instance possède ». C'est le mécanisme. L'interface utilisateur est un bloc YAML.

Le bloc fournisseur, clé par clé

Les fournisseurs personnalisés se trouvent dans $DSH_HOME/settings.yaml, et vous pouvez également les créer depuis l'interface utilisateur web sous Paramètres → Modèles. Voici l'exemple tiré directement de la documentation officielle :

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Ce que chaque clé fait :

• my-gateway est l'ID du fournisseur. C'est un identifiant permanent, alors choisissez un nom avec lequel vous pouvez vivre ; le nom d'affichage montré dans l'interface utilisateur est défini séparément.
• apiKeyEnv nomme la variable d'environnement qui contient votre clé API. Le fichier de paramètres ne contient jamais le secret lui-même, seulement cette référence. Plus d'informations sur l'emplacement de la clé réelle ci-dessous.
• api déclare le protocole de communication. openai-completions est la valeur documentée pour les points de terminaison compatibles OpenAI, ce qui permet à la promesse du « n'importe quel modèle » de fonctionner : la plupart des passerelles, des environnements d'exécution locaux et des fournisseurs hébergés parlent ce protocole.
• baseURL est la racine du point de terminaison auquel le harnais envoie les requêtes.
• models liste les ID de modèles disponibles via ce fournisseur. Chaque entrée nécessite au moins un id, qui doit correspondre à ce que le point de terminaison attend dans le corps de la requête.
• input déclare les modalités par modèle. Les modèles personnalisés sont par défaut en mode texte uniquement, donc un modèle de vision doit explicitement déclarer input: [text, image] ou les pièces jointes d'images ne l'atteindront pas. Il existe également un defaultInput au niveau de la route qui définit une valeur de secours pour chaque modèle du fournisseur ; un input au niveau du modèle le remplace.
• compat contient des commutateurs de compatibilité pour les points de terminaison qui s'écartent du comportement standard d'OpenAI. La documentation en mentionne deux : supportsDeveloperRole: false pour les backends qui rejettent le rôle developer, et maxTokensField: max_tokens pour les backends qui veulent l'ancien nom de champ pour la limite de sortie. Compat peut être défini au niveau de la route ou par modèle.

Une commodité à connaître : lorsque vous ajoutez un fournisseur personnalisé via l'interface utilisateur web, une option « Récupérer les modèles disponibles » interroge la route GET /models compatible OpenAI du point de terminaison et remplit la liste des modèles pour vous. Si votre point de terminaison implémente cette route, vous évitez la saisie manuelle.

Où se trouve la clé API réelle

Les secrets sont stockés en mode écriture seule dans $DSH_HOME/.credentials.yaml. Après avoir enregistré une clé via l'interface utilisateur, dsh ne renvoie qu'un descripteur expurgé ; la valeur littérale n'est jamais affichée à nouveau. settings.yaml contient des références (noms apiKeyEnv, descripteurs d'identifiants), jamais les clés elles-mêmes. Cette séparation signifie que vous pouvez commettre ou partager un fichier de paramètres sans divulguer quoi que ce soit, et faire pivoter une clé sans toucher à la configuration du fournisseur.

Recette 1 : Exécuter un modèle local via Ollama

Ollama expose une API compatible OpenAI à http://localhost:11434/v1, que Ollama documente dans son propre guide de compatibilité OpenAI. Étant donné que dsh parle openai-completions à n'importe quelle URL de base, l'appairage est simple.

[VÉRIFIER : la documentation de dsh ne montre pas d'exemple spécifique à Ollama ; cette recette applique le schéma de fournisseur personnalisé documenté au point de terminaison compatible OpenAI documenté par Ollama. Testez sur votre installation avant de publier en interne.]

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

Notes à ce sujet :

• Ollama ne nécessite pas de clé API localement, mais le schéma attend une référence d'identifiant, alors définissez une valeur factice : export OLLAMA_API_KEY=ollama. Ollama ignore tout ce que vous envoyez.
• L'id du modèle doit correspondre à l'étiquette servie par Ollama. Exécutez ollama list et copiez les noms exactement, balise incluse.
• Tirez d'abord le modèle (ollama pull gpt-oss:20b) et confirmez que le serveur répond avant de le connecter à dsh. Nous avons couvert la configuration locale complète dans comment exécuter GPT-OSS en utilisant Ollama, et le même schéma fonctionne pour d'autres modèles open-weight comme Kimi K3 si votre matériel le permet.

Une vérification rapide vous épargne une session d'agent déroutante : accédez à http://localhost:11434/v1/models dans Apidog avant de toucher la configuration de dsh. Si cette requête renvoie votre liste de modèles, l'URL de base est correcte, le serveur est actif, et l'option « Récupérer les modèles disponibles » dans l'interface utilisateur de dsh fonctionnera également. Si ce n'est pas le cas, aucune configuration de harnais ne le corrigera.

Gestion des attentes : les harnais d'agent s'appuient fortement sur l'appel d'outils et le contexte long. Les petits modèles locaux gèrent la boucle pour les tests, mais ils planifieront moins bien et abandonneront les appels d'outils plus souvent que les modèles de pointe autour desquels le harnais a été construit. C'est bien pour le développement de plugins ; c'est frustrant pour le travail réel.

Recette 2 : Un point de terminaison hébergé compatible OpenAI (Qwen via DashScope)

Pour un exemple hébergé, choisissez un fournisseur qui documente sa compatibilité OpenAI plutôt qu'un fournisseur dont vous supposez qu'il l'a. Alibaba Cloud Model Studio (DashScope) le fait : sa page de compatibilité OpenAI documente un point de terminaison /compatible-mode/v1 pour les modèles Qwen, avec des domaines régionaux spécifiques à l'espace de travail (pour Singapour : https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) et une authentification via la variable d'environnement DASHSCOPE_API_KEY.

Mappé sur le schéma dsh :

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max

Remplacez {WorkspaceId} par le domaine de votre espace de travail réel depuis la console Model Studio, et vérifiez la liste des modèles du fournisseur pour les ID actuels ; nous tenons un aperçu du niveau phare dans notre guide API Qwen 3.8. Le même schéma s'étend à tout fournisseur avec une compatibilité OpenAI documentée : l'API Kimi de Moonshot, OpenRouter, un déploiement vLLM, ou la passerelle interne de votre entreprise. Les seules parties qui changent sont baseURL, le nom de la variable d'environnement et les ID de modèle. Si vous avez configuré des modèles open source dans Codex, cela vous semblera familier ; le bloc YAML de dsh joue le même rôle que la configuration model_providers de Codex.

Deux spécificités des points de terminaison hébergés :

• Si le point de terminaison du fournisseur rejette les requêtes avec des erreurs étranges concernant les rôles ou les champs de jetons, c'est à cela que servent les commutateurs compat. Essayez d'abord supportsDeveloperRole: false ; les implémentations plus anciennes compatibles OpenAI sont antérieures au rôle developer.
• Les modèles de vision doivent déclarer explicitement input: [text, image], même si le modèle hébergé prend en charge les images. dsh suppose que les modèles personnalisés sont en mode texte uniquement, sauf indication contraire.

Recette 3 : Les fournisseurs de catalogue intégrés

Vous n'avez pas besoin d'un bloc personnalisé pour les clouds grand public. dsh est livré avec des fournisseurs de catalogue pour DeepSeek, Anthropic et OpenAI, où la configuration consiste principalement à « coller une clé API ». Les entrées de catalogue spécialisées ont leurs propres flux d'authentification natifs : Bedrock utilise les identifiants AWS, Vertex demande un projet ADC, Azure a besoin de sa version d'API, et Codex s'authentifie via OAuth.

Les fournisseurs de catalogue sont la voie à faible friction lorsque vous voulez simplement Claude ou GPT derrière le harnais, et c'est ainsi que la plupart des gens exécuteront DeepSeek V4-Pro, dont le lancement de l'API en août 2026 est arrivé en même temps que le harnais lui-même (détails sur api-docs.deepseek.com). Les fournisseurs personnalisés sont destinés à tout ce que le catalogue ne couvre pas : environnements d'exécution locaux, passerelles, fournisseurs régionaux et agrégateurs compatibles OpenAI.

Sélectionner le modèle et ce que les sessions retiennent

L'ajout d'un fournisseur rend ses modèles disponibles ; la sélection d'un modèle dans Paramètres → Modèles en fait la valeur par défaut pour les nouvelles sessions. Deux comportements de la documentation à assimiler :

1. Les sessions existantes conservent le modèle avec lequel elles ont été démarrées. Les sessions enregistrent leur modèle d'origine, donc changer la valeur par défaut en cours de projet ne réécrit pas silencieusement l'historique ni ne modifie ce qu'une session en cours utilise.
2. Si vous supprimez le fournisseur qui possède la valeur par défaut actuelle, le compositeur bloque l'entrée jusqu'à ce que vous choisissiez un nouveau modèle. Le harnais échoue bruyamment plutôt que de deviner.

Cette épinglage de session est important pour la reproductibilité : lorsque vous comparez dsh à d'autres harnais (nous l'avons fait exactement dans DeepSeek Harness vs Claude Code), vous pouvez être sûr que la transcription d'une session reflète un seul modèle, et non un échange en cours d'exécution.

Dépannage des défaillances courantes

URL de base incorrecte ou inaccessible. La défaillance la plus courante est la moins exotique. Confirmez que l'URL se termine là où le protocole l'attend (généralement /v1 pour les points de terminaison compatibles OpenAI, /compatible-mode/v1 pour DashScope) et qu'un simple GET {baseURL}/models réussit en dehors du harnais. C'est le point de contrôle où Télécharger Apidog se rentabilise en cinq minutes : envoyez la requête avec le même en-tête (Authorization: Bearer $KEY) que le harnais enverra, et lisez le code de statut réel et le corps au lieu d'une erreur de harnais enveloppée. Si vous développez hors ligne ou si le fournisseur est instable, simulez les réponses /models et /chat/completions du fournisseur dans Apidog et pointez baseURL vers le mock pendant que vous construisez.

Variable d'environnement manquante ou vide. apiKeyEnv nomme une variable ; elle n'en crée pas une. Si la variable n'est pas définie dans l'environnement où dsh s'exécute réellement, les requêtes sont envoyées sans authentification et renvoient un 401. N'oubliez pas qu'un processus lancé depuis une interface graphique ou un gestionnaire de services peut ne pas hériter de votre profil shell. Exécutez echo $GATEWAY_API_KEY dans le même contexte qui lance dsh web, pas seulement dans un terminal aléatoire.

Inadéquation de la modalité d'entrée. Vous attachez une image, et le modèle ne la voit jamais, ou la requête échoue. Les modèles personnalisés sont en mode texte uniquement par défaut. Ajoutez input: [text, image] sur l'entrée du modèle, ou définissez defaultInput au niveau de la route si chaque modèle du fournisseur gère les images.

Particularités du protocole. Les erreurs mentionnant un rôle non pris en charge ou un paramètre de jeton rejeté indiquent des commutateurs de compatibilité : supportsDeveloperRole: false et maxTokensField: max_tokens sont les deux documentés.

Tout fonctionnait hier. Préversion développeur. Épinglez la version que vous déployez, lisez les notes de publication avant de mettre à niveau, et attendez-vous à ce que le schéma des paramètres change. Le répertoire deepseek-harness est la source de vérité, pas n'importe quel article de blog, y compris celui-ci.

Une autre note d'intégration : les fournisseurs de modèles ne sont que la moitié de l'histoire de la personnalisation. L'autre moitié concerne les outils que l'agent peut appeler, et vous pouvez câbler directement vos flux de travail API ; nous couvrons cela dans l'utilisation d'Apidog CLI dans DeepSeek Harness.

FAQ

DeepSeek Harness prend-il officiellement en charge Ollama ?

La documentation officielle des fournisseurs ne mentionne pas Ollama par son nom. Ce qu'elle prend en charge est tout point de terminaison parlant le protocole openai-completions, et Ollama documente une API compatible OpenAI à http://localhost:11434/v1. La recette ci-dessus combine les deux moitiés documentées ; testez-la sur votre installation, car dsh est une préversion développeur et les schémas peuvent changer entre les versions.

Où dsh stocke-t-il mes clés API ?

Dans $DSH_HOME/.credentials.yaml, en mode écriture seule. L'interface utilisateur affiche un descripteur expurgé après l'enregistrement, et settings.yaml ne contient que des références comme les noms apiKeyEnv. Vous ne vous retrouvez jamais avec une clé en texte clair dans votre configuration de fournisseur.

Puis-je exécuter différents modèles pour différentes sessions ?

Oui. La sélection d'un modèle définit la valeur par défaut pour les nouvelles sessions uniquement ; chaque session existante conserve le modèle avec lequel elle a été démarrée. Vous pouvez donc exécuter un modèle bon marché comme DeepSeek V4-Flash pour les sessions de routine, passer par défaut à un modèle plus lourd pour un problème difficile, et vos sessions antérieures restent inchangées.

Mon point de terminaison personnalisé renvoie des erreurs que la même requête ne produit pas dans curl. Que faire ?

Comparez les charges utiles exactes. Le harnais peut envoyer un rôle developer ou un champ de limite de jetons plus récent que votre backend n'accepte pas ; les corrections documentées sont supportsDeveloperRole: false et maxTokensField: max_tokens sous compat. Rejouer la requête formatée par le harnais dans un client API vous montre sur quel champ le backend échoue.