Migrálás a Mistral SDK verziói között
Ezen az oldalon
- Miért fontos ez a lecke
- Négy generáció két év alatt
- A 0.x-től az 1.x-ig: a Mistral kliens és a láncolt metódusok
- Az 1.x-től a 2.x-ig: minden a mistralai.client alá kerül
- A 2.x-től a 3.x-ig: httpx2 és beépített eszközök
- Mi a helyzet a TypeScriptkel?
- A migrálás végrehajtása
- Ha nem tudsz azonnal migrálni
- Főbb megállapítások
A leckét 2026. november 2-án írtuk át. Az előző verzió a „V1-ről V2-re való átállást“ említette, ami valójában a régi 0.x kliens és az 1.0-s verzió közötti átmenetet jelentette 2024 augusztusában. Azóta a Python SDK két további fő kiadást ért meg: a 2.0-t 2026 márciusában és a 3.0-t 2026 szeptemberében. Ez a lecke a hivatalos migrációs útmutatók és kiadási jegyzetek alapján újraépíti a teljes történetet. Frissítve 2026. november 3-án: Javítottuk a TypeScript streamelő ciklust, amely korábban közvetlenül a
string | ContentChunk[]tartalmat adta át aprocess.stdout.writemetódusnak, ami szigorú módban hibákat okozott.
Miért fontos ez a lecke
Két forgatókönyvben fogsz találkozni ezzel az anyaggal: vagy egy régebben írt projektet folytatsz, amely egy függőségfrissítés után nem indul el, vagy egy online oktatóanyagot követsz, amelynek példái már nem működnek. Mindkét esetben tedd fel ugyanazt az első kérdést: melyik SDK-generációhoz írták ezt a kódot? Szinte mindig egyetlen sor árulja el: az import utasítás.
Négy generáció két év alatt
| Generáció | Python (mistralai) | TypeScript (@mistralai/mistralai) | Megkülönböztető kódrészlet |
|---|---|---|---|
| 0.x | 0.4.2-ig (2024. július) | 0.5.0-ig (2024. június) | MistralClient, lapos metódusok: client.chat(...) |
| 1.x | 1.0.0 (2024. aug. 7.) → 1.9.11 (2025. okt.) | 2024. augusztustól | from mistralai import Mistral, láncolt metódusok: client.chat.complete(...) |
| 2.x | 2.0.0 (2026. márc. 10.) | 2.0.0 (2026. márc. 18.) | Python: from mistralai.client import Mistral; TypeScript: kizárólag ES modulok |
| 3.x | 3.0.0 (2026. szept. 28.), 3.7.0 2026. nov. 1-jétől | 3.0 (2026. okt.), ma 3.5.0 | Python: httpx2 HTTP kliens |
TypeScriptben az import { Mistral } from '@mistralai/mistralai' import utasítás nem változott az 1.x óta. Pythonban kétszer is változott: itt történik a legtöbb hiba.
A 0.x-től az 1.x-ig: a Mistral kliens és a láncolt metódusok
Az 1.0-s verzió leváltotta a két klienst, a MistralClient-et (szinkron) és a MistralAsyncClient-et (aszinkron), egyetlen osztállyal, a Mistral-lal. Emellett a lapos metódusokat névterekkel váltotta fel: a chat csoportosítja a beszélgetési műveleteket, és egy szinttel mélyebbre kell menned a complete() eléréséhez. Az üzeneteket, amelyeket korábban a ChatMessage osztállyal írtak, most szótárakként vagy a UserMessage, SystemMessage, AssistantMessage és ToolMessage osztályokkal kell megadni.
# 0.x (régi)
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"}],
)
A streamelés ugyanerre a logikára épül, egy csapdával, amely gyakran fél óra hibakeresésbe kerül: a fogadott töredék most be van csomagolva, és tartalmát egy közbülső .data szinten keresztül olvassuk ki. A változatlanul másolt régi 0.x kód az első töredéknél AttributeError hibát dob.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x és újabb
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
A hivatalos 1.0-s útmutató tartalmazza a teljes táblázatot. A leggyakoribb hozzárendelések:
| 0.x | 1.x és újabb |
|---|---|
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 és metódusai | _async változatok: client.chat.complete_async, client.chat.stream_async… |
Az 1.x-től a 2.x-ig: minden a mistralai.client alá kerül
A 2.0-s verzió nem érintette a metódusneveket: a client.chat.complete továbbra is client.chat.complete marad. Viszont megváltoztatta minden más címét. Az SDK névtér-csomaggá (PEP 420) vált, és minden import a mistralai-ról a mistralai.client-re költözött:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x és újabb
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Figyeld meg a harmadik sort: a hibaosztályok már nem a modellek között élnek, hanem a mistralai.client.errors alatt, ahol a MistralError az közös alap (amelyből az SDKError és az HTTPValidationError örököl).
A felhőszolgáltatói kliensek csatlakoztak ehhez a névtérhez. Az 1.x-ben ezek a mistralai csomaggal együtt kerültek kiszállításra, de külön modulokban, mint a mistralai_azure és a 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 és újabb
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")
Három további változás történt a 2.0-ban, amely érinthet téged. A minimális verzió mostantól a Python 3.10 (az 1.9.11 még elfogadta a Python 3.9-et). 42 típust neveztek át egy szabályos konvenció szerint: {Ige}{Entitás}Request a kéréseknek és {Ige}{Entitás}Response a válaszoknak. A gyakori kódban látható egyetlen átnevezés a Tools, amely ConversationRequestTool lett. Végül az enumerációk mostantól elfogadják az ismeretlen értékeket, így az API által hozzáadott új érték már nem okoz összeomlást egy régebbi SDK-verzióban.
A 2.x-től a 3.x-ig: httpx2 és beépített eszközök
A 2026. szeptember 28-án megjelent 3.0-s verzió sem az importokat, sem a gyakori metódusokat nem változtatja meg. Három pont azonban tönkretehet egy projektet:
- A HTTP kliens
httpx2lesz. Ha saját klienst adsz át az SDK-nak (példáulclient=vagyasync_client=paraméterek, proxy vagy közös fejlécek esetén), annakhttpx2kliensnek kell lennie; a nyers transzport kérések, válaszok és hibák ishttpx2típusok. - A beépített eszközök kikerülnek a chat kiegészítésekből. A
client.chat.completeés aclient.agents.completemár nem fogadja el aweb_search,web_search_premiuméscode_interpretereszközöket: ezeket a Conversations API-n (client.beta.conversations) vagy egy ágenssel keresztül kell használni. A Mistral dokumentációja elmagyarázza, miért: a chat kiegészítés válaszai nem hordozhatják ezeket az eszközök által visszaadott hivatkozásokat. - Az
mcpésagentsextra csomagok mostantól az MCP 2.2-re támaszkodnak.
A 3.0 verzió hozzáadja a szolgáltatásfiók tokenes hitelesítést is: a Mistral() beolvassa a tokent a MISTRAL_SA_TOKEN_PATH környezeti változó által megadott fájlból.
Mi a helyzet a TypeScriptkel?
A régi JavaScript 0.x kliensről a TypeScript SDK 1.x-re való átállás szinte pontosan tükrözi a Python átmenetet. Az import alapértelmezett exportról named exportra változik, a konstruktor egy konfigurációs objektumot fogad, és a metódusok láncolttá válnak:
// 0.x (régi)
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 és újabb
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' }],
});
A streamelés a client.chatStream(...)-ról a client.chat.stream(...)-ra költözik, és akárcsak Pythonban, a tartalmat a chunk.data segítségével olvassuk ki:
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;
// a tartalom lehet töredékek listája is: csak szöveget írunk ki
if (typeof content === 'string') process.stdout.write(content);
}
A TypeScript 2.0 (2026. március 18.) megtartotta ezeket az importokat, de az SDK-t mostantól kizárólag ES modulokként teszik közzé: egy require('@mistralai/mistralai') hívás CommonJS-ben már nem működik. A futásidejű validáció átkerül a Zod v4-re, ami csak azokat a projekteket érinti, amelyek közvetlenül importálnak sémákat az SDK-ból. A felhő kliensek pedig külön csomagokba kerültek: @mistralai/mistralai-azure (MistralAzure) és @mistralai/mistralai-gcp (MistralGCP, korábban MistralGoogleCloud).
A migrálás végrehajtása
Egy valós projekten meghatározott sorrendben haladj, ne pedig a hibák megjelenésekor javítsd azokat. Kezd azzal, hogy az importok alapján azonosítod a kód generációját, majd frissítsd a csomagot (pip install --upgrade mistralai vagy npm install @mistralai/mistralai@latest): amíg a régi verzió van telepítve, vakon javítgatsz. Ezután haladj az alábbiak szerint:
- Keresd meg a régi importokat:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Cseréld le őket az ebben a leckében található hozzárendelések szerint, ne felejtsd el a hibákat, amelyek a
mistralai.client.errorsalá költöztek - Frissítsd a hívásokat: láncolt metódusok, többes számú
inputsaz embeddingshez,.dataa streamelő ciklusokban - Helyezd át a beépített eszközöket (
web_search,code_interpreter) a chat kiegészítésekből a Conversations API-ba
Végül teszteld le egyesével az összes használt végpontot: a chat, az embeddings és a streamelés mindegyikének megvannak a maga változásai, és egy projekt elindulása még nem garantálja, hogy mindhármat helyesen hívja meg.
Ha nem tudsz azonnal migrálni
Ezen verziók egyike sem kínál átmeneti módot vagy kompatibilitási aliasokat. Ha egy gyártási befagyasztás megakadályozza a migrálást, rögzítsd expliciten a verziót a függőségeid között; ellenkező esetben a következő telepítés a legfrissebb verziót húzza be, és tönkreteszi az alkalmazást:
# Python: maradj az 1.x-en
pip install "mistralai<2"
# Python: maradj a 2.x-en
pip install "mistralai>=2,<3"
# npm: maradj az 1.x-en
npm install @mistralai/mistralai@1
Kezeld ezt a rögzítést halasztásként: új funkciók csak az aktuális verzióban érkeznek.
Hivatalos források: 0.x → 1.0 migrációs útmutató · Python 2.0.0 kiadási jegyzetek · Python 3.0.0 kiadási jegyzetek · TypeScript 2.0.0 kiadási jegyzetek · Verziótörténet a PyPI-n · Websearch — beépített eszközök
Főbb megállapítások
- Azonosítsd a kód generációját az import alapján:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x és 3.x) - Az 1.0 (2024. aug.) bemutatta a
Mistralklienst, a láncolt metódusokat és a streamelés.dataszintjét - A 2.0 (2026. márc.) minden Python importot a
mistralai.clientalá, a hibákat amistralai.client.errorsalá helyezett, és felemelte a minimumot Python 3.10-re - A 3.0 (2026. szept.) átvált a
httpx2-re, és a Conversations API és az ágensek számára tartja fenn aweb_searchéscode_interpretereszközöket - TypeScriptben az import nem változott az 1.x óta, de a 2.0 csak az ES modulokat fogadja el