API Codestral in Python
In questa pagina
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
mistralaiesponeclient.fim.complete()per FIM eclient.chat.complete()per la chat - I parametri
promptesuffixsono specifici dell’endpoint FIM - Usa
temperature=0per il completamento automatico,0.2-0.7per la generazione creativa stoplimita la generazione a un blocco di codice coerentemin_tokensemax_tokenscontrollano la lunghezza dell’output- Gestisci sempre gli errori HTTP nel codice di produzione