Installazzjoni tal-SDK ta' Mistral għat-TypeScript
F'din il-paġna
Lezzjoni aġġornata fit-3 ta’ Novembru, 2026 wara li tħaddmu l-eżempji bl-SDK
@mistralai/mistralai3.5.0 u TypeScript 7.0.2. Il-verżjoni oriġinali ma kinitx tikkompileja. Meta tħaddemnpx tscmingħajr TypeScript installat, dan jinżel il-pakketttscnpm abbandunat (verżjoni 2.0.4) minflok il-kompilatur. Is-skript tat-test kien jinsab barra mill-foldersrciddikjarat f’tsconfig.json. L-oġġettprocessjiġi rikonoxxut biss b’@types/node. Fl-aħħar nett, il-modalità stretta (strict mode) tiċħadmodels.data.lengthumodel.idmingħajr validazzjoni minn qabel. Il-tsconfig.jsonissa jsegwi x-xenarju “ikkompila mbagħad ħaddem b’Node.js” tal-gwida ta’ TypeScript, u Node.js 18 u 20, li laħqu t-tmiem tal-ħajja tagħhom, m’għadx huma elenkati bħala suffiċjenti. Sorsi: Download TypeScript · Choosing compiler options (TypeScript) · TypeScript 6.0 changes · tsx and TypeScript · SDK supported runtimes · Node.js release schedule.
Għaliex tuża l-SDK ta’ TypeScript?
Jekk l-istack tiegħek jiddependi fuq Node.js, Deno, jew Bun, l-SDK ta’ Mistral għat-TypeScript jippermettilek tintegra l-mudelli direttament fl-applikazzjonijiet JavaScript u TypeScript tiegħek. Tevita saffi intermedjarji ta’ Python jew il-kitba ta’ sejħiet HTTP personalizzati. Dan huwa l-aktar xenarju komuni meta żżid l-AI f’applikazzjoni web eżistenti: API ta’ Express, backend ta’ Next.js, jew ħaddiem (worker) ta’ Node li jipproċessa fila ta’ messaġġi.
It-tipar statiku (static typing) ta’ TypeScript iżid netwerk ta’ sigurtà li jħallas lura fi żmien l-ewwel siegħa ta’ żvilupp. L-editur tiegħek jikkompleta l-ismijiet tal-parametri minflok ma jħallik tgħaġġel bejn maxTokens u max_tokens; l-iżbalji fil-kaxxa (casing) jew oqsma inventati joħorġu fil-ħin tal-kompilazzjoni, mhux fil-produzzjoni fit-3 ta’ filgħodu; u d-dokumentazzjoni tal-parametri tidher meta tgħaddi l-maws fuqha mingħajr ma toħroġ mill-fajl. Dan in-netwerk ta’ sigurtà huwa saħansitra aktar importanti għax ir-risponsijiet tal-API huma oġġetti mbejjna (nested) fejn huwa faċli li titlef livell.
Prerekwiżiti
L-SDK huwa mmirat lejn verżjonijiet LTS (Long Term Support) miżmuma ta’ Node.js. Mill-3 ta’ Novembru, 2026, dawn huma l-verżjonijiet 22, 24, u 26; Node.js 18 u 20 ma jirċievux aktar patches tas-sigurtà. Iċċekkja l-verżjoni tiegħek b’node --version qabel ma tkompli: l-SDK jiddependi fuq il-moduli ES u l-API nattiva fetch. Għandek bżonn ukoll maniġer tal-pakketti (npm, yarn, jew pnpm) u ċavetta tal-API ta’ Mistral maħluqa u disponibbli bħala varjabbli tal-ambjent, kif kopert fil-lezzjonijiet preċedenti.
Installazzjoni
L-SDK uffiċjali huwa ppubblikat fuq npm bħala @mistralai/mistralai:
# Bl-użu ta' npm
npm install @mistralai/mistralai
# Bl-użu ta' yarn
yarn add @mistralai/mistralai
# Bl-użu ta' pnpm
pnpm add @mistralai/mistralai
Konfigurazzjoni ta’ TypeScript
Jekk tuża TypeScript—li nirrakkomandawlek—installa tliet għodod bħala dipendenzi ta’ żvilupp: il-kompilatur, tsx (li jħaddem fajls .ts mingħajr pass ta’ build), u @types/node (li jiddeskrivi oġġetti ta’ Node.js bħal process lil TypeScript):
npm install -D typescript tsx @types/node
Taqbiżx dan il-pass. Mingħajr TypeScript installat fil-proġett, npx tsc iġib il-pakkett tsc minn npm—kompilatur antik abbandunat (2.0.4)—minflok TypeScript. Imbagħad, iddikjara l-proġett bħala moduli ES, kif titlob id-dokumentazzjoni ta’ TypeScript għal kodiċi kkompilat u mbagħad imħaddem minn Node.js:
npm pkg set type=module
Fl-aħħar nett, oħloq tsconfig.json. Dan juża l-issettjar li l-gwida uffiċjali ta’ TypeScript tirrakkomanda għal dan ix-xenarju (module: nodenext). Jippermetti wkoll il-modalità stretta (strict mode), li tifforzalek tittratta valuri li jistgħu jonqsu fir-risponsijiet tal-API—restrizzjoni sana—u jikkompila src/ f’dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Tliet linji jistħoqqilhom spjegazzjoni, peress li kull waħda tipprevjeni żball li ltqajna miegħu waqt li ttestjajna din il-lezzjoni:
"types": ["node"]itella’ t-tipi ta’ Node.js. Minn TypeScript 6.0 ‘l hawn, il-pakketti@typesma jitgħabbewx awtomatikament. Mingħajr din il-linja,process.enviwassal għall-iżball “Cannot find name ‘process’”, anke jekk@types/nodeikun installat."rootDir": "src"jistabbilixxi r-raġuni tas-sors għall-fajls ikkompilati:src/test-mistral.tsisirdist/test-mistral.js. Mingħajru, TypeScript 7 jirrapporta l-iżball TS5011 kull meta s-sorsi tiegħek ma jkunux fir-raġuni tal-proġett."skipLibCheck": truejaqbeż iċ-ċekkjar tat-tipi għall-fajls tad-dikjarazzjoni tad-dipendenzi. Din hija wkoll setting predefinit f’tsconfig.jsoniġġenerat minnnpx tsc --init. Bl-SDK 3.5.0 u TypeScript 7, li tonqos din tikkawża żball fid-dikjarazzjonijiet tal-SDK innifsu li l-kodiċi tiegħek ma jistax jissewwa.
L-SDK huwa ppubblikat bħala moduli ES u jiġbor it-tipi tiegħu stess: l-ebda pakkett @types/ mhu meħtieġ għalih. Jekk l-editur tiegħek ma jkollux awto-kompletament, il-problema tinsab f’tsconfig.json tiegħek, mhux f’pakkett ta’ tipi nieqes.
Ikkonfigura l-Varjabbli tal-Ambjent
Qatt ma tħalli ċ-ċavetta tal-API hard-coded fil-kodiċi sors tiegħek. F’Node.js, is-soluzzjoni standard hija dotenv, li ttella’ varjabbli minn fajl lokali meta jibda l-proċess:
npm install dotenv
Oħloq fajl .env fir-raġuni tal-proġett tiegħek:
MISTRAL_API_KEY=your-api-key-here
Żid dan il-fajl fil-.gitignore tiegħek immedjatament, qabel l-ewwel commit tiegħek. Dan huwa l-mument eżatt fejn iċ-ċwievet jitxerrdu:
.env
.env.local
L-importazzjoni dotenv/config trid tiġi qabel kwalunkwe qari ta’ process.env. Inkella, il-varjabbli tibqa’ mhux definita meta tistanzja l-klijent:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Ivverifika l-Installazzjoni
Qabel ma tikteb loġika tan-negozju, ivvalida l-katina kollha—installazzjoni, ċavetta, network—b’skript minimu. Oħloq src/test-mistral.ts u sempliċiment itlob il-lista ta’ mudelli aċċessibbli għall-kont tiegħek:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Elenga l-mudelli disponibbli
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Available models: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Tip ta' mudell mhux magħruf għal din il-verżjoni tal-SDK huwa mmarkat bħala 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Dawn iż-żewġ ċekkijiet mhumiex dekorattivi. L-SDK jiddikjara data bħala opzjonali, u kull entrata fil-lista hija jew karta ta’ mudell bażiku, karta ta’ mudell imfajjan (fine-tuned), jew valur mhux magħruf (type: 'UNKNOWN'). Meta l-API żżid tip ġdid ta’ mudell, l-SDK iżommu f’din il-forma minflok ma jikkraċċja. Mingħajr dawn iż-żewġ testijiet, il-modalità stretta tirrifjuta li tikkompileja.
Fl-iżvilupp, ħaddmu b’tsx, installat qabel, li jittraspileja waqt it-tħaddim u jiffrankalek pass ta’ build:
npx tsx src/test-mistral.ts
Twissija: tsx ma jiċċekkjax it-tipi; ineħħihom u jeżegwixxi. Biss tsc jirrapporta żbalji tat-tipar. Ħaddem npx tsc --noEmit biex tiċċekkja mingħajr ma tikkompileja. Biex tikkompileja u mbagħad tħaddem, kif se jagħmel il-pipeline tal-build tiegħek:
npx tsc && node dist/test-mistral.js
Ċavetta valida turi n-numru ta’ mudelli u l-ewwel ħames entrati. Ċavetta miċħuda turi żball Status 401 (Invalid API Key): il-katina taħdem, biss iċ-ċavetta hija l-ħatija.
Organizza l-Proġett
Ladarba l-verifika tgħaddi, struttura l-proġett sabiex iċ-ċavetta u l-klijent ma jinxterdux madwar fajls differenti:
mon-projet/
├── src/
│ ├── index.ts # Punt tad-dħul
│ ├── mistral-client.ts # Inizjalizzazzjoni tal-klijent (singleton)
│ └── utils/
├── .env # Varjabbli tal-ambjent (injorati minn git)
├── .gitignore
├── package.json
└── tsconfig.json
Iċ-ċentralizzazzjoni tal-inizjalizzazzjoni tal-klijent f’modulu ddedikat tevita li terġa’ toħloqu f’kull fajl. Aktar importanti minn hekk, dan jikkawża li l-applikazzjoni tfalli fil-bidu minflok fl-ewwel sejħa tal-utent jekk iċ-ċavetta tkun nieqsa:
// 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,
});
Il-bqija tal-kodiċi sempliċiment jimporta dan il-klijent diġà mibni:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Innota l-estensjoni .js fl-importazzjoni relattiva. B’module: nodenext, TypeScript jeħtieġ l-isem tal-fajl kif se jeżisti wara l-kompilazzjoni, u tsx jaf kif jimmapjah lura għall-fajl .ts. L-ordni tal-importazzjoni hija importanti wkoll: dotenv/config jeżegwixxi qabel mistral-client.js, allura ċ-ċavetta tiġi mħottta meta dak il-modulu jiċċekkja l-preżenza tagħha.
Punti Ewlenin
- Installa l-SDK ta’ TypeScript b’
npm install @mistralai/mistralai - L-importazzjoni ewlenija hija
import { Mistral } from '@mistralai/mistralai' - Installa
typescript,tsx, u@types/nodebħala dipendenzi ta’ żvilupp qabel ma ssejjaħnpx tsc - Uża
module: nodenextu"type": "module"għal kodiċi kkompilat u mbagħad imħaddem minn Node.js; l-importazzjonijiet relattivi jieħdu l-estensjoni.js - Uża fajl
.envb’dotenvbiex timmaniġġja ċ-ċavetta tal-API - L-SDK jipprovdi tipi nativi ta’ TypeScript: sfrutta l-awto-kompletament, u ħalli
tscjiċċekkja dak litsxjaqbeż - Iċċentralizza l-inizjalizzazzjoni tal-klijent f’modulu ddedikat