Migrera mellan versioner av Mistral SDK
På denna sida
- Varför denna lektion är viktig
- Fyra generationer på två år
- Från 0.x till 1.x: klienten Mistral och kedjade metoder
- Från 1.x till 2.x: allt flyttas under mistralai.client
- Från 2.x till 3.x: httpx2 och inbyggda verktyg
- Hur ser det ut för TypeScript?
- Genomföra migrationen
- Om du inte kan migrera omedelbart
- Viktiga punkter
Lektionen omskriven den 2 november 2026. Den tidigare versionen hänvisade till “övergången från V1 till V2”, vilket egentligen var övergången från den äldre 0.x-klienten till version 1.0 i augusti 2024. Sedan dess har Python SDK sett två ytterligare huvudsläpp: 2.0 i mars 2026 och 3.0 i september 2026. Denna lektion rekonstruerar hela historiken baserat på officiella migrationsguider och versionsanteckningar. Uppdaterad 3 november 2026: Åtgärdade TypeScript-streamingloopen, som tidigare skickade innehåll av typen
string | ContentChunk[]direkt tillprocess.stdout.write, vilket orsakade fel i strikt läge.
Varför denna lektion är viktig
Du kommer att stöta på detta material i två scenarier: antingen återupptar du ett projekt som skrevs för en tid sedan och som vägrar starta efter en beroendeuppdatering, eller så följer du en onlinehandledning vars exempel inte längre fungerar. I båda fallen ska du ställa samma första fråga: för vilken SDK-generation skrevs denna kod? Nästan alltid avslöjar en enda rad svaret: import-satsen.
Fyra generationer på två år
| Generation | Python (mistralai) | TypeScript (@mistralai/mistralai) | Särskiljande kodfunktion |
|---|---|---|---|
| 0.x | upp till 0.4.2 (juli 2024) | upp till 0.5.0 (juni 2024) | MistralClient, platta metoder: client.chat(...) |
| 1.x | 1.0.0 (7 aug 2024) → 1.9.11 (okt 2025) | från aug 2024 | from mistralai import Mistral, kedjade metoder: client.chat.complete(...) |
| 2.x | 2.0.0 (10 mar 2026) | 2.0.0 (18 mar 2026) | Python: from mistralai.client import Mistral; TypeScript: endast ES-moduler |
| 3.x | 3.0.0 (28 sep 2026), 3.7.0 per 1 nov 2026 | 3.0 (okt 2026), 3.5.0 idag | Python: HTTP-klienten httpx2 |
I TypeScript har importen import { Mistral } from '@mistralai/mistralai' inte ändrats sedan 1.x. I Python har den ändrats två gånger: det är där de flesta fel uppstår.
Från 0.x till 1.x: klienten Mistral och kedjade metoder
Version 1.0 ersatte de två klienterna, MistralClient (synkron) och MistralAsyncClient (asynkron), med en enda klass, Mistral. Den ersatte också platta metoder med namnrymder: chat grupperar konversationsoperationer, och du går ett steg djupare för att nå complete(). Meddelanden, som tidigare skrevs med klassen ChatMessage, skrivs nu som ordlistor (dictionaries) eller med klasserna UserMessage, SystemMessage, AssistantMessage och ToolMessage.
# 0.x (äldre)
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 följer samma logik, med en fälla som ofta kostar en halvtimmes felsökning: det mottagna fragmentet är nu inslaget, och dess innehåll läses via en mellanliggande .data-nivå. Äldre 0.x-kod som kopieras rakt av ger ett AttributeError vid det första fragmentet.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x och senare
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Den officiella guiden för 1.0 innehåller hela tabellen. De vanligaste mappningarna är:
| 0.x | 1.x och senare |
|---|---|
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 och dess metoder | _async-varianter: client.chat.complete_async, client.chat.stream_async… |
Från 1.x till 2.x: allt flyttas under mistralai.client
Version 2.0 rörde inte vid metodnamnen: client.chat.complete förblir client.chat.complete. Den ändrade adressen för allt annat. SDK:t blev ett namnrymdspaket (PEP 420), och alla importer migrerade från mistralai till mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x och senare
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Observera den tredje raden: felklasser finns inte längre bland modeller utan i mistralai.client.errors, med MistralError som gemensam bas (som SDKError och HTTPValidationError ärver ifrån).
Klienter för molnleverantörer anslöt sig till samma namnrymd. I 1.x levererades de med paketet mistralai men i separata moduler, mistralai_azure och 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 och senare
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")
Tre andra ändringar i 2.0 kan påverka dig. Minimiversionen är nu Python 3.10 (1.9.11 accepterade Python 3.9). 42 typer bytte namn enligt en regelbunden konvention: {Verb}{Entity}Request för förfrågningar och {Verb}{Entity}Response för svar. Den enda namnändringen som syns i vanlig kod är Tools, som blev ConversationRequestTool. Slutligen accepterar uppräkningar (enumerations) nu okända värden, så ett nytt värde som läggs till av API:t kraschar inte längre en äldre SDK-version.
Från 2.x till 3.x: httpx2 och inbyggda verktyg
Version 3.0, släppt den 28 september 2026, ändrar varken importer eller vanliga metoder. Tre punkter kan dock krossa ett projekt:
- HTTP-klienten blir
httpx2. Om du skickar din egen klient till SDK:t (parametrarclient=ellerasync_client=, till exempel för en proxy eller gemensamma rubriker), måste det vara enhttpx2-klient; råa transportförfrågningar, svar och fel är ocksåhttpx2-typer. - Inbyggda verktyg lämnar chat-completions.
client.chat.completeochclient.agents.completeaccepterar inte längre verktygenweb_search,web_search_premiumochcode_interpreter: de används via Conversations API (client.beta.conversations) eller en agent. Mistral-dokumentationen förklarar varför: svar från chat-completion kan inte bära de referenser som dessa verktyg returnerar. - Tilläggen
mcpochagentsförlitar sig nu på MCP 2.2.
Version 3.0 lägger också till autentisering med tjänstekontotoken: Mistral() läser token från filen som anges av miljövariabeln MISTRAL_SA_TOKEN_PATH.
Hur ser det ut för TypeScript?
Övergången från den äldre JavaScript 0.x-klienten till TypeScript SDK 1.x speglar Python-övergången nästan exakt. Importen ändras från en standardexport till en namngiven export, konstruktorn tar ett konfigurationsobjekt och metoderna blir kedjade:
// 0.x (äldre)
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 och senare
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 flyttas från client.chatStream(...) till client.chat.stream(...), och liksom i Python läses innehåll 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 också vara en lista med fragment: vi skriver bara text
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18 mars 2026) behöll dessa importer, men SDK:t publiceras nu endast som ES-moduler: ett require('@mistralai/mistralai') i CommonJS fungerar inte längre. Körningsvalidering flyttas till Zod v4, vilket endast påverkar projekt som importerar scheman direkt från SDK:t. Molnklienter finns i separata paket: @mistralai/mistralai-azure (MistralAzure) och @mistralai/mistralai-gcp (MistralGCP, tidigare MistralGoogleCloud).
Genomföra migrationen
På ett riktigt projekt ska du arbeta i en definierad ordning snarare än att fixa fel när de dyker upp. Börja med att identifiera kodgenerationen via dess importer, uppdatera sedan paketet (pip install --upgrade mistralai eller npm install @mistralai/mistralai@latest): så länge den gamla versionen är installerad fixar du i blindo. Fortsätt sedan enligt följande:
- Sök efter gamla importer:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Ersätt dem enligt mappningarna i denna lektion, glöm inte felen som flyttas till
mistralai.client.errors - Uppdatera anrop: kedjade metoder, pluralformen
inputsför inbäddningar,.datai streamingloopar - Flytta inbyggda verktyg (
web_search,code_interpreter) från chat-completions till Conversations API
Testa slutligen varje slutpunkt du använder, en i taget: chat, inbäddningar och streaming har alla sina egna ändringar, och ett projekt som startar anropar inte nödvändigtvis alla tre korrekt.
Om du inte kan migrera omedelbart
Ingen av dessa versioner erbjuder ett övergångsläge eller kompatibilitetsalias. Om en produktionsfrys hindrar dig från att migrera, lås explicit versionen i dina beroenden; annars hämtar nästa installation den senaste versionen och krossar applikationen:
# Python: stanna på 1.x
pip install "mistralai<2"
# Python: stanna på 2.x
pip install "mistralai>=2,<3"
# npm: stanna på 1.x
npm install @mistralai/mistralai@1
Behandla denna låsning som en respit: nya funktioner kommer endast i den aktuella versionen.
Officiella källor: Migrationsguide 0.x → 1.0 · Versionsanteckningar Python 2.0.0 · Versionsanteckningar Python 3.0.0 · Versionsanteckningar TypeScript 2.0.0 · Versionshistorik på PyPI · Websearch — inbyggda verktyg
Viktiga punkter
- Identifiera kodgenerationen via dess import:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x och 3.x) - 1.0 (aug 2024) introducerade klienten
Mistral, kedjade metoder och.data-nivån för streaming - 2.0 (mar 2026) flyttade alla Python-importer under
mistralai.client, fel undermistralai.client.errors, och höjde minimikravet till Python 3.10 - 3.0 (sep 2026) byter till
httpx2och reserverarweb_searchochcode_interpreterför Conversations API och agenter - I TypeScript har importen inte ändrats sedan 1.x, men 2.0 accepterar endast ES-moduler