Klient MistralAzure w Pythonie
Na tej stronie
Programowanie z MistralAzure
Twój punkt końcowy Azure jest już wdrożony i odpowiada; teraz musisz napisać kod, który będzie go niezawodnie wykorzystywał. Ta lekcja szczegółowo opisuje klienta Python MistralAzure: inicjalizację, wzorce, których będziesz używać na co dzień – proste wywołania, strumieniowanie, wykonanie asynchroniczne i wywoływanie funkcji – oraz kilka specyficznych cech odróżniających Azure od bezpośredniego API.
Instalacja i konfiguracja
Zaktualizowano 2 listopada 2026 r. — Mistral SDK 2 i nowsze. Od wersji 2.0 SDK dla Pythona (marzec 2026) klient Azure jest importowany z
mistralai.azure.client, a jego parametry z wersji 1,azure_endpointiazure_api_key, zostały zmienione naserver_urliapi_key. Kod w tej lekcji dotyczy aktualnej wersji (3.7.0 z 1 listopada 2026 r.). Źródła: notatki wydania v2.0.0 · Mistral on Azure.
Klient Azure jest zawarty w pakiecie mistralai; nie są wymagane żadne dodatkowe zależności.
pip install mistralai
Inicjalizacja wymaga dwóch parametrów:
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— adres URL Twojego punktu końcowego Azureapi_key— klucz uwierzytelniający punktu końcowego
Trzeci, opcjonalny parametr, api_version, domyślnie przyjmuje wartość 2024-05-01-preview. SDK automatycznie dodaje go do każdego żądania jako parametr URL.
Uzupełnianie czatu (Chat Completions)
Od tego momentu doświadczenie jest identyczne jak w przypadku standardowego klienta. Użyj wiadomości systemowej, aby określić rolę modelu, wiadomości użytkownika dla pytania i odczytaj odpowiedź z choices[0].message.content.
response = client.chat.complete(
model="azureai",
messages=[
{"role": "system", "content": "Jesteś asystentem technicznym specjalizującym się w Pythonie."},
{"role": "user", "content": "Jak zaimplementować dekorator pamięci podręcznej?"}
]
)
print(response.choices[0].message.content)
Parametry generowania zachowują się dokładnie tak samo jak w bezpośrednim API Mistral. Jeśli odpowiedź jest zbyt nieprzewidywalna lub rozwlekła, skoryguj to tutaj, a nie w prompcie.
response = client.chat.complete(
model="azureai",
messages=[
{"role": "user", "content": "Wygeneruj haiku o chmurze obliczeniowej."}
],
temperature=0.7,
max_tokens=150,
top_p=0.95
)
temperature— kontroluje kreatywność (0,0 = deterministyczne, 1,0 = kreatywne)max_tokens— ogranicza długość odpowiedzitop_p— próbkowanie jądra (nucleus sampling)
Strumieniowanie
W przypadku odpowiedzi liczących kilkaset słów standardowe wywołanie zmusza użytkownika do wpatrywania się w zamarznięty ekran przez kilka sekund. Strumieniowanie eliminuje to pozorne oczekiwanie, wyświetlając tekst w miarę jego generowania. Jest to tryb domyślny zawsze, gdy involved jest interfejs ludzki.
stream = client.chat.stream(
model="azureai",
messages=[
{"role": "user", "content": "Wyjaśnij, jak działa balanser obciążenia."}
]
)
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
print(content, end="", flush=True)
print() # Nowa linia na końcu
Zwróć uwagę na sprawdzenie if content: niektóre fragmenty przychodzą puste i bez tego zabezpieczenia wypisałyby None na ekran.
Wywołania asynchroniczne
W serwerze WWW – FastAPI, Django async – wywołanie blokujące zajmuje worker na cały czas generowania, często kilka sekund na żądanie. Klient asynchroniczny oddaje kontrolę podczas oczekiwania, pozwalając pojedynczemu procesowi obsłużyć dziesiątki współbieżnych żądań.
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
# Wykonanie
result = asyncio.run(generate_response("Czym jest Kubernetes?"))
print(result)
Wywoływanie funkcji
Wywoływanie funkcji zachowuje się identycznie jak w bezpośrednim API. Opisujesz dostępne narzędzia, model decyduje, czy jedno z nich wywołać, a Twój kod faktycznie wykonuje funkcję – model jedynie formułuje intencję i argumenty.
import json
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Pobierz pogodę dla miasta",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Nazwa miasta"}
},
"required": ["city"]
}
}
}
]
response = client.chat.complete(
model="azureai",
messages=[{"role": "user", "content": "Jaka jest pogoda w Paryżu?"}],
tools=tools,
tool_choice="auto"
)
# Sprawdź, czy model chce wywołać funkcję
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"Wywołano funkcję: {tool_call.function.name}")
print(f"Argumenty: {args}")
Obsługa błędów
W środowisku produkcyjnym powtarzają się trzy rodziny błędów, które wymagają różnych reakcji. Kod 429 sygnalizuje limit szybkości i wymaga ponownej próby z wykładniczym opóźnieniem (exponential backoff). Kod 401 wskazuje na nieprawidłowy lub wygasły klucz: ponawianie jest bezcelowe, więc natychmiast zakończ niepowodzeniem z jasnym komunikatem. Kod 404 prawie zawsze wskazuje na błędnie skonfigurowaną zmienną AZUREAI_ENDPOINT. Rozróżnienie tych przypadków uchroni Cię przed godzinami debugowania literówki w adresie URL.
import time
from mistralai.azure.client import MistralAzure
def robust_call(client, messages, max_retries=3):
"""Wywołanie z wykładniczą ponowną próbą i obsługą błędów."""
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"Limit szybkości — ponawianie za {wait}s")
time.sleep(wait)
elif "401" in error_str:
raise ValueError("Nieprawidłowy lub wygasły klucz API") from e
elif "404" in error_str:
raise ValueError("Nie znaleziono punktu końcowego — sprawdź AZUREAI_ENDPOINT") from e
else:
if attempt == max_retries - 1:
raise
time.sleep(1)
raise RuntimeError("Niepowodzenie po wszystkich ponownych próbach")
Pomiar zużycia
Każda odpowiedź zawiera obiekt usage szczegółowo opisujący zużyte tokeny. Odczytuj to systematycznie: jest to jedyna wiarygodna miara do szacowania kosztów i wykrywania promptu systemowego, który spuchł od powtarzających się edycji.
response = client.chat.complete(
model="azureai",
messages=[{"role": "user", "content": "Cześć"}]
)
usage = response.usage
print(f"Tokeny promptu : {usage.prompt_tokens}")
print(f"Tokeny odpowiedzi: {usage.completion_tokens}")
print(f"Łączna liczba tokenów: {usage.total_tokens}")
Kluczowe wnioski
- Klient
MistralAzuredziała jak standardowy klient, używającmodel="azureai" - Strumieniowanie (
chat.stream) jest zalecane w interfejsach użytkownika - Wywołania asynchroniczne (
complete_async) są niezbędne w serwerach WWW - Wywoływanie funkcji i tryb JSON działają identycznie jak w bezpośrednim API
- Zawsze implementuj wykładnicze ponawianie prób, aby obsługiwać błędy
429