Мигриране между версиите на Mistral SDK
На тази страница
- Защо този урок е важен
- Четири поколения за две години
- От 0.x към 1.x: клиентът Mistral и верижните методи
- От 1.x към 2.x: всичко се премества под mistralai.client
- От 2.x към 3.x: httpx2 и вградени инструменти
- А какво става с TypeScript?
- Извършване на миграцията
- Ако не можете да мигрирате веднага
- Ключови изводи
Урокът е пренаписан на 2 ноември 2026 г. Предишната версия споменаваше „преминаване от V1 към V2“, което всъщност беше преходът от наследения клиент 0.x към версия 1.0 през август 2024 г. Оттогава Python SDK има още две основни издания: 2.0 през март 2026 г. и 3.0 през септември 2026 г. Този урок възстановява пълната история въз основа на официалните ръководства за миграция и бележките към изданията. Актуализирано на 3 ноември 2026 г.: Поправен е цикълът за поточно предаване в TypeScript, който преди това предаваше съдържание от тип
string | ContentChunk[]директно наprocess.stdout.write, причинявайки грешки в строг режим.
Защо този урок е важен
Ще се сблъскате с този материал в два сценария: възобновявате проект, написан преди известно време, който отказва да стартира след актуализация на зависимостите, или следвате онлайн урок, чиито примери вече не работят. И в двата случая задайте един и същи първи въпрос: за кое поколение SDK е написан този код? Почти винаги един ред Ви казва отговора: инструкцията за импортиране.
Четири поколения за две години
| Поколение | Python (mistralai) | TypeScript (@mistralai/mistralai) | Отличителна черта на кода |
|---|---|---|---|
| 0.x | до 0.4.2 (юли 2024 г.) | до 0.5.0 (юни 2024 г.) | MistralClient, плоски методи: client.chat(...) |
| 1.x | 1.0.0 (7 авг. 2024 г.) → 1.9.11 (окт. 2025 г.) | от авг. 2024 г. | from mistralai import Mistral, верижни методи: client.chat.complete(...) |
| 2.x | 2.0.0 (10 март 2026 г.) | 2.0.0 (18 март 2026 г.) | Python: from mistralai.client import Mistral; TypeScript: само ES модули |
| 3.x | 3.0.0 (28 септ. 2026 г.), 3.7.0 към 1 ноем. 2026 г. | 3.0 (окт. 2026 г.), 3.5.0 днес | Python: HTTP клиент httpx2 |
В TypeScript импортирането import { Mistral } from '@mistralai/mistralai' не се е променяло от версия 1.x насам. В Python то се е променяло два пъти: там възникват повечето проблеми със съвместимостта.
От 0.x към 1.x: клиентът Mistral и верижните методи
Версия 1.0 замени двата клиента, MistralClient (синхронен) и MistralAsyncClient (асинхронен), с един единствен клас, Mistral. Тя също така замени плоските методи с именни пространства: chat групира операциите за разговор и трябва да отидете едно ниво по-надолу, за да достигнете до complete(). Съобщенията, които преди се пишеха с помощта на класа ChatMessage, сега се пишат като речници или с използване на класовете UserMessage, SystemMessage, AssistantMessage и ToolMessage.
# 0.x (наследен)
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"}],
)
Поточното предаване следва същата логика, но има капан, който често струва половин час дебъгване: полученият фрагмент сега е обвит и съдържанието му се чете чрез междинно ниво .data. Наследеният код от 0.x, копиран както си е, ще предизвика AttributeError при първия фрагмент.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x и по-нови
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
Официалното ръководство за 1.0 предоставя пълната таблица. Най-честите съответствия са:
| 0.x | 1.x и по-нови |
|---|---|
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 и неговите методи | Варианти с _async: client.chat.complete_async, client.chat.stream_async… |
От 1.x към 2.x: всичко се премества под mistralai.client
Версия 2.0 не промени имената на методите: client.chat.complete остава client.chat.complete. Тя промени адреса на всичко останало. SDK стана пакет с именни пространства (PEP 420) и всички импорти се преместиха от mistralai към mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x и по-нови
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Обърнете внимание на третия ред: класовете за грешки вече не живеят сред моделите, а в mistralai.client.errors, като MistralError е общият базов клас (от който наследяват SDKError и HTTPValidationError).
Клиентите за облачни доставчици се присъединиха към същото именното пространство. Във версия 1.x те се доставяха с пакета mistralai, но в отделни модули, mistralai_azure и 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 и по-нови
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")
Три други промени във версия 2.0 могат да Ви засегнат. Минималната версия вече е Python 3.10 (1.9.11 приемаше Python 3.9). 42 типа бяха преименувани според редовна конвенция: {Verb}{Entity}Request за заявки и {Verb}{Entity}Response за отговори. Единственото преименуване, видимо в обикновения код, е Tools, което стана ConversationRequestTool. Накрая, изброенията вече приемат неизвестни стойности, така че нова стойност, добавена от API, вече не срива по-стара версия на SDK.
От 2.x към 3.x: httpx2 и вградени инструменти
Версия 3.0, издадена на 28 септември 2026 г., не променя нито импортирането, нито обичайните методи. Въпреки това, три точки могат да сринат проекта:
- HTTP клиентът става
httpx2. Ако предадете свой собствен клиент на SDK (параметриclient=илиasync_client=, например за прокси или общи заглавки), той трябва да бъде клиент наhttpx2; суровите транспортни заявки, отговори и грешки също са типове наhttpx2. - Вградените инструменти напускат завършванията на чат.
client.chat.completeиclient.agents.completeвече не приемат инструментитеweb_search,web_search_premiumиcode_interpreter: те се използват чрез API за разговори (client.beta.conversations) или агент. Документацията на Mistral обяснява защо: отговорите за завършване на чат не могат да носят референциите, които тези инструменти връщат. - Допълненията
mcpиagentsвече разчитат на MCP 2.2.
Версия 3.0 също така добавя удостоверяване с токен за сервизен акаунт: Mistral() чете токена от файла, посочен от променливата на средата MISTRAL_SA_TOKEN_PATH.
А какво става с TypeScript?
Преминаването от наследения JavaScript клиент 0.x към TypeScript SDK 1.x почти точно огледално отразява прехода в Python. Импортирането се променя от експорт по подразбиране към именуван експорт, конструкторът приема обект с конфигурация, а методите стават верижни:
// 0.x (наследен)
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 и по-нови
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' }],
});
Поточното предаване се премества от client.chatStream(...) към client.chat.stream(...), и както при Python, съдържанието се чете чрез 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;
// съдържанието може да бъде и списък от фрагменти: пишем само текст
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18 март 2026 г.) запази тези импорти, но SDK вече се публикува само като ES модули: require('@mistralai/mistralai') в CommonJS вече не работи. Валидирането по време на изпълнение се премества в Zod v4, което засяга само проекти, които импортират схеми директно от SDK. А облачните клиенти живеят в отделни пакети: @mistralai/mistralai-azure (MistralAzure) и @mistralai/mistralai-gcp (MistralGCP, предишно име MistralGoogleCloud).
Извършване на миграцията
В реален проект действайте в определен ред, вместо да оправяте грешки, докато се появяват. Започнете с идентифициране на поколението на кода чрез неговите импорти, след това актуализирайте пакета (pip install --upgrade mistralai или npm install @mistralai/mistralai@latest): докато старата версия е инсталирана, Вие поправяте на сляпо. След това продължете, както следва:
- Търсете стари импорти:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Заменете ги според съответствията в този урок, не забравяйте грешките, които се местят в
mistralai.client.errors - Актуализирайте извикванията: верижни методи, множествено число
inputsза вграждания,.dataв циклите за поточно предаване - Преместете вградените инструменти (
web_search,code_interpreter) от завършванията на чат към API за разговори
Накрая тествайте всяка крайна точка, която използвате, една по една: чат, вграждания и поточно предаване имат свои собствени промени и проект, който стартира, не непременно извиква и трите правилно.
Ако не можете да мигрирате веднага
Нито една от тези версии не предлага режим на преход или псевдоними за съвместимост. Ако замразяване на продукцията Ви пречи да мигрирате, фиксирайте изрично версията във Вашите зависимости; в противен случай следващата инсталация ще изтегли най-новата версия и ще срине приложението:
# Python: останете на 1.x
pip install "mistralai<2"
# Python: останете на 2.x
pip install "mistralai>=2,<3"
# npm: останете на 1.x
npm install @mistralai/mistralai@1
Третирайте това фиксиране като отсрочка: нови функции пристигат само в текущата версия.
Официални източници: Ръководство за миграция от 0.x към 1.0 · Бележки към изданието на Python 2.0.0 · Бележки към изданието на Python 3.0.0 · Бележки към изданието на TypeScript 2.0.0 · История на версиите в PyPI · Websearch — вградени инструменти
Ключови изводи
- Идентифицирайте поколението на кода чрез неговия импорт:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x и 3.x) - 1.0 (авг. 2024 г.) въведе клиента
Mistral, верижните методи и нивото.dataпри поточно предаване - 2.0 (март 2026 г.) премести всички Python импорти под
mistralai.client, грешките подmistralai.client.errorsи повиши минимума до Python 3.10 - 3.0 (септ. 2026 г.) преминава към
httpx2и запазваweb_searchиcode_interpreterза API за разговори и агенти - В TypeScript импортирането не се е променяло от 1.x насам, но 2.0 приема само ES модули