Migrering mellem Mistral SDK-versioner
På denne side
- Hvorfor denne lektion er vigtig
- Fire generationer på to år
- Fra 0.x til 1.x: Mistral-klienten og kædede metoder
- Fra 1.x til 2.x: alt flytter under mistralai.client
- Fra 2.x til 3.x: httpx2 og indbyggede værktøjer
- Hvad med TypeScript?
- Gennemførelse af migrationen
- Hvis du ikke kan migrere med det samme
- 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 tilprocess.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
| Generation | Python (mistralai) | TypeScript (@mistralai/mistralai) | Kendetegnende kode-funktion |
|---|---|---|---|
| 0.x | op til 0.4.2 (juli 2024) | op til 0.5.0 (juni 2024) | MistralClient, flade metoder: client.chat(...) |
| 1.x | 1.0.0 (7. aug. 2024) → 1.9.11 (okt. 2025) | fra aug. 2024 | from mistralai import Mistral, kædede 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: kun ES-moduler |
| 3.x | 3.0.0 (28. sep. 2026), 3.7.0 pr. 1. nov. 2026 | 3.0 (okt. 2026), 3.5.0 i dag | Python: 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.x | 1.x og nyere |
|---|---|
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 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 (parametreneclient=ellerasync_client=, f.eks. til en proxy eller fælles headers), skal det være enhttpx2-klient; rå transportanmodninger, svar og fejl er ogsåhttpx2-typer. - Indbyggede værktøjer forlader chat-fuldførelser.
client.chat.completeogclient.agents.completeaccepterer ikke længere værktøjerneweb_search,web_search_premiumogcode_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
mcpogagentsafhæ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:
- Søg efter gamle imports:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Erstat dem i henhold til mapping’erne i denne lektion; glem ikke fejl, som flytter til
mistralai.client.errors - Opdater kald: kædede metoder, flertalsformen
inputstil embeddings,.datai streaming-løkker - 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 undermistralai.client.errorsog hævede minimumskravet til Python 3.10 - 3.0 (sep. 2026) skifter til
httpx2og reservererweb_searchogcode_interpretertil Conversations API og agenter - I TypeScript har importen ikke ændret sig siden 1.x, men 2.0 accepterer kun ES-moduler