Namestitev TypeScript SDK za Mistral
Na tej strani
Lekcija posodobljena 3. novembra 2026 po zagonu primerov s SDK
@mistralai/mistralairazličice 3.5.0 in TypeScript 7.0.2. Izvirna različica se ni prevedla. Zagonnpx tscbrez nameščenega TypeScripta prenese opuščen paket npmtsc(različica 2.0.4) namesto prevajalnika. Testna skripta je bila locirana zunaj mapesrc, deklarirane vtsconfig.json. Predmetprocessje prepoznan le s paketom@types/node. Končno, strogi način zavrnemodels.data.lengthinmodel.idbrez predhodnega preverjanja.tsconfig.jsonzdaj sledi scenariju „prevedi, nato zaženi z Node.js” iz uradnega vodnika za TypeScript, Node.js 18 in 20, ki sta dosegla konec življenjske dobe, pa nista več navedena kot zadostna. Viri: Prenesi TypeScript · Izbira možnosti prevajalnika (TypeScript) · Spremembe v TypeScriptu 6.0 · tsx in TypeScript · Podprta izvajalna okolja SDK · Razpored izdaj Node.js.
Zakaj uporabljati TypeScript SDK?
Če tvoj sklad temelji na Node.js, Deno ali Bun, ti TypeScript SDK za Mistral omogoča neposredno integracijo modelov v tvoje aplikacije JavaScript in TypeScript. Izogneš se vmesnim slojem Python ali pisanju prilagojenih klicev HTTP. To je najpogostejši scenarij pri dodajanju umetne inteligence obstoječi spletni aplikaciji: API Express, zaledje Next.js ali delavec Node, ki obdeluje čakalno vrsto sporočil.
Statično tipkanje TypeScripta doda varnostno mrežo, ki se povrne že v prvi uri razvoja. Urejevalnik dopolni imena parametrov, namesto da bi ugibal med maxTokens in max_tokens; napake pri velikosti črk ali izmišljena polja se sprožijo ob času prevajanja, ne v proizvodnji ob 3. uri zjutraj; dokumentacija parametrov pa se prikaže ob lebdenju, ne da bi zapustil datoteko. Ta varnostna mreža je še toliko pomembnejša, ker so odgovori API gnezdeni predmeti, kjer je enostavno spregledati raven.
Predpogoji
SDK cilja na vzdrževane različice LTS za Node.js. Od 3. novembra 2026 so to različice 22, 24 in 26; Node.js 18 in 20 ne prejemata več varnostnih popravkov. Pred nadaljevanjem preveri svojo različico z node --version: SDK se zanaša na module ES in izvorni API fetch. Potrebuješ tudi upravitelja paketov (npm, yarn ali pnpm) ter ključ API Mistral, ki je ustvarjen in na voljo kot okoljska spremenljivka, kot je opisano v prejšnjih lekcijah.
Namestitev
Uradni SDK je objavljen na npm kot @mistralai/mistralai:
# Z npm
npm install @mistralai/mistralai
# Z yarn
yarn add @mistralai/mistralai
# Z pnpm
pnpm add @mistralai/mistralai
Konfiguracija TypeScripta
Če uporabljaš TypeScript – kar priporočamo – namesti tri orodja kot razvojne odvisnosti: prevajalnik, tsx (ki zažene datoteke .ts brez koraka gradnje) in @types/node (ki TypeScriptu opisuje predmete Node.js, kot je process):
npm install -D typescript tsx @types/node
Tega koraka ne preskoči. Brez nameščenega TypeScripta v projektu npx tsc pridobi paket tsc z npm – opuščen legacy prevajalnik (2.0.4) – namesto TypeScripta. Nato projekt deklariraj kot module ES, kot zahteva dokumentacija TypeScripta za kodo, ki je prevedena in nato zagnana z Node.js:
npm pkg set type=module
Nazadnje ustvari tsconfig.json. Uporablja nastavitve, ki jih uradni vodnik za TypeScript priporoča za ta scenarij (module: nodenext). Omogoča tudi strogi način, ki te prisili k obravnavi potencialno manjkajočih vrednosti v odgovorih API – zdrava omejitev – in prevede src/ v dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Tri vrstice si zaslužijo razlago, saj vsaka prepreči napako, na katero smo naleteli med testiranjem te lekcije:
"types": ["node"]naloži tipe Node.js. Od TypeScripta 6.0 paketi@typesniso več samodejno naloženi. Brez te vrsticeprocess.envsproži napako „Cannot find name ‘process’”, tudi če je@types/nodenameščen."rootDir": "src"nastavi korensko mapo za prevedene datoteke:src/test-mistral.tspostanedist/test-mistral.js. Brez tega TypeScript 7 poroča napako TS5011, kadar tvoji viri niso v korenu projekta."skipLibCheck": truepreskoči preverjanje tipov v datotekah z deklaracijami odvisnosti. To je tudi privzeta nastavitev vtsconfig.json, ki ga ustvarinpx tsc --init. Pri SDK 3.5.0 in TypeScriptu 7 izpuščanje tega povzroči napako v lastnih deklaracijah SDK, ki je tvoja koda ne more popraviti.
SDK je objavljen kot moduli ES in vključuje lastne tipe: zanj ni potreben noben paket @types/. Če tvojemu urejevalniku manjka samodejno dopolnjevanje, težava ni v manjkajočem paketu tipov, temveč v tvojem tsconfig.json.
Konfiguracija okoljske spremenljivke
Ključa API nikoli ne vgrajuj neposredno v izvorno kodo. V Node.js je standardna rešitev dotenv, ki naloži spremenljivke iz lokalne datoteke ob zagonu procesa:
npm install dotenv
Ustvari datoteko .env v korenu projekta:
MISTRAL_API_KEY=your-api-key-here
To datoteko takoj dodaj v .gitignore, še pred prvim potrditvijo. Ključi uhajajo prav v tem trenutku:
.env
.env.local
Uvoz dotenv/config mora precediti vsakršno branje process.env. V nasprotnem primeru spremenljivka ostane nedefinirana, ko inicializiraš odjemalca:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Preveri namestitev
Preden napišeš poslovno logiko, potrdi celotno verigo – namestitev, ključ, omrežje – z minimalno skripto. Ustvari src/test-mistral.ts in preprosto zahtevaj seznam modelov, dostopnih tvojemu računu:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Izpiši razpoložljive modele
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, neznan tej različici SDK, je označen kot 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Ti dve preverjanji nista okrasni. SDK deklarira data kot izbirno, vsak vnos na seznamu pa je bodisi osnovna kartica modela, kartica fino uglašenega modela ali neznana vrednost (type: 'UNKNOWN'). Ko API doda novo vrsto modela, jo SDK ohrani v tej obliki namesto, da bi se sesul. Brez teh dveh testov strogi način zavrne prevajanje.
V razvojnem okolju ga zaženi z tsx, ki si ga namestil prej; ta prevaja sproti in ti prihrani korak gradnje:
npx tsx src/test-mistral.ts
Opozorilo: tsx ne preverja tipov; odstrani jih in izvrši kodo. Le tsc poroča napake tipkanja. Za preverjanje brez prevajanja zaženi npx tsc --noEmit. Za prevajanje in nato zagon, kot bo to storila tvoja cevovod gradnje:
npx tsc && node dist/test-mistral.js
Veljaven ključ prikaže število modelov in prvih pet vnosov. Zavrnjen ključ prikaže napako Status 401 (Invalid API Key): veriga deluje, kriv je le ključ.
Organiziraj projekt
Ko preverjanje uspe, strukturiraj projekt tako, da se ključ in odjemalec ne razpršita po datotekah:
mon-projet/
├── src/
│ ├── index.ts # Vstopna točka
│ ├── mistral-client.ts # Inicializacija odjemalca (samotenec)
│ └── utils/
├── .env # Okoljske spremenljivke (ignorirane v git)
├── .gitignore
├── package.json
└── tsconfig.json
Centralizacija inicializacije odjemalca v namenskem modulu prepreči njegovo ponovno ustvarjanje v vsaki datoteki. Še pomembneje: povzroči, da aplikacija odpove ob zagonu in ne šele ob prvem klicu uporabnika, če ključ manjka:
// 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,
});
Preostanek kode preprosto uvozi tega vnaprej zgrajenega odjemalca:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Upoštevaj končnico .js v relativnem uvozu. Pri module: nodenext TypeScript zahteva ime datoteke, kot bo obstajala po prevajanju, tsx pa ve, da jo preslika v datoteko .ts. Pomemben je tudi vrstni red uvoza: dotenv/config se izvrši pred mistral-client.js, zato je ključ naložen, ko ta modul preveri njegovo prisotnost.
Ključne ugotovitve
- Namesti TypeScript SDK z
npm install @mistralai/mistralai - Glavni uvoz je
import { Mistral } from '@mistralai/mistralai' - Namesti
typescript,tsxin@types/nodekot razvojne odvisnosti pred klicemnpx tsc - Uporabi
module: nodenextin"type": "module"za kodo, ki je prevedena in nato zagnana z Node.js; relativni uvozi prevzamejo končnico.js - Uporabi datoteko
.envzdotenvza upravljanje ključa API - SDK zagotavlja izvorne tipe TypeScripta: izkoristi samodejno dopolnjevanje in pusti
tsc, da preveri tisto, kartsxpreskoči - Centraliziraj inicializacijo odjemalca v namenskem modulu