Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Migracija tarp Mistral SDK versijų

Paskaita 10 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Kodėl ši pamoka svarbi
  2. Keturios kartos per dvejus metus
  3. Nuo 0.x iki 1.x: Mistral klientas ir grandininiai metodai
  4. Nuo 1.x iki 2.x: viskas persikelia į mistralai.client
  5. Nuo 2.x iki 3.x: httpx2 ir integruoti įrankiai
  6. O kaip su TypeScript?
  7. Migracijos vykdymas
  8. Jei negali migruoti iškart
  9. Svarbiausi punktai

Pamoka perrašyta 2026 m. lapkričio 2 d. Ankstesnė versija kalbėjo apie „perėjimą iš V1 į V2“, kas iš tikrųjų buvo perėjimas nuo senosios 0.x kliento versijos prie 1.0 versijos 2024 m. rugpjūtį. Nuo to laiko Python SDK išleido dar du pagrindinius leidimus: 2.0 (2026 m. kovą) ir 3.0 (2026 m. rugsėjį). Ši pamoka atkuria visą istoriją, remdamasi oficialiomis migracijos gairėmis ir leidimų pastabomis. Atnaujinta 2026 m. lapkričio 3 d.: Ištaisyta TypeScript srautinio perdavimo kilpa, kuri anksčiau tiesiogiai perdavė string | ContentChunk[] turinį į process.stdout.write, dėl ko griežtuoju režimu kildavo klaidų.

Kodėl ši pamoka svarbi

Su šia medžiaga susidursi dviejose situacijose: arba tęsi prieš kurį laiką rašytą projektą, kuris po priklausomybių atnaujinimo atsisako paleisti, arba seki internetinę pamoką, kurios pavyzdžiai nebeveikia. Abiem atvejais užduok tą patį pirmąjį klausimą: kuriai SDK kartai šis kodas buvo parašytas? Beveik visada atsakymą rasi vienoje eilutėje: importo instrukcijoje.

Keturios kartos per dvejus metus

KartaPython (mistralai)TypeScript (@mistralai/mistralai)Skiriamasis kodo bruožas
0.xiki 0.4.2 (2024 m. liepa)iki 0.5.0 (2024 m. birželis)MistralClient, plokšti metodai: client.chat(...)
1.x1.0.0 (2024 m. rugpjūčio 7 d.) → 1.9.11 (2025 m. spalis)nuo 2024 m. rugpjūčiofrom mistralai import Mistral, grandininiai metodai: client.chat.complete(...)
2.x2.0.0 (2026 m. kovo 10 d.)2.0.0 (2026 m. kovo 18 d.)Python: from mistralai.client import Mistral; TypeScript: tik ES moduliai
3.x3.0.0 (2026 m. rugsėjo 28 d.), 3.7.0 nuo 2026 m. lapkričio 1 d.3.0 (2026 m. spalis), šiandien 3.5.0Python: httpx2 HTTP klientas

TypeScript kalboje importas import { Mistral } from '@mistralai/mistralai' nepakito nuo 1.x versijos. Python kalboje jis keitėsi du kartus: būtent čia ir įvyksta dauguma sutrikimų.

Nuo 0.x iki 1.x: Mistral klientas ir grandininiai metodai

1.0 versija pakeitė du klientus, MistralClient (sinchroninis) ir MistralAsyncClient (asinchroninis), viena klase – Mistral. Ji taip pat pakeitė plokščius metodus vardų erdvėmis: chat sugrupuoja pokalbių operacijas, o norint pasiekti complete(), reikia nusileisti vienu lygmeniu žemiau. Žinutės, kurios anksčiau buvo rašomos naudojant ChatMessage klasę, dabar rašomos kaip žodynai arba naudojant UserMessage, SystemMessage, AssistantMessage ir ToolMessage klases.

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

Srautinis perdavimas laikosi tos pačios logikos, tačiau čia slypi spąstai, dėl kurių dažnai tenka gaišti pusvalandį derinant: gautas fragmentas dabar yra apgaubtas, o jo turinys skaitomas per tarpinį .data lygmenį. Senasis 0.x kodas, nukopijuotas kaip yra, pirmajame fragmente išmeta AttributeError.

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

# 1.x ir vėlesnės
for chunk in client.chat.stream(model=..., messages=...):
    print(chunk.data.choices[0].delta.content)

Oficiali 1.0 gairė pateikia pilną lentelę. Dažniausiai naudojami atitikmenys:

0.x1.x ir vėlesnės
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 ir jo metodai_async variantai: client.chat.complete_async, client.chat.stream_async…

Nuo 1.x iki 2.x: viskas persikelia į mistralai.client

2.0 versija nepakeitė metodų pavadinimų: client.chat.complete lieka client.chat.complete. Ji pakeitė visko kitą adresą. SDK tapo vardų erdvės paketu (PEP 420), o visi importai persikėlė iš mistralai į mistralai.client:

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

# 2.x ir vėlesnės
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Atkreipk dėmesį į trečią eilutę: klaidų klasės nebegyvena tarp modelių, o yra mistralai.client.errors, kur MistralError yra bendra bazinė klasė (iš kurios paveldimos SDKError ir HTTPValidationError).

Debesų tiekėjų klientai prisijungė prie tos pačios vardų erdvės. 1.x versijoje jie buvo tiekiami su mistralai paketu, bet atskiruose moduliuose: mistralai_azure ir 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 ir vėlesnės
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")

Dar trys 2.0 versijos pakeitimai gali tave paveikti. Minimali versija dabar yra Python 3.10 (1.9.11 priėmė Python 3.9). 42 tipai buvo pervadinti pagal taisyklingą konvenciją: {Veiksmažodis}{Entitas}Request užklausoms ir {Veiksmažodis}{Entitas}Response atsakymams. Vienintelis pervardymas, matomas įprastame kode, yra Tools, kuris tapo ConversationRequestTool. Galiausiai, enumeracijos dabar priima nežinomas reikšmes, todėl nauja API pridėta reikšmė nebepaleidžia senesnės SDK versijos.

Nuo 2.x iki 3.x: httpx2 ir integruoti įrankiai

2026 m. rugsėjo 28 d. išleista 3.0 versija nekeičia nei importų, nei bendrų metodų. Tačiau trys punktai gali sugadinti projektą:

  • HTTP klientas tampa httpx2. Jei SDK perduodi savo klientą (parametrai client= arba async_client=, pavyzdžiui, proxy ar bendroms antraštėms), tai turi būti httpx2 klientas; neapdorotos transporto užklausos, atsakymai ir klaidos taip pat yra httpx2 tipai.
  • Integruoti įrankiai palieka pokalbių užbaigimus. client.chat.complete ir client.agents.complete nebeprima web_search, web_search_premium ir code_interpreter įrankių: jie naudojami per Pokalbių API (client.beta.conversations) arba agentą. Mistral dokumentacija paaiškina kodėl: pokalbių užbaigimo atsakymai negali nešti nuorodų, kurias grąžina šie įrankiai.
  • mcp ir agents papildiniai dabar remiasi MCP 2.2.

3.0 versija taip pat pridėjo tarnybos paskyros žetono autentifikavimą: Mistral() nuskaitys žetoną iš failo, nurodyto MISTRAL_SA_TOKEN_PATH aplinkos kintamajame.

O kaip su TypeScript?

Perėjimas nuo senosios JavaScript 0.x kliento versijos prie TypeScript SDK 1.x beveik tiksliai atkartoja Python perėjimą. Importas keičiasi iš numatytojo eksporto į įvardytąjį eksportą, konstruktorius priima konfigūracijos objektą, o metodai tampa grandininiais:

// 0.x (senoji versija)
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 ir vėlesnės
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' }],
});

Srautinis perdavimas perkeliamas iš client.chatStream(...) į client.chat.stream(...), ir, kaip ir Python atveju, turinys skaitomas per 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;
  // turinys taip pat gali būti fragmentų sąrašas: rašome tik tekstą
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (2026 m. kovo 18 d.) paliko šiuos importus nepakeistus, tačiau SDK dabar leidžiamas tik kaip ES moduliai: require('@mistralai/mistralai') CommonJS aplinkoje nebeveikia. Vykdymo laiko validacija perkelta į Zod v4, kas paveikia tik tuos projektus, kurie tiesiogiai importuoja schemas iš SDK. Debesų klientai gyvena atskiruose paketuose: @mistralai/mistralai-azure (MistralAzure) ir @mistralai/mistralai-gcp (MistralGCP, anksčiau MistralGoogleCloud).

Migracijos vykdymas

Realiam projektui veiksmus atlik nustatyta tvarka, o ne taisyk klaidas joms atsirandant. Pradėk nustatydamas kodo kartą pagal jo importus, tada atnaujink paketą (pip install --upgrade mistralai arba npm install @mistralai/mistralai@latest): kol įdiegta senoji versija, taisai akluoju būdu. Tada veik taip:

  1. Ieškok senų importų: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Pakeisk juos pagal šioje pamokoje pateiktus atitikmenis, nepamiršk klaidų, kurios persikelia į mistralai.client.errors
  3. Atnaujink kvietimus: grandininiai metodai, daugiskaitinis inputs įterpiniams, .data srautinio perdavimo kilpose
  4. Perkelk integruotus įrankius (web_search, code_interpreter) iš pokalbių užbaigimų į Pokalbių API

Galiausiai testuok kiekvieną naudojamą galinį tašką po vieną: pokalbiai, įterpiniai ir srautinis perdavimas turi savo pakeitimus, ir projektas, kuris paleidžiamas, nebūtinai teisingai kviečia visus tris.

Jei negali migruoti iškart

Nė viena iš šių versijų nesiūlo perėjimo režimo ar suderinamumo aliasų. Jei gamybinė aplinka neleidžia migruoti, aiškiai pritvirtink versiją savo priklausomybėse; priešingu atveju kitas diegimas atsisiųs naujausią versiją ir sugadins programą:

# Python: likti ties 1.x
pip install "mistralai<2"

# Python: likti ties 2.x
pip install "mistralai>=2,<3"

# npm: likti ties 1.x
npm install @mistralai/mistralai@1

Į šį pritvirtinimą žiūrėk kaip į atidėjimą: naujos funkcijos atsiranda tik dabartinėje versijoje.

Oficialūs šaltiniai: 0.x → 1.0 migracijos gairė · Python 2.0.0 leidimo pastabos · Python 3.0.0 leidimo pastabos · TypeScript 2.0.0 leidimo pastabos · Versijų istorija PyPI · Websearch — integruoti įrankiai

Svarbiausi punktai

  • Nustatyk kodo kartą pagal importą: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x ir 3.x)
  • 1.0 (2024 m. rugpjūtis) pristatė Mistral klientą, grandininius metodus ir srautinio perdavimo .data lygmenį
  • 2.0 (2026 m. kovas) perkėlė visus Python importus į mistralai.client, klaidas į mistralai.client.errors ir pakėlė minimumą iki Python 3.10
  • 3.0 (2026 m. rugsėjis) pereina prie httpx2 ir rezervuoja web_search bei code_interpreter Pokalbių API ir agentams
  • TypeScript kalboje importas nepakito nuo 1.x, tačiau 2.0 priima tik ES modulius