Mistrali SDK versioonide vahel migreerumine
Sellel lehel
Õ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 funktsioonileprocess.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õlvkond | Python (mistralai) | TypeScript (@mistralai/mistralai) | Eristav koodi omadus |
|---|---|---|---|
| 0.x | kuni 0.4.2 (juuli 2024) | kuni 0.5.0 (juuni 2024) | MistralClient, tasased meetodid: client.chat(...) |
| 1.x | 1.0.0 (7. aug 2024) → 1.9.11 (okt 2025) | alates aug 2024 | from mistralai import Mistral, ahelmeetodid: client.chat.complete(...) |
| 2.x | 2.0.0 (10. märts 2026) | 2.0.0 (18. märts 2026) | Python: from mistralai.client import Mistral; TypeScript: ainult ES-moodulid |
| 3.x | 3.0.0 (28. sept 2026), 3.7.0 seisuga 1. nov 2026 | 3.0 (okt 2026), täna 3.5.0 | Python: 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.x | 1.x ja uuem |
|---|---|
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 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
- 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 (parameetridclient=võiasync_client=, näiteks puhverserveri või ühiste päiste jaoks), peab see olemahttpx2klient; ka toored transpordipäringud, vastused ja vead onhttpx2tüübid. - Sisseehitatud tööriistad lahkuvad vestluse lõpetamistest.
client.chat.completejaclient.agents.completeei aktsepteeri enam tööriistuweb_search,web_search_premiumjacode_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
mcpjaagentstuginevad 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:
- Otsi vanu importe:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Asenda need vastavalt selles õppetunnis toodud vastetele, ära unusta vigu, mis kolivad aadressile
mistralai.client.errors - Uuenda väljakutseid: ahelmeetodid, mitmus
inputsmanuste puhul,.datavoogedastuse tsüklites - 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 allamistralai.client.errorsja tõstis miinimumiks Python 3.10 - 3.0 (september 2026) lülitub
httpx2-le ja reserveeribweb_searchjacode_interpretervestluste API-le ja agentidele - TypeScriptis pole import alates 1.x muutunud, kuid 2.0 aktsepteerib ainult ES-mooduleid