Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Selitev med različicami Mistral SDK

Lekcija 10 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Zakaj je ta lekcija pomembna
  2. Štiri generacije v dveh letih
  3. Od 0.x do 1.x: odjemalec Mistral in verižne metode
  4. Od 1.x do 2.x: vse se premakne pod mistralai.client
  5. Od 2.x do 3.x: httpx2 in vgrajena orodja
  6. Kaj pa TypeScript?
  7. Izvedba selitve
  8. Če se ne moreš seliti takoj
  9. Ključne ugotovitve

Lekcija ponovno napisana 2. novembra 2026. Prejšnja različica se je nanašala na „prehod z V1 na V2”, kar je bil pravzaprav prehod s starega odjemalca 0.x na različico 1.0 avgusta 2024. Od takrat je Python SDK doživel še dve glavni izdaji: 2.0 marca 2026 in 3.0 septembra 2026. Ta lekcija rekonstruira celotno zgodovino na podlagi uradnih vodnikov za selitev in opomb ob izdajah. Posodobljeno 3. novembra 2026: Popravljena zanka za pretakanje v TypeScriptu, ki je prej neposredno posredovala vsebino string | ContentChunk[] v process.stdout.write, kar je povzročalo napake v strogem načinu.

Zakaj je ta lekcija pomembna

S tem gradivom se boš srečal v dveh scenarijih: ali nadaljuješ projekt, napisan pred časom, ki se po posodobitvi odvisnosti noče zagnati, ali pa slediš spletnemu vadniku, katerega primeri ne delujejo več. V obeh primerih si zastavi isto prvo vprašanje: za katero generacijo SDK je bila ta koda napisana? Skoraj vedno ti odgovor pove ena sama vrstica: ukaz za uvoz.

Štiri generacije v dveh letih

GeneracijaPython (mistralai)TypeScript (@mistralai/mistralai)Razlikovalna lastnost kode
0.xdo 0.4.2 (julij 2024)do 0.5.0 (junij 2024)MistralClient, ravne metode: client.chat(...)
1.x1.0.0 (7. avg. 2024) → 1.9.11 (okt. 2025)od avg. 2024from mistralai import Mistral, verižne metode: client.chat.complete(...)
2.x2.0.0 (10. mar. 2026)2.0.0 (18. mar. 2026)Python: from mistralai.client import Mistral; TypeScript: samo ES moduli
3.x3.0.0 (28. sep. 2026), 3.7.0 na dan 1. nov. 20263.0 (okt. 2026), 3.5.0 danesPython: HTTP odjemalec httpx2

V TypeScriptu se uvoz import { Mistral } from '@mistralai/mistralai' ni spremenil od različice 1.x. V Pythonu se je spremenil dvakrat: tu pride do večine napak.

Od 0.x do 1.x: odjemalec Mistral in verižne metode

Različica 1.0 je zamenjala dva odjemalca, MistralClient (sinhroni) in MistralAsyncClient (asinhroni), z enim samim razredom, Mistral. Zamenjala je tudi ravne metode z imenskimi prostori: chat združuje operacije pogovora, za dostop do complete() pa moraš iti eno raven globlje. Sporočila, ki so bila prej zapisana z uporabo razreda ChatMessage, so zdaj zapisana kot slovarji ali z uporabo razredov UserMessage, SystemMessage, AssistantMessage in ToolMessage.

# 0.x (staro)
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"}],
)

Pretakanje sledi isti logiki, s pastjo, ki pogosto stane pol ure odpravljanja napak: prejeti delček je zdaj ovit, njegova vsebina pa se bere preko vmesne ravni .data. Koda legacy 0.x, kopirana takšna, kot je, vrže AttributeError že pri prvem delčku.

# 0.x
for chunk in client.chat_stream(model=..., messages=...):
    print(chunk.choices[0].delta.content)

# 1.x in kasneje
for chunk in client.chat.stream(model=..., messages=...):
    print(chunk.data.choices[0].delta.content)

Uradni vodnik za 1.0 ponuja popolno tabelo. Najpogostejša preslikava je:

0.x1.x in kasneje
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 in njegove metoderazličice _async: client.chat.complete_async, client.chat.stream_async…

Od 1.x do 2.x: vse se premakne pod mistralai.client

Različica 2.0 ni spremenila imen metod: client.chat.complete ostane client.chat.complete. Spremenila je naslov vsega drugega. SDK je postal imenski paket (PEP 420), vsi uvozi pa so se preselili iz mistralai v mistralai.client:

# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError

# 2.x in kasneje
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Opazi tretjo vrstico: razredi za napake ne živijo več med modeli, temveč v mistralai.client.errors, pri čemer je MistralError skupna osnova (od katere dedujeta SDKError in HTTPValidationError).

Odjemalci za ponudnike oblaka so se pridružili istemu imenskemu prostoru. V različici 1.x so bili dobavljeni s paketom mistralai, vendar v ločenih modulih, mistralai_azure in 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 in kasneje
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 spremembe v različici 2.0 lahko vplivajo nate. Najnižja zahtevana različica je zdaj Python 3.10 (različica 1.9.11 je sprejemala Python 3.9). 42 tipov je bilo preimenovanih po rednem dogovoru: {Glagol}{Entiteta}Request za zahteve in {Glagol}{Entiteta}Response za odgovore. Edino preimenovanje, vidno v običajni kodi, je Tools, ki je postal ConversationRequestTool. Končno, naštevanja zdaj sprejemajo neznane vrednosti, tako da nova vrednost, ki jo doda API, ne bo sesula starejše različice SDK.

Od 2.x do 3.x: httpx2 in vgrajena orodja

Različica 3.0, izdana 28. septembra 2026, ne spremeni niti uvozov niti običajnih metod. Vendar pa lahko tri točke porušijo projekt:

  • HTTP odjemalec postane httpx2. Če SDK posreduješ svoj odjemalec (parametra client= ali async_client=, na primer za posredniški strežnik ali skupne glave), mora biti to odjemalec httpx2; tudi surove zahteve prevoza, odgovori in napake so tipi httpx2.
  • Vgrajena orodja zapustijo zaključke pogovora. client.chat.complete in client.agents.complete ne sprejemata več orodij web_search, web_search_premium in code_interpreter: uporabljajo se preko API-ja za pogovore (client.beta.conversations) ali agenta. Dokumentacija Mistral pojasnjuje zakaj: odgovori na zaključke pogovora ne morejo prenašati referenc, ki jih vračajo ta orodja.
  • Dodatka mcp in agents zdaj temeljita na MCP 2.2.

Različica 3.0 dodaja tudi avtentikacijo s žetonom storitvenega računa: Mistral() prebere žeton iz datoteke, določene z okoljsko spremenljivko MISTRAL_SA_TOKEN_PATH.

Kaj pa TypeScript?

Prehod s starega odjemalca JavaScript 0.x na TypeScript SDK 1.x skoraj natančno zrcali prehod v Pythonu. Uvoz se spremeni iz privzetega izvoza v imenovani izvoz, konstruktor sprejme konfiguracijski objekt, metode pa postanejo verižne:

// 0.x (staro)
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 in kasneje
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' }],
});

Pretakanje se premakne iz client.chatStream(...) v client.chat.stream(...), vsebina pa se bere preko chunk.data, tako kot v Pythonu:

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;
  // vsebina je lahko tudi seznam delčkov: pišemo samo besedilo
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (18. marec 2026) je obdržal te uvoze, vendar je SDK zdaj objavljen izključno kot ES moduli: require('@mistralai/mistralai') v CommonJS ne deluje več. Preverjanje med izvajanjem se premakne na Zod v4, kar vpliva le na projekte, ki uvažajo sheme neposredno iz SDK. Odjemalci za oblak pa živijo v ločenih paketih: @mistralai/mistralai-azure (MistralAzure) in @mistralai/mistralai-gcp (MistralGCP, prej MistralGoogleCloud).

Izvedba selitve

Na realnem projektu postopaj po določenem vrstnem redu, namesto da bi napake odpravljal sproti, ko se pojavijo. Najprej identificiraj generacijo kode preko njenih uvozov, nato posodobi paket (pip install --upgrade mistralai ali npm install @mistralai/mistralai@latest): dokler je nameščena stara različica, popravilaš na slepo. Nato postopaj takole:

  1. Poišči stare uvoze: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Zamenjaj jih glede na preslikave v tej lekciji, ne pozabi na napake, ki se selijo v mistralai.client.errors
  3. Posodobi klice: verižne metode, množina inputs za vdelave, .data v zankah za pretakanje
  4. Premakni vgrajena orodja (web_search, code_interpreter) iz zaključkov pogovora v API za pogovore

Na koncu testiraj vsako končno točko, ki jo uporabljaš, eno za drugo: pogovor, vdelave in pretakanje imajo vsak svoje spremembe, in projekt, ki se zažene, nujno ne kliče vseh treh pravilno.

Če se ne moreš seliti takoj

Nobena od teh različic ne ponuja načina prehoda ali aliasov za združljivost. Če zamrznitev proizvodnje preprečuje selitev, izrecno pripni različico v svoje odvisnosti; sicer bo naslednja namestitev pridobila najnovejšo različico in porušila aplikacijo:

# 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

To pripnanje obravnavaj kot odlog: nove funkcije prispejo le v trenutno različico.

Uradni viri: vodnik za selitev 0.x → 1.0 · opombe ob izdaji Python 2.0.0 · opombe ob izdaji Python 3.0.0 · opombe ob izdaji TypeScript 2.0.0 · zgodovina različic na PyPI · Websearch — vgrajena orodja

Ključne ugotovitve

  • Generacijo kode identificiraj po uvozu: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x in 3.x)
  • 1.0 (avgust 2024) je uvedel odjemalca Mistral, verižne metode in raven .data pri pretakanju
  • 2.0 (marec 2026) je preselil vse uvoze v Pythonu pod mistralai.client, napake pod mistralai.client.errors in dvignil minimum na Python 3.10
  • 3.0 (september 2026) prehaja na httpx2 in rezervira web_search ter code_interpreter za API za pogovore in agente
  • V TypeScriptu se uvoz ni spremenil od različice 1.x, vendar 2.0 sprejema le ES module