Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Μετάβαση μεταξύ εκδόσεων του Mistral SDK

Μάθημα 10 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Γιατί έχει σημασία αυτό το μάθημα
  2. Τέσσερις γενιές σε δύο χρόνια
  3. Από την 0.x στην 1.x: ο πελάτης Mistral και οι αλυσιδωτές μέθοδοι
  4. Από την 1.x στην 2.x: όλα μετακινούνται κάτω από το mistralai.client
  5. Από την 2.x στην 3.x: httpx2 και ενσωματωμένα εργαλεία
  6. Τι γίνεται με το TypeScript;
  7. Διεξαγωγή της μετάβασης
  8. Αν δεν μπορείτε να μεταβείτε αμέσως
  9. Βασικά σημεία

Μάθημα ξαναγράφηκε στις 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.x1.0.0 (7 Αυγ 2024) → 1.9.11 (Οκτ 2025)από Αύγ 2024from mistralai import Mistral, αλυσιδωτές μέθοδοι: client.chat.complete(...)
2.x2.0.0 (10 Μαρ 2026)2.0.0 (18 Μαρ 2026)Python: from mistralai.client import Mistral; TypeScript: μόνο ES modules
3.x3.0.0 (28 Σεπ 2026), 3.7.0 από 1 Νοε 20263.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. Επίσης, αντικατέστησε τις επίπεδες μεθόδους με namespaces: το 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.x1.x και νεότερες
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 και οι μέθοδοί τουΠαραλλαγές _async: client.chat.complete_async, client.chat.stream_async…

Από την 1.x στην 2.x: όλα μετακινούνται κάτω από το mistralai.client

Η έκδοση 2.0 δεν άγγιξε τα ονόματα των μεθόδων: το client.chat.complete παραμένει client.chat.complete. Άλλαξε όμως τη διεύθυνση όλων των άλλων. Το SDK έγινε ένα namespace package (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).

Οι πελάτες παρόχων cloud εντάχθηκαν στο ίδιο namespace. Στην 1.x, παραδίδονταν με το πακέτο mistralai αλλά σε ξεχωριστά modules, τα 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· τα αιτήματα μεταφοράς raw, οι αποκρίσεις και τα σφάλματα είναι επίσης τύποι httpx2.
  • Τα ενσωματωμένα εργαλεία φεύγουν από τις ολοκληρώσεις chat. Τα client.chat.complete και client.agents.complete δεν δέχονται πλέον τα εργαλεία web_search, web_search_premium και code_interpreter: χρησιμοποιούνται μέσω του API Συνομιλιών (client.beta.conversations) ή ενός πράκτορα. Η τεκμηρίωση του Mistral εξηγεί γιατί: οι αποκρίσεις ολοκλήρωσης chat δεν μπορούν να μεταφέρουν τις αναφορές που επιστρέφουν αυτά τα εργαλεία.
  • Τα extras mcp και agents βασίζονται πλέον στο MCP 2.2.

Η έκδοση 3.0 προσθέτει επίσης έλεγχο ταυτότητας με token λογαριασμού υπηρεσίας: το Mistral() διαβάζει το token από το αρχείο που καθορίζεται από τη μεταβλητή περιβάλλοντος 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;
  // το content μπορεί επίσης να είναι λίστα θραυσμάτων: γράφουμε μόνο κείμενο
  if (typeof content === 'string') process.stdout.write(content);
}

Το TypeScript 2.0 (18 Μαρτίου 2026) διατήρησε αυτές τις εισαγωγές, αλλά το SDK δημοσιεύεται πλέον αποκλειστικά ως ES modules: ένα require('@mistralai/mistralai') σε CommonJS δεν λειτουργεί πλέον. Ο έλεγχος χρόνου εκτέλεσης μετακινείται στο Zod v4, το οποίο επηρεάζει μόνο έργα που εισάγουν σχήματα απευθείας από το SDK. Και οι πελάτες cloud ζουν σε ξεχωριστά πακέτα: @mistralai/mistralai-azure (MistralAzure) και @mistralai/mistralai-gcp (MistralGCP, πρώην MistralGoogleCloud).

Διεξαγωγή της μετάβασης

Σε ένα πραγματικό έργο, προχωρήστε με καθορισμένη σειρά αντί να διορθώνετε σφάλματα καθώς εμφανίζονται. Ξεκινήστε εντοπίζοντας τη γενιά κώδικα μέσω των εισαγωγών του και, στη συνέχεια, ενημερώστε το πακέτο (pip install --upgrade mistralai ή npm install @mistralai/mistralai@latest): όσο είναι εγκατεστημένη η παλιά έκδοση, διορθώνετε τυφλά. Στη συνέχεια, προχωρήστε ως εξής:

  1. Αναζητήστε παλιές εισαγωγές: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Αντικαταστήστε τες σύμφωνα με τις αντιστοιχίσεις σε αυτό το μάθημα, μην ξεχνάτε τα σφάλματα, τα οποία μετακινούνται στο mistralai.client.errors
  3. Ενημερώστε τις κλήσεις: αλυσιδωτές μέθοδοι, πληθυντικός inputs για embeddings, .data σε βρόχους ροής
  4. Μετακινήστε τα ενσωματωμένα εργαλεία (web_search, code_interpreter) από τις ολοκληρώσεις chat στο API Συνομιλιών

Τέλος, δοκιμάστε κάθε endpoint που χρησιμοποιείτε, ένα προς ένα: το chat, τα embeddings και η ροή έχουν τις δικές τους αλλαγές, και ένα έργο που ξεκινά δεν καλεί απαραίτητα και τα τρία σωστά.

Αν δεν μπορείτε να μεταβείτε αμέσως

Καμία από αυτές τις εκδόσεις δεν προσφέρει λειτουργία μετάβασης ή ψευδώνυμα συμβατότητας. Αν ένα πάγωμα παραγωγής σας εμποδίζει να μεταβείτε, καρφιτσώστε ρητά την έκδοση στις εξαρτήσεις σας· διαφορετικά, η επόμενη εγκατάσταση θα λάβει την τελευταία έκδοση και θα διακόψει την εφαρμογή:

# 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 modules