Salt la conținutul principal
Română— Alege o limbă
Meniu

Migrarea între versiunile SDK Mistral

Lecția 10 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De ce contează această lecție
  2. Patru generații în doi ani
  3. De la 0.x la 1.x: clientul Mistral și metodele înlănțuite
  4. De la 1.x la 2.x: totul se mută sub mistralai.client
  5. De la 2.x la 3.x: httpx2 și instrumente integrate
  6. Dar despre TypeScript?
  7. Desfășurarea migrării
  8. Dacă nu puteți migra imediat
  9. Puncte cheie

Lecție rescrisă la 2 noiembrie 2026. Versiunea anterioară făcea referire la „trecerea de la V1 la V2“, care a fost de fapt tranziția de la clientul legacy 0.x la versiunea 1.0 în august 2024. De atunci, SDK-ul Python a cunoscut încă două lansări majore: 2.0 în martie 2026 și 3.0 în septembrie 2026. Această lecție reconstruiește istoricul complet pe baza ghidurilor oficiale de migrare și a notelor de lansare. Actualizat la 3 noiembrie 2026: S-a corectat bucla de streaming TypeScript, care transmitea anterior conținutul string | ContentChunk[] direct către process.stdout.write, provocând erori în modul strict.

De ce contează această lecție

Veți întâlni acest material în două scenarii: reluați un proiect scris cu ceva timp în urmă, care refuză să pornească după o actualizare a dependențelor, sau urmați un tutorial online ale cărui exemple nu mai funcționează. În ambele cazuri, puneți-vă aceeași primă întrebare: pentru care generație de SDK a fost scris acest cod? Aproape întotdeauna, o singură linie vă oferă răspunsul: instrucțiunea de import.

Patru generații în doi ani

GenerațiePython (mistralai)TypeScript (@mistralai/mistralai)Caracteristică distinctivă de cod
0.xpână la 0.4.2 (iulie 2024)până la 0.5.0 (iunie 2024)MistralClient, metode plate: client.chat(...)
1.x1.0.0 (7 aug. 2024) → 1.9.11 (oct. 2025)din aug. 2024from mistralai import Mistral, metode înlănțuite: client.chat.complete(...)
2.x2.0.0 (10 mar. 2026)2.0.0 (18 mar. 2026)Python: from mistralai.client import Mistral; TypeScript: doar module ES
3.x3.0.0 (28 sep. 2026), 3.7.0 la 1 nov. 20263.0 (oct. 2026), 3.5.0 astăziPython: client HTTP httpx2

În TypeScript, importul import { Mistral } from '@mistralai/mistralai' nu s-a schimbat de la versiunea 1.x. În Python, acesta s-a modificat de două ori: aici apar cele mai multe erori de compatibilitate.

De la 0.x la 1.x: clientul Mistral și metodele înlănțuite

Versiunea 1.0 a înlocuit cei doi clienți, MistralClient (sincron) și MistralAsyncClient (asincron), cu o singură clasă, Mistral. De asemenea, a înlocuit metodele plate cu spații de nume: chat grupează operațiunile de conversație, iar pentru a ajunge la complete() trebuie să coborâți un nivel. Mesajele, care erau scrise anterior folosind clasa ChatMessage, sunt acum scrise ca dicționare sau folosind clasele UserMessage, SystemMessage, AssistantMessage și ToolMessage.

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

Streaming-ul urmează aceeași logică, cu o capcană care costă adesea o jumătate de oră de depanare: fragmentul recepționat este acum împachetat, iar conținutul său se citește printr-un nivel intermediar .data. Codul legacy 0.x copiat ca atare va genera o eroare AttributeError la primul fragment.

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

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

Ghidul oficial 1.0 oferă tabelul complet. Cele mai frecvente corespondențe sunt:

0.x1.x și ulterior
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 și metodele saleVariante _async: client.chat.complete_async, client.chat.stream_async…

De la 1.x la 2.x: totul se mută sub mistralai.client

Versiunea 2.0 nu a atins numele metodelor: client.chat.complete rămâne client.chat.complete. A schimbat însă adresa tuturor celorlalte elemente. SDK-ul a devenit un pachet spațiu de nume (PEP 420), iar toate importurile au migrat de la mistralai la mistralai.client:

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

# 2.x și ulterior
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Observați a treia linie: clasele de erori nu mai locuiesc printre modele, ci în mistralai.client.errors, având MistralError ca bază comună (din care moștenesc SDKError și HTTPValidationError).

Clienții pentru provideri de cloud s-au alăturat aceluiași spațiu de nume. În versiunea 1.x, aceștia erau livrați împreună cu pachetul mistralai, dar în module separate, mistralai_azure și 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 și ulterior
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")

Trei alte modificări în versiunea 2.0 vă pot afecta. Versiunea minimă este acum Python 3.10 (1.9.11 accepta Python 3.9). 42 de tipuri au fost redenumite conform unei convenții regulate: {Verb}{Entity}Request pentru cereri și {Verb}{Entity}Response pentru răspunsuri. Singura redenumire vizibilă în codul comun este Tools, care a devenit ConversationRequestTool. În final, enumerările acceptă acum valori necunoscute, astfel încât o nouă valoare adăugată de API nu mai blochează o versiune mai veche a SDK-ului.

De la 2.x la 3.x: httpx2 și instrumente integrate

Versiunea 3.0, lansată la 28 septembrie 2026, nu modifică nici importurile, nici metodele comune. Totuși, trei aspecte pot bloca un proiect:

  • Clientul HTTP devine httpx2. Dacă transmiteți propriul client către SDK (parametrii client= sau async_client=, de exemplu pentru un proxy sau antete comune), acesta trebuie să fie un client httpx2; cererile, răspunsurile și erorile de transport brute sunt, de asemenea, tipuri httpx2.
  • Instrumentele integrate părăsesc completările de chat. client.chat.complete și client.agents.complete nu mai acceptă instrumentele web_search, web_search_premium și code_interpreter: acestea se utilizează prin API-ul Conversations (client.beta.conversations) sau printr-un agent. Documentația Mistral explică motivul: răspunsurile de completare chat nu pot transporta referințele pe care aceste instrumente le returnează.
  • Extensiile mcp și agents se bazează acum pe MCP 2.2.

Versiunea 3.0 adaugă, de asemenea, autentificarea prin token de cont de serviciu: Mistral() citește tokenul din fișierul specificat de variabila de mediu MISTRAL_SA_TOKEN_PATH.

Dar despre TypeScript?

Trecerea de la clientul legacy JavaScript 0.x la SDK-ul TypeScript 1.x oglindește aproape exact tranziția Python. Importul se schimbă dintr-un export default într-un export numit, constructorul primește un obiect de configurare, iar metodele devin înlănțuite:

// 0.x (legacy)
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 și ulterior
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' }],
});

Streaming-ul trece de la client.chatStream(...) la client.chat.stream(...), iar ca și în Python, conținutul se citește prin 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 poate fi și o listă de fragmente: scriem doar textul
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (18 martie 2026) a păstrat aceste importuri, dar SDK-ul este acum publicat exclusiv ca module ES: un require('@mistralai/mistralai') în CommonJS nu mai funcționează. Validarea la runtime trece la Zod v4, ceea ce afectează doar proiectele care importă scheme direct din SDK. Iar clienții de cloud se află în pachete separate: @mistralai/mistralai-azure (MistralAzure) și @mistralai/mistralai-gcp (MistralGCP, fostul MistralGoogleCloud).

Desfășurarea migrării

Pe un proiect real, procedați într-o ordine definită, în loc să reparați erorile pe măsură ce apar. Începeți prin identificarea generației de cod prin importurile sale, apoi actualizați pachetul (pip install --upgrade mistralai sau npm install @mistralai/mistralai@latest): atâta timp cât este instalată vechea versiune, reparați orb. Apoi procedați astfel:

  1. Căutați importurile vechi: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Înlocuiți-le conform corespondențelor din această lecție; nu uitați erorile, care se mută în mistralai.client.errors
  3. Actualizați apelurile: metode înlănțuite, pluralul inputs pentru embeddings, .data în buclele de streaming
  4. Mutați instrumentele integrate (web_search, code_interpreter) din completările chat în API-ul Conversations

În final, testați fiecare endpoint pe care îl utilizați, unul câte unul: chat, embeddings și streaming au fiecare modificările lor, iar un proiect care pornește nu înseamnă neapărat că le apelează pe toate corect.

Dacă nu puteți migra imediat

Niciuna dintre aceste versiuni nu oferă un mod de tranziție sau aliasuri de compatibilitate. Dacă o înghețare a producției vă împiedică să migrați, fixați explicit versiunea în dependențele dumneavoastră; altfel, următoarea instalare va prelua cea mai recentă versiune și va bloca aplicația:

# Python: rămâneți pe 1.x
pip install "mistralai<2"

# Python: rămâneți pe 2.x
pip install "mistralai>=2,<3"

# npm: rămâneți pe 1.x
npm install @mistralai/mistralai@1

Considerați această fixare ca pe o amânare: noile funcționalități ajung doar în versiunea curentă.

Surse oficiale: Ghid de migrare 0.x → 1.0 · Note de lansare Python 2.0.0 · Note de lansare Python 3.0.0 · Note de lansare TypeScript 2.0.0 · Istoric versiuni pe PyPI · Websearch — instrumente integrate

Puncte cheie

  • Identificați generația de cod prin importul său: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x și 3.x)
  • 1.0 (aug. 2024) a introdus clientul Mistral, metodele înlănțuite și nivelul .data pentru streaming
  • 2.0 (mar. 2026) a mutat toate importurile Python sub mistralai.client, erorile sub mistralai.client.errors și a ridicat minimul la Python 3.10
  • 3.0 (sep. 2026) trece la httpx2 și rezervă web_search și code_interpreter pentru API-ul Conversations și agenți
  • În TypeScript, importul nu s-a schimbat de la 1.x, dar 2.0 acceptă doar module ES