Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Migrācija starp Mistral SDK versijām

Nodarbība 10 no 14 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Kāpēc šī nodarbība ir svarīga
  2. Četras paaudzes divu gadu laikā
  3. No 0.x uz 1.x: klients Mistral un ķēdes metodes
  4. No 1.x uz 2.x: viss pārvietojas zem mistralai.client
  5. No 2.x uz 3.x: httpx2 un iebūvētie rīki
  6. Kā ir ar TypeScript?
  7. Migrācijas veikšana
  8. Ja nevari migrēt uzreiz
  9. Galvenās atziņas

Nodarbība pārrakstīta 2026. gada 2. novembrī. Iepriekšējā versija minēja “pāreju no V1 uz V2”, kas patiesībā bija pāreja no mantotā 0.x klienta uz 1.0 versiju 2024. gada augustā. Kopš tā laika Python SDK ir piedzīvojis vēl divus lielos laidienus: 2.0 2026. gada martā un 3.0 2026. gada septembrī. Šī nodarbība atjauno pilnu vēsturi, balstoties uz oficiālajiem migrācijas ceļvežiem un laidiena piezīmēm. Atjaunināts 2026. gada 3. novembrī: Labota TypeScript straumēšanas cilpa, kas iepriekš nodeva string | ContentChunk[] saturu tieši funkcijai process.stdout.write, izraisot kļūdas stingrajā režīmā.

Kāpēc šī nodarbība ir svarīga

Tu saskarsies ar šo materiālu divos scenārijos: vai nu atsāc projektu, kas rakstīts pirms kāda laika un atsakās startēt pēc atkarību atjaunināšanas, vai arī seko tiešsaistes apmācībai, kuras piemēri vairs nedarbojas. Abos gadījumos uzdod vienu un to pašu pirmo jautājumu: kurai SDK paaudzei šis kods ir rakstīts? Gandrīz vienmēr atbildi sniedz viena rindiņa: importa instrukcija.

Četras paaudzes divu gadu laikā

PaaudzePython (mistralai)TypeScript (@mistralai/mistralai)Atšķirīgā koda iezīme
0.xlīdz 0.4.2 (2024. gada jūlijs)līdz 0.5.0 (2024. gada jūnijs)MistralClient, plakanas metodes: client.chat(...)
1.x1.0.0 (2024. gada 7. aug.) → 1.9.11 (2025. gada okt.)no 2024. gada augustafrom mistralai import Mistral, ķēdes metodes: client.chat.complete(...)
2.x2.0.0 (2026. gada 10. marts)2.0.0 (2026. gada 18. marts)Python: from mistralai.client import Mistral; TypeScript: tikai ES moduļi
3.x3.0.0 (2026. gada 28. sept.), 3.7.0 uz 2026. gada 1. nov.3.0 (2026. gada okt.), 3.5.0 šodienPython: httpx2 HTTP klients

TypeScript valodā imports import { Mistral } from '@mistralai/mistralai' nav mainījies kopš 1.x versijas. Python valodā tas ir mainījies divreiz: tieši tur notiek lielākā daļa kļūmju.

No 0.x uz 1.x: klients Mistral un ķēdes metodes

Versija 1.0 aizstāja divus klientus, MistralClient (sinhrono) un MistralAsyncClient (asinhrono), ar vienu klasi Mistral. Tā arī aizstāja plakanas metodes ar nosauktelpām: chat grupē sarunu operācijas, un, lai sasniegtu complete(), jāiet par līmeni dziļāk. Ziņojumi, kas iepriekš tika rakstīti, izmantojot klasi ChatMessage, tagad tiek rakstīti kā vārdnīcas vai izmantojot klases UserMessage, SystemMessage, AssistantMessage un ToolMessage.

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

Straumēšana seko tai pašai loģikai, taču tajā slēpjas lamatas, kas bieži vien izmaksā pusstundu ilgu atkļūdošanu: saņemtais fragments tagad ir ietīts, un tā saturs tiek nolasīts caur starpposma .data līmeni. Mantots 0.x kods, nokopēts tāds, kāds tas ir, pirmajā fragmentā izraisīs AttributeError.

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

# 1.x un vēlāk
for chunk in client.chat.stream(model=..., messages=...):
    print(chunk.data.choices[0].delta.content)

Oficiālais 1.0 ceļvedis sniedz pilnu tabulu. Biežākās atbilstības ir šādas:

0.x1.x un vēlāk
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 un tā metodes_async varianti: client.chat.complete_async, client.chat.stream_async…

No 1.x uz 2.x: viss pārvietojas zem mistralai.client

Versija 2.0 nemainīja metožu nosaukumus: client.chat.complete paliek client.chat.complete. Tā mainīja visu pārējo adresi. SDK kļuva par nosauktelpas pakotni (PEP 420), un visi importi pārcēlās no mistralai uz mistralai.client:

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

# 2.x un vēlāk
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Ņem vērā trešo rindiņu: kļūdu klases vairs neatrodas starp modeļiem, bet gan sadaļā mistralai.client.errors, kur MistralError ir kopējā bāze (no kuras mantotas SDKError un HTTPValidationError).

Mākoņa pakalpojumu sniedzēju klienti pievienojās tai pašai nosauktelpai. 1.x versijā tie tika piegādāti kopā ar pakotni mistralai, bet atsevišķos moduļos mistralai_azure un 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 un vēlāk
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")

Trīs citas izmaiņas versijā 2.0 var tevi ietekmēt. Minimālā versija tagad ir Python 3.10 (1.9.11 pieņēma Python 3.9). Tika pārdēvēti 42 tipi saskaņā ar regulāru konvenciju: {Verb}{Entity}Request pieprasījumiem un {Verb}{Entity}Response atbildēm. Vienīgais pārdēvējums, kas redzams parastajā kodā, ir Tools, kas kļuva par ConversationRequestTool. Visbeidzot, uzskaitījumi tagad pieņem nezināmas vērtības, tāpēc jauna vērtība, ko pievieno API, vairs neizraisa vecākas SDK versijas sabrukšanu.

No 2.x uz 3.x: httpx2 un iebūvētie rīki

Versija 3.0, kas izlaista 2026. gada 28. septembrī, nemaina ne importus, ne parastās metodes. Tomēr trīs punkti var izjaukt projektu:

  • HTTP klients kļūst par httpx2. Ja tu nodod savu klientu SDK (parametri client= vai async_client=, piemēram, starpniekserverim vai kopīgajām galvenēm), tam ir jābūt httpx2 klientam; arī izejas transporta pieprasījumi, atbildes un kļūdas ir httpx2 tipi.
  • Iebūvētie rīki pamet sarunu pabeigšanu. client.chat.complete un client.agents.complete vairs nepieņem rīkus web_search, web_search_premium un code_interpreter: tie tiek izmantoti, izmantojot Conversations API (client.beta.conversations) vai aģentu. Mistral dokumentācija paskaidro, kāpēc: sarunu pabeigšanas atbildes nevar nest atsauces, ko šie rīki atgriež.
  • Papildinājumi mcp un agents tagad paļaujas uz MCP 2.2.

Versija 3.0 arī pievieno pakalpojumu konta žetona autentifikāciju: Mistral() nolasa žetonu no faila, ko norāda vides mainīgais MISTRAL_SA_TOKEN_PATH.

Kā ir ar TypeScript?

Pāreja no mantotā JavaScript 0.x klienta uz TypeScript SDK 1.x gandrīz precīzi atspoguļo pāreju Python valodā. Imports mainās no noklusējuma eksporta uz nosauktu eksportu, konstruktors pieņem konfigurācijas objektu, un metodes kļūst par ķēdēm:

// 0.x (mantotais)
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 un vēlāk
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' }],
});

Straumēšana pārvietojas no client.chatStream(...) uz client.chat.stream(...), un, tāpat kā Python valodā, saturs tiek nolasīts caur 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;
  // saturs var būt arī fragmentu saraksts: mēs rakstām tikai tekstu
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (2026. gada 18. marts) saglabāja šos importus, taču SDK tagad tiek publicēts tikai kā ES moduļi: require('@mistralai/mistralai') CommonJS vidē vairs nedarbojas. Izpildlaika validācija pāriet uz Zod v4, kas ietekmē tikai projektus, kas importē shēmas tieši no SDK. Un mākoņa klienti dzīvo atsevišķās pakotnēs: @mistralai/mistralai-azure (MistralAzure) un @mistralai/mistralai-gcp (MistralGCP, iepriekš MistralGoogleCloud).

Migrācijas veikšana

Reālā projektā rīkojies noteiktā secībā, nevis labo kļūdas, tiklīdz tās parādās. Sāc ar koda paaudzes identificēšanu, izmantojot tā importus, pēc tam atjaunini pakotni (pip install --upgrade mistralai vai npm install @mistralai/mistralai@latest): kamēr ir instalēta vecā versija, tu labo akli. Tad rīkojies šādi:

  1. Meklē vecos importus: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Aizstāj tos saskaņā ar šīs nodarbības atbilstībām, neaizmirsti par kļūdām, kas pārvietojas uz mistralai.client.errors
  3. Atjaunini izsaukumus: ķēdes metodes, daudzskaitļa inputs iegulšanai (embeddings), .data straumēšanas cilpās
  4. Pārvieto iebūvētos rīkus (web_search, code_interpreter) no sarunu pabeigšanas uz Conversations API

Visbeidzot, testē katru izmantoto galapunktu pa vienam: sarunām, iegulšanai un straumēšanai ir savas izmaiņas, un projekts, kas startē, ne vienmēr pareizi izsauc visus trīs.

Ja nevari migrēt uzreiz

Neviena no šīm versijām nepiedāvā pārejas režīmu vai saderības aliasus. Ja ražošanas iesaldēšana neļauj tev migrēt, eksplicīti piespraud versiju savās atkarībās; pretējā gadījumā nākamā instalācija iegūs jaunāko versiju un izjauks lietotni:

# Python: paliec uz 1.x
pip install "mistralai<2"

# Python: paliec uz 2.x
pip install "mistralai>=2,<3"

# npm: paliec uz 1.x
npm install @mistralai/mistralai@1

Uztver šo piespraušanu kā atelpu: jaunas funkcijas nonāk tikai pašreizējā versijā.

Oficiālie avoti: 0.x → 1.0 migrācijas ceļvedis · Python 2.0.0 laidiena piezīmes · Python 3.0.0 laidiena piezīmes · TypeScript 2.0.0 laidiena piezīmes · Versiju vēsture vietnē PyPI · Websearch — iebūvētie rīki

Galvenās atziņas

  • Identificē koda paaudzi pēc tās importa: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x un 3.x)
  • 1.0 (2024. gada aug.) ieviesa klientu Mistral, ķēdes metodes un straumēšanas .data līmeni
  • 2.0 (2026. gada marts) pārvietoja visus Python importus zem mistralai.client, kļūdas zem mistralai.client.errors un paaugstināja minimumu līdz Python 3.10
  • 3.0 (2026. gada sept.) pāriet uz httpx2 un rezervē web_search un code_interpreter Conversations API un aģentiem
  • TypeScript valodā imports nav mainījies kopš 1.x, taču 2.0 pieņem tikai ES moduļus