Instaliraj Mistral TypeScript SDK
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. nakon pokretanja primjera sa SDK-om
@mistralai/mistralaiverzije 3.5.0 i TypeScriptom 7.0.2. Izvorna verzija se nije kompajlirala. Pokretanjenpx tscbez instaliranog TypeScripta preuzima napušteni npm pakettsc(verzija 2.0.4) umjesto kompajlera. Test skripta se nalazila izvan mapesrcdeklarirane utsconfig.json. Objektprocessprepoznat je samo uz@types/node. Konačno, strogi način (strict mode) odbijamodels.data.lengthimodel.idbez prethodne validacije.tsconfig.jsonsada slijedi scenarij “kompajliraj pa pokreni s Node.js” iz vodiča za TypeScript, a Node.js 18 i 20, kojima je istekao životni vijek, više nisu navedeni kao dovoljni. Izvori: Preuzmi TypeScript · Odabir opcija kompajlera (TypeScript) · Promjene u TypeScriptu 6.0 · tsx i TypeScript · Podržana izvršna okruženja za SDK · Raspored izdanja Node.jsa.
Zašto koristiti TypeScript SDK?
Ako tvoj stack ovisi o Node.jsu, Denu ili Bunu, Mistral TypeScript SDK omogućuje ti izravnu integraciju modela u tvoje JavaScript i TypeScript aplikacije. Izbjegavaš međuslojeve u Pythonu ili pisanje prilagođenih HTTP poziva. Ovo je najčešći scenarij kada dodaješ AI u postojeću web aplikaciju: Express API, Next.js backend ili Node worker koji obrađuje red poruka.
Statičko tipiziranje TypeScripta dodaje sigurnosnu mrežu koja se isplati već u prvom satu razvoja. Tvoj uređivač dovršava nazive parametara umjesto da nagađaš između maxTokens i max_tokens; pogreške u velikim i malim slovima ili izmišljena polja okidaju se tijekom kompajliranja, a ne u produkciji u 3 ujutro; dokumentacija parametara pojavljuje se na lebdeći pokazivač bez napuštanja datoteke. Ova sigurnosna mreža još je važnija jer su odgovori API-ja ugniježđeni objekti u kojima je lako propustiti razinu.
Preduvjeti
SDK cilja održavane LTS verzije Node.jsa. Zaključno s 3. studenim 2026., to su verzije 22, 24 i 26; Node.js 18 i 20 više ne primaju sigurnosne zakrpe. Provjeri svoju verziju s node --version prije nastavka: SDK se oslanja na ES module i nativni fetch API. Također trebaš upravitelja paketa (npm, yarn ili pnpm) i Mistral API ključ kreiran i dostupan kao varijabla okruženja, kako je obrađeno u prethodnim lekcijama.
Instalacija
Službeni SDK objavljen je na npm-u kao @mistralai/mistralai:
# S npm-om
npm install @mistralai/mistralai
# S yarnom
yarn add @mistralai/mistralai
# S pnpm-om
pnpm add @mistralai/mistralai
Konfiguracija TypeScripta
Ako koristiš TypeScript – što preporučujemo – instaliraj tri alata kao razvojne ovisnosti: kompajler, tsx (koji pokreće .ts datoteke bez koraka izgradnje) i @types/node (koji TypeScriptu opisuje Node.js objekte poput process):
npm install -D typescript tsx @types/node
Nemoj preskočiti ovaj korak. Bez TypeScripta instaliranog u projektu, npx tsc dohvaća paket tsc s npm-a – napušteni legacy kompajler (2.0.4) – umjesto TypeScripta. Zatim, deklariraj projekt kao ES module, kako dokumentacija TypeScripta zahtijeva za kod koji se kompajlira, a zatim pokreće putem Node.jsa:
npm pkg set type=module
Konačno, kreiraj tsconfig.json. Koristi postavke koje službeni vodič za TypeScript preporučuje za ovaj scenarij (module: nodenext). Također omogućuje strogi način (strict mode), koji te prisiljava da rukuješ potencijalno nedostajućim vrijednostima u odgovorima API-ja – zdravo ograničenje – i kompajlira src/ u dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Tri retka zaslužuju objašnjenje, jer svaki sprječava grešku na koju smo naišli tijekom testiranja ove lekcije:
"types": ["node"]učitava Node.js tipove. Od TypeScripta 6.0, paketi@typesviše se ne učitavaju automatski. Bez ovog retka,process.envizaziva grešku “Cannot find name ‘process’”, čak i s instaliranim@types/node."rootDir": "src"postavlja izvorni korijen za kompajlirane datoteke:src/test-mistral.tspostajedist/test-mistral.js. Bez toga, TypeScript 7 prijavljuje grešku TS5011 kad god tvoji izvori nisu u korijenu projekta."skipLibCheck": truepreskače provjeru tipova u deklaracijskim datotekama ovisnosti. Ovo je također zadana postavka utsconfig.jsongeneriranom snpx tsc --init. Sa SDK-om 3.5.0 i TypeScriptom 7, izostavljanje ovoga uzrokuje grešku u vlastitim deklaracijama SDK-a koju tvoj kod ne može popraviti.
SDK je objavljen kao ES modul i uključuje vlastite tipove: nije potreban nikakav paket @types/ za njega. Ako tvom uređivaču nedostaje automatsko dovršavanje, problem leži u tvom tsconfig.json, a ne u nedostajućem paketu tipova.
Konfiguriraj varijablu okruženja
Nikada ne hardkodiraj API ključ u izvornom kodu. U Node.jsu, standardno rješenje je dotenv, koji učitava varijable iz lokalne datoteke pri pokretanju procesa:
npm install dotenv
Kreiraj .env datoteku u korijenu svog projekta:
MISTRAL_API_KEY=tvoj-api-ključ-ovdje
Odmah dodaj ovu datoteku u svoj .gitignore, prije prvog commita. To je točan trenutak kada ključevi cure:
.env
.env.local
Uvoz dotenv/config mora prethoditi svakom čitanju process.env. Inače, varijabla ostaje nedefinirana kada instanciraš klijenta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Provjeri instalaciju
Prije pisanja poslovne logike, validiraj cijeli lanac – instalaciju, ključ, mrežu – s minimalnom skriptom. Kreiraj src/test-mistral.ts i jednostavno zatraži popis modela dostupnih tvom računu:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Popis dostupnih modela
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 modela nepoznat ovoj verziji SDK-a označen je kao 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Ove dvije provjere nisu dekorativne. SDK deklarira data kao opcionalno, a svaki unos na popisu je ili osnovna kartica modela, kartica fino podešenog modela ili nepoznata vrijednost (type: 'UNKNOWN'). Kada API doda novi tip modela, SDK ga zadržava u ovom obliku umjesto da se sruši. Bez ove dvije provjere, strogi način odbija kompajliranje.
U razvoju, pokreni ga s tsx, instaliranim ranije, koji transpilira u letu i štedi ti korak izgradnje:
npx tsx src/test-mistral.ts
Upozorenje: tsx ne provjerava tipove; on ih uklanja i izvršava. Samo tsc prijavljuje greške tipiziranja. Pokreni npx tsc --noEmit za provjeru bez kompajliranja. Za kompajliranje pa pokretanje, kako će to raditi tvoj pipeline izgradnje:
npx tsc && node dist/test-mistral.js
Valjani ključ prikazuje broj modela i prvih pet unosa. Odbijeni ključ prikazuje grešku Status 401 (Invalid API Key): lanac radi, samo je ključ problematičan.
Organiziraj projekt
Kada provjera prođe, strukturiraj projekt tako da se ključ i klijent ne rasprše po datotekama:
mon-projet/
├── src/
│ ├── index.ts # Ulazna točka
│ ├── mistral-client.ts # Inicijalizacija klijenta (singleton)
│ └── utils/
├── .env # Varijable okruženja (git-ignored)
├── .gitignore
├── package.json
└── tsconfig.json
Centraliziranje inicijalizacije klijenta u namjenski modul izbjegava njegovo ponovno kreiranje u svakoj datoteci. Još važnije, to uzrokuje da aplikacija zakaže pri pokretanju, a ne pri prvom pozivu korisnika, ako ključ nedostaje:
// 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,
});
Ostatak koda jednostavno uvozi ovog unaprijed izgrađenog klijenta:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Obrati pažnju na .js ekstenziju u relativnom uvozu. S module: nodenext, TypeScript zahtijeva ime datoteke kakvo će postojati nakon kompajliranja, a tsx zna kako ga mapirati na .ts datoteku. Redoslijed uvoza također je bitan: dotenv/config izvršava se prije mistral-client.js, tako da je ključ učitan kada taj modul provjerava njegovu prisutnost.
Ključne točke
- Instaliraj TypeScript SDK s
npm install @mistralai/mistralai - Glavni uvoz je
import { Mistral } from '@mistralai/mistralai' - Instaliraj
typescript,tsxi@types/nodekao razvojne ovisnosti prije pozivanjanpx tsc - Koristi
module: nodenexti"type": "module"za kod koji se kompajlira, a zatim pokreće putem Node.jsa; relativni uvozi uzimaju.jsekstenziju - Koristi
.envdatoteku sdotenvza upravljanje API ključem - SDK pruža nativne TypeScript tipove: iskoristi automatsko dovršavanje i dopusti
tscda provjeri ono štotsxpreskače - Centraliziraj inicijalizaciju klijenta u namjenski modul