Inštalácia TypeScript SDK pre Mistral
Na tejto strane
Lekcia aktualizovaná 3. novembra 2026 po spustení príkladov so SDK
@mistralai/mistralaiverzie 3.5.0 a TypeScriptom 7.0.2. Pôvodná verzia sa nekompilovala. Spustenienpx tscbez nainštalovaného TypeScriptu stiahne opustený balík npmtsc(verzia 2.0.4) namiesto kompilátora. Testovací skript sa nachádzal mimo priečinkasrcdeklarovaného vtsconfig.json. Objektprocessje rozpoznaný až s@types/node. Nakoniec, striktný režim odmietamodels.data.lengthamodel.idbez predchádzajúcej validácie.tsconfig.jsonteraz nasleduje scenár „skompiluj a potom spusti s Node.js“ z príručky TypeScriptu a Node.js 18 a 20, ktoré dosiahli koniec životnosti, už nie sú uvedené ako dostatočné. Zdroje: Stiahnuť TypeScript · Výber možností kompilátora (TypeScript) · Zmeny v TypeScriptu 6.0 · tsx a TypeScript · Podporované behové prostredia SDK · Harmonóm vydaní Node.js.
Prečo používať TypeScript SDK?
Ak tvoj stack závisí od Node.js, Deno alebo Bun, TypeScript SDK pre Mistral ti umožňuje integrovať modely priamo do tvojich aplikácií v JavaScripte a TypeScriptu. Vyhneš sa tak medzivrstvám v Pythone alebo písaniu vlastných HTTP volaní. Toto je najbežnejší scenár pri pridávaní umelej inteligencie do existujúcej webovej aplikácie: Express API, backend v Next.js alebo Node worker spracúvajúci frontu správ.
Statické typovanie v TypeScripte pridáva bezpečnostnú sieť, ktorá sa vypláca už v prvej hodine vývoja. Tvoj editor dopĺňa názvy parametrov namiesto toho, aby si hádal medzi maxTokens a max_tokens; chyby v písaní alebo vymyslené polia sa objavia už pri kompilácii, nie v produkcii o tretej ráno; a dokumentácia parametrov sa zobrazí po nabehnutí kurzorom bez opustenia súboru. Táto bezpečnostná sieť je ešte dôležitejšia, pretože odpovede API sú vnorené objekty, kde je ľahké prehliadnuť úroveň.
Predpoklady
SDK cieli na udržiavané LTS verzie Node.js. K 3. novembru 2026 sú to verzie 22, 24 a 26; Node.js 18 a 20 už nedostávajú bezpečnostné záplaty. Skontroluj svoju verziu príkazom node --version predtým, než budeš pokračovať: SDK sa spolieha na ES moduly a natívne API fetch. Potrebuješ tiež správcu balíkov (npm, yarn alebo pnpm) a kľúč API pre Mistral, ktorý je vytvorený a dostupný ako premenná prostredia, ako bolo pokryté v predchádzajúcich lekciách.
Inštalácia
Oficiálne SDK je publikované na npm ako @mistralai/mistralai:
# S npm
npm install @mistralai/mistralai
# S yarn
yarn add @mistralai/mistralai
# S pnpm
pnpm add @mistralai/mistralai
Konfigurácia TypeScriptu
Ak používaš TypeScript – čo odporúčame – nainštaluj tri nástroje ako vývojové závislosti: kompilátor, tsx (ktorý spúšťa súbory .ts bez kroku zostavenia) a @types/node (ktorý popisuje objekty Node.js ako process pre TypeScript):
npm install -D typescript tsx @types/node
Tento krok nevynechávaj. Bez nainštalovaného TypeScriptu v projekte npx tsc stiahne balík tsc z npm – opustený legacy kompilátor (2.0.4) – namiesto TypeScriptu. Ďalej deklaruj projekt ako ES moduly, ako vyžaduje dokumentácia TypeScriptu pre kód skompilovaný a potom spustený Node.js:
npm pkg set type=module
Nakoniec vytvor tsconfig.json. Používa nastavenia, ktoré oficiálna príručka TypeScriptu odporúča pre tento scenár (module: nodenext). Tiež povoľuje striktný režim, ktorý ťa núti riešiť potenciálne chýbajúce hodnoty v odpovediach API – čo je zdravé obmedzenie – a kompiluje src/ do dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Tri riadky si zaslúžia vysvetlenie, keďže každý z nich predchádza chybe, na ktorú sme narazili pri testovaní tejto lekcie:
"types": ["node"]načíta typy Node.js. Od TypeScriptu 6.0 sa balíky@typesuž nenačítavajú automaticky. Bez tohto riadkuprocess.envvyvolá chybu „Cannot find name ‘process’“, aj keď je nainštalovaný@types/node."rootDir": "src"nastavuje koreňový adresár zdrojových súborov pre skompilované súbory:src/test-mistral.tssa stanedist/test-mistral.js. Bez toho TypeScript 7 hlási chybu TS5011 vždy, keď tvoje zdroje nie sú v koreňovom adresári projektu."skipLibCheck": truepreskočí kontrolu typov v deklaračných súboroch závislostí. Toto je tiež predvolené nastavenie vtsconfig.jsongenerovanom príkazomnpx tsc --init. Pri SDK 3.5.0 a TypeScriptu 7 vynechanie tohto nastavenia spôsobí chybu vo vlastných deklaráciách SDK, ktorú tvoj kód nemôže opraviť.
SDK je publikované ako ES moduly a obsahuje vlastné typy: nie je potrebný žiadny balík @types/. Ak ti editor nenabíza automatické dopĺňanie, problém je v tvojom tsconfig.json, nie v chýbajúcom balíku typov.
Konfigurácia premennej prostredia
Nikdy neukladaj kľúč API natvrdo do zdrojového kódu. V Node.js je štandardným riešením dotenv, ktorý načíta premenné z lokálneho súboru pri štarte procesu:
npm install dotenv
Vytvor súbor .env v koreňovom adresári tvojho projektu:
MISTRAL_API_KEY=tvoj-api-kľúč-tu
Okamžite pridaj tento súbor do .gitignore, ešte pred prvým commitom. Toto je presný moment, kedy unikajú kľúče:
.env
.env.local
Import dotenv/config musí predchádzať akémukoľvek čítaniu process.env. Inak zostane premenná nedefinovaná, keď inštancuješ klienta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Overenie inštalácie
Pred písaním business logiky over celý reťazec – inštaláciu, kľúč, sieť – pomocou minimálneho skriptu. Vytvor src/test-mistral.ts a jednoducho požiadaj o zoznam modelov dostupných pre tvoj účet:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Zoznam dostupných modelov
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Available models: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Typ modelu neznámy pre túto verziu SDK je označený ako 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Tieto dve kontroly nie sú len ozdobné. SDK deklaruje data ako voliteľné a každá položka zoznamu je buď základná karta modelu, karta doladeného modelu, alebo neznáma hodnota (type: 'UNKNOWN'). Keď API pridá nový typ modelu, SDK ho zachová v tejto forme namiesto pádu. Bez týchto dvoch testov striktný režim odmietne kompiláciu.
Vo vývoji ho spusti pomocou tsx, ktoré sme nainštalovali skôr; transpiluje za behu a šetrí ti krok zostavenia:
npx tsx src/test-mistral.ts
Upozornenie: tsx nekontroluje typy; odstráni ich a vykoná kód. Iba tsc hlási chyby v typovaní. Na kontrolu bez kompilácie spusti npx tsc --noEmit. Na skompilovanie a následné spustenie, ako to urobí tvoj build pipeline:
npx tsc && node dist/test-mistral.js
Platný kľúč zobrazí počet modelov a prvých päť položiek. Zamietnutý kľúč zobrazí chybu Status 401 (Invalid API Key): reťazec funguje, chyba je len v kľúči.
Organizácia projektu
Akonáhle overenie prebehne úspešne, štruktúruj projekt tak, aby sa kľúč a klient neroztrieštili po súboroch:
mon-projet/
├── src/
│ ├── index.ts # Vstupný bod
│ ├── mistral-client.ts # Inicializácia klienta (singleton)
│ └── utils/
├── .env # Premenné prostredia (ignorované gitom)
├── .gitignore
├── package.json
└── tsconfig.json
Centralizácia inicializácie klienta do vyhradeného modulu predchádza jeho opätovnému vytváraniu v každom súbore. Ešte dôležitejšie je, že to spôsobí zlyhanie aplikácie pri štarte, a nie až pri prvom volaní používateľa, ak chýba kľúč:
// 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,
});
Zvyšok kódu jednoducho importuje tohto predpripraveného klienta:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Všimni si príponu .js v relatívnom importe. Pri module: nodenext TypeScript vyžaduje názov súboru tak, ako bude existovať po skompilovaní, a tsx vie, že ho má namapovať na súbor .ts. Poradie importov tiež záleží: dotenv/config sa vykoná pred mistral-client.js, takže kľúč je načítaný v momente, keď tento modul kontroluje jeho prítomnosť.
Kľúčové poznatky
- Nainštaluj TypeScript SDK príkazom
npm install @mistralai/mistralai - Hlavný import je
import { Mistral } from '@mistralai/mistralai' - Nainštaluj
typescript,tsxa@types/nodeako vývojové závislosti pred volanímnpx tsc - Použi
module: nodenexta"type": "module"pre kód skompilovaný a potom spustený Node.js; relatívne importy berú príponu.js - Použi súbor
.envsdotenvna správu kľúča API - SDK poskytuje natívne typy TypeScriptu: využívaj automatické dopĺňanie a nechaj
tsckontrolovať to, čotsxpreskakuje - Centralizuj inicializáciu klienta do vyhradeného modulu