Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

A Mistral TypeScript SDK telepítése

8. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Miért használd a TypeScript SDK-t?
  2. Előfeltételek
  3. Telepítés
  4. TypeScript konfiguráció
  5. Környezeti változó konfigurálása
  6. A telepítés ellenőrzése
  7. A projekt szervezése
  8. Főbb megállapítások

A leckét 2026. november 3-án frissítettük, miután a példákat lefuttattuk a @mistralai/mistralai SDK 3.5.0 és a TypeScript 7.0.2 verziójával. Az eredeti verzió nem fordult le. A npx tsc parancs futtatása a TypeScript telepítése nélkül az elhagyatott tsc npm csomagot (2.0.4-es verzió) tölti le a fordító helyett. A tesztelő szkript a tsconfig.json fájlban deklarált src mappán kívül helyezkedett el. A process objektum csak a @types/node csomaggal ismerhető fel. Végül a szigorú mód elutasítja a models.data.length és a model.id hivatkozásokat előzetes validálás nélkül. A tsconfig.json most a TypeScript útmutató „fordítás, majd futtatás Node.js-szel“ forgatókönyvét követi, és a Node.js 18-as és 20-as verziói, amelyek elérték az életciklusuk végét, már nem szerepelnek megfelelőként. Források: TypeScript letöltése · Fordítási beállítások kiválasztása (TypeScript) · TypeScript 6.0 változásai · tsx és TypeScript · SDK által támogatott futási környezetek · Node.js kiadási ütemterv.

Miért használd a TypeScript SDK-t?

Ha a technológiai stacked Node.js-re, Denóra vagy Bunra épül, a Mistral TypeScript SDK lehetővé teszi, hogy a modelleket közvetlenül integráld JavaScript és TypeScript alkalmazásaiddal. Így elkerülheted a köztes Python rétegeket vagy az egyedi HTTP-hívások megírását. Ez a leggyakoribb forgatókönyv, amikor AI-t adsz hozzá egy meglévő webalkalmazáshoz: legyen szó egy Express API-ról, egy Next.js backendről vagy egy üzenetsort feldolgozó Node munkafolyamatról.

A TypeScript statikus típusossága olyan biztonsági hálót jelent, amely már a fejlesztés első órájában megtérül. A szerkesztőd kiegészíti a paraméterneveket, így nem kell találgatnod a maxTokens és a max_tokens között; a nagybetűhibák vagy a kitalált mezők fordítási időben jeleznek hibát, nem pedig éjjel 3-kor éles környezetben; a paraméterek dokumentációja pedig az egérmutató alá húzáskor jelenik meg, anélkül, hogy elhagynád a fájlt. Ez a biztonsági háló annál is fontosabb, mert az API-válaszok beágyazott objektumok, ahol könnyű elrontani egy szintet.

Előfeltételek

Az SDK a karbantartott LTS (hosszú távú támogatású) Node.js verziókat célozza meg. 2026. november 3-án ezek a 22-es, 24-es és 26-os verziók; a Node.js 18 és 20 már nem kap biztonsági javításokat. Mielőtt folytatnád, ellenőrizd a verziódat a node --version paranccsal: az SDK az ES modulokra és a natív fetch API-ra támaszkik. Szükséged lesz továbbá egy csomagkezelőre (npm, yarn vagy pnpm) és egy Mistral API-kulcsra, amelyet létrehoztál és környezeti változóként elérhetővé tettél, ahogy azt a korábbi leckékben tárgyaltuk.

Telepítés

A hivatalos SDK az @mistralai/mistralai néven érhető el az npm-en:

# npm-mel
npm install @mistralai/mistralai

# yarn-nal
yarn add @mistralai/mistralai

# pnpm-nel
pnpm add @mistralai/mistralai

TypeScript konfiguráció

Ha TypeScriptet használsz – amit ajánlunk –, telepítsd a következő három eszközt fejlesztési függőségként: a fordítót, a tsx-et (amely build lépés nélkül futtatja a .ts fájlokat) és az @types/node-ot (amely leírja a Node.js objektumokat, mint például a process a TypeScript számára):

npm install -D typescript tsx @types/node

Ne hagyd ki ezt a lépést. Ha a TypeScript nincs telepítve a projektben, az npx tsc parancs a tsc csomagot tölti le az npm-ről – egy elhagyatott, régi fordítót (2.0.4) – a TypeScript helyett. Ezután deklaráld a projektet ES modulokként, ahogy azt a TypeScript dokumentációja előírja a Node.js által futtatott kód fordításához:

npm pkg set type=module

Végül hozd létre a tsconfig.json fájlt. Ez azokat a beállításokat használja, amelyeket a hivatalos TypeScript útmutató javasol ehhez a forgatókönyvhöz (module: nodenext). Emellett engedélyezi a szigorú módot, amely rákényszerít, hogy kezeld a potenciálisan hiányzó értékeket az API-válaszokban – ez egészséges kényszer –, és a src/ mappát a dist/ mappába fordítja:

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

Három sor magyarázatra szorul, mivel mindegyik egy olyan hibát előz meg, amellyel a lecke tesztelése során találkoztunk:

  • A "types": ["node"] betölti a Node.js típusokat. A TypeScript 6.0 óta az @types csomagok már nem töltődnek be automatikusan. E sor nélkül a process.env a „Cannot find name ‘process’“ hibaüzenetet váltja ki, még akkor is, ha az @types/node telepítve van.
  • A "rootDir": "src" beállítja a forrásfájlok gyökérkönyvtárát a fordított fájlokhoz: a src/test-mistral.ts fájlból dist/test-mistral.js lesz. Enélkül a TypeScript 7 TS5011 hibát jelez, ha a forrásfájljaid nem a projekt gyökerében vannak.
  • A "skipLibCheck": true kihagyja a függőségi deklarációs fájlok típusellenőrzését. Ez az npx tsc --init által generált tsconfig.json alapértelmezett beállítása is. Az SDK 3.5.0 és a TypeScript 7 esetén ennek elhagyása hibát okoz az SDK saját deklarációiban, amelyet a kódod nem tud javítani.

Az SDK ES modulokként jelenik meg, és tartalmazza a saját típusait: nincs szükség hozzá @types/ csomagra. Ha a szerkesztőd nem kínál automatikus kiegészítést, a hiba a tsconfig.json fájlodban rejlik, nem egy hiányzó típuscsomagban.

Környezeti változó konfigurálása

Soha ne kódold bele az API-kulcsot közvetlenül a forráskódba. Node.js környezetben a szabványos megoldás a dotenv, amely a folyamat indításakor betölti a változókat egy helyi fájlból:

npm install dotenv

Hozz létre egy .env fájlt a projekted gyökerében:

MISTRAL_API_KEY=your-api-key-here

Azonnal add hozzá ezt a fájlt a .gitignore listához, még az első commit előtt. Pontosan ekkor szivárognak ki a kulcsok:

.env
.env.local

A dotenv/config importálásának meg kell előznie a process.env bármilyen olvasását. Ellenkező esetben a változó definiálatlan marad, amikor példányosítod a klienst:

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

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

A telepítés ellenőrzése

Mielőtt üzleti logikát írnál, validáld a teljes láncot – telepítés, kulcs, hálózat – egy minimális szkripttel. Hozd létre a src/test-mistral.ts fájlt, és egyszerűen kérd le a fiókod számára elérhető modellek listáját:

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

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

  // Elérhető modellek listázása
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Az SDK ezen verziója számára ismeretlen modelltípus 'UNKNOWN'ként van megjelölve
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Ez a két ellenőrzés nem csupán díszítés. Az SDK a data mezőt opcionálisként deklarálja, és a lista minden egyes eleme lehet egy alapmodell-kártya, egy finomhangolt modell-kártya vagy egy ismeretlen érték (type: 'UNKNOWN'). Amikor az API egy új modelltípust ad hozzá, az SDK ebben a formában őrzi meg azt, ahelyett, hogy összeomlana. E két teszt nélkül a szigorú mód megtagadja a fordítást.

Fejlesztés közben a korábban telepített tsx segítségével futtasd, amely menet közben transzpilál, így megspórolsz egy build lépést:

npx tsx src/test-mistral.ts

Figyelem: a tsx nem ellenőrzi a típusokat; eltávolítja őket és végrehajtja a kódot. Csak a tsc jelzi a típusozási hibákat. Futtasd az npx tsc --noEmit parancsot a fordítás nélküli ellenőrzéshez. A fordításhoz és futtatáshoz, ahogy azt a build folyamataid is teszik majd:

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

Érvényes kulcs esetén megjelenik a modellek száma és az első öt elem. Elutasított kulcs esetén egy Status 401 hiba (Invalid API Key) jelenik meg: a lánc működik, csak a kulccsal van probléma.

A projekt szervezése

Miután az ellenőrzés sikeres, strukturáld át a projektet úgy, hogy a kulcs és a kliens ne szóródjon szét a fájlok között:

mon-projet/
├── src/
│   ├── index.ts          # Belépési pont
│   ├── mistral-client.ts # Kliens inicializálása (singleton)
│   └── utils/
├── .env                  # Környezeti változók (git-ből ignorálva)
├── .gitignore
├── package.json
└── tsconfig.json

A kliens inicializálásának központosítása egy dedikált modulban elkerüli, hogy minden fájlban újra létre kelljen hozni. Ami még fontosabb: ez biztosítja, hogy az alkalmazás már induláskor hibát jelezzen, ha hiányzik a kulcs, ne pedig az első felhasználói híváskor:

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

A kód többi része egyszerűen importálja ezt az előre elkészített klienst:

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

Figyeld meg a .js kiterjesztést a relatív importban. A module: nodenext beállítás mellett a TypeScript megköveteli a fájlnevét úgy, ahogy az a fordítás után létezni fog, a tsx pedig tudja, hogy ezt leképezze a .ts fájlra. Az importálás sorrendje is számít: a dotenv/config a mistral-client.js előtt hajtódik végre, így a kulcs betöltődik, mire az a modul ellenőrzi a jelenlétét.

Főbb megállapítások

  • Telepítsd a TypeScript SDK-t az npm install @mistralai/mistralai paranccsal
  • A fő import: import { Mistral } from '@mistralai/mistralai'
  • Telepítsd a typescript, tsx és @types/node csomagokat fejlesztési függőségként, mielőtt az npx tsc parancsot hívnád
  • Használd a module: nodenext és a "type": "module" beállításokat a Node.js által futtatott kódhoz; a relatív importok .js kiterjesztést kapnak
  • Használj .env fájlt a dotenv segítségével az API-kulcs kezelésére
  • Az SDK natív TypeScript típusokat biztosít: használd ki az automatikus kiegészítést, és hagyd, hogy a tsc ellenőrizze azt, amit a tsx kihagy
  • Központosítsd a kliens inicializálását egy dedikált modulban