Un service de modèle compatible API a une tâche ingrate mais cruciale : transformer plusieurs formats de requêtes publiques en le prompt exact attendu par un modèle, puis renvoyer les tokens générés sous la forme de réponse attendue par le client. deepseek-recipe encapsule cette couche de traduction pour DeepSeek V4 et V4.1.

Il n'exécute pas le modèle. Il n'ouvre pas de port HTTP, n'exécute pas d'outils, ne recherche pas sur le web et ne stocke pas les conversations. Garder cette limite visible vous fera gagner du temps dans ce tutoriel : la sortie est un prompt rendu qu'un backend d'inférence pourrait consommer, pas une réponse du modèle.

Installer le binding Python

Le package officiel nécessite Python 3.10 ou plus récent :

python3 -m pip install deepseek-recipe

Pour un projet reproductible, installez-le dans un environnement virtuel et figez la version après la première exécution vérifiée. Le dépôt a été publié récemment en septembre 2026 et son API peut encore évoluer. Enregistrez à la fois la version du package Python et l'encodage V4/V4.1 sélectionné par votre application.

Le package est soutenu par une famille de crates Rust. Les utilisateurs Python n'ont pas besoin de réécrire leur service en Rust ; le binding expose les types de conversion et d'encodage requis pour une intégration normale.

Générer une conversation V4.1 minimale

Créez un petit script basé sur l'exemple officiel :

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

Il y a deux étapes délibérées. request.convert(...) mappe la charge utile Chat Completions dans la représentation Conversation partagée de la bibliothèque. render_conversation(...) applique l'encodage de prompt V4.1. Les garder séparées permet à un service API de normaliser différents protocoles externes avant de s'engager sur une disposition de tokens spécifique au modèle.

La chaîne du modèle dans la requête fait partie de la charge utile côté client ; l'objet d'encodage sélectionné contrôle comment la conversation normalisée est rendue. Ne déduisez pas qu'un nom de modèle arbitraire télécharge ou sélectionne automatiquement des poids. Votre service environnant doit valider le modèle demandé et router le prompt vers un backend approprié.

Try DeepSeek on MidassAI

Inspecter avant de connecter l'inférence

Imprimez le prompt uniquement dans un fixture de développement local, jamais dans des logs de production contenant des données utilisateur. Confirmez que les messages système et utilisateur sont représentés dans l'ordre prévu. Ajoutez des exemples Unicode, au contenu vide et multilignes. Si votre service prend en charge les images ou les outils, créez des fixtures séparés pour chacun au lieu de supposer que le cas texte seul prouve la compatibilité.

C'est aussi le bon moment pour les tests golden. Stockez un petit ensemble de charges utiles d'entrée non sensibles et d'attentes structurelles approuvées. La sortie encodée exacte peut légitimement changer selon les versions du package, donc décidez si une mise à jour de version doit mettre à jour les snapshots ou échouer jusqu'à révision.

Au minimum, testez :

un message système et un message utilisateur ;
une conversation multi-tours avec une réponse d'assistant ;
le mode thinking et chaque valeur d'effort de raisonnement prise en charge que vous exposez ;
temperature, top_p, et les limites de tokens de sortie à leurs bords autorisés ;
un outil de fonction client avec des arguments ;
des rôles malformés, des types de contenu et des options non prises en charge.

Le dernier groupe est important car la compatibilité du protocole est aussi une compatibilité de rejet. Un service qui supprime silencieusement un champ non pris en charge est plus difficile à déboguer qu'un service qui renvoie une erreur précise.

Comprendre ce que la bibliothèque peut traduire

La portée actuelle couvre les requêtes de style Messages, Chat Completions et Responses, y compris les réponses complètes et en streaming. La représentation partagée prend en charge le texte, les images, le thinking et les appels d'outils client. L'analyse de sortie couvre le contenu thinking, les appels d'outils, les objets JSON et les séquences d'arrêt.

Pour les requêtes Responses, les espaces de noms d'outils et l'outil personnalisé apply_patch sont pris en charge. Cela ne signifie pas que la bibliothèque applique les patches. Elle représente et analyse l'appel d'outil ; une application hôte décide toujours si l'outil existe, demande la permission, l'exécute et renvoie son résultat au modèle.

Le prétraitement d'image V4.1 est disponible via le composant image et OpenCV. Les images peuvent arriver en données base64 ou URLs externes. Un service de production doit définir des limites de taille, des vérifications de type média, des délais d'expiration de téléchargement et des restrictions réseau avant de confier du contenu distant au code de prétraitement.

Gérer explicitement les champs non pris en charge

À partir de la version vérifiée, logprobs et top_logprobs ne sont pas pris en charge. Ni le contenu de document, l'audio ou la vidéo, la récupération de fichier par file_id, les complétions multiples via n > 1, ou le contenu thinking chiffré.

Les attentes de sortie structurée nécessitent de la prudence. La bibliothèque peut analyser la sortie d'objet JSON, mais elle n'impose pas de schéma JSON, d'expressions régulières ou de définitions d'outils strictes. Si votre API annonce ces garanties, la validation doit se faire ailleurs. Un objet JSON analysé peut toujours violer le schéma de l'appelant.

Le stockage de conversation est également hors du package. previous_response_id ne récupère pas le contexte précédent. Votre service HTTP doit résoudre l'état de conversation stocké et passer les messages résultants dans la conversion, ou rejeter clairement le champ.

Les outils serveur tels que web_search ne sont pas pris en charge car la couche recipe n'exécute pas les outils. Si un client envoie une telle requête, ne la transformez pas en appel de fonction client sans documenter la différence sémantique.

L'intégrer à un service API sans brouiller les responsabilités

Un pipeline de service propre a quatre limites :

Authentification, limites de débit, limites de taille de corps et validation API publique.
Normalisation deepseek-recipe et encodage V4/V4.1.
Un backend d'inférence qui consomme des tokens et produit des tokens générés.
Analyse Recipe, orchestration d'outils appartenant à l'application et streaming HTTP.

Gardez des métriques autour de chaque limite. Le temps de conversion de requête, le temps jusqu'au premier token généré, le temps d'attente d'outil et le temps de sérialisation de réponse répondent à différentes questions opérationnelles. Les combiner en un seul numéro de latence rend les régressions difficiles à localiser.

Ne passez pas les prompts rendus dans les logs ou les systèmes de traçage par défaut. Enregistrez des métadonnées sûres telles que le nombre de messages, les types de contenu, la version d'encodage, le nombre de tokens et les erreurs de conversion. Si la journalisation de charge utile échantillonnée est inévitable, rendez-la sur option, expurgée, contrôlée par accès et de courte durée.

Quand ce tutoriel n'est pas la bonne voie

Utilisez deepseek-recipe lorsque vous construisez ou adaptez un service d'inférence et avez besoin d'une conversion de protocole spécifique à DeepSeek. Si vous voulez seulement appeler un endpoint compatible DeepSeek existant, utilisez le SDK client ou l'API HTTP de ce service. Ajouter un encodeur de prompt à un client d'application duplique le comportement du serveur et peut rendre les mises à jour plus difficiles.

Le package est plus valuable précisément parce que ce n'est pas un serveur tout-en-un. Il donne aux équipes d'infrastructure une couche de conversion partagée et testable tout en laissant le déploiement, la planification, la sécurité et les outils sous leur contrôle. Une première intégration réussie se termine par un prompt vérifié et une liste de champs non pris en charge—pas par une affirmation que toute la pile de service est complète.

Source vérifiée : dépôt officiel deepseek-recipe, consulté le 14 septembre 2026.

Convertir les requêtes API DeepSeek V4.1 avec Python