Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Migrera mellan versioner av Mistral SDK

Lektion 10 av 14 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Varför denna lektion är viktig
  2. Fyra generationer på två år
  3. Från 0.x till 1.x: klienten Mistral och kedjade metoder
  4. Från 1.x till 2.x: allt flyttas under mistralai.client
  5. Från 2.x till 3.x: httpx2 och inbyggda verktyg
  6. Hur ser det ut för TypeScript?
  7. Genomföra migrationen
  8. Om du inte kan migrera omedelbart
  9. 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 till process.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

GenerationPython (mistralai)TypeScript (@mistralai/mistralai)Särskiljande kodfunktion
0.xupp till 0.4.2 (juli 2024)upp till 0.5.0 (juni 2024)MistralClient, platta metoder: client.chat(...)
1.x1.0.0 (7 aug 2024) → 1.9.11 (okt 2025)från aug 2024from mistralai import Mistral, kedjade metoder: client.chat.complete(...)
2.x2.0.0 (10 mar 2026)2.0.0 (18 mar 2026)Python: from mistralai.client import Mistral; TypeScript: endast ES-moduler
3.x3.0.0 (28 sep 2026), 3.7.0 per 1 nov 20263.0 (okt 2026), 3.5.0 idagPython: 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.x1.x och senare
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 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 (parametrar client= eller async_client=, till exempel för en proxy eller gemensamma rubriker), måste det vara en httpx2-klient; råa transportförfrågningar, svar och fel är också httpx2-typer.
  • Inbyggda verktyg lämnar chat-completions. client.chat.complete och client.agents.complete accepterar inte längre verktygen web_search, web_search_premium och code_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 mcp och agents fö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:

  1. Sök efter gamla importer: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Ersätt dem enligt mappningarna i denna lektion, glöm inte felen som flyttas till mistralai.client.errors
  3. Uppdatera anrop: kedjade metoder, pluralformen inputs för inbäddningar, .data i streamingloopar
  4. 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 under mistralai.client.errors, och höjde minimikravet till Python 3.10
  • 3.0 (sep 2026) byter till httpx2 och reserverar web_search och code_interpreter för Conversations API och agenter
  • I TypeScript har importen inte ändrats sedan 1.x, men 2.0 accepterar endast ES-moduler