Vai al contenuto principale
Italiano— Scegli una lingua
Menu

La tua prima chiamata API in Python

Lezione 5 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il tuo primo scambio con un modello Mistral
  2. Inizializzare il client
  3. Inviare una richiesta con chat.complete()
  4. Leggere l’oggetto restituito
  5. Regolare il comportamento del modello
  6. Una chiamata pronta per la produzione
  7. Punti chiave

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 naturalmente
  • length: la risposta è stata troncata perché ha raggiunto max_tokens
  • model_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.usage ti dice quanti token sono stati consumati (utile per il monitoraggio dei costi)
  • temperature controlla la creatività; max_tokens limita la lunghezza
  • Inizia con mistral-small-latest: è veloce, economico e performante