Migracija između verzija Mistral SDK-a
Na ovoj stranici
Lekcija je ponovno napisana 2. studenoga 2026. Prethodna verzija govorila je o „prijelazu s V1 na V2“, što je zapravo bio prijelaz sa zastarjelog klijenta 0.x na verziju 1.0 u kolovozu 2024. Od tada je Python SDK doživio još dva velika izdanja: 2.0 u ožujku 2026. i 3.0 u rujnu 2026. Ova lekcija rekonstruira cijelu povijest na temelju službenih vodiča za migraciju i bilješki o izdanjima. Ažurirano 3. studenoga 2026.: Ispravljena petlja za strujanje (streaming) u TypeScriptu koja je prethodno prosljeđivala sadržaj tipa
string | ContentChunk[]izravno uprocess.stdout.write, što je uzrokovalo kvarove u strogom načinu rada.
Zašto je ova lekcija važna
Na ovaj ćeš materijal naići u dva scenarija: ili nastavljaš s projektom napisanim prije nekog vremena koji odbija pokrenuti nakon ažuriranja ovisnosti, ili slijediš mrežni vodič čiji primjeri više ne rade. U oba slučaja postavi isto prvo pitanje: za koju je generaciju SDK-a ovaj kod napisan? Gotovo uvijek ti jedan redak daje odgovor: naredba za uvoz (import).
Četiri generacije u dvije godine
| Generacija | Python (mistralai) | TypeScript (@mistralai/mistralai) | Prepoznatljiva značajka koda |
|---|---|---|---|
| 0.x | do 0.4.2 (srpanj 2024.) | do 0.5.0 (lipanj 2024.) | MistralClient, ravne metode: client.chat(...) |
| 1.x | 1.0.0 (7. kol. 2024.) → 1.9.11 (lis. 2025.) | od kol. 2024. | from mistralai import Mistral, ulančane metode: client.chat.complete(...) |
| 2.x | 2.0.0 (10. ožu. 2026.) | 2.0.0 (18. ožu. 2026.) | Python: from mistralai.client import Mistral; TypeScript: samo ES moduli |
| 3.x | 3.0.0 (28. ruj. 2026.), 3.7.0 na dan 1. stu. 2026. | 3.0 (lis. 2026.), 3.5.0 danas | Python: HTTP klijent httpx2 |
U TypeScriptu uvoz import { Mistral } from '@mistralai/mistralai' nije se promijenio od verzije 1.x. U Pythonu se promijenio dva puta: tu se događa većina kvarova.
Od 0.x do 1.x: klijent Mistral i ulančane metode
Verzija 1.0 zamijenila je dva klijenta, MistralClient (sinkroni) i MistralAsyncClient (asinkroni), jednom klasom, Mistral. Također je zamijenila ravne metode imenskim prostorima: chat grupira operacije razgovora, a za dolazak do complete() ideš jednu razinu dublje. Poruke, koje su se prije pisale pomoću klase ChatMessage, sada se pišu kao rječnici (dictionary) ili korištenjem klasa UserMessage, SystemMessage, AssistantMessage i ToolMessage.
# 0.x (zastarjelo)
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"}],
)
Strujanje (streaming) slijedi istu logiku, s jednom zamkom koja često košta pola sata debugiranja: primljeni fragment sada je omotan, a njegov se sadržaj čita kroz međurazinu .data. Zastarjeli kod 0.x kopiran kakav jest podiže AttributeError na prvom fragmentu.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x i novije
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Službeni vodič za 1.0 sadrži punu tablicu. Najčešća mapiranja su:
| 0.x | 1.x i novije |
|---|---|
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 njegove metode | varijante _async: client.chat.complete_async, client.chat.stream_async… |
Od 1.x do 2.x: sve se seli pod mistralai.client
Verzija 2.0 nije dirala nazive metoda: client.chat.complete ostaje client.chat.complete. Promijenila je adresu svega ostalog. SDK je postao imenski paket (PEP 420), a svi su se uvozi preselili s mistralai na mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x i novije
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Obrati pozornost na treći redak: klase za pogreške više ne žive među modelima, već u mistralai.client.errors, pri čemu je MistralError zajednička baza (od koje nasljeđuju SDKError i HTTPValidationError).
Klijenti za pružatelje oblaka pridružili su se istom imenskom prostoru. U verziji 1.x isporučivali su se uz paket mistralai, ali u odvojenim modulima, 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 novije
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 druge promjene u verziji 2.0 mogu te pogoditi. Minimalna verzija sada je Python 3.10 (1.9.11 prihvatio je Python 3.9). 42 tipa preimenovano je prema pravilnom konvencijom: {Glagol}{Entitet}Request za zahtjeve i {Glagol}{Entitet}Response za odgovore. Jedino preimenovanje vidljivo u uobičajenom kodu je Tools, koje je postalo ConversationRequestTool. Konačno, enumeracije sada prihvaćaju nepoznate vrijednosti, pa nova vrijednost koju doda API više ne ruši stariju verziju SDK-a.
Od 2.x do 3.x: httpx2 i ugrađeni alati
Verzija 3.0, objavljena 28. rujna 2026., ne mijenja ni uvoze ni uobičajene metode. Međutim, tri točke mogu srušiti projekt:
- HTTP klijent postaje
httpx2. Ako SDK-u proslijediš vlastiti klijent (parametriclient=iliasync_client=, na primjer za proxy ili zajednička zaglavlja), on mora biti klijenthttpx2; sirovi zahtjevi prijenosa, odgovori i pogreške također su tipovihttpx2. - Ugrađeni alati napuštaju dovršetke razgovora.
client.chat.completeiclient.agents.completeviše ne prihvaćaju alateweb_search,web_search_premiumicode_interpreter: oni se koriste putem API-ja za razgovore (client.beta.conversations) ili agenta. Mistralova dokumentacija objašnjava zašto: odgovori na dovršetke razgovora ne mogu nositi reference koje ovi alati vraćaju. - Dodaci
mcpiagentssada se oslanjaju na MCP 2.2.
Verzija 3.0 također dodaje autentifikaciju tokenom računa usluge: Mistral() čita token iz datoteke određene varijablom okoline MISTRAL_SA_TOKEN_PATH.
A što je s TypeScriptom?
Prijelaz sa zastarjelog JavaScript klijenta 0.x na TypeScript SDK 1.x gotovo je zrcalna slika prijelaza u Pythonu. Uvoz se mijenja s izvoza po zadanim postavkama (default export) na imenovani izvoz, konstruktor prima objekt konfiguracije, a metode postaju ulančane:
// 0.x (zastarjelo)
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 novije
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' }],
});
Strujanje se seli s client.chatStream(...) na client.chat.stream(...), a kao i u Pythonu, sadržaj se čita putem 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 can also be a list of fragments: we only write text
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18. ožujka 2026.) zadržao je ove uvoze, ali se SDK sada objavljuje isključivo kao ES moduli: require('@mistralai/mistralai') u CommonJS-u više ne radi. Validacija u vrijeme izvođenja prelazi na Zod v4, što utječe samo na projekte koji izravno uvoze sheme iz SDK-a. Klijenti za oblak žive u odvojenim paketima: @mistralai/mistralai-azure (MistralAzure) i @mistralai/mistralai-gcp (MistralGCP, ranije MistralGoogleCloud).
Provođenje migracije
Na stvarnom projektu postupaj određenim redoslijedom umjesto da popravljaš pogreške kako se pojavljuju. Prvo identificiraj generaciju koda putem njegovih uvoza, zatim ažuriraj paket (pip install --upgrade mistralai ili npm install @mistralai/mistralai@latest): dokle god je instalirana stara verzija, popravljaš naslijepo. Zatim postupi ovako:
- Potraži stare uvoze:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Zamijeni ih prema mapiranjima u ovoj lekciji, ne zaboravi pogreške koje se sele u
mistralai.client.errors - Ažuriraj pozive: ulančane metode, množina
inputsza ugradnje (embeddings),.datau petljama za strujanje - Premjesti ugrađene alate (
web_search,code_interpreter) iz dovršetaka razgovora u API za razgovore (Conversations API)
Na kraju testiraj svaku krajnju točku koju koristiš, jednu po jednu: chat, ugradnje i strujanje imaju svoje vlastite promjene, a projekt koji se pokrene nužno ne poziva sve tri ispravno.
Ako ne možeš migrirati odmah
Nijedna od ovih verzija ne nudi način prijelaza ili aliasa za kompatibilnost. Ako zamrzavanje proizvodnje sprječava migraciju, eksplicitno pričvrsti verziju u svoje ovisnosti; u suprotnom, sljedeća instalacija dohvatit će najnoviju verziju i srušiti aplikaciju:
# Python: ostani na 1.x
pip install "mistralai<2"
# Python: ostani na 2.x
pip install "mistralai>=2,<3"
# npm: ostani na 1.x
npm install @mistralai/mistralai@1
Ovo pričvršćivanje tretiraj kao odgodu: nove značajke stižu samo u trenutnu verziju.
Službeni izvori: Vodič za migraciju 0.x → 1.0 · Bilješke o izdanju Python 2.0.0 · Bilješke o izdanju Python 3.0.0 · Bilješke o izdanju TypeScript 2.0.0 · Povijest verzija na PyPI-ju · Websearch — ugrađeni alati
Ključne točke
- Identificiraj generaciju koda prema njegovom uvozu:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x i 3.x) - 1.0 (kol. 2024.) uveo je klijenta
Mistral, ulančane metode i razinu.dataza strujanje - 2.0 (ožu. 2026.) preselio je sve Python uvoze pod
mistralai.client, pogreške podmistralai.client.errorsi podigao minimum na Python 3.10 - 3.0 (ruj. 2026.) prelazi na
httpx2i rezerviraweb_searchicode_interpreterza API za razgovore i agente - U TypeScriptu se uvoz nije promijenio od verzije 1.x, ali 2.0 prihvaća samo ES module