Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Namestitev TypeScript SDK za Mistral

Lekcija 8 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Zakaj uporabljati TypeScript SDK?
  2. Predpogoji
  3. Namestitev
  4. Konfiguracija TypeScripta
  5. Konfiguracija okoljske spremenljivke
  6. Preveri namestitev
  7. Organiziraj projekt
  8. Ključne ugotovitve

Lekcija posodobljena 3. novembra 2026 po zagonu primerov s SDK @mistralai/mistralai različice 3.5.0 in TypeScript 7.0.2. Izvirna različica se ni prevedla. Zagon npx tsc brez nameščenega TypeScripta prenese opuščen paket npm tsc (različica 2.0.4) namesto prevajalnika. Testna skripta je bila locirana zunaj mape src, deklarirane v tsconfig.json. Predmet process je prepoznan le s paketom @types/node. Končno, strogi način zavrne models.data.length in model.id brez predhodnega preverjanja. tsconfig.json zdaj 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 @types niso več samodejno naloženi. Brez te vrstice process.env sproži napako „Cannot find name ‘process’”, tudi če je @types/node nameščen.
  • "rootDir": "src" nastavi korensko mapo za prevedene datoteke: src/test-mistral.ts postane dist/test-mistral.js. Brez tega TypeScript 7 poroča napako TS5011, kadar tvoji viri niso v korenu projekta.
  • "skipLibCheck": true preskoči preverjanje tipov v datotekah z deklaracijami odvisnosti. To je tudi privzeta nastavitev v tsconfig.json, ki ga ustvari npx 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, tsx in @types/node kot razvojne odvisnosti pred klicem npx tsc
  • Uporabi module: nodenext in "type": "module" za kodo, ki je prevedena in nato zagnana z Node.js; relativni uvozi prevzamejo končnico .js
  • Uporabi datoteko .env z dotenv za upravljanje ključa API
  • SDK zagotavlja izvorne tipe TypeScripta: izkoristi samodejno dopolnjevanje in pusti tsc, da preveri tisto, kar tsx preskoči
  • Centraliziraj inicializacijo odjemalca v namenskem modulu