Migreren tussen Mistral SDK-versies
Op deze pagina
- Waarom deze les belangrijk is
- Vier generaties in twee jaar
- Van 0.x naar 1.x: de Mistral-client en gekoppelde methoden
- Van 1.x naar 2.x: alles verhuist naar mistralai.client
- Van 2.x naar 3.x: httpx2 en ingebouwde tools
- Hoe zit het met TypeScript?
- De migratie uitvoeren
- Als u niet direct kunt migreren
- Belangrijkste punten
Les herschreven op 2 november 2026. De vorige versie verwees naar “de overstap van V1 naar V2”, wat eigenlijk de overgang was van de verouderde 0.x-client naar versie 1.0 in augustus 2024. Sindsdien heeft de Python SDK nog twee grote releases gezien: 2.0 in maart 2026 en 3.0 in september 2026. Deze les reconstrueert de volledige geschiedenis op basis van officiële migratiegidsen en release-opmerkingen. Bijgewerkt op 3 november 2026: De TypeScript-streaminglus is gecorrigeerd; eerder werd
string | ContentChunk[]-inhoud direct aanprocess.stdout.writedoorgegeven, wat fouten veroorzaakte in de strikte modus.
Waarom deze les belangrijk is
U krijgt met deze stof te maken in twee scenario’s: u hervat een project dat enige tijd geleden is geschreven en dat weigert te starten na een update van afhankelijkheden, of u volgt een online tutorial waarvan de voorbeelden niet meer werken. Stel in beide gevallen eerst dezelfde vraag: voor welke SDK-generatie is deze code geschreven? Bijna altijd geeft één regel u het antwoord: de import-instructie.
Vier generaties in twee jaar
| Generatie | Python (mistralai) | TypeScript (@mistralai/mistralai) | Onderscheidend codekenmerk |
|---|---|---|---|
| 0.x | tot 0.4.2 (juli 2024) | tot 0.5.0 (juni 2024) | MistralClient, vlakke methoden: client.chat(...) |
| 1.x | 1.0.0 (7 aug 2024) → 1.9.11 (okt 2025) | vanaf aug 2024 | from mistralai import Mistral, gekoppelde methoden: client.chat.complete(...) |
| 2.x | 2.0.0 (10 mrt 2026) | 2.0.0 (18 mrt 2026) | Python: from mistralai.client import Mistral; TypeScript: alleen ES-modules |
| 3.x | 3.0.0 (28 sep 2026), 3.7.0 per 1 nov 2026 | 3.0 (okt 2026), 3.5.0 vandaag | Python: httpx2 HTTP-client |
In TypeScript is de import import { Mistral } from '@mistralai/mistralai' niet veranderd sinds 1.x. In Python is deze twee keer gewijzigd: daar treden de meeste storingen op.
Van 0.x naar 1.x: de Mistral-client en gekoppelde methoden
Versie 1.0 verving de twee clients, MistralClient (synchroon) en MistralAsyncClient (asynchroon), door één enkele klasse, Mistral. Het verving ook vlakke methoden door namespaces: chat groepeert conversatiebewerkingen en u gaat één niveau dieper om bij complete() te komen. Berichten, die eerder werden geschreven met de ChatMessage-klasse, worden nu geschreven als woordenboeken of met behulp van de klassen UserMessage, SystemMessage, AssistantMessage en ToolMessage.
# 0.x (verouderd)
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"}],
)
Streaming volgt dezelfde logica, met een valkuil die vaak een half uur debuggen kost: het ontvangen fragment is nu ingepakt en de inhoud wordt gelezen via een tussenliggend .data-niveau. Verouderde 0.x-code die als zodanig wordt gekopieerd, leidt bij het eerste fragment tot een AttributeError.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x en later
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
De officiële 1.0-gids bevat de volledige tabel. De meest voorkomende toewijzingen zijn:
| 0.x | 1.x en later |
|---|---|
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 en zijn methoden | _async-varianten: client.chat.complete_async, client.chat.stream_async… |
Van 1.x naar 2.x: alles verhuist naar mistralai.client
Versie 2.0 heeft de methodenamen niet gewijzigd: client.chat.complete blijft client.chat.complete. Het adres van al het andere is wel veranderd. De SDK werd een namespace-pakket (PEP 420) en alle imports verhuisden van mistralai naar mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x en later
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Let op de derde regel: foutklassen bevinden zich niet langer tussen de modellen, maar in mistralai.client.errors, met MistralError als gemeenschappelijke basis (waarvan SDKError en HTTPValidationError erven).
Clients voor cloudproviders sloten zich aan bij dezelfde namespace. In 1.x werden ze meegeleverd met het mistralai-pakket, maar in aparte modules, mistralai_azure en 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 en later
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")
Drie andere wijzigingen in 2.0 kunnen u beïnvloeden. De minimumversie is nu Python 3.10 (1.9.11 accepteerde Python 3.9). 42 typen zijn hernoemd volgens een vaste conventie: {Werkwoord}{Entiteit}Request voor verzoeken en {Werkwoord}{Entiteit}Response voor antwoorden. De enige hernoeming die zichtbaar is in gewone code is Tools, dat ConversationRequestTool is geworden. Tot slot accepteren enumeraties nu onbekende waarden, zodat een nieuwe waarde die door de API wordt toegevoegd, een oudere SDK-versie niet meer laat crashen.
Van 2.x naar 3.x: httpx2 en ingebouwde tools
Versie 3.0, uitgebracht op 28 september 2026, wijzigt noch imports noch veelgebruikte methoden. Drie punten kunnen echter een project breken:
- De HTTP-client wordt
httpx2. Als u uw eigen client aan de SDK doorgeeft (parametersclient=ofasync_client=, bijvoorbeeld voor een proxy of gemeenschappelijke headers), moet dit eenhttpx2-client zijn; ruwe transportverzoeken, -antwoorden en -fouten zijn ookhttpx2-typen. - Ingebouwde tools verdwijnen uit chat-completions.
client.chat.completeenclient.agents.completeaccepteren de toolsweb_search,web_search_premiumencode_interpreterniet langer: deze worden gebruikt via de Conversations API (client.beta.conversations) of een agent. De Mistral-documentatie legt uit waarom: antwoorden op chat-completions kunnen de referenties die deze tools retourneren niet dragen. - De extra’s
mcpenagentsvertrouwen nu op MCP 2.2.
Versie 3.0 voegt ook authenticatie via serviceaccount-tokens toe: Mistral() leest het token uit het bestand dat is opgegeven door de omgevingsvariabele MISTRAL_SA_TOKEN_PATH.
Hoe zit het met TypeScript?
De overstap van de verouderde JavaScript 0.x-client naar de TypeScript SDK 1.x weerspiegelt bijna exact de Python-overgang. De import verandert van een standaardexport naar een benoemde export, de constructor accepteert een configuratieobject en methoden worden gekoppeld:
// 0.x (verouderd)
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 en later
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' }],
});
Streaming verhuist van client.chatStream(...) naar client.chat.stream(...), en net als in Python wordt de inhoud gelezen via 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;
// content kan ook een lijst fragmenten zijn: we schrijven alleen tekst
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18 maart 2026) behield deze imports, maar de SDK wordt nu uitsluitend gepubliceerd als ES-modules: een require('@mistralai/mistralai') in CommonJS werkt niet meer. Runtime-validatie verhuist naar Zod v4, wat alleen projecten beïnvloedt die schema’s rechtstreeks uit de SDK importeren. En cloudclients bevinden zich in aparte pakketten: @mistralai/mistralai-azure (MistralAzure) en @mistralai/mistralai-gcp (MistralGCP, voorheen MistralGoogleCloud).
De migratie uitvoeren
Werk op een echt project in een vaste volgorde in plaats van fouten op te lossen zodra ze verschijnen. Begin met het identificeren van de codegeneratie via de imports, update vervolgens het pakket (pip install --upgrade mistralai of npm install @mistralai/mistralai@latest): zolang de oude versie is geïnstalleerd, repareert u blindelings. Ga vervolgens als volgt te werk:
- Zoek naar oude imports:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Vervang ze volgens de toewijzingen in deze les, vergeet de fouten niet, die verhuizen naar
mistralai.client.errors - Update aanroepen: gekoppelde methoden, meervoudige
inputsvoor embeddings,.datain streaming-lussen - Verplaats ingebouwde tools (
web_search,code_interpreter) van chat-completions naar de Conversations API
Test tot slot elk eindpunt dat u gebruikt, één voor één: chat, embeddings en streaming hebben elk hun eigen wijzigingen en een project dat start, roept niet noodzakelijkerwijs alle drie correct aan.
Als u niet direct kunt migreren
Geen van deze versies biedt een overgangsmodus of compatibiliteitsaliassen. Als een productievries prevents u om te migreren, pin de versie dan expliciet in uw afhankelijkheden; anders haalt de volgende installatie de nieuwste versie op en breekt het de applicatie:
# Python: blijf op 1.x
pip install "mistralai<2"
# Python: blijf op 2.x
pip install "mistralai>=2,<3"
# npm: blijf op 1.x
npm install @mistralai/mistralai@1
Beschouw deze pinning als uitstel: nieuwe functies komen alleen beschikbaar in de huidige versie.
Officiële bronnen: 0.x → 1.0 migratiegids · Python 2.0.0 release-opmerkingen · Python 3.0.0 release-opmerkingen · TypeScript 2.0.0 release-opmerkingen · Versiegeschiedenis op PyPI · Websearch — ingebouwde tools
Belangrijkste punten
- Identificeer codegeneratie aan de hand van de import:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x en 3.x) - 1.0 (aug 2024) introduceerde de
Mistral-client, gekoppelde methoden en het streaming.data-niveau - 2.0 (mrt 2026) verplaatste alle Python-imports naar
mistralai.client, fouten naarmistralai.client.errorsen verhoogde het minimum naar Python 3.10 - 3.0 (sep 2026) schakelt over op
httpx2en reserveertweb_searchencode_interpretervoor de Conversations API en agents - In TypeScript is de import niet veranderd sinds 1.x, maar 2.0 accepteert alleen ES-modules