DEV Community

Cover image for Comment exécuter n'importe quel modèle dans DeepSeek Harness ?
Antoine Laurent
Antoine Laurent

Posted on Originally published at apidog.com

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

DeepSeek Harness (dsh) est livré avec les modèles DeepSeek intégrés, mais vous n’êtes pas limité à ceux-ci. Le harnais traite les fournisseurs de modèles comme de la 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 exposé par cette URL. Une instance Ollama locale, une passerelle d’entreprise, Qwen via le mode compatible de DashScope, ou des fournisseurs de catalogue comme Anthropic et OpenAI se connectent tous au même mécanisme.

Essayez Apidog dès aujourd’hui

Ce guide détaille ce bloc clé par clé, puis propose trois recettes : 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 officiel des fournisseurs sur la branche master, récupéré le 20 août 2026. Attention : dsh est une préversion pour développeurs et le README avertit que des changements incompatibles sont attendus. Vérifiez toujours la documentation correspondant à votre version installée avant un déploiement en production.

Si vous découvrez le harnais, commencez par comprendre DeepSeek Harness et son fonctionnement, puis revenez ici pour configurer les fournisseurs.

Pourquoi changer de modèle dans un harnais d’agent ?

Un harnais d’agent exécute une boucle : le modèle planifie, appelle des outils, lit les résultats, puis recommence. Le harnais possède cette boucle ; le modèle est interchangeable.

Voici les principales raisons de changer de fournisseur ou de modèle.

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 plutôt que V4-Pro, réduit la facture sans changer le flux de travail. Vous pouvez garder un modèle haut de gamme pour les sessions complexes.

Localisation des données. Certaines bases de code ne doivent pas quitter votre infrastructure. Un fournisseur pointant vers un modèle exécuté sur votre matériel permet de conserver localement les invites, les contenus de fichiers et les sorties d’outils.

Développement local. Pour créer des plugins ou tester le comportement d’un agent, un modèle local réduit les coûts d’API et élimine la dépendance réseau. Utilisez un petit modèle pour tester la boucle, puis repassez à un modèle plus puissant lorsque la qualité de raisonnement est importante.

Cette flexibilité découle de l’architecture de dsh : tout dans le harnais est un plugin, y compris l’adaptateur de modèle. Les routes de fournisseur sont gérées par le plugin dsh-llm-pi-ai, documenté dans le catalogue de configuration des plugins comme propriétaire des routes de fournisseur de l’instance.

Le bloc fournisseur, clé par clé

Les fournisseurs personnalisés sont configurés dans $DSH_HOME/settings.yaml. Vous pouvez aussi les créer depuis l’interface web, dans Paramètres → Modèles.

Exemple issu 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]
Enter fullscreen mode Exit fullscreen mode

Voici le rôle de chaque clé :

  • my-gateway : ID permanent du fournisseur. Choisissez un nom stable ; le nom affiché dans l’interface est défini séparément.
  • apiKeyEnv : nom de la variable d’environnement contenant la clé API. Le fichier de paramètres contient seulement une référence, jamais le secret.
  • api : protocole utilisé pour communiquer avec le fournisseur. Utilisez openai-completions pour les points de terminaison compatibles OpenAI.
  • baseURL : URL racine vers laquelle dsh envoie les requêtes.
  • models : liste des modèles accessibles depuis ce fournisseur.
  • id : ID attendu par le point de terminaison dans le corps de la requête.
  • input : modalités acceptées par un modèle. Les modèles personnalisés sont en texte seul par défaut. Pour activer les images, déclarez explicitement : 
  input: [text, image]
Enter fullscreen mode Exit fullscreen mode
  • defaultInput : valeur de secours définie au niveau de la route pour tous les modèles du fournisseur. Un input défini au niveau d’un modèle le remplace.
  • compat : options pour les points de terminaison qui diffèrent du comportement OpenAI standard :
    • supportsDeveloperRole: false pour un backend qui rejette le rôle developer
    • maxTokensField: max_tokens pour un backend qui attend l’ancien nom du champ de limite de sortie

Vous pouvez définir compat au niveau de la route ou au niveau d’un modèle.

Lorsque vous ajoutez un fournisseur personnalisé via l’interface web, l’option Récupérer les modèles disponibles interroge généralement la route compatible OpenAI GET /models. Si votre endpoint l’implémente, vous pouvez remplir la liste sans saisir les ID à la main.

Où se trouve la clé API réelle ?

Les secrets sont stockés en écriture seule dans :

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

Après avoir enregistré une clé dans l’interface, dsh ne renvoie qu’un descripteur expurgé. La valeur littérale n’est plus affichée.

Le fichier settings.yaml contient des références — noms apiKeyEnv et descripteurs d’identifiants — mais pas les clés elles-mêmes. Vous pouvez donc partager ou versionner votre configuration sans exposer de secrets, puis faire pivoter une clé sans modifier le bloc fournisseur.

Recette 1 : exécuter un modèle local avec Ollama

Ollama expose une API compatible OpenAI sur :

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

Cette compatibilité est documentée dans le guide de compatibilité OpenAI d’Ollama. Comme dsh peut utiliser openai-completions avec une URL de base personnalisée, la configuration est directe.

La documentation dsh ne fournit pas d’exemple spécifique à Ollama. Cette recette applique le schéma de fournisseur personnalisé documenté par dsh à l’endpoint compatible OpenAI documenté par Ollama. Testez-la dans votre environnement avant une publication interne.

Ajoutez ce fournisseur dans $DSH_HOME/settings.yaml :

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
Enter fullscreen mode Exit fullscreen mode

Ensuite :

  1. Définissez une valeur factice pour la variable d’environnement : 
   export OLLAMA_API_KEY=ollama
Enter fullscreen mode Exit fullscreen mode

Ollama ne requiert pas de clé en local, mais le schéma dsh attend une référence d’identifiant.

  1. Téléchargez le modèle : 
   ollama pull gpt-oss:20b
Enter fullscreen mode Exit fullscreen mode
  1. Vérifiez les modèles servis : 
   ollama list
Enter fullscreen mode Exit fullscreen mode
  1. Copiez exactement le nom affiché par Ollama, balise comprise, dans models[].id.

Avant de connecter dsh, vérifiez la réponse du serveur :

curl http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

Vous pouvez aussi appeler cette URL dans Apidog. Si GET /v1/models retourne la liste des modèles, l’URL de base est correcte et le serveur est accessible. L’option Récupérer les modèles disponibles de dsh devrait alors fonctionner aussi.

Pour une configuration locale complète, consultez comment exécuter GPT-OSS avec Ollama. Le même schéma s’applique à d’autres modèles open-weight, tels que Kimi K3, si votre matériel est suffisant.

Gardez toutefois des attentes réalistes : les harnais d’agent dépendent fortement des appels d’outils et du contexte long. Un petit modèle local convient pour tester des plugins et la boucle d’agent, mais planifiera généralement moins bien et échouera plus souvent sur les appels d’outils qu’un modèle haut de gamme.

Recette 2 : un endpoint hébergé compatible OpenAI avec Qwen via DashScope

Pour un fournisseur hébergé, choisissez un service qui documente explicitement sa compatibilité OpenAI.

Alibaba Cloud Model Studio, aussi appelé DashScope, documente cette compatibilité sur sa page dédiée. Pour les modèles Qwen, le point de terminaison utilise /compatible-mode/v1.

Pour Singapour, le format est :

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

La clé est fournie via la variable DASHSCOPE_API_KEY.

Configuration 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
Enter fullscreen mode Exit fullscreen mode

Remplacez {WorkspaceId} par le domaine réel de votre espace de travail Model Studio. Vérifiez également la liste de modèles du fournisseur avant de choisir un ID. Pour un aperçu du niveau phare, consultez le guide de l’API Qwen 3.8.

Le même modèle de configuration s’applique à tout fournisseur documentant une compatibilité OpenAI, par exemple :

  • Moonshot et l’API Kimi ;
  • OpenRouter ;
  • un déploiement vLLM ;
  • une passerelle interne d’entreprise.

En pratique, vous modifiez surtout :

apiKeyEnv: VOTRE_VARIABLE
baseURL: https://votre-endpoint/v1
models:
  - id: votre-modele
Enter fullscreen mode Exit fullscreen mode

Si vous avez déjà configuré des modèles open source dans Codex, la logique sera familière : le bloc YAML dsh joue un rôle similaire à model_providers dans Codex.

Deux points à vérifier avec les endpoints hébergés :

  1. Erreurs liées aux rôles ou aux limites de jetons Commencez par ajouter une section de compatibilité : 
   compat:
     supportsDeveloperRole: false
Enter fullscreen mode Exit fullscreen mode

Pour les implémentations qui attendent l’ancien champ de limite de sortie :

   compat:
     maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode
  1. Modèles de vision Déclarez explicitement les images : 
   models:
     - id: votre-modele-vision
       input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Recette 3 : utiliser les fournisseurs de catalogue intégrés

Vous n’avez pas besoin d’un bloc personnalisé pour les principaux fournisseurs cloud. dsh inclut des fournisseurs de catalogue pour DeepSeek, Anthropic et OpenAI. Dans ce cas, la configuration consiste principalement à fournir une clé API.

Certaines entrées de catalogue utilisent leurs mécanismes d’authentification natifs :

  • Bedrock utilise les identifiants AWS ;
  • Vertex requiert un projet ADC ;
  • Azure nécessite sa version d’API ;
  • Codex s’authentifie via OAuth.

Utilisez les fournisseurs de catalogue lorsque vous voulez rapidement brancher Claude ou GPT au harnais. C’est aussi le chemin courant pour DeepSeek V4-Pro, dont le lancement d’API en août 2026 a coïncidé avec celui du harnais. Consultez les détails sur api-docs.deepseek.com.

Les fournisseurs personnalisés restent adaptés aux cas non couverts par le catalogue :

  • modèles locaux ;
  • passerelles internes ;
  • fournisseurs régionaux ;
  • agrégateurs compatibles OpenAI.

Sélectionner le modèle et comprendre ce que les sessions conservent

Ajouter un fournisseur rend ses modèles disponibles. Sélectionner un modèle dans Paramètres → Modèles en fait le modèle par défaut pour les nouvelles sessions.

Retenez ces deux comportements :

  1. Les sessions existantes conservent leur modèle d’origine.

    Une session enregistre le modèle utilisé à son démarrage. Modifier le modèle par défaut ne réécrit pas l’historique et ne modifie pas une session en cours.

  2. Supprimer le fournisseur du modèle par défaut bloque le compositeur.

    Vous devez choisir un nouveau modèle. Le harnais échoue explicitement plutôt que de sélectionner un remplaçant arbitraire.

Ce comportement améliore la reproductibilité : une transcription de session correspond à un seul modèle. C’est utile, notamment lorsque vous comparez dsh à d’autres harnais, comme dans DeepSeek Harness vs Claude Code.

Dépanner les échecs fréquents

URL de base incorrecte ou inaccessible

C’est le problème le plus courant.

Vérifiez que l’URL se termine au bon chemin :

  • généralement /v1 pour un endpoint compatible OpenAI ;
  • /compatible-mode/v1 pour DashScope.

Testez ensuite l’endpoint hors de dsh :

curl -H "Authorization: Bearer $KEY" \
  "{baseURL}/models"
Enter fullscreen mode Exit fullscreen mode

Vous pouvez faire le même test dans Télécharger Apidog pour inspecter le code HTTP et le corps de réponse exacts, plutôt qu’une erreur encapsulée par le harnais.

Pour développer hors ligne ou contourner un fournisseur instable, simulez les réponses :

GET /models
POST /chat/completions
Enter fullscreen mode Exit fullscreen mode

Puis pointez baseURL vers votre mock pendant le développement.

Variable d’environnement absente ou vide

apiKeyEnv désigne une variable : il ne la crée pas.

Si la variable n’existe pas dans l’environnement où dsh est réellement exécuté, les requêtes partiront sans authentification et recevront souvent un 401.

Vérifiez-la dans le même contexte de lancement que dsh web :

echo $GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

Attention : un processus lancé par une interface graphique ou un gestionnaire de services peut ne pas hériter de votre profil shell.

Modalité d’entrée incorrecte

Si vous joignez une image mais que le modèle ne la reçoit pas — ou si la requête échoue — ajoutez la modalité au modèle :

models:
  - id: vision-preview
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Si tous les modèles du fournisseur gèrent les images, vous pouvez définir defaultInput au niveau de la route.

Particularités du protocole

Les erreurs indiquant un rôle non pris en charge ou un paramètre de jeton rejeté signalent généralement un écart avec l’API OpenAI attendue par dsh.

Utilisez les options documentées :

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

« Tout fonctionnait hier »

dsh est une préversion pour développeurs. Épinglez la version déployée, consultez les notes de publication avant toute mise à niveau et attendez-vous à des changements de schéma.

Le dépôt deepseek-harness est la source de vérité, pas un article de blog, y compris celui-ci.

Les fournisseurs de modèles ne sont qu’une moitié de la personnalisation. L’autre concerne les outils appelables par l’agent. Pour connecter directement vos flux de travail API, consultez l’utilisation d’Apidog CLI dans DeepSeek Harness.

FAQ

DeepSeek Harness prend-il officiellement en charge Ollama ?

La documentation officielle des fournisseurs ne cite pas Ollama par son nom. Elle prend toutefois en charge tout point de terminaison utilisant le protocole openai-completions, et Ollama documente une API compatible OpenAI sur http://localhost:11434/v1.

La recette ci-dessus combine ces deux éléments documentés. Testez-la dans votre installation : dsh est une préversion et les schémas peuvent évoluer entre les versions.

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

Dans :

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

Le stockage est en écriture seule. Après l’enregistrement, l’interface affiche un descripteur expurgé. Le fichier settings.yaml ne contient que des références, comme les noms apiKeyEnv, jamais les clés en clair.

Puis-je utiliser différents modèles selon les sessions ?

Oui. Le modèle sélectionné devient le défaut des nouvelles sessions uniquement. Chaque session existante conserve le modèle avec lequel elle a démarré.

Vous pouvez donc utiliser un modèle économique comme DeepSeek V4-Flash pour les tâches de routine, passer temporairement à un modèle plus puissant pour un problème complexe, puis conserver intactes les sessions précédentes.

Mon endpoint personnalisé échoue alors que la même requête fonctionne avec 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 ne prend pas en charge. Essayez les correctifs documentés :

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Rejouez dans un client API la requête formatée par le harnais : vous identifierez précisément le champ qui fait échouer le backend.

Top comments (0)