Il client MistralAzure in Python
In questa pagina
Programmare con MistralAzure
Il tuo endpoint Azure è distribuito e risponde; ora devi scrivere il codice che lo utilizzerà in modo affidabile. Questa lezione approfondisce il client Python MistralAzure: inizializzazione, i pattern che userai quotidianamente (chiamate semplici, streaming, esecuzione asincrona e function calling) e le poche specificità che distinguono Azure dall’API diretta.
Installazione e configurazione
Aggiornato il 2 novembre 2026 — Mistral SDK 2 e versioni successive. Dalla versione 2.0 dell’SDK Python (marzo 2026), il client Azure si importa da
mistralai.azure.cliente i suoi parametri di versione 1azure_endpointeazure_api_keysono diventati rispettivamenteserver_urleapi_key. Il codice in questa lezione segue la versione corrente (3.7.0, 1° novembre 2026). Fonti: Note di rilascio v2.0.0 · Mistral su Azure.
Il client Azure è incluso nel pacchetto mistralai; non sono necessarie dipendenze aggiuntive.
pip install mistralai
L’inizializzazione richiede due parametri:
import os
from mistralai.azure.client import MistralAzure
client = MistralAzure(
server_url=os.environ["AZUREAI_ENDPOINT"],
api_key=os.environ["AZUREAI_API_KEY"]
)
server_url— L’URL del tuo endpoint Azureapi_key— La chiave di autenticazione dell’endpoint
Un terzo parametro opzionale, api_version, ha come valore predefinito 2024-05-01-preview. L’SDK lo aggiunge automaticamente a ogni richiesta come parametro URL.
Completamenti chat
Da qui, l’esperienza rispecchia quella del client standard. Usa un messaggio di sistema per definire il ruolo del modello, un messaggio utente per la domanda e leggi la risposta da choices[0].message.content.
response = client.chat.complete(
model="azureai",
messages=[
{"role": "system", "content": "Sei un assistente tecnico specializzato in Python."},
{"role": "user", "content": "Come implemento un decoratore per la cache?"}
]
)
print(response.choices[0].message.content)
I parametri di generazione si comportano esattamente come con l’API Mistral diretta. Se una risposta è troppo imprevedibile o verbosa, correggila qui, non nel prompt.
response = client.chat.complete(
model="azureai",
messages=[
{"role": "user", "content": "Genera un haiku sul cloud computing."}
],
temperature=0.7,
max_tokens=150,
top_p=0.95
)
temperature— Controlla la creatività (0.0 = deterministico, 1.0 = creativo)max_tokens— Limita la lunghezza della rispostatop_p— Campionamento del nucleo (nucleus sampling)
Streaming
Per risposte che si estendono per diverse centinaia di parole, una chiamata standard lascia l’utente a fissare uno schermo bloccato per diversi secondi. Lo streaming elimina questa attesa percepita visualizzando il testo man mano che viene generato. Questa è la modalità predefinita ogni volta che è coinvolta un’interfaccia umana.
stream = client.chat.stream(
model="azureai",
messages=[
{"role": "user", "content": "Spiega come funziona un load balancer."}
]
)
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
print(content, end="", flush=True)
print() # Nuova riga alla fine
Nota il controllo if content: alcuni chunk arrivano vuoti e, senza questa precauzione, stamperemmo None a schermo.
Chiamate asincrone
In un server web (FastAPI, Django async), una chiamata bloccante occupa un worker per l’intera durata della generazione, spesso diversi secondi per richiesta. Il client asincrono cede il controllo durante l’attesa, permettendo a un singolo processo di gestire decine di richieste concorrenti.
import asyncio
from mistralai.azure.client import MistralAzure
client = MistralAzure(
server_url=os.environ["AZUREAI_ENDPOINT"],
api_key=os.environ["AZUREAI_API_KEY"]
)
async def generate_response(prompt: str) -> str:
response = await client.chat.complete_async(
model="azureai",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
# Esecuzione
result = asyncio.run(generate_response("Cos'è Kubernetes?"))
print(result)
Function Calling
Il function calling si comporta in modo identico all’API diretta. Descrivi gli strumenti disponibili, il modello decide se chiamarne uno e il tuo codice esegue effettivamente la funzione: il modello formula solo l’intento e gli argomenti.
import json
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Ottieni il meteo per una città",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Nome della città"}
},
"required": ["city"]
}
}
}
]
response = client.chat.complete(
model="azureai",
messages=[{"role": "user", "content": "Che tempo fa a Parigi?"}],
tools=tools,
tool_choice="auto"
)
# Verifica se il modello vuole chiamare una funzione
if response.choices[0].message.tool_calls:
tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
print(f"Funzione chiamata: {tool_call.function.name}")
print(f"Argomenti: {args}")
Gestione degli errori
In produzione, ricorrono tre famiglie di errori, che richiedono risposte diverse. Un 429 segnala un limite di frequenza (rate limit) e richiede un nuovo tentativo con backoff esponenziale. Un 401 indica una chiave non valida o scaduta: ritentare è inutile, quindi fallisci immediatamente con un messaggio chiaro. Un 404 punta quasi sempre a una variabile AZUREAI_ENDPOINT configurata male. Distinguere questi casi ti evita di passare un’ora a debuggare un errore di battitura in un URL.
import time
from mistralai.azure.client import MistralAzure
def robust_call(client, messages, max_retries=3):
"""Chiamata con retry esponenziale e gestione errori."""
for attempt in range(max_retries):
try:
return client.chat.complete(
model="azureai",
messages=messages
)
except Exception as e:
error_str = str(e)
if "429" in error_str:
wait = 2 ** attempt
print(f"Limite di frequenza — nuovo tentativo tra {wait}s")
time.sleep(wait)
elif "401" in error_str:
raise ValueError("Chiave API non valida o scaduta") from e
elif "404" in error_str:
raise ValueError("Endpoint non trovato — controlla AZUREAI_ENDPOINT") from e
else:
if attempt == max_retries - 1:
raise
time.sleep(1)
raise RuntimeError("Fallito dopo tutti i tentativi")
Misurare il consumo
Ogni risposta include un oggetto usage che dettaglia i token consumati. Leggilo sistematicamente: è l’unica misura affidabile per stimare i costi e individuare un prompt di sistema diventato gonfio a causa di modifiche ripetute.
response = client.chat.complete(
model="azureai",
messages=[{"role": "user", "content": "Ciao"}]
)
usage = response.usage
print(f"Token prompt : {usage.prompt_tokens}")
print(f"Token risposta : {usage.completion_tokens}")
print(f"Token totali : {usage.total_tokens}")
Punti chiave
- Il client
MistralAzurefunziona come il client standard, usandomodel="azureai" - Lo streaming (
chat.stream) è raccomandato per le interfacce utente - Le chiamate asincrone (
complete_async) sono essenziali per i server web - Il function calling e la modalità JSON funzionano in modo identico all’API diretta
- Implementa sempre un retry esponenziale per gestire gli errori
429