Migration zwischen Mistral SDK-Versionen

Lektion neu geschrieben am 2. November 2026. Die vorherige Version bezog sich auf den Wechsel von V1 zu V2, was tatsächlich den Übergang vom Legacy-Client 0.x auf Version 1.0 im August 2024 bezeichnet. Seitdem hat das Python SDK zwei weitere Hauptversionen erhalten: 2.0 im März 2026 und 3.0 im September 2026. Diese Lektion rekonstruiert die vollständige Historie basierend auf offiziellen Migrationsleitfäden und Release-Notes. Aktualisiert am 3. November 2026: Der TypeScript-Streaming-Loop wurde korrigiert, der zuvor string | ContentChunk[]-Inhalte direkt an process.stdout.write übergeben hat, was zu Fehlern im strikten Modus führte.

Warum diese Lektion wichtig ist

Sie werden auf dieses Material in zwei Szenarien stoßen: Sie setzen ein vor einiger Zeit geschriebenes Projekt fort, das nach einem Abhängigkeits-Update nicht mehr startet, oder Sie folgen einem Online-Tutorial, dessen Beispiele nicht mehr funktionieren. In beiden Fällen stellen Sie dieselbe erste Frage: Für welche SDK-Generation wurde dieser Code geschrieben? Fast immer verrät eine einzige Zeile die Antwort: die Import-Anweisung.

Vier Generationen in zwei Jahren

In TypeScript hat sich der Import import { Mistral } from '@mistralai/mistralai' seit 1.x nicht geändert. In Python hat er sich zweimal geändert: Dort liegen die meisten Unterbrechungen.

Von 0.x zu 1.x: Der Mistral-Client und verkettete Methoden

Version 1.0 ersetzte die beiden Clients, MistralClient (synchron) und MistralAsyncClient (asynchron), durch eine einzige Klasse, Mistral. Sie ersetzte zudem flache Methoden durch Namespaces: chat gruppiert Gesprächsoperationen, und Sie gehen eine Ebene tiefer, um complete() zu erreichen. Nachrichten, die zuvor mit der ChatMessage-Klasse geschrieben wurden, werden nun als Wörterbücher oder mit den Klassen UserMessage, SystemMessage, AssistantMessage und ToolMessage geschrieben.

# 0.x (Legacy)
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 folgt derselben Logik, mit einer Falle, die oft eine halbe Stunde Debugging kostet: Der empfangene Fragment ist nun eingewickelt, und sein Inhalt wird über eine Zwischenstufe .data gelesen. Legacy-Code 0.x, der unverändert kopiert wird, wirft bei dem ersten Fragment eine AttributeError.

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

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

Der offizielle 1.0-Leitfaden bietet die vollständige Tabelle. Die häufigsten Zuordnungen sind:

Von 1.x zu 2.x: Alles bewegt sich unter mistralai.client

Version 2.0 berührte keine Methoden-Namen: client.chat.complete bleibt client.chat.complete. Sie änderte die Adresse von allem anderen. Das SDK wurde zu einem Namespace-Package (PEP 420), und alle Imports migrierten von mistralai zu mistralai.client:

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

# 2.x und später
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Beachten Sie die dritte Zeile: Fehlerklassen leben nicht mehr unter Modellen, sondern in mistralai.client.errors, mit MistralError als gemeinsamer Basis (von der SDKError und HTTPValidationError erben).

Cloud-Provider-Clients schlossen sich demselben Namespace an. In 1.x wurden sie mit dem mistralai-Paket ausgeliefert, aber in separaten Modulen, mistralai_azure und 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 und später
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")

Drei weitere Änderungen in 2.0 können Sie betreffen. Die Mindestversion ist nun Python 3.10 (1.9.11 akzeptierte Python 3.9). 42 Typen wurden gemäß einer regelmäßigen Konvention umbenannt: {Verb}{Entity}Request für Anfragen und {Verb}{Entity}Response für Antworten. Die einzige Umbenennung, die im allgemeinen Code sichtbar ist, ist Tools, die zu ConversationRequestTool wurde. Schließlich akzeptieren Aufzählungen nun unbekannte Werte, sodass ein neuer Wert, der von der API hinzugefügt wurde, eine ältere SDK-Version nicht abstürzt.

Von 2.x zu 3.x: httpx2 und integrierte Tools

Version 3.0, veröffentlicht am 28. September 2026, ändert weder Imports noch gängige Methoden. Dennoch können drei Punkte ein Projekt unterbrechen:

• Der HTTP-Client wird zu httpx2. Wenn Sie Ihren eigenen Client an das SDK übergeben (Parameter client= oder async_client=, beispielsweise für einen Proxy oder gemeinsame Header), muss es sich um einen httpx2-Client handeln; rohe Transport-Anfragen, -Antworten und -Fehler sind ebenfalls httpx2-Typen.
• Integrierte Tools verlassen Chat-Vervollständigungen. client.chat.complete und client.agents.complete akzeptieren nicht mehr die Tools web_search, web_search_premium und code_interpreter: Sie werden über die Conversations-API (client.beta.conversations) oder einen Agenten verwendet. Die Mistral-Dokumentation erklärt, warum: Chat-Vervollständigungs-Antworten können die Referenzen nicht tragen, die diese Tools zurückgeben.
• Die mcp- und agents-Extras stützen sich nun auf MCP 2.2.

Version 3.0 fügt zudem die Authentifizierung mit Service-Account-Token hinzu: Mistral() liest den Token aus der Datei, die durch die Umgebungsvariable MISTRAL_SA_TOKEN_PATH angegeben wird.

Was ist mit TypeScript?

Der Wechsel vom Legacy-JavaScript-Client 0.x zum TypeScript-SDK 1.x spiegelt den Python-Übergang fast exakt wider. Der Import ändert sich von einem Standardexport zu einem benannten Export, der Konstruktor nimmt ein Konfigurationsobjekt entgegen, und Methoden werden verkettet:

// 0.x (Legacy)
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 und später
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 bewegt sich von client.chatStream(...) zu client.chat.stream(...), und wie in Python wird der Inhalt über chunk.data gelesen:

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 kann auch eine Liste von Fragmenten sein: wir schreiben nur Text
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (18. März 2026) behielt diese Imports bei, aber das SDK wird nun ausschließlich als ES-Module veröffentlicht: Ein require('@mistralai/mistralai') in CommonJS funktioniert nicht mehr. Die Laufzeitvalidierung verlagert sich auf Zod v4, was nur Projekte betrifft, die Schemas direkt aus dem SDK importieren. Und Cloud-Clients leben in separaten Paketen: @mistralai/mistralai-azure (MistralAzure) und @mistralai/mistralai-gcp (MistralGCP, vormals MistralGoogleCloud).

Durchführung der Migration

Bei einem echten Projekt gehen Sie in einer definierten Reihenfolge vor, anstatt Fehler so zu beheben, wie sie auftreten. Beginnen Sie damit, die Code-Generierung über ihre Imports zu identifizieren, aktualisieren Sie dann das Paket (pip install --upgrade mistralai oder npm install @mistralai/mistralai@latest): Solange die alte Version installiert ist, beheben Sie blind. Dann fahren Sie wie folgt fort:

1. Suchen Sie nach alten Imports: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
2. Ersetzen Sie sie gemäß den Zuordnungen in dieser Lektion, vergessen Sie nicht die Fehler, die sich zu mistralai.client.errors bewegen
3. Aktualisieren Sie Aufrufe: verkettete Methoden, Plural inputs für Embeddings, .data in Streaming-Loops
4. Verschieben Sie integrierte Tools (web_search, code_interpreter) von Chat-Vervollständigungen zur Conversations-API

Testen Sie schließlich jeden Endpunkt, den Sie verwenden, einzeln: Chat, Embeddings und Streaming haben jeweils ihre eigenen Änderungen, und ein Projekt, das startet, ruft nicht unbedingt alle drei korrekt auf.

Wenn Sie nicht sofort migrieren können

Keine dieser Versionen bietet einen Übergangsmodus oder Kompatibilitätsalias. Wenn eine Produktions-Freeze Sie daran hindert, zu migrieren, fixieren Sie die Version explizit in Ihren Abhängigkeiten; andernfalls holt die nächste Installation die neueste Version und bricht die Anwendung:

# Python: bei 1.x bleiben
pip install "mistralai<2"

# Python: bei 2.x bleiben
pip install "mistralai>=2,<3"

# npm: bei 1.x bleiben
npm install @mistralai/mistralai@1

Behandeln Sie diese Fixierung als eine Verzögerung: Neue Funktionen kommen nur in der aktuellen Version an.

Offizielle Quellen: Migrationsleitfaden 0.x → 1.0 · Release-Notes Python 2.0.0 · Release-Notes Python 3.0.0 · Release-Notes TypeScript 2.0.0 · Versionshistorie auf PyPI · Websearch — integrierte Tools

Kernaussagen

• Identifizieren Sie die Code-Generierung über ihren Import: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x und 3.x)
• 1.0 (August 2024) führte den Mistral-Client, verkettete Methoden und die Streaming-Ebene .data ein
• 2.0 (März 2026) bewegte alle Python-Imports unter mistralai.client, Fehler unter mistralai.client.errors, und erhöhte das Minimum auf Python 3.10
• 3.0 (September 2026) wechselt zu httpx2 und reserviert web_search und code_interpreter für die Conversations-API und Agenten
• In TypeScript hat sich der Import seit 1.x nicht geändert, aber 2.0 akzeptiert ausschließlich ES-Module