Mistral SDK -versioiden välillä siirtyminen
Tällä sivulla
- Miksi tämä oppitunti on tärkeä
- Neljä sukupolvea kahdessa vuodessa
- Siirtyminen versiosta 0.x versioon 1.x: Mistral-asiakas ja ketjutetut metodit
- Siirtyminen versiosta 1.x versioon 2.x: kaikki siirtyy kohtaan mistralai.client
- Siirtyminen versiosta 2.x versioon 3.x: httpx2 ja sisäänrakennetut työkalut
- Entä TypeScript?
- Siirtymän toteuttaminen
- Jos et voi siirtyä heti
- Keskeiset asiat
Oppitunti kirjoitettu uudelleen 2. marraskuuta 2026. Edellinen versio viittasi “siirtymiseen versiosta V1 versioon V2”, mikä itse asiassa tarkoitti siirtymää vanhentuneesta 0.x-asiakkaasta versioon 1.0 elokuussa 2024. Sen jälkeen Python SDK on julkaissut kaksi uutta pääversiota: 2.0 maaliskuussa 2026 ja 3.0 syyskuussa 2026. Tämä oppitunti rekonstruoi koko historian virallisten siirtymäopaiden ja julkaisutietojen perusteella. Päivitetty 3. marraskuuta 2026: Korjattu TypeScriptin suoratoistosilmukka, joka aiemmin välitti sisällön
string | ContentChunk[]suoraan funktiolleprocess.stdout.write, aiheuttaen virheitä tiukassa tilassa.
Miksi tämä oppitunti on tärkeä
Kohtaat tämän materiaalin kahdessa tilanteessa: joko jatkat projektia, joka on kirjoitettu jonkin aikaa sitten ja kieltäytyy käynnistymästä riippuvuuksien päivityksen jälkeen, tai seuraat verkkotutoriaalia, jonka esimerkit eivät enää toimi. Molemmissa tapauksissa esitä sama ensimmäinen kysymys: mille SDK-sukupolvelle tämä koodi on kirjoitettu? Lähes aina yksi rivi kertoo vastauksen: tuontilauseke.
Neljä sukupolvea kahdessa vuodessa
| Sukupolvi | Python (mistralai) | TypeScript (@mistralai/mistralai) | Erottava koodin ominaisuus |
|---|---|---|---|
| 0.x | aina 0.4.2:een asti (heinäkuu 2024) | aina 0.5.0:aan asti (kesäkuu 2024) | MistralClient, litteät metodit: client.chat(...) |
| 1.x | 1.0.0 (7.8.2024) → 1.9.11 (lokakuu 2025) | elokuusta 2024 alkaen | from mistralai import Mistral, ketjutetut metodit: client.chat.complete(...) |
| 2.x | 2.0.0 (10.3.2026) | 2.0.0 (18.3.2026) | Python: from mistralai.client import Mistral; TypeScript: vain ES-moduulit |
| 3.x | 3.0.0 (28.9.2026), 3.7.0 tilanne 1.11.2026 | 3.0 (lokakuu 2026), 3.5.0 tänään | Python: httpx2 HTTP-asiakas |
TypeScriptissä tuonti import { Mistral } from '@mistralai/mistralai' ei ole muuttunut versiosta 1.x lähtien. Pythonissa se on muuttunut kahdesti: siellä tapahtuu useimmat rikkoontumiset.
Siirtyminen versiosta 0.x versioon 1.x: Mistral-asiakas ja ketjutetut metodit
Versio 1.0 korvasi kaksi asiakasta, MistralClient (synkroninen) ja MistralAsyncClient (asynkroninen), yhdellä luokalla, Mistral. Se korvasi myös litteät metodit nimiavaruuksilla: chat ryhmittelee keskusteluoperaatiot, ja sinun täytyy mennä yksi taso syvemmälle päästäksesi metodiin complete(). Viestit, jotka aiemmin kirjoitettiin käyttämällä ChatMessage-luokkaa, kirjoitetaan nyt sanakirjoina tai käyttämällä luokkia UserMessage, SystemMessage, AssistantMessage ja ToolMessage.
# 0.x (vanhentunut)
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"}],
)
Suoratoisto noudattaa samaa logiikkaa, mutta siinä on ansa, joka maksaa usein puoli tuntia vianetsintää: vastaanotettu osa on nyt kääritty, ja sen sisältö luetaan välillisen .data-tason kautta. Vanhentunut 0.x-koodi, joka kopioidaan sellaisenaan, nostaa AttributeError-virheen ensimmäisessä osassa.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x ja uudemmat
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Virallinen 1.0-opas tarjoaa täyden taulukon. Yleisimmät kuvaukset ovat:
| 0.x | 1.x ja uudemmat |
|---|---|
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 ja sen metodit | _async-variantit: client.chat.complete_async, client.chat.stream_async… |
Siirtyminen versiosta 1.x versioon 2.x: kaikki siirtyy kohtaan mistralai.client
Versio 2.0 ei koskenut metodien nimiin: client.chat.complete pysyy client.chat.complete:na. Se muutti kaiken muun osoitteen. SDK:sta tuli nimiavaruuspaketti (PEP 420), ja kaikki tuonnit siirtyivät kohteesta mistralai kohteeseen mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x ja uudemmat
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Huomaa kolmas rivi: virheluokat eivät enää asu mallien joukossa, vaan osoitteessa mistralai.client.errors, jossa MistralError toimii yhteisenä kantaluokkana (josta SDKError ja HTTPValidationError periytyvät).
Pilvipalveluntarjoajien asiakkaat liittyivät samaan nimiavaruuteen. Versiossa 1.x ne toimitettiin mistralai-paketin mukana, mutta erillisissä moduuleissa, mistralai_azure ja 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 ja uudemmat
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")
Kolme muuta muutosta versiossa 2.0 voivat vaikuttaa sinuun. Vähimmäisversio on nyt Python 3.10 (versio 1.9.11 hyväksyi Python 3.9:n). 42 tyyppiä nimettiin uudelleen säännöllisen käytännön mukaisesti: {Verb}{Entity}Request pyynnöille ja {Verb}{Entity}Response vastauksille. Ainoa yleisessä koodissa näkyvä uudelleennimeäminen on Tools, josta tuli ConversationRequestTool. Lopuksi, luetelmat hyväksyvät nyt tuntemattomia arvoja, joten API:n lisäämä uusi arvo ei enää kaada vanhempaa SDK-versiota.
Siirtyminen versiosta 2.x versioon 3.x: httpx2 ja sisäänrakennetut työkalut
Versio 3.0, julkaistu 28. syyskuuta 2026, ei muuta tuonteja eikä yleisiä metodeja. Kolme seikkaa voi kuitenkin rikkoa projektin:
- HTTP-asiakkaaksi tulee
httpx2. Jos välität oman asiakkaasi SDK:lle (parametritclient=taiasync_client=, esimerkiksi välityspalvelinta tai yhteisiä otsikoita varten), sen on oltavahttpx2-asiakas; raakakuljetuspyynnöt, -vastaukset ja -virheet ovat myöshttpx2-tyyppejä. - Sisäänrakennetut työkalut poistuvat keskustelun täydennyksistä.
client.chat.completejaclient.agents.completeeivät enää hyväksy työkalujaweb_search,web_search_premiumjacode_interpreter: niitä käytetään Conversations API:n (client.beta.conversations) tai agentin kautta. Mistralin dokumentaatio selittää miksi: keskustelun täydennysvastaukset eivät voi sisältää näiden työkalujen palautamia viittauksia. - Lisäosat
mcpjaagentsluottavat nyt versioon MCP 2.2.
Versio 3.0 lisää myös palvelutilin tunnistautumisen: Mistral() lukee tunnuksen tiedostosta, jonka määrittelee ympäristömuuttuja MISTRAL_SA_TOKEN_PATH.
Entä TypeScript?
Siirtyminen vanhentuneesta JavaScript 0.x -asiakkaasta TypeScript SDK 1.x:ään peilaa Pythonin siirtymää lähes täydellisesti. Tuonti muuttuu oletusviennistä nimetyksi vienniksi, muodostin ottaa vastaan konfiguraatio-objektin, ja metodeista tulee ketjutettuja:
// 0.x (vanhentunut)
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 ja uudemmat
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' }],
});
Suoratoisto siirtyy muodosta client.chatStream(...) muotoon client.chat.stream(...), ja kuten Pythonissa, sisältö luetaan kohdan chunk.data kautta:
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;
// sisältö voi olla myös lista osia: kirjoitamme vain tekstiä
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18.3.2026) piti nämä tuonnit ennallaan, mutta SDK julkaistaan nyt vain ES-moduuleina: require('@mistralai/mistralai') CommonJS:ssä ei enää toimi. Aikavalidointi siirtyy Zod v4:ään, mikä vaikuttaa vain projekteihin, jotka tuovat skeemoja suoraan SDK:sta. Pilviasiakkaat asuvat erillisissä paketeissa: @mistralai/mistralai-azure (MistralAzure) ja @mistralai/mistralai-gcp (MistralGCP, aiemmin MistralGoogleCloud).
Siirtymän toteuttaminen
Todellisessa projektissa etene määritellyssä järjestyksessä äläkä korjaa virheitä sitä mukaa kuin ne ilmenevät. Aloita tunnistamalla koodin sukupolvi sen tuontien perusteella, päivitä sitten paketti (pip install --upgrade mistralai tai npm install @mistralai/mistralai@latest): niin kauan kuin vanha versio on asennettuna, korjaat sokkona. Etene sitten seuraavasti:
- Etsi vanhat tuonnit:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Korvaa ne tämän oppitunnin kuvausten mukaisesti, älä unohda virheitä, jotka siirtyvät osoitteeseen
mistralai.client.errors - Päivitä kutsut: ketjutetut metodit, monikko
inputsupotuksille,.datasuoratoistosilmukoissa - Siirrä sisäänrakennetut työkalut (
web_search,code_interpreter) keskustelun täydennyksistä Conversations API:hin
Lopuksi testaa jokainen käyttämäsi päätepiste yksi kerrallaan: keskustelulla, upotuksilla ja suoratoistolla on kullakin omat muutoksensa, ja projekti, joka käynnistyy, ei välttämättä kutsu kaikkia kolmea oikein.
Jos et voi siirtyä heti
Mikään näistä versioista ei tarjoa siirtymätilaa tai yhteensopivuusaliaksia. Jos tuotannon jäädytys estää sinua siirtymästä, kiinnitä versio nimenomaisesti riippuvuuksiisi; muuten seuraava asennus hakee uusimman version ja rikkoo sovelluksen:
# Python: pysy versiossa 1.x
pip install "mistralai<2"
# Python: pysy versiossa 2.x
pip install "mistralai>=2,<3"
# npm: pysy versiossa 1.x
npm install @mistralai/mistralai@1
Kohtele tätä kiinnitystä lykkäyksenä: uudet ominaisuudet saapuvat vain nykyiseen versioon.
Viralliset lähteet: 0.x → 1.0 siirtymäopas · Python 2.0.0 julkaisutiedot · Python 3.0.0 julkaisutiedot · TypeScript 2.0.0 julkaisutiedot · Versiohistoria PyPI:ssä · Websearch — sisäänrakennetut työkalut
Keskeiset asiat
- Tunnista koodin sukupolvi sen tuonnin perusteella:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x ja 3.x) - 1.0 (eloakuu 2024) esitteli
Mistral-asiakkaan, ketjutetut metodit ja suoratoiston.data-tason - 2.0 (maaliskuu 2026) siirsi kaikki Python-tuonnit kohtaan
mistralai.client, virheet kohtaanmistralai.client.errorsja nosti vähimmäisvaatimuksen Python 3.10:een - 3.0 (syyskuu 2026) vaihtaa käyttöön
httpx2:n ja varaaweb_search- jacode_interpreter-työkalut Conversations API:lle ja agenteille - TypeScriptissä tuonti ei ole muuttunut versiosta 1.x lähtien, mutta 2.0 hyväksyy vain ES-moduulit