Guide d'intégration de l'API DeepSeek : Demandes compatibles avec OpenAI via ECAIX

Ce guide explique comment tester un identifiant de modèle DeepSeek via ECAIX en utilisant un point de terminaison API compatible avec OpenAI. Il couvre la demande minimale fonctionnelle, des exemples en Python et curl, la vérification des identifiants de modèle, le streaming, la sortie structurée, les outils, et un chemin de diagnostic pour les erreurs courantes.

Le guide décrit l'accès via le portefeuille ECAIX à un identifiant de modèle exposé dans le catalogue actuel d'ECAIX. Il ne prétend pas que ECAIX soit le point de terminaison officiel de l'API DeepSeek ni que toutes les fonctionnalités DeepSeek soient disponibles via toutes les routes de portefeuille. Vérifiez toujours la page du modèle en direct et la documentation du fournisseur avant de transférer un travail en production.

Démarrage rapide

Utilisez cette séquence si vous avez déjà une application avec le SDK OpenAI :

1. Consultez la page du modèle DeepSeek v4.1 Flash et confirmez que l'identifiant est disponible.
2. Créez une clé API ECAIX.
3. Configurez l'URL de base compatible avec OpenAI à https://ecaix.com/api/ai/v1.
4. Gardez le SDK et le code de l'application inchangés là où c'est possible.
5. Exécutez la demande minimale ci-dessous.
6. Ajoutez le streaming, la sortie JSON ou les outils uniquement après que la demande de base fonctionne.

Point de terminaison et identifiant de modèle

Pour les clients compatibles avec OpenAI :

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

L'identifiant de modèle n'est pas une promesse permanente dans un article de blog. Vérifiez-le sur la page du répertoire des modèles en direct avant chaque nouvelle intégration ou déploiement. Si vous avez besoin d'un membre différent de la famille DeepSeek, copiez l'identifiant exact du détail de la page du modèle plutôt que de deviner un suffixe.

Le format du point de terminaison est également important. Le SDK doit recevoir le chemin de base se terminant par /v1 ; le client ajoute ensuite /chat/completions ou un autre chemin d'opération. Ne pas ajouter /chat/completions à base_url si le SDK l'ajoute déjà.

Python avec le SDK OpenAI

Installez ou mettez à jour le SDK Python OpenAI dans votre environnement virtuel :

python -m pip install --upgrade openai

Ensuite, utilisez l'URL de base ECAIX et la clé API :

const client = new OpenAI({
  apiKey: process.env.ECAIX_API_KEY,
  baseURL: "https://ecaix.com/api/ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

console.log(response.choices[0].message.content);

Utilisez du code côté serveur pour la demande API. Une application navigateur doit appeler votre propre backend plutôt que d'exposer une clé ECAIX dans le JavaScript côté client.

Demande de diagnostic avec curl

Si le SDK échoue, retirez le SDK de l'équation et testez directement le point de terminaison. Sauvegardez les en-têtes et le corps séparément pour distinguer un problème HTTP d'un problème de format de réponse.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

Ne copiez pas les en-têtes sauvegardés ou la réponse dans une demande publique sans avoir enlevé les clés API, les identifiants de demande, les prompts, les chemins de dépôt et les données clients.

Diagnostic de la réponse

Utilisez l'ordre suivant :

1. Code HTTP : déterminez si la demande a atteint un point de terminaison valide.
2. Corps de la réponse : lisez le code d'erreur du fournisseur ou du portefeuille.
3. Identifiant de modèle : copiez l'identifiant exact du répertoire des modèles actuel.
4. Authentification : vérifiez l'en-tête de clé, le compte et les permissions.
5. Forme de la demande : réduisez le corps à model, messages et une limite d'entrée minimale.
6. Champs de fonctionnalité : ajoutez le streaming, le JSON ou les outils un par un.
7. Comportement du SDK : comparez la demande du SDK avec la demande directe via curl.

Cela évite que les problèmes de bibliothèque client ne soient confondus avec le routage du modèle ou les permissions du compte.

Réponses en streaming

Si l'application a besoin d'une sortie incrémentale, ajoutez le streaming uniquement après qu'une demande normale réussisse :

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Le comportement exact des événements dépend du point de terminaison et du SDK. Vérifiez comment votre cadre gère un delta vide, un événement d'utilisation final, une interruption de connexion et une terminaison de type [DONE]. Ne considérez pas une implémentation de streaming comme prête à la production jusqu'à ce que vous ayez testé les interruptions et les retours.

Sortie structurée et JSON

Si vous avez besoin d'une sortie lisible par machine, commencez par une demande normale puis ajoutez la plus petite option de sortie structurée supportée par le point de terminaison et le modèle. Validez le contenu retourné avec un vrai parseur JSON. Une demande disant "retournez du JSON" n'est pas la même chose qu'une réponse conforme à un schéma.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with keys title and priority."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

L'acceptation de response_format peut dépendre du modèle et du chemin. Si le point de terminaison retourne une erreur de paramètre non supporté, retirez le champ et vérifiez la documentation du chemin avant d'essayer un autre format.

Appels de fonctions et outils

L'appel d'outils nécessite un test séparé de la génération de texte. Commencez par une seule fonction inoffensive et inspectez le nom et les arguments retournés avant d'exécuter quoi que ce soit.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

print(response.choices[0].message.tool_calls)

Un modèle peut retourner une réponse de texte valide tout en échouant à l'appel d'outils en raison de la conversion de schéma, des paramètres non supportés ou du comportement spécifique au client. N'exécutez jamais les arguments d'outils retournés contre un système de production sans avoir validé le schéma et ajouté des contrôles d'autorisation.

Chemins compatibles avec OpenAI et Anthropic

ECAIX expose différentes surfaces de compatibilité pour différents clients :

Lisez la documentation des Completions de Chat, la documentation des Réponses, et la documentation des Messages Anthropic avant de choisir un chemin. Le même identifiant de modèle peut ne pas exposer des champs ou un comportement identiques sur chaque surface de compatibilité.

Détails actuels des modèles

Utilisez les pages de détails en direct pour vérifier les capacités et la disponibilité :

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Ces pages sont plus fiables qu'un article statique pour les identifiants de modèle actuels, les informations de contexte et les liens de prix.

Erreurs courantes

Checklist de sécurité et production

Avant de passer au-delà d'un projet de test, confirmez :

• Les clés API sont stockées côté serveur et peuvent être mises à jour.
• Les prompts et les réponses ne contiennent pas de secrets ou de données clients non autorisés.
• Vous comprenez si le portefeuille enregistre les demandes et pendant combien de temps les logs sont conservés.
• La disponibilité et les prix des modèles sont vérifiés sur les pages en direct.
• Les temps d'attente, les retours, l'idempotence et les limites de débit sont gérés par votre application.
• Les interruptions de streaming ne créent pas de tâches dupliquées.
• Les appels d'outils ont des listes blanches, des validations, des autorisations et des journaux d'audit.
• Les termes du fournisseur et du portefeuille permettent le travail que vous prévoyez d'envoyer.

En