Intégration de Pi Agent avec DeepSeek
DeepSeek fournit une API compatible avec OpenAI, vous pouvez donc réutiliser la couche d'adaptateur OpenAI existante de Pi sans développer d'adaptateur distinct pour DeepSeek.
Le travail essentiel pour l'intégration ne consiste qu'en deux choses : déclarer le fournisseur et les paramètres du modèle dans models.json, et fournir la clé API via des variables d'environnement.
L'architecture globale est présentée dans le diagramme suivant :
Ce que l'on appelle une "API compatible avec OpenAI" signifie que le protocole d'interface HTTP du fournisseur est cohérent avec celui d'OpenAI. Tant que le protocole est compatible, tout outil prenant en charge OpenAI peut l'appeler directement ; DeepSeek appartient à cette catégorie.
Installer Pi
Pi dépend de l'environnement d'exécution Node.js. Avant l'installation, veuillez vous assurer que Node.js est prêt.
Installer Node.js
Téléchargez l'installateur correspondant à votre système depuis le site officiel de Node.js et installez-le avec les options par défaut.
Installer Pi CLI
Installez globalement via npm dans le terminal :
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Les utilisateurs de Linux et macOS peuvent également utiliser le script d'installation officiel pour installer en une seule commande :
curl -fsSL https://pi.dev/install.sh | sh
Vérifier l'installation
Exécutez la commande suivante. Si le numéro de version s'affiche normalement, l'installation a réussi :
pi --version
Sortie similaire à :
0.83.0
Configurer le fournisseur DeepSeek
Pi définit des fournisseurs de modèles personnalisés via models.json. Cette section intègre DeepSeek en tant qu'API compatible avec OpenAI.
Chemin du fichier de configuration
Les différents systèmes d'exploitation ont des chemins de configuration différents. Veuillez suivre celui correspondant à votre système :
| Système d'exploitation | Chemin du fichier de configuration |
|---|---|
| Linux / macOS | ~/.pi/agent/models.json |
| Windows | %USERPROFILE%\.pi\agent\models.json |
Écrire models.json
Écrivez le contenu suivant dans le fichier de configuration :
{
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com",
"api": "openai-completions",
"apiKey": "$DEEPSEEK_API_KEY",
"models": [
{
"id": "deepseek-v4-pro",
"name": "DeepSeek V4 Pro",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 1.74,
"output": 3.48,
"cacheRead": 0.145,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
},
{
"id": "deepseek-v4-flash",
"name": "DeepSeek V4 Flash",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 0.14,
"output": 0.28,
"cacheRead": 0.028,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
}
]
}
}
}
Explication des éléments de configuration
Ce qui suit explique un par un les principaux champs utilisés dans models.json :
| Champ | Type | Obligatoire ? | Description | Valeur par défaut |
|---|---|---|---|---|
| baseUrl | string | Requis | Point de terminaison d'API compatible avec OpenAI pour DeepSeek | https://api.deepseek.com |
| api | string | Requis | Protocole d'intégration ; déclare l'utilisation du protocole compatible avec OpenAI Completions | openai-completions |
| apiKey | string | Requis | Lit la clé à partir d'une variable d'environnement portant le même nom ; nul besoin d'écrire la clé en clair dans le fichier de configuration | $DEEPSEEK_API_KEY |
| contextWindow | nombre | Requis | Taille de la fenêtre de contexte (tokens) | 1000000 |
| maxTokens | nombre | Requis | Longueur maximale de sortie par requête (tokens) | 384000 |
| raisonnement | booléen | Optional | Déclare que le modèle prend en charge la capacité de raisonnement en chaîne (chain-of-thought) | vrai |
| coût | objet | Optional | Enregistre les prix unitaires pour les entrées/sorties/les succès de cache, utilisés par l'interface Pi pour estimer les coûts | — |
| requiresReasoning ContentOnAssistantMessages | booléen | Recommandé | Dans les conversations à plusieurs tours, les messages de l'assistant doivent conserver le champ reasoning_content ; sinon, des problèmes de compatibilité peuvent survenir | vrai |
| thinkingFormat | string | Recommandé | Analyse et affiche le processus de raisonnement selon le format de contenu de réflexion spécifique à DeepSeek | deepseek |
| reasoningEffortMap | objet | Recommandé | Associe les niveaux d'effort de raisonnement de Pi aux niveaux réellement pris en charge par DeepSeek | — |
reasoningEffortMap associe les cinq niveaux de raisonnement de Pi (minimal / low / medium / high / xhigh) aux niveaux pris en charge par DeepSeek. À l'exception de xhigh associé à max, tous les autres convergent vers high.
Sélection du modèle
La configuration déclare deux modèles DeepSeek. Les principales différences sont les suivantes :
| Modèle | Fenêtre de contexte | Sortie maximale | Prix unitaire d'entrée | Prix unitaire de sortie | Prix unitaire des hits de cache | Scénarios applicables |
|---|---|---|---|---|---|---|
| deepseek-v4-pro | 1,000,000 | 384,000 | 1.74 | 3.48 | 0.145 | Capacité de raisonnement renforcée, adaptée aux tâches complexes |
| deepseek-v4-flash | 1,000,000 | 384,000 | 0.14 | 0.28 | 0.028 | Réponse plus rapide, coût inférieur |
Les prix unitaires sont en dollars américains par million de tokens.
Obtenir et définir la clé API
Demandez d'abord une clé API sur la plateforme ouverte DeepSeek :https://platform.deepseek.com/api_keys。

Pour Linux / macOS, exportez la variable d'environnement dans le terminal :
export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
Pour Windows (PowerShell), définissez-la comme suit :
$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"
Il est recommandé d'écrire la commande export dans la configuration du shell (comme ~/.bashrc, ~/.zshrc ou PowerShell Profile) pour éviter de devoir le définir à nouveau chaque fois que vous ouvrez un nouveau terminal.
Veuillez remplacer « your DeepSeek API Key » dans l'exemple par votre vraie clé. La clé API est une information sensible ; veuillez la garder en sécurité et ne jamais la committer dans un dépôt.
Exécuter et tester
Une fois configuré, vous pouvez lancer Pi et passer au modèle DeepSeek.
Lancer Pi
Entrez dans le répertoire du projet :
cd ~/example-test/
Exécutez directement la commande pi :
pi
Passer au modèle DeepSeek
Après être entré dans l'interface interactive, basculez en suivant ces étapes :
Saisissez/modelOuvrez le sélecteur de modèle.

Sélectionnez le fournisseur deepseek, puis choisissez DeepSeek-V4-Pro ou DeepSeek-V4-Flash.

Ensuite, interrogez le modèle actuel.

Après avoir basculé, vous pouvez commencer à coder directement dans ce framework de terminal minimaliste.

Étapes de test suggérées
Vérifiez si l'intégration est complète et utilisable en parcourant la liste de contrôle ci-dessous :
| Élément de test | Mode opératoire | Résultat attendu |
|---|---|---|
| Authentification et connectivité | Envoyez une phrase, par exemple, "Bonjour, veuillez présenter la plateforme d'apprentissage d'exemple" | Recevez une réponse normale sans erreurs d'authentification 401 / 403, confirmant que apiKey et baseUrl sont correctement configurés |
| Capacité de raisonnement | Posez une question qui nécessite un raisonnement en plusieurs étapes, par exemple en lui demandant d'analyser d'abord puis de fournir une solution | Affichez un processus de réflexion visible, indiquant que thinkingFormat et reasoning sont actifs |
| Appels d'outils à plusieurs tours | Demandez à Pi d'appeler continuellement des outils pour lire des fichiers, exécuter des commandes, modifier du code et vérifier les résultats | La conversation multi-tours reste stable sans erreurs causées par l'absence de reasoning_content |
| Basculement de l'effort de raisonnement | Dans /model, passez de medium à xhigh | Le comportement est conforme au mappage reasoningEffortMap ; xhigh correspond au max de DeepSeek |
| Calcul des coûts | Après avoir exécuté quelques tâches réelles, vérifiez les statistiques de coûts | Les statistiques de l'interface correspondent aux prix unitaires définis dans le champ cost |
Parmi ceux-ci, « Appels d'outils multi-tours » est le scénario clé pour vérifier si la configuration requiresReasoningContentOnAssistantMessages est correcte.
Dépannage courant
Si vous rencontrez des problèmes lors de l'intégration, utilisez la liste de contrôle suivante pour les localiser rapidement.
Impossible de voir DeepSeek dans le sélecteur de modèles
Vérifiez si le chemin de models.json est correct. Les chemins pour Windows et Linux / macOS sont différents.
Vérifiez également que le format JSON ne comporte pas d'erreurs de syntaxe, telles que des virgules de fin ou des guillemets non fermés.
Échec de l'authentification
Confirmez que la variable d'environnement DEEPSEEK_API_KEY a été définie correctement.
Remarque : la session de terminal dans laquelle vous exécutez la commande pi doit être la même session que celle où vous avez défini la variable d'environnement.
Les appels d'outils multi-tours signalent des erreurs
Vérifiez d'abord si requiresReasoningContentOnAssistantMessages et thinkingFormat ont été entièrement configurés comme décrit ci-dessus.
Besoin de capacités de personnalisation supplémentaires
Vous pouvez consulterla documentation officielle des modèles Pi, pour des options de configuration plus complètes.
Autres extensions