Salt la conținutul principal
Română— Alege o limbă
Meniu

Instalarea SDK-ului TypeScript Mistral

Lecția 8 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De ce să utilizați SDK-ul TypeScript?
  2. Condiții prealabile
  3. Instalare
  4. Configurare TypeScript
  5. Configurarea variabilei de mediu
  6. Verificarea instalării
  7. Organizarea proiectului
  8. Puncte cheie

Lecție actualizată la 3 noiembrie 2026 după rularea exemplelor cu SDK-ul @mistralai/mistralai versiunea 3.5.0 și TypeScript 7.0.2. Versiunea originală nu se compila. Rularea comenzii npx tsc fără ca TypeScript să fie instalat descarcă pachetul npm abandonat tsc (versiunea 2.0.4) în locul compilatorului propriu-zis. Scriptul de test se afla în afara dosarului src declarat în tsconfig.json. Obiectul process este recunoscut doar cu @types/node. În final, modul strict respinge models.data.length și model.id fără o validare prealabilă. Fișierul tsconfig.json respectă acum scenariul „compilează apoi rulează cu Node.js“ din ghidul TypeScript, iar versiunile Node.js 18 și 20, care au ajuns la sfârșitul ciclului de viață, nu mai sunt listate ca fiind suficiente. Surse: Descărcare TypeScript · Alegerea opțiunilor compilatorului (TypeScript) · Modificări TypeScript 6.0 · tsx și TypeScript · Runtimuri suportate de SDK · Calendarul lansărilor Node.js.

De ce să utilizați SDK-ul TypeScript?

Dacă stiva dumneavoastră tehnologică se bazează pe Node.js, Deno sau Bun, SDK-ul TypeScript Mistral vă permite să integrați modelele direct în aplicațiile JavaScript și TypeScript. Evitați astfel straturile intermediare Python sau scrierea de apeluri HTTP personalizate. Acesta este scenariul cel mai frecvent atunci când adăugați inteligență artificială unei aplicații web existente: un API Express, un backend Next.js sau un worker Node care procesează o coadă de mesaje.

Tipizarea statică din TypeScript adaugă o plasă de siguranță care își dovedește utilitatea în prima oră de dezvoltare. Editorul completează numele parametrilor în loc să vă oblige să ghiciți între maxTokens și max_tokens; erorile de capitalizare sau câmpurile inventate sunt semnalate la compilare, nu în producție la ora 3 dimineața; iar documentația parametrilor apare la trecerea cursorului peste ele, fără a părăsi fișierul. Această plasă de siguranță este cu atât mai importantă deoarece răspunsurile API sunt obiecte imbricate, unde este ușor să omiteți un nivel.

Condiții prealabile

SDK-ul țintește versiunile LTS (Long Term Support) întreținute ale Node.js. La data de 3 noiembrie 2026, acestea sunt versiunile 22, 24 și 26; Node.js 18 și 20 nu mai primesc patch-uri de securitate. Verificați versiunea cu node --version înainte de a continua: SDK-ul se bazează pe module ES și pe API-ul nativ fetch. Aveți nevoie, de asemenea, de un manager de pachete (npm, yarn sau pnpm) și de o cheie API Mistral creată și disponibilă ca variabilă de mediu, așa cum s-a prezentat în lecțiile anterioare.

Instalare

SDK-ul oficial este publicat pe npm sub numele @mistralai/mistralai:

# Cu npm
npm install @mistralai/mistralai

# Cu yarn
yarn add @mistralai/mistralai

# Cu pnpm
pnpm add @mistralai/mistralai

Configurare TypeScript

Dacă utilizați TypeScript – ceea ce recomandăm – instalați trei instrumente ca dependențe de dezvoltare: compilatorul, tsx (care rulează fișiere .ts fără o etapă de build) și @types/node (care descrie obiectele Node.js, precum process, pentru TypeScript):

npm install -D typescript tsx @types/node

Nu săriți peste acest pas. Fără TypeScript instalat în proiect, comanda npx tsc preia pachetul tsc de pe npm – un compilator legacy abandonat (2.0.4) – în locul TypeScript. În continuare, declarați proiectul ca module ES, așa cum cere documentația TypeScript pentru codul compilat și apoi rulat de Node.js:

npm pkg set type=module

În final, creați tsconfig.json. Acesta utilizează setările recomandate de ghidul oficial TypeScript pentru acest scenariu (module: nodenext). De asemenea, activează modul strict, care vă obligă să gestionați valorile potențial lipsă din răspunsurile API – o constrângere sănătoasă – și compilează src/ în dist/:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "skipLibCheck": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

Trei linii merită explicate, deoarece fiecare previne o eroare întâlnită în timpul testării acestei lecții:

  • "types": ["node"] încarcă tipurile Node.js. Începând cu TypeScript 6.0, pachetele @types nu mai sunt încărcate automat. Fără această linie, process.env declanșează eroarea „Cannot find name ‘process’“, chiar și cu @types/node instalat.
  • "rootDir": "src" setează rădăcina sursă pentru fișierele compilate: src/test-mistral.ts devine dist/test-mistral.js. Fără aceasta, TypeScript 7 raportează eroarea TS5011 ori de câte ori sursele nu se află la rădăcina proiectului.
  • "skipLibCheck": true sare peste verificarea tipurilor pentru fișierele de declarație ale dependențelor. Aceasta este, de asemenea, o setare implicită în tsconfig.json generat de npx tsc --init. Cu SDK-ul 3.5.0 și TypeScript 7, omiterea acesteia provoacă o eroare în propriile declarații ale SDK-ului pe care codul dumneavoastră nu o poate remedia.

SDK-ul este publicat ca module ES și își include propriile tipuri: nu este nevoie de niciun pachet @types/ pentru el. Dacă editorul dumneavoastră nu oferă auto-completare, problema se află în tsconfig.json, nu într-un pachet de tipuri lipsă.

Configurarea variabilei de mediu

Nu introduceți niciodată cheia API direct în codul sursă. În Node.js, soluția standard este dotenv, care încarcă variabilele dintr-un fișier local la pornirea procesului:

npm install dotenv

Creați un fișier .env la rădăcina proiectului:

MISTRAL_API_KEY=your-api-key-here

Adăugați acest fișier în .gitignore imediat, înainte de primul commit. Acesta este momentul exact în care cheile sunt expuse accidental:

.env
.env.local

Importul dotenv/config trebuie să precede orice citire a lui process.env. În caz contrar, variabila rămâne nedefinită atunci când instanțiați clientul:

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

Verificarea instalării

Înainte de a scrie logica de afaceri, validați întregul lanț – instalare, cheie, rețea – cu un script minimal. Creați src/test-mistral.ts și solicitați simplu lista de modele accesibile contului dumneavoastră:

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

async function main() {
  const client = new Mistral({
    apiKey: process.env.MISTRAL_API_KEY,
  });

  // Listează modelele disponibile
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Un tip de model necunoscut acestei versiuni de SDK este marcat 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Aceste două verificări nu sunt decorative. SDK-ul declară data ca opțional, iar fiecare intrare din listă este fie o fișă de model de bază, fie o fișă de model finisat (fine-tuned), fie o valoare necunoscută (type: 'UNKNOWN'). Când API-ul adaugă un nou tip de model, SDK-ul îl păstrează sub această formă în loc să crapeze. Fără aceste două teste, modul strict refuză compilarea.

În dezvoltare, rulați-l cu tsx, instalat anterior, care transpilează din mers și vă scutește de o etapă de build:

npx tsx src/test-mistral.ts

Atenție: tsx nu verifică tipurile; le elimină și execută codul. Doar tsc raportează erorile de tipizare. Rulați npx tsc --noEmit pentru a verifica fără a compila. Pentru a compila și apoi rula, așa cum va face pipeline-ul de build:

npx tsc && node dist/test-mistral.js

O cheie validă afișează numărul de modele și primele cinci intrări. O cheie respinsă afișează o eroare Status 401 (Invalid API Key): lanțul funcționează, doar cheia este eronată.

Organizarea proiectului

Odată ce verificarea a reușit, structurați proiectul astfel încât cheia și clientul să nu fie dispersate în mai multe fișiere:

mon-projet/
├── src/
│   ├── index.ts          # Punct de intrare
│   ├── mistral-client.ts # Inițializarea clientului (singleton)
│   └── utils/
├── .env                  # Variabile de mediu (ignorate de git)
├── .gitignore
├── package.json
└── tsconfig.json

Centralizarea inițializării clientului într-un modul dedicat evită recrearea acestuia în fiecare fișier. Mai important, face ca aplicația să eșueze la pornire, și nu la primul apel al utilizatorului, dacă cheia lipsește:

// 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,
});

Restul codului importă simplu acest client pre-construit:

// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';

Observați extensia .js în importul relativ. Cu module: nodenext, TypeScript cere numele fișierului așa cum va exista acesta după compilare, iar tsx știe să îl mapese la fișierul .ts. Ordinea importurilor contează, de asemenea: dotenv/config se execută înainte de mistral-client.js, astfel încât cheia este încărcată atunci când acel modul verifică prezența ei.

Puncte cheie

  • Instalați SDK-ul TypeScript cu npm install @mistralai/mistralai
  • Importul principal este import { Mistral } from '@mistralai/mistralai'
  • Instalați typescript, tsx și @types/node ca dependențe de dezvoltare înainte de a apela npx tsc
  • Utilizați module: nodenext și "type": "module" pentru codul compilat și apoi rulat de Node.js; importurile relative primesc extensia .js
  • Utilizați un fișier .env cu dotenv pentru a gestiona cheia API
  • SDK-ul oferă tipuri native TypeScript: profitați de auto-completare și lăsați tsc să verifice ceea ce tsx omite
  • Centralizați inițializarea clientului într-un modul dedicat