Tutoriel API DeepSeek V4.1 Flash : créer un agent de réparation visuelle des bugs

Qu’est-ce que DeepSeek V4.1 Flash ?

DeepSeek sert V4.1 Flash via l’API sous l’ID de modèle deepseek-flash. Il accepte l’entrée image, prend en charge les modes avec et sans raisonnement, dispose d’une fenêtre de contexte d’un million de jetons et peut retourner jusqu’à 384 K jetons via Chat Completions et l’API Responses.

Notre aperçu de DeepSeek V4.1 Flash couvre le lancement, l’architecture et les benchmarks. 

Comment fonctionne DeepSeek V4.1 Flash ?

DeepSeek décrit V4.1 Flash comme une épine dorsale MoE de 552 Md de paramètres, tandis que Hugging Face annonce 763 Md de paramètres pour le checkpoint publié. L’écart provient essentiellement de la mémoire conditionnelle Engram (196 Md), ainsi que de l’encodeur et du projecteur de vision, des composants inclus dans le checkpoint mais en dehors du backbone MoE.

Son design Causal Encoder-Decoder réutilise les états de l’encodeur mis en cache, avec 8 Md de paramètres actifs par jeton en entrée et 16 Md en sortie.

Quoi de neuf dans DeepSeek V4.1 Flash ?

V4.1 Flash est le premier modèle de la nouvelle famille V4.1, avec une compréhension d’image intégrée nativement. Les embeddings visuels et textuels sont entraînés conjointement dès le pré-entraînement, plutôt qu’ajoutés ensuite comme dans le modèle expérimental V4-Flash-Vision-Exp.

L’API Responses est antérieure à V4.1 Flash ; DeepSeek a ajouté une prise en charge native lors du déploiement initial de V4. Les noms de modèles retirés deepseek-v4-flash et deepseek-v4-flash-vision-exp pointent désormais vers V4.1 Flash.

Combien coûte DeepSeek V4.1 Flash ?

La tarification de DeepSeek est basée sur les heures de pointe, avec un tarif hors pointe fixé à 50 % du tarif de pointe. Lors de mon exécution, l’entrée mise en cache coûtait 0,003 $ par million de jetons hors pointe et 0,006 $ en pointe, l’entrée non mise en cache 0,15 $ hors pointe et 0,30 $ en pointe, et la sortie 0,60 $ hors pointe et 1,20 $ en pointe, selon la page de tarification de DeepSeek. 

Les heures de pointe sont 01:00–04:00 et 06:00–10:00 UTC, du lundi au vendredi, hors jours fériés chinois. Toutes les autres heures sont hors pointe, et les jours fériés chinois sont entièrement hors pointe.

Ce que nous allons construire : l’agent de réparation visuelle Launch Metrics

Nimbus Analytics Launch Metrics est un tableau de bord Flask pour les visiteurs totaux, les inscriptions, le taux de conversion, le chiffre d’affaires et les inscriptions quotidiennes. J’ai placé trois bugs dans trois fichiers, sans indiquer à l’agent leur nature. Le code et le tableau de bord cassé sont dans ce référentiel GitHub.

Tableau de bord cassé à côté du design de référence. Image par l’auteur.

Les trois bugs requièrent des preuves différentes. L’un apparaît dans la capture, un autre affecte le comportement du navigateur, et le troisième échoue sous pytest. L’agent ne reçoit aucune liste de bugs.

Avant de confier cela à l’agent, je définis ce que « corrigé » signifie : la suite pytest doit passer, et une nouvelle capture doit correspondre visuellement à une image de référence. L’avis du modèle ne suffit pas : le runner vérifie ces deux éléments de preuve.

Comment fonctionne la boucle de réparation

La boucle alterne entre une requête au modèle et l’exécution d’outils locaux. V4.1 Flash renvoie du raisonnement, un message ou des appels d’outils ; Python exécute les outils demandés et ajoute les résultats à l’historique. La boucle s’arrête quand le modèle répond sans nouvel appel d’outil ou atteint la limite de quatorze tours.

Boucle de réparation reliant modèle, outils et navigateur. Image par l’auteur.

Comment configurer l’API DeepSeek V4.1 Flash

Vous aurez besoin de Python 3.10 ou plus et d’une clé API DeepSeek créditée. L’API DeepSeek suit le format des requêtes OpenAI, donc ce projet utilise le openai package Python avec base_url pointant vers DeepSeek.

Créez un environnement virtuel et installez les dépendances du projet.

python3 -m venv .venv
source .venv/bin/activate
pip install openai flask playwright pytest python-dotenv requests streamlit
playwright install chromium

J’ai testé avec openai 3.14.1, flask 3.1.3 et playwright 1.63.0. Enregistrez la clé dans un fichier .env à la racine du projet sous DEEPSEEK_API_KEY=sk-... et chargez-la avec python-dotenv. Si votre clé fonctionne déjà avec l’API Responses, passez le bloc de code suivant ; sinon, la requête vérifie la clé et l’URL de base.

from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")

response = client.responses.create(model="deepseek-flash", input="Say hi in five words.")
print(response.output_text)

Si un court message de salutation s’affiche, la clé et l’URL de base sont correctes.

Étape 1 : montrer au modèle à quoi ressemble « corrigé »

La première entrée de l’agent contient une capture de référence, une courte tâche et l’URL live. C’est la seule image envoyée dans un message utilisateur. Toutes les autres captures proviennent d’un outil.

Le runner envoie l’image de référence comme URL de données base64 à chaque requête. DeepSeek recommande l’API Files lorsqu’une image est réutilisée. Un file_id évite de renvoyer la même image à chaque fois.

Obtenir une première réaction avant toute modification

Dans l’image jointe, j’ai demandé ce que le modèle vérifierait en premier, sans lui donner d’outils. Cela m’a permis d’examiner son plan avant toute édition. La réponse proposait : lister les fichiers du projet, remonter les variables CSS et prendre une capture ; j’ai utilisé reasoning: {"effort": "high"}, le niveau de raisonnement par défaut de DeepSeek.

Étape 2 : donner à l’agent des outils utiles

L’agent reçoit quatre tools de fonction et un outil personnalisé. 

• list_files et read_file inspectent le projet, tous deux limités à dashboard/ et tests/. 

• run_tests exécute pytest.

• capture_dashboard_screenshot lance Chromium en mode headless via Playwright.

L’outil personnalisé est apply_patch, déclaré comme {"type": "custom", "name": "apply_patch"} et accepté « pour compatibilité Codex ». Tout autre nom d’outil personnalisé renvoie une erreur 400, tandis que les types intégrés comme la recherche web ou l’utilisation d’ordinateur sont ignorés sans erreur.

Les arguments de fonction arrivent en JSON texte et sont vérifiés avant l’exécution Python. apply_patch arrive comme entrée d’outil personnalisé : le code le traite donc à part et vérifie le patch avant d’écrire les fichiers. Les erreurs d’outil sont renvoyées au modèle au lieu d’arrêter la boucle.

Renvoyer les captures Playwright en sortie d’outil

Quand capture_dashboard_screenshot s’exécute, son résultat n’est pas enregistré sur disque. Python le renvoie comme une partie input_image au sein de function_call_output. DeepSeek lit alors la capture comme une image et non une description texte.

history.append({
    "type": "function_call_output",
    "call_id": item.call_id,
    "output": [{"type": "input_image", "image_url": f"data:image/png;base64,{png_b64}"}],
})

L’agent peut patcher le CSS, reprendre une capture et vérifier si les valeurs sont lisibles.

Étape 3 : construire la boucle d’agent et gérer vous‑même l’historique

L’historique vit dans une liste Python car l’API ne prend pas en charge previous_response_id ni les conversations côté serveur. Le mode reasoning exige aussi chaque élément de raisonnement des tours d’outils précédents.

Important : si la sortie d’outil est insérée entre deux appels d’un même tour, la requête suivante renvoie une erreur 400. Ajoutez tous les éléments de response.output dans l’ordre, puis exécutez les outils et ajoutez leurs résultats.

Le runner limite l’agent à quatorze tours et aux répertoires dashboard/ et tests/. Il n’offre aucun accès shell, vérifie les arguments des outils et utilise pytest pour la vérification.

DeepSeek V4.1 Flash accepte‑t‑il des sorties structurées ?

Oui, via l’API Responses, DeepSeek V4.1 Flash accepte un JSON Schema via text.format. L’option response_format de Chat Completions prend en charge le mode JSON mais pas les schémas. Après l’arrêt de la boucle, la requête finale consigne les bugs, les correctifs, les résultats des tests, les résultats de capture et la méthode de vérification.

Le projet inclut aussi une application Streamlit dans app_streamlit.py. Le même agent s’exécute en générateur avec stream=True, de sorte que la page affiche le raisonnement et les appels d’outils en temps réel. La barre latérale ajuste l’effort de raisonnement et le niveau de détail des images.

L’interface Streamlit diffuse l’exécution de l’agent. Vidéo par l’auteur.

Étape 4 : exécuter l’agent de correction visuelle

L’exécution paraissait terminée après un patch, mais la page live n’était pas d’accord.

Trouver et corriger les bugs

L’agent a passé ses deux premiers tours à observer avant de modifier quoi que ce soit : le premier a listé les fichiers et pris une capture de référence, le second a lu app.py, index.html, style.css et le fichier de tests. 

Au troisième tour, il a exécuté pytest, puis au quatrième, il a appliqué un patch unique corrigeant la formule de conversion, la couleur de la métrique, et alignant le sélecteur JavaScript sur l’ID du canvas.

-    conversion_rate = data["conversions"] / data["signups"] * 100
+    conversion_rate = data["conversions"] / data["total_visitors"] * 100

Au cinquième tour, tous les cinq tests passaient. C’est là que l’exécution a cessé d’être nette. Chaque nouvelle capture affichait toujours 15 % de conversion et un graphique vide.

Détecter l’obsolescence du système et y remédier

L’agent a confirmé que les fichiers sur disque contenaient les correctifs, a relancé la capture et a vérifié si le serveur chargeait bien le Python et les templates modifiés. Deux tests de fraîcheur temporaires n’apparaissaient pas non plus dans la page live.

Au quatorzième tour, la boucle avait atteint sa limite et identifié la cause : run_tests vérifie le code sur disque, tandis que la capture reflète un processus en cours d’exécution avec un état périmé. Flask a démarré avec debug=False, donc aucun reloader n’a chargé le module Python modifié, et l’auto‑reload des templates n’était pas activé.

Le changement CSS était visible, tandis que la valeur issue du Python et le graphique basé sur le template restaient périmés. Pytest importait app.py depuis le disque ; des tests au vert ne garantissaient donc pas une page à jour.

Après avoir redémarré Flask, le tableau de bord correspondait à l’image de référence. La pièce manquante était un outil restart_server, pas un patch de code supplémentaire.

Le redémarrage rend visibles les changements patchés. Image par l’auteur.

L’agent a‑t‑il corrigé le tableau de bord ?

Oui, l’agent a corrigé le tableau de bord sur disque. Il n’a modifié que les trois fichiers fautifs, et pytest est passé de quatre échecs à cinq tests réussis. Après redémarrage de Flask, la page live montrait toutes les corrections.

Étape 5 : mesurer l’usage, le cache et le coût

Parce que l’agent renvoie son historique, les requêtes ultérieures répètent une grande partie de l’entrée des tours précédents. DeepSeek confronte ce préfixe répété à son cache automatique. Le cache fonctionne au mieux des possibilités, ces chiffres ne valent donc que pour cette exécution.

Sur quatorze tours de réparation et une requête finale de rapport JSON, l’API a compté 156 724 jetons d’entrée, dont 137 088 mis en cache, soit 87 % de taux de hit. La sortie totalise 11 497 jetons, dont 9 362 de raisonnement. L’exécution a eu lieu hors pointe, si bien que les quinze requêtes ont coûté environ 0,0103 $.

La sortie de raisonnement est la plus grande catégorie de coût. Image par l’auteur.

Une base de code plus large, davantage de captures ou un taux de cache plus faible modifieraient le volume de jetons et le coût.

Limites connues de l’API DeepSeek V4.1 Flash

Trois limites de l’API pèsent avant de dépasser la démo.

• Les réponses en arrière‑plan ne sont pas prises en charge, donc les tours longs bloquent jusqu’à la fin.

• parallel_tool_calls et max_tool_calls sont ignorés ; les appels d’outils en parallèle restent activés.

• La troncature automatique n’est pas prise en charge : les requêtes qui dépassent la limite de contexte renvoient une erreur 400.

Checklist de déploiement d’un agent DeepSeek V4.1 Flash

Avant d’utiliser ce schéma en production, placez les contrôles dans le code applicatif plutôt que dans les instructions du modèle.

• Appliquer des limites de tours et de coûts, et alerter quand elles sont atteintes
• Restreindre l’accès aux fichiers et vérifier chaque argument d’outil
• ajouter des outils pour redémarrer et contrôler le service, afin que la vérification porte sur le code courant
• Consigner l’usage de jetons, les appels d’outils, les résultats des tests et l’état final

Quand utiliser apply_patch plutôt que des tools classiques ?

Utilisez apply_patch lorsqu’une modification unique doit mettre à jour plusieurs fichiers, comme ici. Exécutez les tests après le patch, car un appel mal formé peut endommager plusieurs fichiers.

Utilisez read_file et write_file quand chaque édition nécessite une validation séparée. Cela prend plus de tours, mais une mauvaise modification n’affecte qu’un seul fichier.

Conclusion

La boucle de réparation visuelle a corrigé les trois bugs en un patch, mais l’exécution n’a pas été un succès « propre ». Pytest passait alors que Flask servait encore l’ancien Python et la sortie des templates, si bien que l’agent n’a pas pu confirmer la page finale avant que je ne redémarre le serveur.

J’ajouterais un outil restart_server et une comparaison pixel à pixel avant de tester une application plus grande. Je conserverais la frontière de fichiers et la limite de tours, puis traiterais pytest et la comparaison de capture comme deux contrôles distincts. La réussite de l’un ne doit jamais se substituer à la réussite de l’autre.