Migracja między wersjami SDK Mistral
Na tej stronie
- Dlaczego ta lekcja jest ważna
- Cztery generacje w dwa lata
- Od 0.x do 1.x: klient Mistral i metody łańcuchowe
- Od 1.x do 2.x: wszystko przenosi się pod mistralai.client
- Od 2.x do 3.x: httpx2 i wbudowane narzędzia
- A co z TypeScriptem?
- Przeprowadzanie migracji
- Jeśli nie możesz przeprowadzić migracji natychmiast
- Kluczowe wnioski
Lekcja przepisana 2 listopada 2026 r. Poprzednia wersja odnosiła się do „przejścia z V1 na V2“, co w rzeczywistości było migracją z przestarzałego klienta 0.x do wersji 1.0 w sierpniu 2024 r. Od tego czasu SDK Python przeszło dwie kolejne główne aktualizacje: 2.0 w marcu 2026 r. i 3.0 we wrześniu 2026 r. Ta lekcja rekonstruuje pełną historię na podstawie oficjalnych przewodników migracyjnych i notatek wydania. Zaktualizowano 3 listopada 2026 r.: Naprawiono pętlę strumieniowania w TypeScript, która wcześniej przekazywała zawartość typu
string | ContentChunk[]bezpośrednio doprocess.stdout.write, co powodowało błędy w trybie ścisłym.
Dlaczego ta lekcja jest ważna
Spotkasz się z tym materiałem w dwóch scenariuszach: wznawiasz projekt napisany jakiś czas temu, który odmawia uruchomienia się po aktualizacji zależności, lub podążasz za tutorialem online, którego przykłady przestały działać. W obu przypadkach zadaj to samo pierwsze pytanie: dla której generacji SDK napisano ten kod? Prawie zawsze odpowiada na nie jedna linijka: instrukcja importu.
Cztery generacje w dwa lata
| Generacja | Python (mistralai) | TypeScript (@mistralai/mistralai) | Wyróżniająca cecha kodu |
|---|---|---|---|
| 0.x | do 0.4.2 (lipiec 2024) | do 0.5.0 (czerwiec 2024) | MistralClient, płaskie metody: client.chat(...) |
| 1.x | 1.0.0 (7 sie 2024) → 1.9.11 (paź 2025) | od sierpnia 2024 | from mistralai import Mistral, metody łańcuchowe: client.chat.complete(...) |
| 2.x | 2.0.0 (10 mar 2026) | 2.0.0 (18 mar 2026) | Python: from mistralai.client import Mistral; TypeScript: tylko moduły ES |
| 3.x | 3.0.0 (28 wrz 2026), 3.7.0 na dzień 1 lis 2026 | 3.0 (paź 2026), 3.5.0 obecnie | Python: klient HTTP httpx2 |
W TypeScript import import { Mistral } from '@mistralai/mistralai' nie zmienił się od wersji 1.x. W Pythonie zmieniał się dwukrotnie: to tam dochodzi do większości błędów.
Od 0.x do 1.x: klient Mistral i metody łańcuchowe
Wersja 1.0 zastąpiła dwa klienty, MistralClient (synchroniczny) i MistralAsyncClient (asynchroniczny), jedną klasą: Mistral. Zastąpiła również płaskie metody przestrzeniami nazw: chat grupuje operacje konwersacyjne, a aby dotrzeć do complete(), musisz zejść o poziom głębiej. Wiadomości, które wcześniej tworzone było za pomocą klasy ChatMessage, teraz zapisuje się jako słowniki lub przy użyciu klas UserMessage, SystemMessage, AssistantMessage i ToolMessage.
# 0.x (przestarzałe)
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage
client = MistralClient(api_key="...")
response = client.chat(
model="mistral-small-latest",
messages=[ChatMessage(role="user", content="Hello")],
)
# 1.x
from mistralai import Mistral
client = Mistral(api_key="...")
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": "Hello"}],
)
Strumieniowanie podlega tej samej logice, z pułapką, która często kosztuje pół godziny debugowania: otrzymywany fragment jest teraz opakowany, a jego zawartość odczytuje się przez pośredni poziom .data. Stary kod 0.x skopiowany bez zmian zgłosi AttributeError przy pierwszym fragmencie.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x i nowsze
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Oficjalny przewodnik 1.0 zawiera pełną tabelę. Najczęstsze mapowania to:
| 0.x | 1.x i nowsze |
|---|---|
client.chat / client.chat_stream | client.chat.complete / client.chat.stream |
client.completions (FIM) | client.fim.complete |
client.embeddings(model=..., input=[...]) | client.embeddings.create(model=..., inputs=[...]) |
client.list_models() | client.models.list() |
client.files.create(...) | client.files.upload(...) |
client.jobs.create(...) | client.fine_tuning.jobs.create(...) |
MistralAsyncClient i jego metody | Warianty _async: client.chat.complete_async, client.chat.stream_async… |
Od 1.x do 2.x: wszystko przenosi się pod mistralai.client
Wersja 2.0 nie zmieniła nazw metod: client.chat.complete pozostaje client.chat.complete. Zmieniła natomiast adres wszystkiego innego. SDK stało się pakietem przestrzeni nazw (PEP 420), a wszystkie importy przeniesiono z mistralai do mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x i nowsze
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Zwróć uwagę na trzecią linię: klasy błędów nie znajdują się już wśród modeli, lecz w mistralai.client.errors, gdzie MistralError jest wspólną klasą bazową (dziedziczą po niej SDKError i HTTPValidationError).
Klienci dostawców chmury dołączyli do tej samej przestrzeni nazw. W wersji 1.x były dostarczane z pakietem mistralai, ale w osobnych modułach: mistralai_azure i mistralai_gcp:
# 1.x
from mistralai_azure import MistralAzure
client = MistralAzure(azure_endpoint="https://your-endpoint.inference.ai.azure.com", azure_api_key="your-azure-key")
from mistralai_gcp import MistralGoogleCloud
client = MistralGoogleCloud(region="europe-west4", project_id="my-project")
# 2.x i nowsze
from mistralai.azure.client import MistralAzure
client = MistralAzure(server_url="https://your-endpoint.inference.ai.azure.com", api_key="your-azure-key")
from mistralai.gcp.client import MistralGCP # pip install "mistralai[gcp]"
client = MistralGCP(region="europe-west4", project_id="my-project")
Trzy inne zmiany w wersji 2.0 mogą Cię dotyczyć. Minimalna wersja to teraz Python 3.10 (1.9.11 akceptował Pythona 3.9). 42 typy zmieniono zgodnie z regularną konwencją: {Czasownik}{Encja}Request dla żądań i {Czasownik}{Encja}Response dla odpowiedzi. Jedyną zmianą widoczną w powszechnym kodzie jest Tools, które stało się ConversationRequestTool. Wreszcie, wyliczenia (enumerations) akceptują teraz nieznane wartości, więc nowa wartość dodana przez API nie spowoduje awarii starszej wersji SDK.
Od 2.x do 3.x: httpx2 i wbudowane narzędzia
Wersja 3.0, wydana 28 września 2026 r., nie zmienia ani importów, ani powszechnych metod. Jednak trzy punkty mogą zepsuć projekt:
- Klient HTTP staje się
httpx2. Jeśli przekażesz własny klient do SDK (parametryclient=lubasync_client=, np. dla proxy lub wspólnych nagłówków), musi to być klienthttpx2; surowe żądania transportu, odpowiedzi i błędy są również typamihttpx2. - Wbudowane narzędzia opuszczają uzupełnienia czatu.
client.chat.completeiclient.agents.completenie akceptują już narzędziweb_search,web_search_premiumicode_interpreter: używa się ich poprzez Conversations API (client.beta.conversations) lub agenta. Dokumentacja Mistral wyjaśnia dlaczego: odpowiedzi z uzupełnień czatu nie mogą przenosić odwołań zwracanych przez te narzędzia. - Dodatki
mcpiagentspolegają teraz na MCP 2.2.
Wersja 3.0 dodaje również uwierzytelnianie tokenem konta usługi: Mistral() odczytuje token z pliku określonego przez zmienną środowiskową MISTRAL_SA_TOKEN_PATH.
A co z TypeScriptem?
Przejście z przestarzałego klienta JavaScript 0.x do SDK TypeScript 1.x niemal dokładnie odwzorowuje migrację w Pythonie. Import zmienia się z eksportu domyślnego na nazwany, konstruktor przyjmuje obiekt konfiguracji, a metody stają się łańcuchowe:
// 0.x (przestarzałe)
import MistralClient from '@mistralai/mistralai';
const client = new MistralClient(process.env.MISTRAL_API_KEY);
const response = await client.chat({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
// 1.x i nowsze
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
Strumieniowanie przenosi się z client.chatStream(...) na client.chat.stream(...), a podobnie jak w Pythonie, zawartość odczytuje się przez chunk.data:
const stream = await client.chat.stream({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
for await (const chunk of stream) {
const content = chunk.data.choices[0]?.delta.content;
// content może być również listą fragmentów: zapisujemy tylko tekst
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18 marca 2026 r.) zachował te importy, ale SDK jest teraz publikowane wyłącznie jako moduły ES: require('@mistralai/mistralai') w CommonJS już nie działa. Walidacja w czasie wykonywania przenosi się do Zod v4, co dotyczy tylko projektów importujących schematy bezpośrednio z SDK. Klienci chmurowi znajdują się w osobnych pakietach: @mistralai/mistralai-azure (MistralAzure) i @mistralai/mistralai-gcp (MistralGCP, dawniej MistralGoogleCloud).
Przeprowadzanie migracji
W rzeczywistym projekcie działaj w określonej kolejności, zamiast naprawiać błędy w miarę ich pojawiania się. Zacznij od zidentyfikowania generacji kodu poprzez jego importy, a następnie zaktualizuj pakiet (pip install --upgrade mistralai lub npm install @mistralai/mistralai@latest): dopóki zainstalowana jest stara wersja, naprawiasz na ślepo. Następnie postępuj zgodnie z poniższymi krokami:
- Wyszukaj stare importy:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Zastąp je zgodnie z mapowaniami z tej lekcji, nie zapomnij o błędach, które przenoszą się do
mistralai.client.errors - Zaktualizuj wywołania: metody łańcuchowe, liczba mnoga
inputsdla osadzeń (embeddings),.dataw pętlach strumieniowania - Przenieś wbudowane narzędzia (
web_search,code_interpreter) z uzupełnień czatu do Conversations API
Na koniec przetestuj każdy używany punkt końcowy po kolei: czat, osadzenia i strumieniowanie mają swoje własne zmiany, a projekt, który się uruchamia, niekoniecznie poprawnie wywołuje wszystkie trzy.
Jeśli nie możesz przeprowadzić migracji natychmiast
Żadna z tych wersji nie oferuje trybu przejściowego ani aliasów zgodności. Jeśli zamrożenie środowiska produkcyjnego uniemożliwia migrację, jawnie przypnij wersję w swoich zależnościach; w przeciwnym razie następna instalacja pobierze najnowszą wersję i zepsuje aplikację:
# Python: pozostań na 1.x
pip install "mistralai<2"
# Python: pozostań na 2.x
pip install "mistralai>=2,<3"
# npm: pozostań na 1.x
npm install @mistralai/mistralai@1
Traktuj to przypięcie jako odroczenie: nowe funkcje pojawiają się tylko w bieżącej wersji.
Źródła oficjalne: Przewodnik migracyjny 0.x → 1.0 · Notatki wydania Python 2.0.0 · Notatki wydania Python 3.0.0 · Notatki wydania TypeScript 2.0.0 · Historia wersji na PyPI · Websearch — wbudowane narzędzia
Kluczowe wnioski
- Zidentyfikuj generację kodu po imporcie:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x i 3.x) - 1.0 (sierpień 2024) wprowadziło klienta
Mistral, metody łańcuchowe i poziom.dataw strumieniowaniu - 2.0 (marzec 2026) przeniosło wszystkie importy Pythona pod
mistralai.client, błędy podmistralai.client.errorsi podniosło minimalne wymaganie do Pythona 3.10 - 3.0 (wrzesień 2026) przechodzi na
httpx2i rezerwujeweb_searchorazcode_interpreterdla Conversations API i agentów - W TypeScript import nie zmienił się od wersji 1.x, ale 2.0 akceptuje wyłącznie moduły ES