Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Installi Mistrali TypeScript SDK

Õppetund 8 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Miks kasutada TypeScripti SDK-d?
  2. Eeldused
  3. Installimine
  4. TypeScripti konfiguratsioon
  5. Keskkonnamuutuja konfigureerimine
  6. Installimise kontrollimine
  7. Projekti organiseerimine
  8. Peamised punktid

Tund uuendatud 3. novembril 2026 pärast näidiste käivitamist @mistralai/mistralai SDK 3.5.0 ja TypeScript 7.0.2-ga. Algne versioon ei kompileerunud. Käsu npx tsc käivitamine ilma TypeScripti installimata laadib alla mahajäetud tsc npm-paketi (versioon 2.0.4) kompilaatori asemel. Testiskript asus väljaspool tsconfig.json-is määratletud src kausta. Objekti process tuntakse ära ainult koos paketiga @types/node. Lõpuks lükkab range režiim tagasi avaldised models.data.length ja model.id ilma eelneva valideerimiseta. Fail tsconfig.json järgib nüüd TypeScripti juhendi stsenaariumi „kompileeri ja käivita Node.js-iga“ ning Node.js versioone 18 ja 20, mis on jõudnud elutsükli lõppu, ei loeta enam sobivaks. Allikad: Laadi alla TypeScript · Kompilaatori suvandite valimine (TypeScript) · TypeScript 6.0 muudatused · tsx ja TypeScript · SDK toetatud käituskeskkonnad · Node.js väljalaskete ajakava.

Miks kasutada TypeScripti SDK-d?

Kui sinu tehnoloogiline stack põhineb Node.js-il, Denol või Bunil, võimaldab Mistrali TypeScripti SDK integreerida mudeleid otse sinu JavaScripti ja TypeScripti rakendustesse. Sa väldid vahepealseid Pythoni kihte või kohandatud HTTP-päringute kirjutamist. See on kõige levinum stsenaarium tehisintellekti lisamisel olemasolevale veebirakendusele: Expressi API, Next.js-i taustasüsteem või Node’i töötaja, mis töötleb sõnumijärjekorda.

TypeScripti staatiline tüübisüsteem lisab turvavõrgustiku, mis tasub end ära juba arenduse esimese tunni jooksul. Sinu koodiredaktor täiendab parameetrite nimesid, sundimata sind arvama, kas kasutada maxTokens või max_tokens; tähestikuvead või väljamõeldud väljad ilmnevad kompileerimise ajal, mitte tootmises kell 3 hommikul; ja parameetrite dokumentatsioon ilmub hõljutades, ilma failist lahkumata. See turvavõrgustik on seda olulisem, et API vastused on pesastatud objektid, kus on lihtne mõni tase vahele jätta.

Eeldused

SDK on suunatud Node.js-i hooldatavatele LTS-versioonidele. Seisuga 3. november 2026 on need versioonid 22, 24 ja 26; Node.js 18 ja 20 ei saa enam turvaparandusi. Kontrolli oma versiooni käsuga node --version enne jätkamist: SDK tugineb ES-moodulitele ja loomulikule fetch API-le. Samuti vajad paketihaldurit (npm, yarn või pnpm) ja Mistrali API võtit, mis on loodud ja kättesaadav keskkonnamuutujana, nagu eelmistes tundides käsitletud.

Installimine

Ametlik SDK on avaldatud npm-is nime all @mistralai/mistralai:

# npm-iga
npm install @mistralai/mistralai

# yarn-iga
yarn add @mistralai/mistralai

# pnpm-iga
pnpm add @mistralai/mistralai

TypeScripti konfiguratsioon

Kui kasutad TypeScripti – mida soovitame –, installi kolm tööriista arendussõltuvustena: kompilaator, tsx (mis käivitab .ts faile ilma kompileerimisetapita) ja @types/node (mis kirjeldab TypeScriptile Node.js-i objekte nagu process):

npm install -D typescript tsx @types/node

Ära jäta seda sammu vahele. Ilma projektis installitud TypeScriptita hangib npx tsc npm-ist paketi tsc – mahajäetud vana kompilaatori (2.0.4) – TypeScripti asemel. Järgmiseks deklareeri projekt ES-moodulina, nagu TypeScripti dokumentatsioon nõuab koodi jaoks, mis kompileeritakse ja seejärel käivitatakse Node.js-i poolt:

npm pkg set type=module

Lõpuks loo fail tsconfig.json. See kasutab seadeid, mida ametlik TypeScripti juhend selle stsenaariumi jaoks soovitab (module: nodenext). Samuti lubab see range režiimi, mis sunnib sind käsitlema API vastustes potentsiaalselt puuduvaid väärtusi – tervislik piirang – ja kompileerib kausta src/ kausta dist/:

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

Kolm rida väärivad selgitust, kuna üks neist hoiab ära vea, millega selle tunni testimisel kokku puutusime:

  • "types": ["node"] laadib Node.js-i tüübid. Alates TypeScript 6.0-st ei laadita @types pakette enam automaatselt. Ilma selle realt käivitab process.env vea „Cannot find name ‘process’“, isegi kui @types/node on installitud.
  • "rootDir": "src" määrab kompileeritud failide allikajuure: src/test-mistral.ts muutub dist/test-mistral.js-iks. Ilma selleta teatab TypeScript 7 veast TS5011 iga kord, kui sinu lähtekood ei asu projekti juurkaustas.
  • "skipLibCheck": true jätab vahele sõltuvuste deklaratsioonifailide tüübikontrolli. See on ka vaikeseade tsconfig.json-is, mille genereerib npx tsc --init. SDK 3.5.0 ja TypeScript 7 korral põhjustab selle väljajätmine vea SDK enda deklaratsioonides, mida sinu kood parandada ei saa.

SDK on avaldatud ES-moodulina ja sisaldab oma tüüpe: selle jaoks ei ole vaja @types/ paketti. Kui sinu redaktoris puudub automaatne täitmine, peitub viga sinu tsconfig.json-is, mitte puuduvas tüüpide paketis.

Keskkonnamuutuja konfigureerimine

Ära kunagi kodeeri API võtit otse oma lähtekoodi. Node.js-is on standardlahenduseks dotenv, mis laadib muutujad kohalikust failist protsessi käivitamisel:

npm install dotenv

Loo projekti juurkausta fail .env:

MISTRAL_API_KEY=sinu-api-võti-siia

Lisa see fail oma .gitignore-i viivitamatult, enne esimest commit’i. Just sel hetkel lekivad võtmed:

.env
.env.local

Import dotenv/config peab eelnema igale process.env lugemisele. Vastasel juhul jääb muutuja kliendi loomisel määratlemata:

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

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

Installimise kontrollimine

Enne äriloogika kirjutamist valideeri kogu ahel – installimine, võti, võrk – minimaalse skriptiga. Loo fail src/test-mistral.ts ja küsi lihtsalt oma kontole juurdepääsetavate mudelite loendit:

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

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

  // Loetle saadaolevad mudelid
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Selle SDK versiooni jaoks tundmatu mudelitüüp on märgitud kui 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Need kaks kontrolli ei ole dekoratiivsed. SDK deklareerib data valikuliseks ja iga loendi kirje on kas baasmudeli kaart, häälestatud mudeli kaart või tundmatu väärtus (type: 'UNKNOWN'). Kui API lisab uue mudelitüübi, säilitab SDK selle selles vormis, selle asemel et kokku kukkuda. Ilma nende kahe testita keeldub range režiim kompileerimast.

Arenduskeskkonnas käivita see tsx-iga, mille installisid varem; see transpileerib reaalajas ja säästab sind kompileerimisetapist:

npx tsx src/test-mistral.ts

Hoiatus: tsx ei kontrolli tüüpe; see eemaldab need ja käivitab koodi. Ainult tsc teatab tüübivigadest. Käivita npx tsc --noEmit, et kontrollida ilma kompileerimata. Kompileerimiseks ja seejärel käivitamiseks, nagu sinu koostetorustik teeb:

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

Kehtiv võti kuvab mudelite arvu ja esimesed viis kirjet. Tagasilükatud võti kuvab vea Status 401 (Invalid API Key): ahel töötab, süüdi on ainult võti.

Projekti organiseerimine

Kui kontrollimine õnnestub, struktureeri projekt nii, et võti ja klient ei oleks failides laiali pillutatud:

mon-projet/
├── src/
│   ├── index.ts          # Sisendpunkt
│   ├── mistral-client.ts # Kliendi initsialiseerimine (singleton)
│   └── utils/
├── .env                  # Keskkonnamuutujad (git-ignored)
├── .gitignore
├── package.json
└── tsconfig.json

Kliendi initsialiseerimise tsentraliseerimine eraldi moodulisse hoiab ära selle uuesti loomise igas failis. Veelgi olulisem on see, et rakendus ebaõnnestub käivitamisel, mitte esimese kasutajakutsu ajal, kui võti puudub:

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

Ülejäänud kood impordib lihtsalt selle eelvalmistatud kliendi:

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

Pane tähele .js laiendit suhtelises importimises. Sättega module: nodenext nõuab TypeScript failinime nii, nagu see pärast kompileerimist eksisteerib, ja tsx teab, kuidas see .ts failile kaardistada. Importimise järjekord on samuti oluline: dotenv/config käivitub enne mistral-client.js, nii et võti on laaditud, kui see moodul kontrollib selle olemasolu.

Peamised punktid

  • Installi TypeScripti SDK käsuga npm install @mistralai/mistralai
  • Peamine import on import { Mistral } from '@mistralai/mistralai'
  • Installi typescript, tsx ja @types/node arendussõltuvustena enne käsu npx tsc kasutamist
  • Kasuta module: nodenext ja "type": "module" koodi jaoks, mille kompileerib ja käivitab Node.js; suhtelised importimised võtavad .js laiendi
  • Kasuta API võtme haldamiseks .env faili koos dotenv-iga
  • SDK pakub loomulikke TypeScripti tüüpe: kasuta automaatset täitmist ja lase tsc-il kontrollida seda, mida tsx vahele jätab
  • Tsentraliseeri kliendi initsialiseerimine eraldi moodulisse