Przejdź do głównej treści
Polski— Wybierz język
Menu

Migracja między wersjami SDK Mistral

Lekcja 10 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego ta lekcja jest ważna
  2. Cztery generacje w dwa lata
  3. Od 0.x do 1.x: klient Mistral i metody łańcuchowe
  4. Od 1.x do 2.x: wszystko przenosi się pod mistralai.client
  5. Od 2.x do 3.x: httpx2 i wbudowane narzędzia
  6. A co z TypeScriptem?
  7. Przeprowadzanie migracji
  8. Jeśli nie możesz przeprowadzić migracji natychmiast
  9. 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 do process.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

GeneracjaPython (mistralai)TypeScript (@mistralai/mistralai)Wyróżniająca cecha kodu
0.xdo 0.4.2 (lipiec 2024)do 0.5.0 (czerwiec 2024)MistralClient, płaskie metody: client.chat(...)
1.x1.0.0 (7 sie 2024) → 1.9.11 (paź 2025)od sierpnia 2024from mistralai import Mistral, metody łańcuchowe: client.chat.complete(...)
2.x2.0.0 (10 mar 2026)2.0.0 (18 mar 2026)Python: from mistralai.client import Mistral; TypeScript: tylko moduły ES
3.x3.0.0 (28 wrz 2026), 3.7.0 na dzień 1 lis 20263.0 (paź 2026), 3.5.0 obecniePython: 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.x1.x i nowsze
client.chat / client.chat_streamclient.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 metodyWarianty _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 (parametry client= lub async_client=, np. dla proxy lub wspólnych nagłówków), musi to być klient httpx2; surowe żądania transportu, odpowiedzi i błędy są również typami httpx2.
  • Wbudowane narzędzia opuszczają uzupełnienia czatu. client.chat.complete i client.agents.complete nie akceptują już narzędzi web_search, web_search_premium i code_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 mcp i agents polegają 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:

  1. Wyszukaj stare importy: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Zastąp je zgodnie z mapowaniami z tej lekcji, nie zapomnij o błędach, które przenoszą się do mistralai.client.errors
  3. Zaktualizuj wywołania: metody łańcuchowe, liczba mnoga inputs dla osadzeń (embeddings), .data w pętlach strumieniowania
  4. 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 .data w strumieniowaniu
  • 2.0 (marzec 2026) przeniosło wszystkie importy Pythona pod mistralai.client, błędy pod mistralai.client.errors i podniosło minimalne wymaganie do Pythona 3.10
  • 3.0 (wrzesień 2026) przechodzi na httpx2 i rezerwuje web_search oraz code_interpreter dla Conversations API i agentów
  • W TypeScript import nie zmienił się od wersji 1.x, ale 2.0 akceptuje wyłącznie moduły ES