La tua prima chiamata API in Python
In questa pagina
Il tuo primo scambio con un modello Mistral
L’SDK è installato e la tua chiave API è pronta: è il momento di inviare una richiesta reale e, soprattutto, di capire cosa ricevi in risposta. Molti sviluppatori si fermano alla prima linea della risposta e ignorano il resto dell’oggetto restituito. È un errore, perché il monitoraggio dei costi e la diagnostica delle risposte troncate risiedono proprio in quei dati rimanenti. Inizieremo con un codice minimo per poi arrivare alla struttura completa.
Inizializzare il client
Il client è il punto di ingresso per tutte le tue interazioni con l’API:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Gestisce le connessioni HTTP, i nuovi tentativi in caso di errori di rete e la serializzazione delle richieste. Istituiscilo una sola volta all’avvio dell’applicazione. Ricreare un client per ogni chiamata ti costringe a pagare inutilmente l’impostazione della connessione ed è una delle cause più subdole di latenza eccessiva.
Inviare una richiesta con chat.complete()
Userai il metodo chat.complete() più spesso. Invia i tuoi messaggi e attende la risposta completa del modello prima di restituire il controllo:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": "Explain the concept of tokenization in three sentences."
}
]
)
print(response.choices[0].message.content)
Qui bastano due parametri. model specifica l’ID del modello: mistral-small-latest punta sempre all’ultima versione di Mistral Small, rendendolo la scelta naturale per iniziare dato che è veloce ed economico. messages si aspetta una lista di messaggi strutturati, ognuno con un role—system, user o assistant—e un campo content contenente il testo. Questa struttura può sembrare pesante per una singola domanda, ma ha perfettamente senso una volta arrivati alla lezione sulle conversazioni multi-turno.
Leggere l’oggetto restituito
L’oggetto response contiene molto più del semplice testo generato:
# Testo della risposta
text = response.choices[0].message.content
# Ruolo (sempre "assistant" per una risposta)
role = response.choices[0].message.role
# Motivo dell'interruzione
finish = response.choices[0].finish_reason # "stop", "length", ecc.
# Statistiche sui token
input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens
total_tokens = response.usage.total_tokens
print(f"Response ({output_tokens} tokens): {text}")
print(f"Total tokens consumed: {total_tokens}")
Presta molta attenzione al campo usage fin dal primo giorno. Registrarlo a ogni chiamata ti dice esattamente quale funzionalità della tua applicazione sta bruciando il tuo budget, senza dover fare ingegneria inversa sulla tua fattura alla fine del mese.
Per quanto riguarda finish_reason, indica perché il modello si è fermato e assume uno di questi valori:
stop: il modello ha terminato la sua risposta naturalmentelength: la risposta è stata troncata perché ha raggiuntomax_tokensmodel_length: il contesto totale (input + output) ha raggiunto il limite del modello
Una risposta che si interrompe a metà frase non è un bug del modello: è un finish_reason pari a length che nessuno ha controllato. Verificalo sempre prima di concludere che ci sia un problema di qualità.
Regolare il comportamento del modello
Tre parametri aggiuntivi ti permettono di orientare la generazione:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": "Propose three names for an educational AI startup."
}
],
temperature=0.7,
max_tokens=500,
top_p=0.95,
)
Temperature controlla il grado di libertà del modello. A 0.0, le risposte sono deterministiche: lo stesso prompt produce sempre lo stesso testo, cosa che desideri per l’estrazione o la classificazione. Tra 0.3 e 0.5, ottieni un buon equilibrio per compiti fattuali. Tra 0.7 e 1.0, le risposte diventano più creative e variegate: questo è l’intervallo usato nell’esempio sopra, dato che stiamo chiedendo idee per nomi e vedere tre volte la stessa idea sarebbe inutile. Sopra 1.0, la generazione diventa altamente casuale e raramente ha utilità pratica.
max_tokens limita la lunghezza della risposta, il che aiuta a controllare i costi e a mantenere gli output gestibili. Ricorda solo che se il modello viene interrotto, finish_reason sarà "length". top_p influisce sulla diversità attraverso un meccanismo diverso: filtra i token meno probabili. Un valore di 0.95 significa che il modello considera solo i token che rappresentano il 95% della probabilità cumulativa.
Una chiamata pronta per la produzione
In condizioni reali, la rete cade, le chiavi scadono e le quote si esauriscono. Avvolgi sempre le tue chiamate nella gestione degli errori:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{"role": "user", "content": "What is the capital of France?"}
],
max_tokens=100,
)
text = response.choices[0].message.content
print(f"Response: {text}")
print(f"Tokens used: {response.usage.total_tokens}")
except Exception as e:
print(f"API call error: {e}")
Usa questo scheletro per i tuoi esperimenti sostituendo semplicemente il contenuto del messaggio. È il punto di partenza per tutto ciò che segue in questo corso.
Punti chiave
client.chat.complete()è il metodo principale per interagire con i modelli- Il testo della risposta si trova in
response.choices[0].message.content response.usageti dice quanti token sono stati consumati (utile per il monitoraggio dei costi)temperaturecontrolla la creatività;max_tokenslimita la lunghezza- Inizia con
mistral-small-latest: è veloce, economico e performante