A Mistral TypeScript SDK telepítése
Ezen az oldalon
A leckét 2026. november 3-án frissítettük, miután a példákat lefuttattuk a
@mistralai/mistralaiSDK 3.5.0 és a TypeScript 7.0.2 verziójával. Az eredeti verzió nem fordult le. Anpx tscparancs futtatása a TypeScript telepítése nélkül az elhagyatotttscnpm csomagot (2.0.4-es verzió) tölti le a fordító helyett. A tesztelő szkript atsconfig.jsonfájlban deklaráltsrcmappán kívül helyezkedett el. Aprocessobjektum csak a@types/nodecsomaggal ismerhető fel. Végül a szigorú mód elutasítja amodels.data.lengthés amodel.idhivatkozásokat előzetes validálás nélkül. Atsconfig.jsonmost 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@typescsomagok már nem töltődnek be automatikusan. E sor nélkül aprocess.enva „Cannot find name ‘process’“ hibaüzenetet váltja ki, még akkor is, ha az@types/nodetelepítve van. - A
"rootDir": "src"beállítja a forrásfájlok gyökérkönyvtárát a fordított fájlokhoz: asrc/test-mistral.tsfájlbóldist/test-mistral.jslesz. Enélkül a TypeScript 7 TS5011 hibát jelez, ha a forrásfájljaid nem a projekt gyökerében vannak. - A
"skipLibCheck": truekihagyja a függőségi deklarációs fájlok típusellenőrzését. Ez aznpx tsc --initáltal generálttsconfig.jsonalapé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/mistralaiparanccsal - A fő import:
import { Mistral } from '@mistralai/mistralai' - Telepítsd a
typescript,tsxés@types/nodecsomagokat fejlesztési függőségként, mielőtt aznpx tscparancsot 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.jskiterjesztést kapnak - Használj
.envfájlt adotenvsegí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
tscellenőrizze azt, amit atsxkihagy - Központosítsd a kliens inicializálását egy dedikált modulban