Migrace mezi verzemi Mistral SDK
Na této stránce
Lekce přepsána 2. listopadu 2026. Předchozí verze odkazovala na „přechod z V1 na V2“, což byl ve skutečnosti přechod od starého klienta 0.x k verzi 1.0 v srpnu 2024. Od té doby prošel Python SDK dvěma dalšími hlavními vydáními: 2.0 v březnu 2026 a 3.0 v září 2026. Tato lekce rekonstruuje celou historii na základě oficiálních migračních průvodců a poznámek k vydání. Aktualizováno 3. listopadu 2026: Opraven streamovací cyklus v TypeScriptu, který dříve předával obsah
string | ContentChunk[]přímo doprocess.stdout.write, což způsobovalo chyby v přísném režimu.
Proč je tato lekce důležitá
S tímto materiálem se setkáš ve dvou situacích: buď obnovuješ projekt napsaný před nějakou dobou, který po aktualizaci závislostí odmítá startovat, nebo sleduješ online tutoriál, jehož příklady již nefungují. V obou případech si polož stejnou první otázku: pro kterou generaci SDK byl tento kód napsán? Téměř vždy ti odpověď prozradí jediný řádek: příkaz pro import.
Čtyři generace během dvou let
| Generace | Python (mistralai) | TypeScript (@mistralai/mistralai) | Rozlišovací znak v kódu |
|---|---|---|---|
| 0.x | až 0.4.2 (červenec 2024) | až 0.5.0 (červen 2024) | MistralClient, ploché metody: client.chat(...) |
| 1.x | 1.0.0 (7. srpna 2024) → 1.9.11 (říjen 2025) | od srpna 2024 | from mistralai import Mistral, řetězené metody: client.chat.complete(...) |
| 2.x | 2.0.0 (10. března 2026) | 2.0.0 (18. března 2026) | Python: from mistralai.client import Mistral; TypeScript: pouze ES moduly |
| 3.x | 3.0.0 (28. září 2026), k 1. listopadu 2026 verze 3.7.0 | 3.0 (říjen 2026), dnes 3.5.0 | Python: HTTP klient httpx2 |
V TypeScriptu se import import { Mistral } from '@mistralai/mistralai' od verze 1.x nezměnil. V Pythonu se změnil dvakrát: právě zde dochází k většině chyb.
Od 0.x k 1.x: klient Mistral a řetězené metody
Verze 1.0 nahradila dva klienty, MistralClient (synchronní) a MistralAsyncClient (asynchronní), jedinou třídou Mistral. Také nahradila ploché metody jmennými prostory: chat sdružuje operace konverzace a pro dosažení complete() musíš jít o úroveň níže. Zprávy, které se dříve zapisovaly pomocí třídy ChatMessage, se nyní zapisují jako slovníky nebo pomocí tříd UserMessage, SystemMessage, AssistantMessage a ToolMessage.
# 0.x (staré)
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"}],
)
Streamování funguje na stejném principu, ale obsahuje past, která často stojí půl hodiny ladění: přijatý fragment je nyní zabalen a jeho obsah se čte přes mezilehlou úroveň .data. Starý kód 0.x zkopírovaný tak, jak je, vyhodí při prvním fragmentu AttributeError.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x a novější
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Oficiální průvodce verzí 1.0 obsahuje úplnou tabulku. Nejčastější mapování jsou:
| 0.x | 1.x a novější |
|---|---|
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 a jeho metody | varianty _async: client.chat.complete_async, client.chat.stream_async… |
Od 1.x k 2.x: vše se přesouvá pod mistralai.client
Verze 2.0 se nedotkla názvů metod: client.chat.complete zůstává client.chat.complete. Změnila však adresu všeho ostatního. SDK se stalo namespace balíčkem (PEP 420) a všechny importy se přesunuly z mistralai do mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x a novější
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Všimni si třetího řádku: třídy chyb již nežijí mezi modely, ale v mistralai.client.errors, přičemž MistralError slouží jako společná základna (od které dědí SDKError a HTTPValidationError).
Klienti pro cloudové poskytovatele se připojili ke stejnému jmennému prostoru. Ve verzi 1.x byly dodávány s balíčkem mistralai, ale v samostatných modulech mistralai_azure a 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 a novější
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")
Další tři změny ve verzi 2.0 se tě mohou dotknout. Minimální verze je nyní Python 3.10 (verze 1.9.11 podporovala Python 3.9). Bylo přejmenováno 42 typů podle pravidelné konvence: {Verb}{Entity}Request pro požadavky a {Verb}{Entity}Response pro odpovědi. Jediné přejmenování viditelné v běžném kódu je Tools, které se stalo ConversationRequestTool. Nakonec, výčtové typy (enums) nyní přijímají neznámé hodnoty, takže nová hodnota přidaná API již nerozbije starší verzi SDK.
Od 2.x k 3.x: httpx2 a vestavěné nástroje
Verze 3.0, vydaná 28. září 2026, nemění ani importy, ani běžné metody. Tři body však mohou projekt rozbít:
- HTTP klientem se stává
httpx2. Pokud předáváš SDK vlastního klienta (parametryclient=neboasync_client=, například pro proxy nebo společná hlavičky), musí se jednat o klientahttpx2; surové požadavky transportu, odpovědi a chyby jsou také typyhttpx2. - Vestavěné nástroje opouštějí dokončování chatu.
client.chat.completeaclient.agents.completejiž nepřijímají nástrojeweb_search,web_search_premiumacode_interpreter: používají se prostřednictvím Conversations API (client.beta.conversations) nebo agenta. Dokumentace Mistralu vysvětluje proč: odpovědi z dokončování chatu nemohou nést reference, které tyto nástroje vracejí. - Doplňky
mcpaagentsnyní spoléhají na MCP 2.2.
Verze 3.0 také přidává autentizaci tokenem servisního účtu: Mistral() čte token ze souboru určeného proměnnou prostředí MISTRAL_SA_TOKEN_PATH.
A co TypeScript?
Přechod od starého JavaScript klienta 0.x k TypeScript SDK 1.x téměř přesně zrcadlí přechod v Pythonu. Import se mění z výchozího exportu na pojmenovaný export, konstruktor přijímá konfigurační objekt a metody se řetězí:
// 0.x (staré)
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 a novější
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' }],
});
Streamování se přesouvá z client.chatStream(...) na client.chat.stream(...) a stejně jako v Pythonu se obsah čte přes 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 může být také seznam fragmentů: zapisujeme pouze text
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18. března 2026) zachoval tyto importy, ale SDK je nyní publikováno pouze jako ES moduly: require('@mistralai/mistralai') v CommonJS již nefunguje. Ověřování v runtime se přesunulo na Zod v4, což ovlivňuje pouze projekty, které importují schémata přímo ze SDK. A cloudoví klienti žijí v samostatných balíčcích: @mistralai/mistralai-azure (MistralAzure) a @mistralai/mistralai-gcp (MistralGCP, dříve MistralGoogleCloud).
Provedení migrace
Na reálném projektu postupuj v definovaném pořadí, místo abys opravoval chyby, jak se objevují. Začni identifikací generace kódu podle jeho importů, poté aktualizuj balíček (pip install --upgrade mistralai nebo npm install @mistralai/mistralai@latest): dokud je nainstalována stará verze, opravuješ naslepo. Poté postupuj takto:
- Vyhledej staré importy:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Nahraď je podle mapování v této lekci, nezapomeň na chyby, které se přesouvají do
mistralai.client.errors - Aktualizuj volání: řetězené metody, množné číslo
inputspro vnoření,.datave streamovacích smyčkách - Přesuň vestavěné nástroje (
web_search,code_interpreter) z dokončování chatu do Conversations API
Nakonec otestuj každý koncový bod, který používáš, jeden po druhém: chat, vnoření i streamování mají své vlastní změny a projekt, který startuje, nemusí nutně všechny tři volat správně.
Pokud nemůžeš migrovat okamžitě
Žádná z těchto verzí nenabízí přechodný režim ani aliasy pro kompatibilitu. Pokud ti produkční zmrazení brání v migraci, explicitně připni verzi ve svých závislostech; jinak si při příští instalaci stáhneš nejnovější verzi a rozbiješ aplikaci:
# Python: zůstat na 1.x
pip install "mistralai<2"
# Python: zůstat na 2.x
pip install "mistralai>=2,<3"
# npm: zůstat na 1.x
npm install @mistralai/mistralai@1
Ber toto připnutí jako odklad: nové funkce přicházejí pouze v aktuální verzi.
Oficiální zdroje: Průvodce migrací 0.x → 1.0 · Poznámky k vydání Python 2.0.0 · Poznámky k vydání Python 3.0.0 · Poznámky k vydání TypeScript 2.0.0 · Historie verzí na PyPI · Websearch — vestavěné nástroje
Klíčové poznatky
- Identifikuj generaci kódu podle importu:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x a 3.x) - 1.0 (srpen 2024) zavedla klienta
Mistral, řetězené metody a úroveň.datapro streamování - 2.0 (březen 2026) přesunula všechny Python importy pod
mistralai.client, chyby podmistralai.client.errorsa zvýšila minimum na Python 3.10 - 3.0 (září 2026) přepíná na
httpx2a vyhrazujeweb_searchacode_interpreterpro Conversations API a agenty - V TypeScriptu se import od verze 1.x nezměnil, ale 2.0 přijímá pouze ES moduly