Tutoriel API Codestral : bien démarrer avec l’API de Mistral

Codestral est un modèle génératif de pointe optimisé pour les tâches de génération de code, notamment le fill-in-the-middle (FIM) et l’autocomplétion. Entraîné sur plus de 80 langages de programmation, Codestral excelle aussi bien sur les langages courants que sur les plus rares, ce qui en fait un outil polyvalent pour les développeurs.

En exploitant l’API Codestral, nous pouvons automatiser et intégrer la génération de code dans nos workflows. Dans ce tutoriel, nous vous proposons un guide pas à pas pour utiliser l’API Codestral.

Pour une présentation générale de Codestral, consultez mon article Qu’est-ce que Codestral de Mistral.

Endpoints de l’API Codestral

Codestral propose deux endpoints principaux pour répondre aux différents besoins :

• codestral.mistral.ai : idéal pour les utilisateurs individuels et les intégrations à petite échelle. Cet endpoint est actuellement gratuit jusqu’au 1er août 2024, puis passera à un abonnement mensuel.
• api.mistral.ai : pensé pour les entreprises et les usages à forte volumétrie, il offre des limites de débit plus élevées et un support robuste pour les applications à grande échelle.

Mistral recommande l’endpoint codestral.mistral.ai si vous comptez utiliser Codestral dans un plugin d’IDE ou si vous prévoyez de créer des outils exposant des endpoints directement aux utilisateurs, afin qu’ils puissent utiliser leur propre clé API.

Mistral recommande l’endpoint api.mistral.ai pour tous les autres cas d’usage, grâce à ses limites de débit plus élevées et son adéquation aux applications métier.

Dans ce tutoriel, nous utiliserons l’endpoint codestral.mistral.ai pour illustrer les capacités de Codestral.

Premiers pas avec l’API Codestral

Obtenir une clé API

Pour utiliser l’API Codestral, vous devez créer un compte Mistral AI et obtenir une clé API. Procédez comme suit :

Étape 1 : inscription

Rendez-vous sur la page d’inscription de Mistral AI et créez un compte.

Étape 2 : récupérer une clé API

Pour api.mistral.ai, accédez à l’onglet API Keys et cliquez sur Create new key pour générer votre clé.

Pour codestral.mistral.ai : ouvrez l’onglet Codestral (celui avec le badge « New » sous l’onglet API Keys) et suivez les instructions pour obtenir votre clé API. Notez qu’il existe actuellement une liste d’attente et qu’un numéro de téléphone est requis pour s’inscrire. Une fois approuvé, vous pourrez accéder à votre clé API ainsi qu’à deux endpoints spécifiques codestral.mistral.ai sur la même page, comme ci-dessous :

Cet article utilise les endpoints codestral.mistral.ai pour présenter Codestral ; tous les exemples seront donc adaptés à ce contexte.

Authentification

Pour authentifier nos requêtes API, nous allons créer deux fonctions Python avec la bibliothèque requests. Elles gèrent la communication avec les deux endpoints de l’API Codestral, en intégrant la clé API dans les en-têtes de requête. Voici les deux fonctions :

1. call_chat_endpoint — pour appeler le Chat Endpoint https://codestral.mistral.ai/v1/chat/completions.
2. call_fim_endpoint — pour appeler le Completion Endpoint https://codestral.mistral.ai/v1/fim/completions.

Voici comment procéder en Python :

import requests
import json

api_key = 'INSERT YOUR API KEY HERE'

def call_chat_endpoint(data, api_key=api_key):
    url = "<https://codestral.mistral.ai/v1/chat/completions>"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    if response.status_code == 200:
        return response.json()
    else:
        return f"Error: {response.status_code}, {response.text}"

def call_fim_endpoint(data, api_key=api_key):
    url = "<https://codestral.mistral.ai/v1/fim/completions>"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    if response.status_code == 200:
        return response.json()
    else:
        return f"Error: {response.status_code}, {response.text}"

Comprendre les endpoints de l’API Codestral

Maintenant que nous avons notre clé API et configuré les fonctions d’authentification, voyons comment utiliser les deux endpoints de Codestral pour générer du code. Commençons par l’endpoint fill-in-the-middle (FIM).

Endpoint fill-in-the-middle

L’endpoint fill-in-the-middle est conçu pour générer du code qui s’insère entre un point de départ (prompt) et un point de fin optionnel (suffix). Il est particulièrement utile lorsqu’il faut produire un bloc précis au sein d’une structure de code plus large.

URL de l’endpoint API : https://codestral.mistral.ai/v1/fim/completions

Paramètres :

• prompt : le point de départ du code.
• suffix (optionnel) : le point de fin du code.
• stop (optionnel) : une séquence de tokens pour arrêter la génération.

Exemple :

prompt = "def fibonacci(n: int):"
suffix = "n = int(input('Enter a number: '))\\nprint(fibonacci(n))"
data = {
    "model": "codestral-latest",
    "prompt": prompt,
    "suffix": suffix,
    "temperature": 0
}

response = call_fim_endpoint(data)

Endpoint instruct

L’endpoint instruct permet de fournir des consignes au modèle pour générer du code. Il est utile pour des tâches de génération plus ouvertes.

URL de l’endpoint API : https://codestral.mistral.ai/v1/chat/completions

Paramètres :

• prompt : l’instruction pour la tâche de génération de code.
• temperature (optionnel) : contrôle le degré d’aléatoire du code généré.
• max_tokens (optionnel) : limite la longueur du code généré.

Exemple :

prompt = "Please write me a function that adds up two numbers"
data = {
    "model": "codestral-latest",
    "messages": [
        {
            "role": "user",
            "content": prompt
        }
    ],
    "temperature": 0
}

response = call_chat_instruct_endpoint(data)

Utilisation avancée de l’API

Limites de débit

Chaque endpoint possède des limites de débit différentes :

• codestral.mistral.ai : 30 requêtes par minute et 2 000 requêtes par jour.
• api.mistral.ai : 200 requêtes par seconde et par espace de travail.

Pour garantir un fonctionnement fluide et éviter de dépasser les quotas, la gestion des limites de débit est essentielle. Une stratégie efficace consiste à implémenter une logique de retry, qui met en pause puis renvoie la requête après un délai défini — on peut utiliser la bibliothèque time de Python pour introduire ce délai.

Vous pouvez aussi suivre votre consommation d’API pour rester dans les seuils autorisés : journalisez le nombre de requêtes effectuées et comparez-le aux limites.

Gestion des erreurs

Codes d’erreur courants :

• 401 Unauthorized : clé API invalide ou authentification absente.
• 429 Too Many Requests : limite de débit dépassée.
• 500 Internal Server Error : problème côté serveur chez Mistral AI.

Pour une erreur 401 Unauthorized, vérifiez la clé API et assurez-vous qu’elle est bien incluse dans les en-têtes de la requête.

Pour une erreur 429 Too Many Requests, implémentez une logique de retry pour attendre puis retenter la requête après un délai.

La logique de retry est également utile pour gérer les 500 Internal Server Error en réessayant plus tard.

Personnaliser la sortie

Pour piloter le format et le style de sortie, vous pouvez ajuster des paramètres comme le prompt (plus précis ou plus général) et la temperature (qui régit la créativité du modèle).

Expérimentez ces paramètres pour trouver le bon équilibre entre créativité et prévisibilité dans le code généré.

Intégrer l’API Codestral

Codestral ne se limite pas à une API autonome : nous pouvons l’intégrer à nos workflows de développement existants. Examinons deux approches principales : via des intégrations IDE/éditeurs de texte ou en créant des scripts personnalisés.

IDEs et éditeurs de texte

Codestral s’intègre sans friction aux IDEs et éditeurs de texte populaires via des plugins ou extensions. Par exemple, vous pouvez configurer Codestral avec Continue.dev pour VS Code ou JetBrains :

1. Installez l’extension Continue pour VS Code ou JetBrains.
2. Sélectionnez Mistral API comme fournisseur et choisissez Codestral comme modèle.
3. Cliquez sur Get API Key pour obtenir la clé API Codestral.
4. Cliquez sur Add model, ce qui remplira automatiquement le fichier config.json.

Scripts personnalisés

Vous pouvez créer des scripts ou applications sur mesure qui exploitent l’API Codestral pour des tâches de génération de code. Voici un exemple simple de script qui génère des fonctions de test :

prompt="""Sure, here is a simple function in Python that adds up two numbers:

def add_two_numbers(num1, num2):
    return num1 + num2

You can use this function like this:
result = add_two_numbers(5, 3)
print(result)  # Outputs: 8

This function takes two arguments, num1 and num2, and returns their sum.\ndef test_add_two_numbers():""" 

suffix="" 

data = { "model": "codestral-latest", "prompt": prompt, "suffix": suffix, "temperature": 0 }

response = call_fim_endpoint(data)

Bonnes pratiques pour utiliser l’API Codestral

Pour tirer le meilleur parti de Codestral, passons en revue quelques bonnes pratiques pour utiliser l’API de façon efficace et responsable.

Prompts clairs et concis

Avec l’API Codestral, la clarté est essentielle. Veillez à ce que vos prompts ou instructions soient bien définis et sans ambiguïté pour obtenir le résultat souhaité. Des prompts précis et contextualisés orientent le modèle vers un code conforme à vos attentes.

Affinage itératif

Optimiser vos interactions avec l’API Codestral est un processus itératif. Testez différents paramètres, prompts et entrées pour atteindre le résultat visé. Analysez les sorties générées et servez-vous-en pour ajuster vos prompts. En affinant continuellement votre approche, vous améliorerez la qualité et la pertinence du code produit.

Utilisation responsable

L’utilisation responsable de l’API Codestral est primordiale. Assurez-vous que vos usages respectent les standards éthiques et juridiques. Évitez de générer du code malveillant ou nuisible. Adoptez les bonnes pratiques de programmation sûre et éthique, et respectez la vie privée et les droits des tiers. Une utilisation responsable contribue à un environnement de développement positif et durable.

Conclusion

Ce tutoriel vous a proposé un guide pratique pour utiliser l’API Codestral en génération de code. Nous avons parcouru les différents endpoints, les bonnes pratiques et les options d’intégration.

Nous vous encourageons à expérimenter l’API et à découvrir comment elle peut accélérer votre propre workflow de développement.

Pour en savoir plus sur Mistral, consultez ce tutoriel Mistral 7B et ce guide pour travailler avec le modèle Mistral Large.