Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Migracija između verzija Mistral SDK-a

Lekcija 10 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Zašto je ova lekcija važna
  2. Četiri generacije u dvije godine
  3. Od 0.x do 1.x: klijent Mistral i ulančane metode
  4. Od 1.x do 2.x: sve se seli pod mistralai.client
  5. Od 2.x do 3.x: httpx2 i ugrađeni alati
  6. A što je s TypeScriptom?
  7. Provođenje migracije
  8. Ako ne možeš migrirati odmah
  9. Ključne točke

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 u process.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

GeneracijaPython (mistralai)TypeScript (@mistralai/mistralai)Prepoznatljiva značajka koda
0.xdo 0.4.2 (srpanj 2024.)do 0.5.0 (lipanj 2024.)MistralClient, ravne metode: client.chat(...)
1.x1.0.0 (7. kol. 2024.) → 1.9.11 (lis. 2025.)od kol. 2024.from mistralai import Mistral, ulančane metode: client.chat.complete(...)
2.x2.0.0 (10. ožu. 2026.)2.0.0 (18. ožu. 2026.)Python: from mistralai.client import Mistral; TypeScript: samo ES moduli
3.x3.0.0 (28. ruj. 2026.), 3.7.0 na dan 1. stu. 2026.3.0 (lis. 2026.), 3.5.0 danasPython: 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.x1.x i novije
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 njegove metodevarijante _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 (parametri client= ili async_client=, na primjer za proxy ili zajednička zaglavlja), on mora biti klijent httpx2; sirovi zahtjevi prijenosa, odgovori i pogreške također su tipovi httpx2.
  • Ugrađeni alati napuštaju dovršetke razgovora. client.chat.complete i client.agents.complete više ne prihvaćaju alate web_search, web_search_premium i code_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 mcp i agents sada 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:

  1. Potraži stare uvoze: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Zamijeni ih prema mapiranjima u ovoj lekciji, ne zaboravi pogreške koje se sele u mistralai.client.errors
  3. Ažuriraj pozive: ulančane metode, množina inputs za ugradnje (embeddings), .data u petljama za strujanje
  4. 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 .data za strujanje
  • 2.0 (ožu. 2026.) preselio je sve Python uvoze pod mistralai.client, pogreške pod mistralai.client.errors i podigao minimum na Python 3.10
  • 3.0 (ruj. 2026.) prelazi na httpx2 i rezervira web_search i code_interpreter za API za razgovore i agente
  • U TypeScriptu se uvoz nije promijenio od verzije 1.x, ali 2.0 prihvaća samo ES module