Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Migrazzjoni bejn il-verżjonijiet tal-SDK ta' Mistral

Lezzjoni 10 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Għaliex din il-lezzjoni hija importanti
  2. Erba’ ġenerazzjonijiet f’sentejn
  3. Minn 0.x għal 1.x: il-klijent Mistral u l-metodi f’katina
  4. Minn 1.x għal 2.x: kollox jimxi taħt mistralai.client
  5. Minn 2.x għal 3.x: httpx2 u għodod integrati
  6. X’inhu dwar TypeScript?
  7. Twettiq tal-migrazzjoni
  8. Jekk ma tistax timmigra immedjatament
  9. 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 lil process.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

ĠenerazzjoniPython (mistralai)TypeScript (@mistralai/mistralai)Karatteristika distintiva tal-kodiċi
0.xsa 0.4.2 (Lulju 2024)sa 0.5.0 (Ġunju 2024)MistralClient, metodi ċatti: client.chat(...)
1.x1.0.0 (7 Aww 2024) → 1.9.11 (Ott 2025)minn Aww 2024from mistralai import Mistral, metodi f’katina: client.chat.complete(...)
2.x2.0.0 (10 Mar 2026)2.0.0 (18 Mar 2026)Python: from mistralai.client import Mistral; TypeScript: moduli ES biss
3.x3.0.0 (28 Set 2026), 3.7.0 sal-1 ta’ Nov 20263.0 (Ott 2026), 3.5.0 illumPython: 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.x1.x u sussegwenti
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 u l-metodi tiegħuVarjanti _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 (parametri client= jew async_client=, pereżempju għal proxy jew headers komuni), irid ikun klijent httpx2; it-talbiet, ir-risposti u l-iżbalji tat-trasport raw huma wkoll tipi httpx2.
  • L-għodod integrati joħorġu mill-kompletamenti tal-chat. client.chat.complete u client.agents.complete ma jaċċettawx aktar l-għodod web_search, web_search_premium, u code_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 mcp u agents issa 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:

  1. Fittex importazzjonijiet antiki: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Ibdilhom skont il-korrispondenzi f’din il-lezzjoni, tinsiex l-iżbalji, li jimxu lejn mistralai.client.errors
  3. Aġġorna s-sejħiet: metodi f’katina, inputs fil-plural għall-embeddings, .data fiċ-ċrieki tat-trażmissjoni (streaming)
  4. 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 .data tat-trażmissjoni
  • 2.0 (Mar 2026) mexxa l-importazzjonijiet kollha tal-Python taħt mistralai.client, l-iżbalji taħt mistralai.client.errors, u għolla l-minimu għal Python 3.10
  • 3.0 (Set 2026) tibdel għal httpx2 u tirriżerva web_search u code_interpreter għ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