Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Migrálás a Mistral SDK verziói között

10. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Miért fontos ez a lecke
  2. Négy generáció két év alatt
  3. A 0.x-től az 1.x-ig: a Mistral kliens és a láncolt metódusok
  4. Az 1.x-től a 2.x-ig: minden a mistralai.client alá kerül
  5. A 2.x-től a 3.x-ig: httpx2 és beépített eszközök
  6. Mi a helyzet a TypeScriptkel?
  7. A migrálás végrehajtása
  8. Ha nem tudsz azonnal migrálni
  9. 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 a process.stdout.write metó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.x0.4.2-ig (2024. július)0.5.0-ig (2024. június)MistralClient, lapos metódusok: client.chat(...)
1.x1.0.0 (2024. aug. 7.) → 1.9.11 (2025. okt.)2024. augusztustólfrom mistralai import Mistral, láncolt metódusok: client.chat.complete(...)
2.x2.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.x3.0.0 (2026. szept. 28.), 3.7.0 2026. nov. 1-jétől3.0 (2026. okt.), ma 3.5.0Python: 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.x1.x és újabb
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 é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 httpx2 lesz. Ha saját klienst adsz át az SDK-nak (például client= vagy async_client= paraméterek, proxy vagy közös fejlécek esetén), annak httpx2 kliensnek kell lennie; a nyers transzport kérések, válaszok és hibák is httpx2 típusok.
  • A beépített eszközök kikerülnek a chat kiegészítésekből. A client.chat.complete és a client.agents.complete már nem fogadja el a web_search, web_search_premium és code_interpreter eszkö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 és agents extra 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:

  1. Keresd meg a régi importokat: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. 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.errors alá költöztek
  3. Frissítsd a hívásokat: láncolt metódusok, többes számú inputs az embeddingshez, .data a streamelő ciklusokban
  4. 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 Mistral klienst, a láncolt metódusokat és a streamelés .data szintjét
  • A 2.0 (2026. márc.) minden Python importot a mistralai.client alá, a hibákat a mistralai.client.errors alá 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 a web_search és code_interpreter eszközöket
  • TypeScriptben az import nem változott az 1.x óta, de a 2.0 csak az ES modulokat fogadja el