Migrazzjoni bejn il-verżjonijiet tal-SDK ta' Mistral
F'din il-paġna
- Għaliex din il-lezzjoni hija importanti
- Erba’ ġenerazzjonijiet f’sentejn
- Minn 0.x għal 1.x: il-klijent Mistral u l-metodi f’katina
- Minn 1.x għal 2.x: kollox jimxi taħt mistralai.client
- Minn 2.x għal 3.x: httpx2 u għodod integrati
- X’inhu dwar TypeScript?
- Twettiq tal-migrazzjoni
- Jekk ma tistax timmigra immedjatament
- Punti Ewlenin
Lezzjon miktuba mill-ġdid fit-2 ta’ Novembru, 2026. Il-verżjoni preċedenti kienet tirreferi għal “moviment minn V1 għal V2”, li fil-fatt kienet it-tranżizzjoni mill-klijent antik 0.x għall-verżjoni 1.0 f’Awwissu 2024. Minn dakinhar, l-SDK tal-Python ra żewġ rilaxxi maġġuri oħra: 2.0 f’Marzu 2026 u 3.0 f’Settembru 2026. Din il-lezzjoni tirrikostruwixxi l-istorja sħiħa abbażi tal-gwidi uffiċjali tal-migrazzjoni u n-noti tar-rilaxx. Aġġornat fit-3 ta’ Novembru, 2026: Issolat iċ-ċirkwit tat-trażmissjoni (streaming) f’TypeScript, li qabel kien jgħaddi kontenut
string | ContentChunk[]direttament lilprocess.stdout.write, u kkawża fallimenti f’mod strett.
Għaliex din il-lezzjoni hija importanti
Se tiltaqa’ ma’ dan il-materjal f’żewġ xenarji: qed tkompli proġett miktub xi żmien ilu li jirrifjuta li jibda wara aġġornament tad-dipendenzi, jew qed issegwi tutorjal online li l-eżempji tiegħu ma jaħdmux aktar. Fiż-żewġ każijiet, agħmel l-ewwel mistoqsija: għal liema ġenerazzjoni tal-SDK inkitbet din il-kodiċi? Kważi dejjem, linja waħda tgħidlek: id-dikjarazzjoni tal-importazzjoni.
Erba’ ġenerazzjonijiet f’sentejn
| Ġenerazzjoni | Python (mistralai) | TypeScript (@mistralai/mistralai) | Karatteristika distintiva tal-kodiċi |
|---|---|---|---|
| 0.x | sa 0.4.2 (Lulju 2024) | sa 0.5.0 (Ġunju 2024) | MistralClient, metodi ċatti: client.chat(...) |
| 1.x | 1.0.0 (7 Aww 2024) → 1.9.11 (Ott 2025) | minn Aww 2024 | from mistralai import Mistral, metodi f’katina: client.chat.complete(...) |
| 2.x | 2.0.0 (10 Mar 2026) | 2.0.0 (18 Mar 2026) | Python: from mistralai.client import Mistral; TypeScript: moduli ES biss |
| 3.x | 3.0.0 (28 Set 2026), 3.7.0 sal-1 ta’ Nov 2026 | 3.0 (Ott 2026), 3.5.0 illum | Python: klijent HTTP httpx2 |
F’TypeScript, l-importazzjoni import { Mistral } from '@mistralai/mistralai' ma nbidlitx mill-verżjoni 1.x ‘l hawn. Fil-Python, inbidlet darbtejn: hemmhekk iseħħu l-biċċa l-kbira tal-ħsarat.
Minn 0.x għal 1.x: il-klijent Mistral u l-metodi f’katina
Il-verżjoni 1.0 sostitwiet iż-żewġ klijenti, MistralClient (sinkronu) u MistralAsyncClient (asinkronu), b’klassi waħda, Mistral. Sostitwiet ukoll il-metodi ċatti b’ispazji tal-ismijiet (namespaces): chat jiġbor flimkien l-operazzjonijiet tal-konversazzjoni, u tmur livell wieħed ‘l isfel biex tilħaq complete(). Il-messaġġi, li qabel kienu miktuba bl-użu tal-klassi ChatMessage, issa jinkitbu bħala dizzjunarji jew bl-użu tal-klassijiet UserMessage, SystemMessage, AssistantMessage, u ToolMessage.
# 0.x (antik)
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"}],
)
It-trażmissjoni (streaming) issegwi l-istess loġika, b’nassa li spiss tispiċċa tiswilek nofs siegħa ta’ debug: il-framment li wasal issa huwa mgeżwer, u l-kontenut tiegħu jinqara permezz ta’ livell intermedjarju .data. Il-kodiċi antik 0.x ikkupjat bħala tali jqajjem AttributeError fl-ewwel framment.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x u sussegwenti
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Il-gwida uffiċjali 1.0 tipprovdi t-tabella sħiħa. L-aktar korrispondenzi frekwenti huma:
| 0.x | 1.x u sussegwenti |
|---|---|
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 u l-metodi tiegħu | Varjanti _async: client.chat.complete_async, client.chat.stream_async… |
Minn 1.x għal 2.x: kollox jimxi taħt mistralai.client
Il-verżjoni 2.0 ma messitx l-ismijiet tal-metodi: client.chat.complete tibqa’ client.chat.complete. Ibdlet l-indirizz ta’ kollox ieħor. L-SDK sar pakkett ta’ spazju tal-ismijiet (namespace package - PEP 420), u l-importazzjonijiet kollha marru minn mistralai għal mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x u sussegwenti
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Innota t-tielet linja: il-klassijiet tal-iżbalji ma jgħixux aktar fost il-mudelli iżda f’mistralai.client.errors, b’MistralError bħala bażi komuni (li minnha jwirtu SDKError u HTTPValidationError).
Il-klijenti tal-fornituri tas-sħab ingħaqdu mal-istess spazju tal-ismijiet. Fil-verżjoni 1.x, kienu jiġu pprovduti mal-pakkett mistralai iżda f’moduli separati, mistralai_azure u 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 u sussegwenti
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")
Tliet bidliet oħra fil-verżjoni 2.0 jistgħu jaffettwawk. Il-verżjoni minima issa hija Python 3.10 (il-verżjoni 1.9.11 kienet taċċetta Python 3.9). 42 tip ġew imsemmija mill-ġdid skont konvenzjoni regolari: {Verb}{Entity}Request għat-talbiet u {Verb}{Entity}Response għar-risposti. L-unika bidla fl-ismijiet viżibbli fil-kodiċi komuni hija Tools, li saret ConversationRequestTool. Fl-aħħar nett, l-enumerazzjonijiet issa jaċċettaw valuri mhux magħrufa, allura valur ġdid miżjud mill-API ma jweġġax aktar verżjoni antika tal-SDK.
Minn 2.x għal 3.x: httpx2 u għodod integrati
Il-verżjoni 3.0, rilaxxata fit-28 ta’ Settembru 2026, ma tbiddilx l-importazzjonijiet jew il-metodi komuni. Madankollu, tliet punti jistgħu jkissru proġett:
- Il-klijent HTTP isir
httpx2. Jekk tgħaddi l-klijent tiegħek stess lill-SDK (parametriclient=jewasync_client=, pereżempju għal proxy jew headers komuni), irid ikun klijenthttpx2; it-talbiet, ir-risposti u l-iżbalji tat-trasport raw huma wkoll tipihttpx2. - L-għodod integrati joħorġu mill-kompletamenti tal-chat.
client.chat.completeuclient.agents.completema jaċċettawx aktar l-għododweb_search,web_search_premium, ucode_interpreter: dawn jintużaw permezz tal-API tal-Konversazzjonijiet (client.beta.conversations) jew aġent. Id-dokumentazzjoni ta’ Mistral tispjega għaliex: ir-risposti tal-kompletament tal-chat ma jistgħux iġorru r-referenzi li dawn l-għodod jirritornaw. - L-estrasjonijiet
mcpuagentsissa jiddependu fuq MCP 2.2.
Il-verżjoni 3.0 żżid ukoll l-awtentikazzjoni bit-token tal-kont tas-servizz: Mistral() taqra t-token mill-fajl speċifikat mill-varjabbli tal-ambjent MISTRAL_SA_TOKEN_PATH.
X’inhu dwar TypeScript?
Il-moviment mill-klijent antik JavaScript 0.x għall-SDK TypeScript 1.x jirrifletti kważi eżattament it-tranżizzjoni tal-Python. L-importazzjoni tinbidel minn esportazzjoni default għal waħda msemmija, il-kostruttur jieħu oġġett ta’ konfigurazzjoni, u l-metodi jsiru f’katina:
// 0.x (antik)
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 u sussegwenti
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' }],
});
It-trażmissjoni (streaming) timxi minn client.chatStream(...) għal client.chat.stream(...), u, bħal fil-Python, il-kontenut jinqara permezz ta’ 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 ta’ Marzu 2026) żamm dawn l-importazzjonijiet, iżda l-SDK issa huwa ppubblikat bħala moduli ES biss: require('@mistralai/mistralai') f’CommonJS ma jaħdimx aktar. Il-validazzjoni tar-runtime timxi għal Zod v4, li taffettwa biss proġetti li jimportaw skemi direttament mill-SDK. U l-klijenti tas-sħab jgħixu f’pakketti separati: @mistralai/mistralai-azure (MistralAzure) u @mistralai/mistralai-gcp (MistralGCP, qabel MistralGoogleCloud).
Twettiq tal-migrazzjoni
Fuq proġett reali, ipproċedi f’ordni definita minflok ma ssolvi l-iżbalji hekk kif jidhru. Ibda billi tidentifika l-ġenerazzjoni tal-kodiċi permezz tal-importazzjonijiet tagħha, imbagħad aġġorna l-pakkett (pip install --upgrade mistralai jew npm install @mistralai/mistralai@latest): sakemm il-verżjoni antika tkun installata, qed issolvi bl-għama. Imbagħad ipproċedi kif ġej:
- Fittex importazzjonijiet antiki:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Ibdilhom skont il-korrispondenzi f’din il-lezzjoni, tinsiex l-iżbalji, li jimxu lejn
mistralai.client.errors - Aġġorna s-sejħiet: metodi f’katina,
inputsfil-plural għall-embeddings,.datafiċ-ċrieki tat-trażmissjoni (streaming) - Mexxi l-għodod integrati (
web_search,code_interpreter) mill-kompletamenti tal-chat għall-API tal-Konversazzjonijiet
Fl-aħħar nett, ittestja kull endpoint li tuża, wieħed wieħed: il-chat, l-embeddings, u t-trażmissjoni (streaming) kull wieħed għandu l-bidliet tiegħu, u proġett li jibda mhux neċessarjament isejjaħ it-tlieta korrettament.
Jekk ma tistax timmigra immedjatament
L-ebda waħda minn dawn il-verżjonijiet ma toffri modalità ta’ tranżizzjoni jew alias ta’ kompatibbiltà. Jekk iffriżar tal-produzzjoni jipprevjenik milli timmigra, pinna espliċitament il-verżjoni fid-dipendenzi tiegħek; inkella, l-installazzjoni li jmiss tiġbed l-aħħar verżjoni u tkisser l-applikazzjoni:
# Python: ibqa' fuq 1.x
pip install "mistralai<2"
# Python: ibqa' fuq 2.x
pip install "mistralai>=2,<3"
# npm: ibqa' fuq 1.x
npm install @mistralai/mistralai@1
Itratta dan il-pinning bħala taffija: karatteristiċi ġodda jaslu biss fil-verżjoni kurrenti.
Sorsi uffiċjali: Gwida tal-migrazzjoni 0.x → 1.0 · Noti tar-rilaxx tal-Python 2.0.0 · Noti tar-rilaxx tal-Python 3.0.0 · Noti tar-rilaxx ta’ TypeScript 2.0.0 · Storja tal-verżjonijiet fuq PyPI · Websearch — għodod integrati
Punti Ewlenin
- Identifika l-ġenerazzjoni tal-kodiċi mill-importazzjoni tiegħu:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x u 3.x) - 1.0 (Aww 2024) introduċiet il-klijent
Mistral, metodi f’katina, u l-livell.datatat-trażmissjoni - 2.0 (Mar 2026) mexxa l-importazzjonijiet kollha tal-Python taħt
mistralai.client, l-iżbalji taħtmistralai.client.errors, u għolla l-minimu għal Python 3.10 - 3.0 (Set 2026) tibdel għal
httpx2u tirriżervaweb_searchucode_interpretergħall-API tal-Konversazzjonijiet u l-aġenti - F’TypeScript, l-importazzjoni ma nbidlitx mill-verżjoni 1.x, iżda l-verżjoni 2.0 taċċetta biss moduli ES