Εγκατάσταση του TypeScript SDK της Mistral
Σε αυτήν τη σελίδα
Μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 μετά την εκτέλεση των παραδειγμάτων με το SDK
@mistralai/mistralaiέκδοσης 3.5.0 και TypeScript 7.0.2. Η αρχική έκδοση δεν μεταγλωττιζόταν. Η εκτέλεση τουnpx tscχωρίς εγκατεστημένο το TypeScript κατεβάζει το εγκαταλελειμμένο πακέτο npmtsc(έκδοση 2.0.4) αντί για τον μεταγλωττιστή. Το σενάριο ελέγχου βρισκόταν εκτός του φακέλουsrcπου δηλώνεται στοtsconfig.json. Το αντικείμενοprocessαναγνωρίζεται μόνο με το@types/node. Τέλος, η αυστηρή λειτουργία (strict mode) απορρίπτει ταmodels.data.lengthκαιmodel.idχωρίς προηγούμενη επικύρωση. Τοtsconfig.jsonακολουθεί πλέον το σενάριο «μεταγλώττιση και στη συνέχεια εκτέλεση με Node.js» του οδηγού TypeScript, ενώ οι εκδόσεις Node.js 18 και 20, που έχουν φτάσει στο τέλος του κύκλου ζωής τους, δεν αναφέρονται πλέον ως επαρκείς. Πηγές: Λήψη TypeScript · Επιλογή επιλογών μεταγλωττιστή (TypeScript) · Αλλαγές στο TypeScript 6.0 · tsx και TypeScript · Υποστηριζόμενα περιβάλλοντα εκτέλεσης SDK · Πρόγραμμα κυκλοφορίας Node.js.
Γιατί να χρησιμοποιήσετε το TypeScript SDK;
Αν η στοίβα τεχνολογιών σας βασίζεται σε Node.js, Deno ή Bun, το TypeScript SDK της Mistral σας επιτρέπει να ενσωματώσετε μοντέλα απευθείας στις εφαρμογές JavaScript και TypeScript. Αποφεύγετε ενδιάμεσα στρώματα Python ή τη συγγραφή προσαρμοσμένων κλήσεων HTTP. Αυτό είναι το πιο συνηθισμένο σενάριο κατά την προσθήκη τεχνητής νοημοσύνης σε μια υπάρχουσα web εφαρμογή: ένα API Express, ένα backend Next.js ή έναν worker Node που επεξεργάζεται μια ουρά μηνυμάτων.
Ο στατικός τύπος του TypeScript προσθέτει ένα δίχτυ ασφαλείας που αποδίδει μέσα στην πρώτη ώρα ανάπτυξης. Ο επεξεργαστής κώδικά σας συμπληρώνει ονόματα παραμέτρων αντί να σας αναγκάζει να μαντέψετε ανάμεσα σε maxTokens και max_tokens· τα σφάλματα πεζών/κεφαλαίων ή τα ανύπαρκτα πεδία εντοπίζονται κατά τη μεταγλώττιση και όχι στην παραγωγή στις 3 π.μ.· και η τεκμηρίωση των παραμέτρων εμφανίζεται με την αιωρούμενη ένδειξη (hover) χωρίς να χρειάζεται να εγκαταλείψετε το αρχείο. Αυτό το δίχτυ ασφαλείας έχει ακόμη μεγαλύτερη σημασία επειδή οι αποκρίσεις API είναι εμφωλευμένα αντικείμενα όπου είναι εύκολο να παραλείψετε ένα επίπεδο.
Προαπαιτούμενα
Το SDK στοχεύει σε συντηρούμενες εκδόσεις LTS του Node.js. Από τις 3 Νοεμβρίου 2026, αυτές είναι οι εκδόσεις 22, 24 και 26· οι Node.js 18 και 20 δεν λαμβάνουν πλέον ενημερώσεις ασφαλείας. Ελέγξτε την έκδοσή σας με node --version πριν συνεχίσετε: το SDK βασίζεται σε λειτουργικές μονάδες ES και στο εγγενές API fetch. Χρειάζεστε επίσης έναν διαχειριστή πακέτων (npm, yarn ή pnpm) και ένα κλειδί API της Mistral, δημιουργημένο και διαθέσιμο ως μεταβλητή περιβάλλοντος, όπως καλύφθηκε σε προηγούμενα μαθήματα.
Εγκατάσταση
Το επίσημο SDK δημοσιεύεται στο npm ως @mistralai/mistralai:
# Με npm
npm install @mistralai/mistralai
# Με yarn
yarn add @mistralai/mistralai
# Με pnpm
pnpm add @mistralai/mistralai
Διαμόρφωση TypeScript
Αν χρησιμοποιείτε TypeScript—κάτι που συνιστούμε—εγκαταστήστε τρία εργαλεία ως εξαρτήσεις ανάπτυξης: τον μεταγλωττιστή, το tsx (το οποίο εκτελεί αρχεία .ts χωρίς βήμα δημιουργίας) και το @types/node (το οποίο περιγράφει αντικείμενα Node.js όπως το process στο TypeScript):
npm install -D typescript tsx @types/node
Μην παραλείψετε αυτό το βήμα. Χωρίς εγκατεστημένο το TypeScript στο έργο, το npx tsc ανακτά το πακέτο tsc από το npm—έναν εγκαταλελειμμένο μεταγλωττιστή παλιάς τεχνολογίας (2.0.4)—αντί για το TypeScript. Στη συνέχεια, δηλώστε το έργο ως λειτουργικές μονάδες ES, όπως απαιτεί η τεκμηρίωση του TypeScript για κώδικα που μεταγλωττίζεται και στη συνέχεια εκτελείται από το Node.js:
npm pkg set type=module
Τέλος, δημιουργήστε το tsconfig.json. Χρησιμοποιεί τις ρυθμίσεις που προτείνει ο επίσημος οδηγός TypeScript για αυτό το σενάριο (module: nodenext). Ενεργοποιεί επίσης την αυστηρή λειτουργία (strict mode), η οποία σας αναγκάζει να χειρίζεστε πιθανώς ελλείπουσες τιμές στις αποκρίσεις API—ένας υγιής περιορισμός—και μεταγλωττίζει το src/ στο dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Τρεις γραμμές αξίζουν εξήγηση, καθώς καθεμία αποτρέπει ένα σφάλμα που συναντήσαμε κατά τη δοκιμή αυτού του μαθήματος:
"types": ["node"]φορτώνει τους τύπους Node.js. Από το TypeScript 6.0 και μετά, τα πακέτα@typesδεν φορτώνονται πλέον αυτόματα. Χωρίς αυτή τη γραμμή, τοprocess.envπροκαλεί το σφάλμα “Cannot find name ‘process’”, ακόμη και με εγκατεστημένο το@types/node."rootDir": "src"ορίζει την πηγή ρίζα για τα μεταγλωττισμένα αρχεία: τοsrc/test-mistral.tsγίνεταιdist/test-mistral.js. Χωρίς αυτό, το TypeScript 7 αναφέρει το σφάλμα TS5011 όποτε οι πηγές σας δεν βρίσκονται στη ρίζα του έργου."skipLibCheck": trueπαραλείπει τον έλεγχο τύπων στα αρχεία δήλωσης εξαρτήσεων. Αυτή είναι επίσης η προεπιλεγμένη ρύθμιση στοtsconfig.jsonπου δημιουργείται από τοnpx tsc --init. Με το SDK 3.5.0 και το TypeScript 7, η παράλειψη αυτού προκαλεί σφάλμα στις ίδιες τις δηλώσεις του SDK που ο κώδικάς σας δεν μπορεί να διορθώσει.
Το SDK δημοσιεύεται ως λειτουργικές μονάδες ES και περιλαμβάνει τους δικούς του τύπους: δεν χρειάζεται κανένα πακέτο @types/ για αυτό. Αν ο επεξεργαστής κώδικά σας lacks αυτόματη συμπλήρωση, το πρόβλημα βρίσκεται στο tsconfig.json σας και όχι σε ένα missing πακέτο τύπων.
Διαμόρφωση της Μεταβλητής Περιβάλλοντος
Μην κωδικοποιείτε ποτέ το κλειδί API απευθείας στον πηγαίο κώδικά σας. Στο Node.js, η τυπική λύση είναι το dotenv, το οποίο φορτώνει μεταβλητές από ένα τοπικό αρχείο κατά την εκκίνηση της διαδικασίας:
npm install dotenv
Δημιουργήστε ένα αρχείο .env στη ρίζα του έργου σας:
MISTRAL_API_KEY=your-api-key-here
Προσθέστε αυτό το αρχείο στο .gitignore σας αμέσως, πριν την πρώτη σας υποβολή (commit). Αυτή είναι ακριβώς η στιγμή που διαρρέουν τα κλειδιά:
.env
.env.local
Η εισαγωγή dotenv/config πρέπει να προηγείται οποιασδήποτε ανάγνωσης του process.env. Διαφορετικά, η μεταβλητή παραμένει undefined όταν δημιουργείτε τον πελάτη:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Επαλήθευση της Εγκατάστασης
Πριν γράψετε επιχειρηματική λογική, επικυρώστε ολόκληρη την αλυσίδα—εγκατάσταση, κλειδί, δίκτυο—με ένα ελάχιστο σενάριο. Δημιουργήστε το src/test-mistral.ts και ζητήστε απλώς τη λίστα των μοντέλων που είναι προσβάσιμα στον λογαριασμό σας:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Λίστα διαθέσιμων μοντέλων
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Available models: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Ένας τύπος μοντέλου άγνωστος σε αυτή την έκδοση SDK σημειώνεται ως 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Αυτοί οι δύο έλεγχοι δεν είναι διακοσμητικοί. Το SDK δηλώνει το data ως προαιρετικό και κάθε καταχώρηση λίστας είναι είτε μια βασική κάρτα μοντέλου, μια κάρτα fine-tuned μοντέλου ή μια άγνωστη τιμή (type: 'UNKNOWN'). Όταν το API προσθέτει έναν νέο τύπο μοντέλου, το SDK τον διατηρεί σε αυτή τη μορφή αντί να καταρρεύσει. Χωρίς αυτές τις δύο δοκιμές, η αυστηρή λειτουργία αρνείται να μεταγλωττίσει.
Κατά την ανάπτυξη, εκτελέστε το με το tsx, που εγκαταστήσατε νωρίτερα, το οποίο μεταγλωττίζει εν κινήσει και σας γλιτώνει ένα βήμα δημιουργίας:
npx tsx src/test-mistral.ts
Προειδοποίηση: Το tsx δεν ελέγχει τους τύπους· τους αφαιρεί και εκτελεί. Μόνο το tsc αναφέρει σφάλματα τύπων. Εκτελέστε npx tsc --noEmit για έλεγχο χωρίς μεταγλώττιση. Για μεταγλώττιση και στη συνέχεια εκτέλεση, όπως θα κάνει η γραμμή δημιουργίας σας:
npx tsc && node dist/test-mistral.js
Ένα έγκυρο κλειδί εμφανίζει τον αριθμό των μοντέλων και τις πρώτες πέντε καταχωρήσεις. Ένα απορριφθέν κλειδί εμφανίζει ένα σφάλμα Status 401 (Invalid API Key): η αλυσίδα λειτουργεί, μόνο το κλειδί είναι ελαττωματικό.
Οργάνωση του Έργου
Μόλις περάσει η επαλήθευση, δομήστε το έργο ώστε το κλειδί και ο πελάτης να μην διασκορπίζονται σε αρχεία:
mon-projet/
├── src/
│ ├── index.ts # Σημείο εισόδου
│ ├── mistral-client.ts # Αρχικοποίηση πελάτη (singleton)
│ └── utils/
├── .env # Μεταβλητές περιβάλλοντος (αγνοούνται από git)
├── .gitignore
├── package.json
└── tsconfig.json
Η κεντρικοποίηση της αρχικοποίησης του πελάτη σε ένα αφιερωμένο module αποφεύγει τη δημιουργία του σε κάθε αρχείο. Πιο σημαντικό, προκαλεί την αποτυχία της εφαρμογής κατά την εκκίνηση και όχι κατά την πρώτη κλήση χρήστη αν λείπει το κλειδί:
// src/mistral-client.ts
import { Mistral } from '@mistralai/mistralai';
if (!process.env.MISTRAL_API_KEY) {
throw new Error('The MISTRAL_API_KEY variable is required.');
}
export const mistral = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Το υπόλοιπο του κώδικα απλώς εισάγει αυτόν τον προ-κατασκευασμένο πελάτη:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Σημειώστε την επέκταση .js στη σχετική εισαγωγή. Με module: nodenext, το TypeScript απαιτεί το όνομα αρχείου όπως θα υπάρχει μετά τη μεταγλώττιση, και το tsx γνωρίζει πώς να το αντιστοιχίσει στο αρχείο .ts. Η σειρά εισαγωγής έχει επίσης σημασία: το dotenv/config εκτελείται πριν από το mistral-client.js, ώστε το κλειδί να φορτώνεται όταν εκείνο το module ελέγχει την παρουσία του.
Βασικά σημεία
- Εγκαταστήστε το TypeScript SDK με
npm install @mistralai/mistralai - Η κύρια εισαγωγή είναι
import { Mistral } from '@mistralai/mistralai' - Εγκαταστήστε τα
typescript,tsxκαι@types/nodeως εξαρτήσεις ανάπτυξης πριν καλέσετε τοnpx tsc - Χρησιμοποιήστε
module: nodenextκαι"type": "module"για κώδικα που μεταγλωττίζεται και στη συνέχεια εκτελείται από το Node.js· οι σχετικές εισαγωγές λαμβάνουν την επέκταση.js - Χρησιμοποιήστε ένα αρχείο
.envμε τοdotenvγια τη διαχείριση του κλειδιού API - Το SDK παρέχει εγγενείς τύπους TypeScript: αξιοποιήστε την αυτόματη συμπλήρωση και αφήστε το
tscνα ελέγξει ό,τι παραλείπει τοtsx - Κεντρικοποιήστε την αρχικοποίηση του πελάτη σε ένα αφιερωμένο module