Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Migrácia medzi verziami Mistral SDK

Lekcia 10 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Prečo je táto lekcia dôležitá
  2. Štyri generácie za dva roky
  3. Z 0.x na 1.x: klient Mistral a reťazené metódy
  4. Z 1.x na 2.x: všetko sa presúva pod mistralai.client
  5. Z 2.x na 3.x: httpx2 a vstavané nástroje
  6. A čo TypeScript?
  7. Vykonanie migrácie
  8. Ak nemôžeš migrovať okamžite
  9. Kľúčové poznatky

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 do process.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áciaPython (mistralai)TypeScript (@mistralai/mistralai)Rozlišovací znak v kóde
0.xaž do 0.4.2 (júl 2024)až do 0.5.0 (jún 2024)MistralClient, ploché metódy: client.chat(...)
1.x1.0.0 (7. aug 2024) → 1.9.11 (okt 2025)od aug 2024from mistralai import Mistral, reťazené metódy: client.chat.complete(...)
2.x2.0.0 (10. mar 2026)2.0.0 (18. mar 2026)Python: from mistralai.client import Mistral; TypeScript: iba ES moduly
3.x3.0.0 (28. sep 2026), k 1. nov 2026 verzia 3.7.03.0 (okt 2026), dnes 3.5.0Python: 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.x1.x a novšie
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 a jeho metódyvarianty _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 (parametre client= alebo async_client=, napríklad pre proxy alebo spoločné hlavičky), musí ísť o klienta httpx2; surové požiadavky transportu, odpovede a chyby sú tiež typmi httpx2.
  • Vstavané nástroje opúšťajú dokončovanie chatu. client.chat.complete a client.agents.complete už neprijímajú nástroje web_search, web_search_premium a code_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 mcp a agents teraz 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:

  1. Vyhľadaj staré importy: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Nahraď ich podľa mapovaní v tejto lekcii, nezabudni na chyby, ktoré sa presúvajú do mistralai.client.errors
  3. Aktualizuj volania: reťazené metódy, množné číslo inputs pre vkladania (embeddings), .data v streamovacích cykloch
  4. 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ň .data pri streamovaní
  • 2.0 (mar 2026) presunula všetky Python importy pod mistralai.client, chyby pod mistralai.client.errors a zvýšila minimum na Python 3.10
  • 3.0 (sep 2026) prepína na httpx2 a vyhradzuje web_search a code_interpreter pre Conversations API a agentov
  • V TypeScripte sa import od verzie 1.x nezmenil, ale 2.0 akceptuje iba ES moduly