Vai al contenuto principale
Italiano— Scegli una lingua
Menu

API Codestral in Python

Lezione 3 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Chiamare Codestral da Python
  2. Installazione e configurazione
  3. Chiamata FIM completa
  4. Chiamata Chat per la generazione di codice
  5. Parametri avanzati
  6. Due pattern da copiare e incollare
  7. Gestione degli errori
  8. Punti chiave

Chiamare Codestral da Python

Questa lezione passa dalla teoria al codice eseguibile. Utilizzerai l’SDK Python di Mistral AI per interrogare Codestral sui suoi due endpoint, ottimizzare i parametri avanzati che distinguono un suggerimento utile da uno verboso e implementare i pattern riscontrati nella maggior parte delle integrazioni reali.

Installazione e configurazione

Installa l’SDK con un singolo comando:

pip install mistralai

Recupera la tua chiave API da console.mistral.ai e leggila dalle variabili d’ambiente invece di codificarla direttamente nel file:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Due piattaforme servono Codestral e scegli tra di esse al momento della creazione della chiave. api.mistral.ai opera su base pay-per-use con fatturazione in base all’utilizzo: questo è il percorso standard quando Codestral è uno dei molti componenti di un’applicazione. codestral.mistral.ai è un endpoint dedicato, accessibile gratuitamente o tramite abbonamento, progettato per l’uso diretto da parte di uno sviluppatore all’interno del proprio editor.

Chiamata FIM completa

Ecco una chiamata FIM dettagliata con tutti i parametri importanti:

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.fim.complete(
    model="codestral-latest",
    prompt="def calculate_vat(price_excl: float, rate: float = 0.20) -> float:",
    suffix="price = float(input('Price excl. VAT: '))\nprint(f'Price incl. VAT: {calculate_vat(price):.2f} EUR')",
    temperature=0,
    max_tokens=150,
    stop=["\n\n"],
)

completion = response.choices[0].message.content
print(completion)

Analisi della risposta

L’oggetto restituito contiene più del semplice testo generato. In produzione, dovresti verificare sistematicamente tre informazioni: il completamento stesso, il consumo di token che determina la tua fattura e il motivo dell’arresto, che ti indica se il modello ha terminato naturalmente o ha raggiunto il tuo limite.

# Accesso al completamento generato
text = response.choices[0].message.content

# Controllo del numero di token utilizzati
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens

# Controllo del motivo dell'arresto
reason = response.choices[0].finish_reason  # "stop", "length", ecc.

Un finish_reason pari a "length" nella metà delle chiamate è un segnale chiaro: il tuo max_tokens è troppo basso e stai fornendo codice troncato ai tuoi utenti.

Chiamata Chat per la generazione di codice

Ogni volta che non c’è un cursore nel mezzo di un file, ad esempio per la generazione completa, la spiegazione o il refactoring, subentra l’endpoint chat. Il messaggio di sistema definisce quindi il formato di output, evitando la necessità di pulire la risposta successivamente:

response = client.chat.complete(
    model="codestral-latest",
    messages=[
        {
            "role": "system",
            "content": "You are an expert Python development assistant. Respond with code only, no explanations."
        },
        {
            "role": "user",
            "content": "Write a Python function that validates an email address using regex."
        }
    ],
    temperature=0.2,
    max_tokens=500,
)

code = response.choices[0].message.content
print(code)

Parametri avanzati

La coppia min_tokens / max_tokens definisce la lunghezza dell’output. Il valore minimo è utile quando si genera un blocco che sai non può essere più corto di un certo volume, come una funzione con la sua gestione degli errori.

# min_tokens: forza una lunghezza minima dell'output
# max_tokens: limita la lunghezza massima
response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    min_tokens=20,
    max_tokens=300,
)

I token di arresto svolgono un ruolo diverso: fermano la generazione su un pattern specifico, mantenendo il completamento nell’ambito della funzione corrente invece di lasciare che il modello prosegua verso quella successiva.

# Arresta la generazione su pattern specifici
response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    stop=["\n\n", "\nclass ", "\ndef "],  # Arresta prima di una nuova funzione/classe
)

Infine, la temperatura governa la variabilità. A 0, lo stesso input produce sempre lo stesso output, requisito fondamentale per il completamento automatico. Intorno a 0.3, il modello propone varianti, cosa interessante quando si visualizzano più suggerimenti. A 0.7, sei in modalità brainstorming del codice, utile per esplorare un approccio ma inadatto a un flusso di modifica.

# temperature=0: deterministico (completamento automatico)
# temperature=0.3: leggermente creativo (più suggerimenti)
# temperature=0.7: creativo (brainstorming del codice)

response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    temperature=0.3,
    top_p=0.95,
)

Due pattern da copiare e incollare

Il primo riproduce il comportamento dell’IDE: dividi il contenuto del file nella posizione del cursore e le due metà diventano rispettivamente prompt e suffix.

def autocomplete_ide(file_content: str, cursor_position: int) -> str:
    """Simula il completamento automatico dell'IDE con Codestral FIM."""
    prompt = file_content[:cursor_position]
    suffix = file_content[cursor_position:]

    response = client.fim.complete(
        model="codestral-latest",
        prompt=prompt,
        suffix=suffix,
        temperature=0,
        max_tokens=100,
        stop=["\n\n", "\ndef ", "\nclass "],
    )

    return response.choices[0].message.content

Il secondo automatizza la documentazione per un progetto esistente: passi una funzione, recuperi il suo docstring e l’istruzione di sistema impone un formato unico affinché il risultato possa essere inserito senza ulteriori modifiche.

def generate_docstring(function_code: str) -> str:
    """Genera un docstring per una funzione Python."""
    response = client.chat.complete(
        model="codestral-latest",
        messages=[
            {
                "role": "system",
                "content": "Generate a Google-style docstring for the following function. Return ONLY the docstring between triple quotes."
            },
            {
                "role": "user",
                "content": function_code
            }
        ],
        temperature=0,
        max_tokens=300,
    )
    return response.choices[0].message.content

Gestione degli errori

Una chiamata di rete prima o poi fallirà, e un’estensione dell’editor che si blocca su un errore di validazione è peggio di un’estensione senza completamento. Pertanto, avvolgi sempre le tue chiamate:

from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError

try:
    response = client.fim.complete(
        model="codestral-latest",
        prompt=prompt,
        suffix=suffix,
    )
except HTTPValidationError as e:
    print(f"Errore di validazione: {e}")
except Exception as e:
    print(f"Errore imprevisto: {e}")

Punti chiave

  • L’SDK mistralai espone client.fim.complete() per FIM e client.chat.complete() per la chat
  • I parametri prompt e suffix sono specifici dell’endpoint FIM
  • Usa temperature=0 per il completamento automatico, 0.2-0.7 per la generazione creativa
  • stop limita la generazione a un blocco di codice coerente
  • min_tokens e max_tokens controllano la lunghezza dell’output
  • Gestisci sempre gli errori HTTP nel codice di produzione