Tutorial sull'API di Codestral: primi passi con l'API di Mistral

Codestral è un modello generativo all’avanguardia ottimizzato per attività di generazione di codice, tra cui fill-in-the-middle (FIM) e completamento del codice. Addestrato su oltre 80 linguaggi di programmazione, Codestral eccelle sia nei linguaggi più comuni che in quelli meno usati, risultando uno strumento versatile per gli sviluppatori.

Sfruttando l'API di Codestral, possiamo automatizzare e integrare la generazione di codice nei nostri flussi di lavoro. In questo tutorial troverai una guida passo passo all’uso dell’API di Codestral.

Se vuoi una panoramica di Codestral, dai un’occhiata al mio articolo Cos’è Codestral di Mistral.

Endpoint dell'API di Codestral

Codestral offre due endpoint API principali per soddisfare esigenze diverse:

• codestral.mistral.ai: ideale per utenti individuali e integrazioni su piccola scala. Questo endpoint è attualmente gratuito fino al 1° agosto 2024, dopodiché diventerà un servizio in abbonamento mensile.
• api.mistral.ai: pensato per casi d’uso aziendali e ad alta domanda, offre limiti di velocità più alti e un supporto robusto per applicazioni su larga scala.

Mistral consiglia l’endpoint codestral.mistral.ai se intendi usare Codestral come parte di un plugin per IDE o se prevedi di creare strumenti che espongono endpoint direttamente agli utenti, permettendo loro di usare le proprie chiavi API.

Mistral consiglia l’endpoint api.mistral.ai per tutti gli altri casi d’uso, grazie ai limiti di velocità più alti e all’idoneità per applicazioni business.

In questo tutorial useremo l’endpoint codestral.mistral.ai per mostrare le capacità di Codestral.

Primi passi con l'API di Codestral

Ottenere una chiave API

Per usare l'API di Codestral, devi registrarti a un account Mistral AI e ottenere una chiave API. Segui questi passaggi:

Passaggio 1: Registrazione

Visita la pagina di registrazione di Mistral AI e crea un account.

Passaggio 2: Ottieni una chiave API

Per api.mistral.ai, vai alla scheda API Keys e clicca su Create new key per generare la tua chiave API.

Per codestral.mistral.ai: vai alla scheda Codestral (quella con il badge “New” sotto la scheda API Keys) e segui le istruzioni nella pagina per ottenere la tua chiave API. Nota che al momento c’è una lista d’attesa e dovrai fornire un numero di telefono per iscriverti. Una volta approvato, potrai accedere alla tua chiave API insieme a due endpoint specifici di codestral.mistral.ai nella stessa pagina, come mostrato di seguito:

Questo articolo usa gli endpoint di codestral.mistral.ai per mostrare Codestral, quindi tutti gli esempi saranno adattati a questo.

Autenticazione

Per autenticare le nostre richieste API, creeremo due funzioni Python usando la libreria requests. Queste funzioni gestiranno la comunicazione con i due endpoint API di Codestral, includendo la chiave API ottenuta nelle intestazioni della richiesta per l’autenticazione. Ecco le due funzioni:

1. call_chat_endpoint — per chiamare il Chat Endpoint https://codestral.mistral.ai/v1/chat/completions.
2. call_fim_endpoint — per chiamare il Completion Endpoint https://codestral.mistral.ai/v1/fim/completions.

Ecco come farlo in 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}"Offerto da

Comprendere gli endpoint dell'API di Codestral

Ora che abbiamo ottenuto la chiave API e impostato le funzioni di autenticazione, vediamo come usare i due endpoint dell’API di Codestral per la generazione di codice. Inizieremo con l’endpoint fill-in-the-middle (FIM).

Endpoint fill-in-the-middle

L’endpoint fill-in-the-middle è progettato per generare codice che si inserisce tra un punto iniziale (prompt) e un punto finale opzionale (suffix). È particolarmente utile quando serve generare un frammento specifico di codice all’interno di una struttura più ampia.

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

Parametri:

• prompt: il punto di partenza del codice.
• suffix (opzionale): il punto finale del codice.
• stop (opzionale): una sequenza di token che interrompe la generazione.

Esempio:

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)Offerto da

Endpoint instruct

L’endpoint instruct fornisce istruzioni al modello per generare codice. È utile per attività di generazione di codice più aperte.

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

Parametri:

• prompt: l’istruzione per l’attività di generazione del codice.
• temperature (opzionale): controlla la casualità del codice generato.
• max_tokens (opzionale): limita la lunghezza del codice generato.

Esempio:

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)Offerto da

Uso avanzato dell'API

Rate limit

Ogni endpoint ha rate limit diversi:

• codestral.mistral.ai: 30 richieste al minuto e 2000 richieste al giorno.
• api.mistral.ai: 200 richieste al secondo per workspace.

Per garantire un funzionamento fluido ed evitare di superare le soglie, è fondamentale gestire i rate limit. Una strategia efficace è implementare una logica di retry, che sospende e reinvia una richiesta dopo un intervallo specificato: possiamo usare la libreria time di Python per introdurre questo ritardo.

In alternativa, puoi tenere traccia del tuo uso dell’API per restare entro i limiti consentiti. Puoi registrare il numero di richieste effettuate e confrontarlo con i rate limit.

Gestione degli errori

I codici di errore comuni includono:

• 401 Unauthorized: chiave API non valida o autenticazione mancante.
• 429 Too Many Requests: superamento del rate limit.
• 500 Internal Server Error: problemi lato server di Mistral AI.

Per un errore 401 Unauthorized, verifica la chiave API e assicurati che sia inclusa correttamente nelle intestazioni della richiesta.

Per un errore 429 Too Many Requests, prova a implementare una logica di retry per attendere e riprovare la richiesta dopo un intervallo.

La logica di retry è utile anche per gestire 500 Internal Server Error e riprovare più tardi.

Personalizzare l'output

Per controllare formato e stile dell’output, puoi regolare parametri come il prompt (rendendolo più specifico o generale) e la temperature (che controlla la creatività del modello).

Sperimenta con questi parametri per trovare il giusto equilibrio tra creatività e prevedibilità nel codice generato.

Integrare l'API di Codestral

Codestral non è solo un’API standalone: possiamo integrarla nei flussi di lavoro di sviluppo esistenti. Vediamo due modi principali per farlo: tramite integrazioni con IDE ed editor di testo o creando script personalizzati.

IDE ed editor di testo

Codestral si integra senza problemi con i principali IDE ed editor tramite plugin o estensioni. Ad esempio, puoi configurare Codestral con Continue.dev per VS Code o JetBrains:

1. Installa l’estensione Continue per VS Code o JetBrains.
2. Seleziona Mistral API come provider e scegli Codestral come modello.
3. Clicca Get API Key per ottenere la chiave API di Codestral.
4. Clicca Add model, che compilerà automaticamente il file config.json.

Script personalizzati

Puoi creare script o applicazioni personalizzate che sfruttano l’API di Codestral per attività di generazione di codice. Ecco un semplice esempio di script che genera funzioni di 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)Offerto da

Best practice per usare l'API di Codestral

Per ottenere il massimo da Codestral, vediamo alcune best practice per usare l’API in modo efficace e responsabile.

Prompt chiari e concisi

Quando usi l’API di Codestral, la chiarezza è fondamentale. Assicurati che i tuoi prompt o le tue istruzioni siano ben definiti e non ambigui per ottenere l’output desiderato. Fornendo prompt specifici e contestuali, puoi guidare il modello verso codice in linea con le tue aspettative.

Affinamento iterativo

Ottimizzare le interazioni con l’API di Codestral implica un processo iterativo di affinamento. Sperimenta con parametri, prompt e input diversi per raggiungere i risultati desiderati. Analizza gli output generati e usali per migliorare i tuoi prompt. Affinando continuamente l’approccio, potrai aumentare nel tempo qualità e pertinenza del codice generato.

Uso responsabile

L’uso responsabile dell’API di Codestral è importante. Assicurati che il tuo utilizzo sia in linea con standard etici e legali. Evita di generare codice potenzialmente dannoso o malevolo. Segui le best practice per una programmazione sicura ed etica e rispetta privacy e diritti altrui. Un uso responsabile contribuisce a un ambiente di sviluppo positivo e sostenibile.

Conclusione

Questo tutorial ha fornito una guida pratica all’uso dell’API di Codestral per la generazione di codice. Abbiamo esplorato i diversi endpoint, le best practice e le opzioni di integrazione.

Ti invito a sperimentare con l’API e scoprire come può migliorare il tuo flusso di sviluppo.

Per saperne di più su Mistral, dai un’occhiata a questo tutorial su Mistral 7B e a questa guida al lavoro con il modello Mistral Large.