Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Mistrali SDK versioonide vahel migreerumine

Õppetund 10 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Miks see õppetund on oluline
  2. Neli põlvkonda kahe aastaga
  3. 0.x-lt 1.x-le: klient Mistral ja ahelmeetodid
  4. 1.x-lt 2.x-le: kõik liigub alla mistralai.client
  5. 2.x-lt 3.x-le: httpx2 ja sisseehitatud tööriistad
  6. Kuidas on lood TypeScriptiga?
  7. Migratsiooni läbiviimine
  8. Kui sa ei saa kohe migreeruda
  9. Peamised punktid

Õppetund kirjutati ümber 2. novembril 2026. Eelmine versioon viitas „liikumisele V1-lt V2-le“, mis tegelikult tähendas üleminekut vananenud 0.x kliendilt versioonile 1.0 augustis 2024. Sellest ajast on Pythoni SDK saanud veel kaks suuremat värskendust: 2.0 märtsis 2026 ja 3.0 septembris 2026. See õppetund taastab täieliku ajaloo ametlike migratsioonijuhiste ja väljalaskemärkmete põhjal. Uuendatud 3. novembril 2026: Parandati TypeScripti voogedastuse tsüklit, mis varem edastas sisu string | ContentChunk[] otse funktsioonile process.stdout.write, põhjustades tõrkeid ranges režiimis.

Miks see õppetund on oluline

Puutud selle materjaliga kokku kahes stsenaariumis: kas jätkad mõni aeg tagasi kirjutatud projekti, mis keeldub pärast sõltuvuste uuendamist käivitumast, või järgid veebiõpetust, mille näited enam ei tööta. Mõlemal juhul esita sama esimene küsimus: millise SDK põlvkonna jaoks see kood on kirjutatud? Peaaegu alati annab vastuse üks rida: importlause.

Neli põlvkonda kahe aastaga

PõlvkondPython (mistralai)TypeScript (@mistralai/mistralai)Eristav koodi omadus
0.xkuni 0.4.2 (juuli 2024)kuni 0.5.0 (juuni 2024)MistralClient, tasased meetodid: client.chat(...)
1.x1.0.0 (7. aug 2024) → 1.9.11 (okt 2025)alates aug 2024from mistralai import Mistral, ahelmeetodid: client.chat.complete(...)
2.x2.0.0 (10. märts 2026)2.0.0 (18. märts 2026)Python: from mistralai.client import Mistral; TypeScript: ainult ES-moodulid
3.x3.0.0 (28. sept 2026), 3.7.0 seisuga 1. nov 20263.0 (okt 2026), täna 3.5.0Python: HTTP-klient httpx2

TypeScriptis pole import import { Mistral } from '@mistralai/mistralai' alates 1.x muutunud. Pythonis on see muutunud kaks korda: seal tekib enamik vigu.

0.x-lt 1.x-le: klient Mistral ja ahelmeetodid

Versioon 1.0 asendas kaks klienti, MistralClient (sünkroonne) ja MistralAsyncClient (asünkroonne), ühe klassiga Mistral. Samuti asendas see tasased meetodid nimeruumidega: chat koondab vestlusoperatsioonid ja sügavamale jõudmiseks kasutad complete(). Sõnumeid, mida varem kirjutati klassi ChatMessage abil, kirjutatakse nüüd sõnastikena või kasutades klasse UserMessage, SystemMessage, AssistantMessage ja ToolMessage.

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

Voogedastus järgib sama loogikat, kuid seal peitub lõks, mis maksab sageli pool tundi silumist: vastuvõetud fragment on nüüd pakendatud ja selle sisu loetakse vahetasandi .data kaudu. Muutmata kujul kopeeritud vana 0.x kood tõstab esimesel fragmendil AttributeError-i.

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

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

Ametlik 1.0 juhend sisaldab täielikku tabelit. Kõige sagedasemad vasted on:

0.x1.x ja uuem
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 ja selle meetodid_async variandid: client.chat.complete_async, client.chat.stream_async…

1.x-lt 2.x-le: kõik liigub alla mistralai.client

Versioon 2.0 ei muutnud meetodite nimesid: client.chat.complete jääb client.chat.complete-iks. See muutis kõige muu asukoha. SDK-st sai nimeruumipakett (PEP 420) ja kõik impordid kolisid aadressilt mistralai aadressile mistralai.client:

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

# 2.x ja uuem
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Pane tähele kolmandat rida: veaklassid ei ela enam mudelite seas, vaid asukohas mistralai.client.errors, kus MistralError on ühine baasklass (millest päranduvad SDKError ja HTTPValidationError).

Pilveteenuse pakkujate kliendid liitusid sama nimeruumiga. Versioonis 1.x kaasati need paketiga mistralai, kuid eraldi moodulites mistralai_azure ja 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 ja uuem
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")

Veel kolm muudatust versioonis 2.0 võivad sind mõjutada. Miinimumversioon on nüüd Python 3.10 (1.9.11 aktsepteeris Python 3.9). 42 tüüpi nimetati ümber regulaarse konventsiooni järgi: päringute jaoks {Verb}{Entity}Request ja vastuste jaoks {Verb}{Entity}Response. Ainuke tavalises koodis nähtav ümbernimetamine on Tools, millest sai ConversationRequestTool. Lõpuks aktsepteerivad loendid nüüd tundmatuid väärtusi, nii et API poolt lisatud uus väärtus ei põhjusta vanema SDK versiooni kokkujooksmist.

2.x-lt 3.x-le: httpx2 ja sisseehitatud tööriistad

  1. septembril 2026 avaldatud versioon 3.0 ei muuda ei importe ega tavapäraseid meetodeid. Siiski on kolm punkti, mis võivad projekti katki teha:
  • HTTP-kliendiks saab httpx2. Kui edastad SDK-le oma kliendi (parameetrid client= või async_client=, näiteks puhverserveri või ühiste päiste jaoks), peab see olema httpx2 klient; ka toored transpordipäringud, vastused ja vead on httpx2 tüübid.
  • Sisseehitatud tööriistad lahkuvad vestluse lõpetamistest. client.chat.complete ja client.agents.complete ei aktsepteeri enam tööriistu web_search, web_search_premium ja code_interpreter: neid kasutatakse vestluste API (client.beta.conversations) või agendi kaudu. Mistrali dokumentatsioon selgitab põhjust: vestluse lõpetamise vastused ei saa edastada viiteid, mida need tööriistad tagastavad.
  • Lisad mcp ja agents tuginevad nüüd MCP 2.2-le.

Versioon 3.0 lisab ka teenusekonto tokeniga autentimise: Mistral() loeb tokeni failist, mille määrab keskkonnamuutuja MISTRAL_SA_TOKEN_PATH.

Kuidas on lood TypeScriptiga?

Liikumine vananenud JavaScripti 0.x kliendilt TypeScripti SDK 1.x-le peegeldab peaaegu täpselt Pythoni üleminekut. Import muutub vaikimisi ekspordilt nimeliseks ekspordiks, konstruktor võtab vastu konfiguratsiooniobjekti ja meetoditest saavad ahelmeetodid:

// 0.x (vananenud)
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 ja uuem
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' }],
});

Voogedastus liigub client.chatStream(...)-ilt client.chat.stream(...)-ile ja nagu Pythonis, loetakse sisu chunk.data kaudu:

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;
  // sisu võib olla ka fragmentide loend: kirjutame ainult teksti
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (18. märts 2026) säilitas need impordid, kuid SDK avaldatakse nüüd ainult ES-moodulitena: require('@mistralai/mistralai') CommonJS-is enam ei tööta. Käitusaja valideerimine liigub Zod v4-le, mis mõjutab ainult projekte, mis impordivad skeeme otse SDK-st. Pilvekliendid asuvad eraldi pakettides: @mistralai/mistralai-azure (MistralAzure) ja @mistralai/mistralai-gcp (MistralGCP, varem MistralGoogleCloud).

Migratsiooni läbiviimine

Reaalses projektis tegutse kindlas järjekorras, mitte ära ei paranda vigu nende ilmnemisel. Alusta koodi põlvkonna tuvastamisest selle importide põhjal, seejärel uuenda paketti (pip install --upgrade mistralai või npm install @mistralai/mistralai@latest): seni, kuni vana versioon on installitud, parandad pimesi. Seejärel toimi nii:

  1. Otsi vanu importe: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Asenda need vastavalt selles õppetunnis toodud vastetele, ära unusta vigu, mis kolivad aadressile mistralai.client.errors
  3. Uuenda väljakutseid: ahelmeetodid, mitmus inputs manuste puhul, .data voogedastuse tsüklites
  4. Viia sisseehitatud tööriistad (web_search, code_interpreter) vestluse lõpetamistelt vestluste API-le

Lõpuks testida iga kasutatavat lõpp-punkti ükshaaval: vestlusel, manustel ja voogedastusel on ühel oma muudatused ning projekt, mis käivitub, ei pruugi tingimata kõiki kolme õigesti kasutada.

Kui sa ei saa kohe migreeruda

Ükski neist versioonidest ei paku üleminekurežiimi ega ühilduvusaliaseid. Kui tootmise külmutamine takistab sul migreerumist, määra versioon sõltuvustes sõnaselgelt; vastasel juhul toob järgmine installimine uusima versiooni ja rikub rakenduse:

# Python: jää versioonile 1.x
pip install "mistralai<2"

# Python: jää versioonile 2.x
pip install "mistralai>=2,<3"

# npm: jää versioonile 1.x
npm install @mistralai/mistralai@1

Kohtle seda fikseerimist hingamisruumina: uued funktsioonid jõuavad ainult praegusesse versiooni.

Ametlikud allikad: 0.x → 1.0 migratsioonijuhend · Python 2.0.0 väljalaskemärkmed · Python 3.0.0 väljalaskemärkmed · TypeScript 2.0.0 väljalaskemärkmed · Versioonide ajalugu PyPI-s · Websearch — sisseehitatud tööriistad

Peamised punktid

  • Tuvasta koodi põlvkond selle impordi järgi: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x ja 3.x)
  • 1.0 (august 2024) tõi kasutusele kliendi Mistral, ahelmeetodid ja voogedastuse tasandi .data
  • 2.0 (märts 2026) viis kõik Pythoni impordid alla mistralai.client, vead alla mistralai.client.errors ja tõstis miinimumiks Python 3.10
  • 3.0 (september 2026) lülitub httpx2-le ja reserveerib web_search ja code_interpreter vestluste API-le ja agentidele
  • TypeScriptis pole import alates 1.x muutunud, kuid 2.0 aktsepteerib ainult ES-mooduleid