Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Installazzjoni tal-SDK ta' Mistral għat-TypeScript

Lezzjoni 8 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Għaliex tuża l-SDK ta’ TypeScript?
  2. Prerekwiżiti
  3. Installazzjoni
  4. Konfigurazzjoni ta’ TypeScript
  5. Ikkonfigura l-Varjabbli tal-Ambjent
  6. Ivverifika l-Installazzjoni
  7. Organizza l-Proġett
  8. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru, 2026 wara li tħaddmu l-eżempji bl-SDK @mistralai/mistralai 3.5.0 u TypeScript 7.0.2. Il-verżjoni oriġinali ma kinitx tikkompileja. Meta tħaddem npx tsc mingħajr TypeScript installat, dan jinżel il-pakkett tsc npm abbandunat (verżjoni 2.0.4) minflok il-kompilatur. Is-skript tat-test kien jinsab barra mill-folder src iddikjarat f’tsconfig.json. L-oġġett process jiġi rikonoxxut biss b’@types/node. Fl-aħħar nett, il-modalità stretta (strict mode) tiċħad models.data.length u model.id mingħajr validazzjoni minn qabel. Il-tsconfig.json issa 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 @types ma jitgħabbewx awtomatikament. Mingħajr din il-linja, process.env iwassal għall-iżball “Cannot find name ‘process’”, anke jekk @types/node ikun installat.
  • "rootDir": "src" jistabbilixxi r-raġuni tas-sors għall-fajls ikkompilati: src/test-mistral.ts isir dist/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": true jaqbeż iċ-ċekkjar tat-tipi għall-fajls tad-dikjarazzjoni tad-dipendenzi. Din hija wkoll setting predefinit f’tsconfig.json iġġenerat minn npx 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/node bħala dipendenzi ta’ żvilupp qabel ma ssejjaħ npx tsc
  • Uża module: nodenext u "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 .env b’dotenv biex timmaniġġja ċ-ċavetta tal-API
  • L-SDK jipprovdi tipi nativi ta’ TypeScript: sfrutta l-awto-kompletament, u ħalli tsc jiċċekkja dak li tsx jaqbeż
  • Iċċentralizza l-inizjalizzazzjoni tal-klijent f’modulu ddedikat