Migracija tarp Mistral SDK versijų
Šiame puslapyje
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
| Karta | Python (mistralai) | TypeScript (@mistralai/mistralai) | Skiriamasis kodo bruožas |
|---|---|---|---|
| 0.x | iki 0.4.2 (2024 m. liepa) | iki 0.5.0 (2024 m. birželis) | MistralClient, plokšti metodai: client.chat(...) |
| 1.x | 1.0.0 (2024 m. rugpjūčio 7 d.) → 1.9.11 (2025 m. spalis) | nuo 2024 m. rugpjūčio | from mistralai import Mistral, grandininiai metodai: client.chat.complete(...) |
| 2.x | 2.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.x | 3.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.0 | Python: 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.x | 1.x ir vėlesnės |
|---|---|
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 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ą (parametraiclient=arbaasync_client=, pavyzdžiui, proxy ar bendroms antraštėms), tai turi būtihttpx2klientas; neapdorotos transporto užklausos, atsakymai ir klaidos taip pat yrahttpx2tipai. - Integruoti įrankiai palieka pokalbių užbaigimus.
client.chat.completeirclient.agents.completenebeprimaweb_search,web_search_premiumircode_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. mcpiragentspapildiniai 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:
- Ieškok senų importų:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Pakeisk juos pagal šioje pamokoje pateiktus atitikmenis, nepamiršk klaidų, kurios persikelia į
mistralai.client.errors - Atnaujink kvietimus: grandininiai metodai, daugiskaitinis
inputsįterpiniams,.datasrautinio perdavimo kilpose - 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ė
Mistralklientą, grandininius metodus ir srautinio perdavimo.datalygmenį - 2.0 (2026 m. kovas) perkėlė visus Python importus į
mistralai.client, klaidas įmistralai.client.errorsir pakėlė minimumą iki Python 3.10 - 3.0 (2026 m. rugsėjis) pereina prie
httpx2ir rezervuojaweb_searchbeicode_interpreterPokalbių API ir agentams - TypeScript kalboje importas nepakito nuo 1.x, tačiau 2.0 priima tik ES modulius