Migrácia medzi verziami Mistral SDK
Na tejto strane
Lekcia prepísaná 2. novembra 2026. Predchádzajúca verzia odkazovala na „prechod z V1 na V2“, čo bol v skutočnosti prechod zo starého klienta 0.x na verziu 1.0 v auguste 2024. Odvtedy vyšli v Python SDK ďalšie dve hlavné vydania: 2.0 v marci 2026 a 3.0 v septembri 2026. Táto lekcia rekonštruuje celú históriu na základe oficiálnych sprievodcov migráciou a poznámok k vydaniu. Aktualizované 3. novembra 2026: Opravený streamovací cyklus v TypeScripte, ktorý predtým odovzdával obsah
string | ContentChunk[]priamo doprocess.stdout.write, čo spôsobovalo chyby v striktnom režime.
Prečo je táto lekcia dôležitá
S týmto materiálom sa stretneš v dvoch situáciách: buď obnovuješ projekt napísaný pred časom, ktorý po aktualizácii závislostí odmieta štartovať, alebo sleduješ online tutoriál, ktorého príklady už nefungujú. V oboch prípadoch si polož tú istú prvú otázku: pre ktorú generáciu SDK bol tento kód napísaný? Takmer vždy ti odpovie jediný riadok: príkaz importu.
Štyri generácie za dva roky
| Generácia | Python (mistralai) | TypeScript (@mistralai/mistralai) | Rozlišovací znak v kóde |
|---|---|---|---|
| 0.x | až do 0.4.2 (júl 2024) | až do 0.5.0 (jún 2024) | MistralClient, ploché metódy: client.chat(...) |
| 1.x | 1.0.0 (7. aug 2024) → 1.9.11 (okt 2025) | od aug 2024 | from mistralai import Mistral, reťazené metódy: client.chat.complete(...) |
| 2.x | 2.0.0 (10. mar 2026) | 2.0.0 (18. mar 2026) | Python: from mistralai.client import Mistral; TypeScript: iba ES moduly |
| 3.x | 3.0.0 (28. sep 2026), k 1. nov 2026 verzia 3.7.0 | 3.0 (okt 2026), dnes 3.5.0 | Python: HTTP klient httpx2 |
V TypeScripte sa import import { Mistral } from '@mistralai/mistralai' od verzie 1.x nezmenil. V Pythone sa zmenil dvakrát: práve tu dochádza k väčšine chýb.
Z 0.x na 1.x: klient Mistral a reťazené metódy
Verzia 1.0 nahradila dva klienty, MistralClient (synchronický) a MistralAsyncClient (asynchrónny), jednou triedou Mistral. Tiež nahradila ploché metódy mennými priestormi: chat zoskupuje operácie konverzácie a pre dosiahnutie complete() musíš ísť o úroveň hlbšie. Správy, ktoré sa predtým zapisovali pomocou triedy ChatMessage, sa teraz zapisujú ako slovníky alebo pomocou tried UserMessage, SystemMessage, AssistantMessage a ToolMessage.
# 0.x (staré)
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"}],
)
Streamovanie funguje na rovnakom princípe, no obsahuje pascu, ktorá často stojí pol hodinu ladenia: prijatý fragment je teraz zabalený a jeho obsah sa číta cez medziúroveň .data. Starý kód 0.x skopírovaný tak, ako je, vyvolá pri prvom fragmente chybu AttributeError.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x a novšie
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Oficiálny sprievodca verziou 1.0 obsahuje úplnú tabuľku. Najčastejšie mapovania sú:
| 0.x | 1.x a novšie |
|---|---|
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 a jeho metódy | varianty _async: client.chat.complete_async, client.chat.stream_async… |
Z 1.x na 2.x: všetko sa presúva pod mistralai.client
Verzia 2.0 nezmenila názvy metód: client.chat.complete zostáva client.chat.complete. Zmenila však adresu všetkého ostatného. SDK sa stalo balíkom menného priestoru (PEP 420) a všetky importy sa presunuli z mistralai do mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x a novšie
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Všimni si tretí riadok: triedy chýb už nežijú medzi modelmi, ale v mistralai.client.errors, pričom MistralError slúži ako spoločná základňa (z ktorej dedí SDKError a HTTPValidationError).
Klienti pre cloudových poskytovateľov sa pripojili k tomu istému mennému priestoru. Vo verzii 1.x boli dodávané s balíkom mistralai, ale v samostatných moduloch mistralai_azure a 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 a novšie
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")
Tri ďalšie zmeny vo verzii 2.0 sa ťa môžu dotknúť. Minimálna verzia je teraz Python 3.10 (verzia 1.9.11 akceptovala Python 3.9). 42 typov bolo premenovaných podľa pravidelnej konvencie: {Verb}{Entity}Request pre požiadavky a {Verb}{Entity}Response pre odpovede. Jediné premenovanie viditeľné v bežnom kóde je Tools, ktoré sa stalo ConversationRequestTool. Nakoniec, enumerácie teraz akceptujú neznáme hodnoty, takže nová hodnota pridaná API už nespôsobí pád staršej verzie SDK.
Z 2.x na 3.x: httpx2 a vstavané nástroje
Verzia 3.0, vydaná 28. septembra 2026, nemení ani importy, ani bežné metódy. Tri body však môžu projekt rozbiť:
- HTTP klientom sa stáva
httpx2. Ak odovzdáš SDK vlastného klienta (parametreclient=aleboasync_client=, napríklad pre proxy alebo spoločné hlavičky), musí ísť o klientahttpx2; surové požiadavky transportu, odpovede a chyby sú tiež typmihttpx2. - Vstavané nástroje opúšťajú dokončovanie chatu.
client.chat.completeaclient.agents.completeuž neprijímajú nástrojeweb_search,web_search_premiumacode_interpreter: používajú sa prostredníctvom Conversations API (client.beta.conversations) alebo agenta. Dokumentácia Mistral vysvetľuje prečo: odpovede na dokončenie chatu nemôžu niesť referencie, ktoré tieto nástroje vracajú. - Extra balíky
mcpaagentsteraz závisia od MCP 2.2.
Verzia 3.0 tiež pridáva autentifikáciu tokenom servisného účtu: Mistral() číta token zo súboru určeného premennou prostredia MISTRAL_SA_TOKEN_PATH.
A čo TypeScript?
Prechod zo starého JavaScript klienta 0.x na TypeScript SDK 1.x takmer presne zrkadlí prechod v Pythone. Import sa mení z predvoleného exportu na pomenovaný export, konštruktor prijíma konfiguračný objekt a metódy sa stávajú reťazenými:
// 0.x (staré)
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 a novšie
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' }],
});
Streamovanie sa presúva z client.chatStream(...) na client.chat.stream(...) a ako v Pythone sa obsah číta cez 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 môže byť aj zoznam fragmentov: zapisujeme iba text
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18. marca 2026) zachoval tieto importy, ale SDK sa teraz publikuje výlučne ako ES moduly: require('@mistralai/mistralai') v CommonJS už nefunguje. Overovanie behom sa presunulo na Zod v4, čo ovplyvňuje iba projekty, ktoré importujú schémy priamo zo SDK. Cloudoví klienti žijú v samostatných balíkoch: @mistralai/mistralai-azure (MistralAzure) a @mistralai/mistralai-gcp (MistralGCP, predtým MistralGoogleCloud).
Vykonanie migrácie
Na reálnom projekte postupuj v stanovenom poradí, namiesto toho, aby si opravoval chyby, ako sa objavia. Najprv identifikuj generáciu kódu podľa jeho importov, potom aktualizuj balík (pip install --upgrade mistralai alebo npm install @mistralai/mistralai@latest): pokiaľ je nainštalovaná stará verzia, opravuješ naslepo. Potom postupuj takto:
- Vyhľadaj staré importy:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Nahraď ich podľa mapovaní v tejto lekcii, nezabudni na chyby, ktoré sa presúvajú do
mistralai.client.errors - Aktualizuj volania: reťazené metódy, množné číslo
inputspre vkladania (embeddings),.datav streamovacích cykloch - Presuň vstavané nástroje (
web_search,code_interpreter) z dokončovania chatu do Conversations API
Nakoniec otestuj každý koncový bod, ktorý používaš, jeden po druhom: chat, vkladania (embeddings) aj streamovanie majú svoje vlastné zmeny a projekt, ktorý sa spustí, nemusí nevyhnutne správne volať všetky tri.
Ak nemôžeš migrovať okamžite
Žiadna z týchto verzií nenúka prechodný režim ani aliasy spätnej kompatibility. Ak ti produkčné zmrazenie bráni v migrácii, explicitne pripni verziu vo svojich závislostiach; inak ďalšia inštalácia stiahne najnovšiu verziu a rozbije aplikáciu:
# Python: zostaň na 1.x
pip install "mistralai<2"
# Python: zostaň na 2.x
pip install "mistralai>=2,<3"
# npm: zostaň na 1.x
npm install @mistralai/mistralai@1
Ber toto pripnutie ako odklad: nové funkcie prichádzajú iba v aktuálnej verzii.
Oficiálne zdroje: Sprievodca migráciou 0.x → 1.0 · Poznámky k vydaniu Python 2.0.0 · Poznámky k vydaniu Python 3.0.0 · Poznámky k vydaniu TypeScript 2.0.0 · História verzií na PyPI · Websearch — vstavané nástroje
Kľúčové poznatky
- Identifikuj generáciu kódu podľa importu:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x a 3.x) - 1.0 (aug 2024) zaviedla klienta
Mistral, reťazené metódy a úroveň.datapri streamovaní - 2.0 (mar 2026) presunula všetky Python importy pod
mistralai.client, chyby podmistralai.client.errorsa zvýšila minimum na Python 3.10 - 3.0 (sep 2026) prepína na
httpx2a vyhradzujeweb_searchacode_interpreterpre Conversations API a agentov - V TypeScripte sa import od verzie 1.x nezmenil, ale 2.0 akceptuje iba ES moduly