6 méthodes pour déployer DeepSeek Harness localement

TLDR DeepSeek Harness (dsh) est l’environnement d’exécution d’agents open source de DeepSeek AI, publié en aperçu développeur autour du 13 août 2026 sous licence MIT. Il suit le principe « Modèle + Harness = Agent », chaque fonctionnalité (modèles, outils, sessions, bacs à sable, boucles, UI) étant implémentée comme des plugins Cordis interchangeables.

La façon la plus rapide de l’exécuter en local est npx @deepseek-ai/dsh web (nécessite Node.js ^22.19 ou ≥24), ce qui lance une interface Web à l’adresse http://127.0.0.1:3080. Vous fournissez une clé API DeepSeek (ou compatible OpenAI) et un workspace. Des builds depuis les sources, applications desktop, Docker, SDK Python et intégrations Ollama sont également disponibles. Pour un accès multi-modèles de niveau production, une meilleure fiabilité et le contrôle des coûts tout en utilisant le harness, routez les requêtes via l’endpoint unifié compatible OpenAI de CometAPI.

Points clés

• DeepSeek Harness n’est pas un modèle — c’est l’orchestrateur/environnement local qui permet aux modèles d’agir sur des fichiers, shells, outils et sessions.
• One-liner officiel : npx @deepseek-ai/dsh web → ouvre l’UI Web locale sur le port 3080.
• L’exigence Node.js est stricte : ^22.19.0 ou ≥24.x.
• Prend en charge les modèles officiels DeepSeek (deepseek-v4-flash, deepseek-v4-pro), les passerelles personnalisées compatibles OpenAI, et les modèles locaux via plugins/Ollama.
• Architecture entièrement basée sur des plugins (noyau Cordis) ; modes disponibles : Standard, Minimal, Code et Creator.
• Adoption rapide : de plusieurs dizaines de milliers à bien plus de 100k étoiles GitHub en quelques jours après le lancement.
• Recommandé pour les power users : associez-le à CometAPI (https://www.cometapi.com/) comme fournisseur personnalisé pour accéder à 500+ modèles, économiser 20–40 % et n’utiliser qu’une seule clé API.
• Utilisez toujours un workspace isolé ; l’agent peut modifier des fichiers et exécuter des commandes.
• Le statut d’aperçu développeur implique des changements potentiellement incompatibles — épinglez les versions pour des expérimentations proches de la production.

Qu’est-ce que DeepSeek Harness et pourquoi c’est important en 2026

DeepSeek Harness (dsh) est un environnement d’exécution d’agents open source développé par DeepSeek AI. Publié sous licence MIT en aperçu développeur, il met l’accent sur la composabilité : chaque capacité — adaptateurs de modèles, outils, compétences, sessions, bacs à sable, stockage, boucles d’agent, planification et UI — existe sous forme de plugin Cordis pouvant être monté, démonté, échangé ou recomposé via la configuration. Il n’existe pratiquement aucun cœur privilégié nécessitant des patchs.

Principes de conception clés :

• Agent = Modèle + Harness.
• Flux d’événements traçables prenant en charge la reprise, le fork, la recherche et la relecture.
• Multiples modes d’exécution (trousse à outils complète standard, mode code/orchestration, mode minimal pour le benchmarking, modes creator/expérimentaux).
• UI Web locale en priorité pour l’usage interactif, plus des options headless et SDK pour l’automatisation.

Ressources officielles :

• GitHub : https://github.com/deepseek-ai/deepseek-harness
• Produit/landing : https://www.deepseek.com/harness/en/ (et pendant chinois)
• Les pages d’installation et miroirs communautaires confirment les mêmes commandes de base.

Note terminologique importante : « déploiement local » peut signifier deux choses différentes. Le DeepSeek Harness abordé dans ce guide s’exécute localement sur votre ordinateur, mais le projet standard deepseek-harness se connecte à DeepSeek V4-Pro ou V4-Flash via une API. Cela signifie que le harness, la configuration, les sessions, la validation et la logique client peuvent être locaux, tandis que l’inférence du modèle est normalement effectuée par l’API de DeepSeek. Si vous avez besoin d’une inférence véritablement hors ligne avec des poids de modèle sur votre propre GPU, c’est une autre architecture de déploiement.

Prérequis et configuration système

Avant l’installation, vérifiez les points suivants :

• Systèmes d’exploitation : Windows 10+, macOS 10.15+, distributions Linux grand public (x64 ou arm64). Le SDK Python a des contraintes supplémentaires (Linux x64/arm64 ou macOS 14+ arm64).
• Node.js : requis pour la voie principale via l’UI Web. Plage ciblée : ^22.19.0 || ≥24.0.0. Vérifiez avec node --version. Les versions intermédiaires impaires hors de cette plage ne sont pas prises en charge.
• Gestionnaires de paquets : npm/npx (inclus avec Node). Les builds depuis les sources nécessitent pnpm (installer via npm install -g pnpm).
• Git : requis pour cloner les sources.
• Python (optionnel) : 3.10+ pour le SDK Python officiel.
• Clé API / endpoint : clé API DeepSeek depuis platform.deepseek.com, ou tout endpoint compatible OpenAI + clé + nom de modèle.
• Matériel : aucun GPU requis pour le harness lui-même — l’inférence modèle se fait à distance (ou via un fournisseur local que vous configurez). Les ressources d’un ordinateur portable standard suffisent pour l’UI Web et l’orchestration.
• Réseau : nécessaire au premier lancement pour récupérer les paquets ; ensuite, l’UI peut fonctionner avec uniquement les appels API du modèle.
• Workspace : préparez un répertoire isolé. L’agent peut lire, écrire et exécuter des commandes dans le workspace configuré — ne le pointez jamais vers des données de production ou personnelles sans garde-fous.

Sources des exigences : README officiel et plusieurs guides d’installation indépendants publiés peu après le lancement.

Méthode 1 : One-liner officiel avec npx (recommandée pour la plupart des utilisateurs)

C’est la voie la plus rapide et officiellement mise en avant.

1. Assurez-vous que Node.js respecte la version requise.
2. Ouvrez un terminal et exécutez :

Bash

npx @deepseek-ai/dsh web

1. Le package se télécharge (ou utilise le cache), démarre le profil UI Web et affiche l’adresse d’écoute — par défaut http://127.0.0.1:3080.
2. Ouvrez cette URL dans un navigateur. Acceptez l’avertissement d’aperçu développeur si affiché.
3. À la première utilisation, configurez un fournisseur de modèle (Settings → Models) en collant votre clé API et en sélectionnant un modèle tel que deepseek-v4-flash ou deepseek-v4-pro.
4. Choisissez ou créez un répertoire de workspace.
5. Commencez à lancer des tâches.

Pour utiliser un port différent :

Bash
npx @deepseek-ai/dsh web --port 8080

One-liners spécifiques à la plateforme qui s’assurent aussi de la présence de Node sont disponibles sur des sites communautaires (PowerShell sur Windows avec winget, Homebrew sur macOS, NodeSource sur Debian/Ubuntu, etc.).

Avantages : aucune empreinte d’installation permanente au-delà du cache npm ; récupère toujours une version publiée récente ; onboarding le plus simple. Inconvénients : nécessite le réseau pour le package initial ; moins pratique pour l’inspection approfondie des sources ou des builds personnalisés.

Méthode 2 : Installer et exécuter depuis les sources

À utiliser si vous voulez lire les plugins Cordis, épingler un commit, développer des presets personnalisés ou contribuer.

Bash

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

La même UI Web apparaît sur le port par défaut. Les builds en aperçu développeur peuvent casser d’un commit à l’autre, traitez donc cela comme une voie expérimentale.

Méthode 3 : Applications desktop (sans configuration Node)

Des wrappers desktop communautaires et tiers empaquettent le runtime pour éviter aux utilisateurs d’installer Node/pnpm eux-mêmes :

• Clients légers basés sur Tauri qui amorcent un runtime Node embarqué et synchronisent le harness amont le plus récent au lancement. Ils tournent sur 127.0.0.1:3080, conservent les données en local et enregistrent les commandes dsh.
• Packaging basé sur Electron incluant des dépendances épinglées.

Téléchargez les installateurs depuis les pages GitHub Releases correspondantes (recherchez « deepseek-harness-desktop »). Au premier lancement, les composants principaux sont téléchargés (quelques centaines de Mo). Pratiques pour les non-développeurs, mais il ne s’agit pas de produits officiels DeepSeek — examinez le dépôt et les sommes de contrôle SHA.

Méthode 4 : Déploiement Docker / conteneur

Des images Docker et des fichiers compose communautaires existent pour exécuter l’UI Web dans un conteneur, souvent avec terminaison HTTPS via nginx et prise en charge de passerelles arbitraires compatibles OpenAI. Flux typique :

Bash

git clone <docker-repo>
cd <docker-repo>
cp .env.example .env   # set API key / public host
docker compose up -d --build

Utile pour l’accès LAN, les serveurs ou les environnements où Node n’est pas souhaité sur l’hôte. Certains setups prennent en charge un settings.yaml personnalisé pour des fournisseurs non-DeepSeek.

Méthode 5 : SDK Python pour un usage programmatique / headless

Pour des agents non supervisés ou l’intégration dans des pipelines Python :

Bash

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk

Définissez les variables d’environnement :

Bash

export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash

Ensuite, exécutez les exemples inclus ou utilisez la classe DeepSeekHarness dans votre propre code, sur un workspace et un répertoire de session isolés. Le SDK embarque son propre runtime et ne nécessite pas Node.js au niveau système.

Méthode 6 : Intégration Ollama

Ollama fournit un lanceur pratique :

Bash

ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud

Ollama peut installer le package si nécessaire et stocke les paramètres de lancement séparément. La recherche Web et le support des outils dépendent du modèle choisi et de l’accès cloud d’Ollama.

Configuration des modèles et fournisseurs (y compris CometAPI)

Dans l’UI Web, allez à Settings → Models.

• Pour l’officiel DeepSeek : collez la clé depuis platform.deepseek.com. Les modèles typiques sont deepseek-v4-flash et deepseek-v4-pro.
• Pour les catalogues de fournisseurs (Anthropic, OpenAI, etc.) : utilisez le flux « Add provider ».
• Pour des endpoints personnalisés / auto-hébergés / agrégateurs : choisissez « Add a custom provider ». Renseignez un Provider ID permanent, le base URL, le protocole (généralement openai-completions), la référence d’environnement ou la valeur de clé API, et au moins un model ID.

Recommandation CometAPI (fortement suggérée pour de nombreux workflows proches de la production) CometAPI est une plateforme d’infrastructure IA unifiée qui expose 500+ modèles (y compris les variantes DeepSeek, GPT, Claude, Gemini, Grok et bien d’autres) via un unique endpoint compatible OpenAI : https://api.cometapi.com/v1.

Avantages avec DeepSeek Harness :

• Une seule clé API au lieu de gérer de multiples identifiants fournisseurs.
• Tarification compétitive (économies rapportées de 20–40 % par rapport aux tarifs directs de nombreux vendeurs).
• Haute disponibilité (objectif SLA 99,9 %), faible latence médiane et facturation à l’usage.
• Changement de modèle facile pour A/B testing ou optimisation des coûts sans modifier la configuration du harness au-delà du model ID.
• Compatibilité immédiate : les modèles d’utilisation de l’OpenAI SDK fonctionnent après avoir seulement changé base_url et la clé.

Dans le formulaire de fournisseur personnalisé du harness :

• Base URL : https://api.cometapi.com/v1
• Protocole : openai-completions (ou l’option équivalente prise en charge)
• Clé API : votre clé CometAPI
• Model ID : toute chaîne de modèle supportée depuis le catalogue des modèles CometAPI

Cette combinaison conserve la puissance de l’environnement d’agent local tout en offrant un accès multi-vendeurs flexible et économique. Les nouveaux utilisateurs reçoivent généralement des crédits d’essai gratuits. Documentation : https://apidoc.cometapi.com/.

Les clés sont stockées en écriture seule (par ex., sous $DSH_HOME/.credentials.yaml) ; l’UI n’affiche que des descripteurs masqués.

Dépannage de DeepSeek Harness

DEEPSEEK_API_KEY introuvable

Vérifiez :

echo $DEEPSEEK_API_KEY

Sur Windows :

echo $env:DEEPSEEK_API_KEY

Si vide, reconfigurez-la.

Erreur 400 reasoning_content

Ceci pointe généralement vers une gestion incorrecte du cycle de vie du raisonnement.

Vérifiez que votre application préserve les informations de raisonnement pertinentes de l’assistant à travers les requêtes multi-tours de réflexion/appels d’outils.

C’est l’un des problèmes centraux que le harness est précisément conçu pour gérer.

Erreur de longueur de contexte

Vérifiez :

input tokens + max_tokens

La limite dure documentée est :

1,048,576 tokens

Réduisez soit le contexte d’entrée, soit la taille de sortie demandée.

Les appels d’outils deviennent mal formés pendant le streaming

Ne supposez pas que les chunks de flux arrivent dans l’ordre des outils.

Agréguez les deltas d’appels d’outils par tool_call.index, comme recommandé par le contrat du harness.

Les requêtes sont anormalement coûteuses

Vérifiez :

• le mode de réflexion (thinking mode)
• la longueur de sortie
• le taux de cache-hit
• la stabilité du préfixe de prompt
• le choix du modèle
• la tarification API actuelle

Une amélioration simple consiste souvent à déplacer les tâches routinières de Pro vers Flash.

Comparaison des méthodes d’installation et de déploiement

Données synthétisées depuis la documentation officielle et les guides publiés après le lancement (août 2026).

Conclusion et prochaines étapes

DeepSeek Harness apporte un environnement d’exécution d’agents entièrement pluginisé, conçu avec soin, sur les machines locales avec une friction quasi nulle via le one-liner npx. Combiné à un routage de modèles flexible — notamment via une plateforme unifiée telle que CometAPI — vous bénéficiez à la fois de workflows de codage agentiques modernes et d’un contrôle pratique des coûts, du choix des modèles et de la localité des données.

Commencez dès aujourd’hui avec :

npx @deepseek-ai/dsh web

Configurez une clé DeepSeek ou CometAPI, pointez-la vers un workspace sûr et explorez le mode Standard. Puis expérimentez le mode Minimal pour le benchmarking, des fournisseurs personnalisés pour l’optimisation des coûts ou le SDK Python pour l’automatisation.

Pour les instructions officielles les plus récentes, privilégiez toujours le dépôt GitHub et la documentation. Pour la fiabilité multi-modèles et des avantages de tarification tout en utilisant le harness, explorez CometAPI et sa documentation sur https://apidoc.cometapi.com/.