Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Migrace mezi verzemi Mistral SDK

Lekce 10 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Proč je tato lekce důležitá
  2. Čtyři generace během dvou let
  3. Od 0.x k 1.x: klient Mistral a řetězené metody
  4. Od 1.x k 2.x: vše se přesouvá pod mistralai.client
  5. Od 2.x k 3.x: httpx2 a vestavěné nástroje
  6. A co TypeScript?
  7. Provedení migrace
  8. Pokud nemůžeš migrovat okamžitě
  9. Klíčové poznatky

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 do process.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

GeneracePython (mistralai)TypeScript (@mistralai/mistralai)Rozlišovací znak v kódu
0.xaž 0.4.2 (červenec 2024)až 0.5.0 (červen 2024)MistralClient, ploché metody: client.chat(...)
1.x1.0.0 (7. srpna 2024) → 1.9.11 (říjen 2025)od srpna 2024from mistralai import Mistral, řetězené metody: client.chat.complete(...)
2.x2.0.0 (10. března 2026)2.0.0 (18. března 2026)Python: from mistralai.client import Mistral; TypeScript: pouze ES moduly
3.x3.0.0 (28. září 2026), k 1. listopadu 2026 verze 3.7.03.0 (říjen 2026), dnes 3.5.0Python: 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.x1.x a novější
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 a jeho metodyvarianty _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 (parametry client= nebo async_client=, například pro proxy nebo společná hlavičky), musí se jednat o klienta httpx2; surové požadavky transportu, odpovědi a chyby jsou také typy httpx2.
  • Vestavěné nástroje opouštějí dokončování chatu. client.chat.complete a client.agents.complete již nepřijímají nástroje web_search, web_search_premium a code_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 mcp a agents nyní 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:

  1. Vyhledej staré importy: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Nahraď je podle mapování v této lekci, nezapomeň na chyby, které se přesouvají do mistralai.client.errors
  3. Aktualizuj volání: řetězené metody, množné číslo inputs pro vnoření, .data ve streamovacích smyčkách
  4. 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ň .data pro streamování
  • 2.0 (březen 2026) přesunula všechny Python importy pod mistralai.client, chyby pod mistralai.client.errors a zvýšila minimum na Python 3.10
  • 3.0 (září 2026) přepíná na httpx2 a vyhrazuje web_search a code_interpreter pro Conversations API a agenty
  • V TypeScriptu se import od verze 1.x nezměnil, ale 2.0 přijímá pouze ES moduly