Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Migrering mellem Mistral SDK-versioner

Lektion 10 af 14 Opdateret 3. november 2026 Udvikler
På denne side
  1. Hvorfor denne lektion er vigtig
  2. Fire generationer på to år
  3. Fra 0.x til 1.x: Mistral-klienten og kædede metoder
  4. Fra 1.x til 2.x: alt flytter under mistralai.client
  5. Fra 2.x til 3.x: httpx2 og indbyggede værktøjer
  6. Hvad med TypeScript?
  7. Gennemførelse af migrationen
  8. Hvis du ikke kan migrere med det samme
  9. Vigtige pointer

Lektionen er omskrevet den 2. november 2026. Den tidligere version omtalte “overgangen fra V1 til V2”, hvilket faktisk var overgangen fra den forældede 0.x-klient til version 1.0 i august 2024. Siden da har Python SDK’et oplevet to store udgivelser mere: 2.0 i marts 2026 og 3.0 i september 2026. Denne lektion rekonstruerer hele historien baseret på officielle migrationsguider og udgivelsesnoter. Opdateret 3. november 2026: Rettet TypeScript-streaming-løkken, som tidligere sendte string | ContentChunk[]-indhold direkte til process.stdout.write, hvilket forårsagede fejl i streng tilstand.

Hvorfor denne lektion er vigtig

Du vil støde på dette materiale i to scenarier: enten genoptager du et projekt, der blev skrevet for nogen tid siden, og som nægter at starte efter en opdatering af afhængigheder, eller også følger du en online tutorial, hvis eksempler ikke længere fungerer. I begge tilfælde skal du stille det samme første spørgsmål: til hvilken SDK-generation er denne kode skrevet? Næsten altid afslører en enkelt linje svaret: import-sætningen.

Fire generationer på to år

GenerationPython (mistralai)TypeScript (@mistralai/mistralai)Kendetegnende kode-funktion
0.xop til 0.4.2 (juli 2024)op til 0.5.0 (juni 2024)MistralClient, flade metoder: client.chat(...)
1.x1.0.0 (7. aug. 2024) → 1.9.11 (okt. 2025)fra aug. 2024from mistralai import Mistral, kædede metoder: client.chat.complete(...)
2.x2.0.0 (10. mar. 2026)2.0.0 (18. mar. 2026)Python: from mistralai.client import Mistral; TypeScript: kun ES-moduler
3.x3.0.0 (28. sep. 2026), 3.7.0 pr. 1. nov. 20263.0 (okt. 2026), 3.5.0 i dagPython: httpx2 HTTP-klient

I TypeScript har importen import { Mistral } from '@mistralai/mistralai' ikke ændret sig siden 1.x. I Python har den ændret sig to gange: det er her, de fleste fejl opstår.

Fra 0.x til 1.x: Mistral-klienten og kædede metoder

Version 1.0 erstattede de to klienter, MistralClient (synkron) og MistralAsyncClient (asynkron), med en enkelt klasse, Mistral. Den erstattede også flade metoder med navnerum: chat grupperer samtaleoperationer, og du går et niveau dybere for at nå complete(). Beskeder, der tidligere blev skrevet ved hjælp af klassen ChatMessage, skrives nu som ordbøger eller ved hjælp af klasserne UserMessage, SystemMessage, AssistantMessage og ToolMessage.

# 0.x (forældet)
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ølger den samme logik, men med en fælde, der ofte koster en halv times fejlfinding: det modtagne fragment er nu indpakket, og dets indhold læses gennem et mellemliggende .data-niveau. Forældet 0.x-kode kopieret som-is vil udløse en AttributeError ved det første fragment.

# 0.x
for chunk in client.chat_stream(model=..., messages=...):
    print(chunk.choices[0].delta.content)

# 1.x og nyere
for chunk in client.chat.stream(model=..., messages=...):
    print(chunk.data.choices[0].delta.content)

Den officielle 1.0-guide indeholder den fulde tabel. De hyppigste mapping’er er:

0.x1.x og nyere
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 og dens metoder_async-varianter: client.chat.complete_async, client.chat.stream_async…

Fra 1.x til 2.x: alt flytter under mistralai.client

Version 2.0 rørte ikke ved metodenavne: client.chat.complete forbliver client.chat.complete. Den ændrede adressen på alt andet. SDK’et blev til et navnerumspakke (PEP 420), og alle imports migrerede fra mistralai til mistralai.client:

# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError

# 2.x og nyere
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Bemærk den tredje linje: fejlklasser lever ikke længere blandt modeller, men i mistralai.client.errors, med MistralError som fælles baseklasse (hvorfra SDKError og HTTPValidationError arver).

Cloud-udbyderklienter sluttede sig til samme navnerum. I 1.x blev de leveret med pakken mistralai, men i separate moduler, mistralai_azure og 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 og nyere
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 andre ændringer i 2.0 kan påvirke dig. Minimumsversionen er nu Python 3.10 (1.9.11 accepterede Python 3.9). 42 typer blev omdøbt efter en regelmæssig konvention: {Verb}{Entity}Request for anmodninger og {Verb}{Entity}Response for svar. Den eneste omdøbning, der er synlig i almindelig kode, er Tools, som blev til ConversationRequestTool. Endelig accepterer enumerationer nu ukendte værdier, så en ny værdi tilføjet af API’et ikke længere får en ældre SDK-version til at crashe.

Fra 2.x til 3.x: httpx2 og indbyggede værktøjer

Version 3.0, udgivet den 28. september 2026, ændrer hverken imports eller almindelige metoder. Tre punkter kan dog bryde et projekt:

  • HTTP-klienten bliver httpx2. Hvis du sender din egen klient til SDK’et (parametrene client= eller async_client=, f.eks. til en proxy eller fælles headers), skal det være en httpx2-klient; rå transportanmodninger, svar og fejl er også httpx2-typer.
  • Indbyggede værktøjer forlader chat-fuldførelser. client.chat.complete og client.agents.complete accepterer ikke længere værktøjerne web_search, web_search_premium og code_interpreter: de bruges via Conversations API (client.beta.conversations) eller en agent. Mistral-dokumentationen forklarer hvorfor: svar fra chat-fuldførelser kan ikke bære de referencer, disse værktøjer returnerer.
  • Ekstra-pakkerne mcp og agents afhænger nu af MCP 2.2.

Version 3.0 tilføjer også godkendelse via servicekonto-token: Mistral() læser tokenet fra filen specificeret af miljøvariablen MISTRAL_SA_TOKEN_PATH.

Hvad med TypeScript?

Overgangen fra den forældede JavaScript 0.x-klient til TypeScript SDK 1.x spejler Python-overgangen næsten nøjagtigt. Importen ændres fra en standard-eksport til en navngiven eksport, konstruktøren tager et konfigurationsobjekt, og metoder bliver kædede:

// 0.x (forældet)
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 og nyere
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 flytter fra client.chatStream(...) til client.chat.stream(...), og som i Python læses indholdet 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 også være en liste over fragmenter: vi skriver kun tekst
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (18. marts 2026) beholdt disse imports, men SDK’et udgives nu kun som ES-moduler: et require('@mistralai/mistralai') i CommonJS fungerer ikke længere. Runtime-validering flytter til Zod v4, hvilket kun påvirker projekter, der importerer skemaer direkte fra SDK’et. Og cloud-klienter lever i separate pakker: @mistralai/mistralai-azure (MistralAzure) og @mistralai/mistralai-gcp (MistralGCP, tidligere MistralGoogleCloud).

Gennemførelse af migrationen

På et rigtigt projekt skal du procedere i en defineret rækkefølge i stedet for at rette fejl, efterhånden som de dukker op. Start med at identificere kodegenerationen via dens imports, og opdater derefter pakken (pip install --upgrade mistralai eller npm install @mistralai/mistralai@latest): så længe den gamle version er installeret, retter du blindt. Fortsæt derefter som følger:

  1. Søg efter gamle imports: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Erstat dem i henhold til mapping’erne i denne lektion; glem ikke fejl, som flytter til mistralai.client.errors
  3. Opdater kald: kædede metoder, flertalsformen inputs til embeddings, .data i streaming-løkker
  4. Flyt indbyggede værktøjer (web_search, code_interpreter) fra chat-fuldførelser til Conversations API

Test til sidst hvert endpoint, du bruger, ét ad gangen: chat, embeddings og streaming har hver deres ændringer, og et projekt, der starter, kalder ikke nødvendigvis alle tre korrekt.

Hvis du ikke kan migrere med det samme

Ingen af disse versioner tilbyder en overgangstilstand eller kompatibilitetsaliasser. Hvis en produktionsfrys forhindrer dig i at migrere, skal du eksplicit fastlåse versionen i dine afhængigheder; ellers vil den næste installation hente den seneste version og bryde applikationen:

# Python: bliv på 1.x
pip install "mistralai<2"

# Python: bliv på 2.x
pip install "mistralai>=2,<3"

# npm: bliv på 1.x
npm install @mistralai/mistralai@1

Behandl denne fastlåsning som en udsættelse: nye funktioner ankommer kun i den aktuelle version.

Officielle kilder: 0.x → 1.0 migrationsguide · Python 2.0.0 udgivelsesnoter · Python 3.0.0 udgivelsesnoter · TypeScript 2.0.0 udgivelsesnoter · Versionshistorik på PyPI · Websearch — indbyggede værktøjer

Vigtige pointer

  • Identificér kodegenerationen ved dens import: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x og 3.x)
  • 1.0 (aug. 2024) introducerede Mistral-klienten, kædede metoder og streaming .data-niveauet
  • 2.0 (mar. 2026) flyttede alle Python-imports under mistralai.client, fejl under mistralai.client.errors og hævede minimumskravet til Python 3.10
  • 3.0 (sep. 2026) skifter til httpx2 og reserverer web_search og code_interpreter til Conversations API og agenter
  • I TypeScript har importen ikke ændret sig siden 1.x, men 2.0 accepterer kun ES-moduler