Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Il client MistralAzure in Python

Lezione 5 di 14 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Programmare con MistralAzure
  2. Installazione e configurazione
  3. Completamenti chat
  4. Streaming
  5. Chiamate asincrone
  6. Function Calling
  7. Gestione degli errori
  8. Misurare il consumo
  9. Punti chiave

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.client e i suoi parametri di versione 1 azure_endpoint e azure_api_key sono diventati rispettivamente server_url e api_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 Azure
  • api_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 risposta
  • top_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 MistralAzure funziona come il client standard, usando model="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