Instalace TypeScript SDK pro Mistral
Na této stránce
Lekce aktualizována 3. listopadu 2026 po spuštění příkladů se SDK
@mistralai/mistralaiverze 3.5.0 a TypeScriptem 7.0.2. Původní verze nešla zkompilovat. Spuštěnínpx tscbez nainstalovaného TypeScriptu stáhne zastaralý balíček npmtsc(verze 2.0.4) místo kompilátoru. Testovací skript se nacházel mimo složkusrcdeklarovanou vtsconfig.json. Objektprocessje rozpoznán pouze s@types/node. Nakonec striktní režim odmítámodels.data.lengthamodel.idbez předchozí validace. Soubortsconfig.jsonnyní následuje scénář „nejprve zkompilovat, poté spustit s Node.js“ z průvodce TypeScriptem a Node.js 18 a 20, které dosáhly konce životnosti, již nejsou uvedeny jako dostatečné. Zdroje: Stáhnout TypeScript · Výběr možností kompilátoru (TypeScript) · Změny v TypeScriptu 6.0 · tsx a TypeScript · Podporovaná runtime prostředí SDK · Harmonogram vydání Node.js.
Proč používat TypeScript SDK?
Pokud váš stack závisí na Node.js, Deno nebo Bun, umožňuje vám TypeScript SDK pro Mistral integrovat modely přímo do vašich aplikací v JavaScriptu a TypeScriptu. Vyhnete se tak mezilehlým vrstvám v Pythonu nebo psaní vlastních HTTP volání. Toto je nejčastější scénář při přidávání AI do existující webové aplikace: API v Expressu, backend v Next.js nebo worker v Node.js zpracovávající frontu zpráv.
Statické typování TypeScriptu přidává bezpečnostní síť, která se vyplatí již během první hodiny vývoje. Váš editor doplňuje názvy parametrů, takže nemusíte hádat mezi maxTokens a max_tokens; chyby v rozlišení velkých a malých písmen nebo vymyšlená pole vyvolají chybu při kompilaci, nikoliv v produkci ve 3 hodiny ráno; a dokumentace parametrů se zobrazí po najetí myší, aniž byste museli opustit soubor. Tato bezpečnostní síť je ještě důležitější, protože odpovědi API jsou vnořené objekty, u kterých je snadné přehlédnout jednu úroveň.
Předpoklady
SDK cílí na udržované LTS verze Node.js. K 3. listopadu 2026 jsou to verze 22, 24 a 26; Node.js 18 a 20 již nedostávají bezpečnostní záplaty. Před pokračováním zkontrolujte svou verzi příkazem node --version: SDK spoléhá na ES moduly a nativní API fetch. Potřebujete také správce balíčků (npm, yarn nebo pnpm) a klíč Mistral API vytvořený a dostupný jako proměnná prostředí, jak bylo popsáno v předchozích lekcích.
Instalace
Oficiální SDK je publikováno na npm jako @mistralai/mistralai:
# S npm
npm install @mistralai/mistralai
# S yarn
yarn add @mistralai/mistralai
# S pnpm
pnpm add @mistralai/mistralai
Konfigurace TypeScriptu
Pokud používáte TypeScript – což doporučujeme – nainstalujte tři nástroje jako vývojové závislosti: kompilátor, tsx (který spouští soubory .ts bez kroku sestavení) a @types/node (který popisuje objekty Node.js, jako je process, pro TypeScript):
npm install -D typescript tsx @types/node
Tento krok nevynechávejte. Bez nainstalovaného TypeScriptu v projektu získá npx tsc balíček tsc z npm – zastaralý legacy kompilátor (2.0.4) – místo TypeScriptu. Dále deklarujte projekt jako ES moduly, jak vyžaduje dokumentace TypeScriptu pro kód zkompilovaný a poté spuštěný Node.js:
npm pkg set type=module
Nakonec vytvořte tsconfig.json. Používá nastavení, která oficiální průvodce TypeScriptem doporučuje pro tento scénář (module: nodenext). Také povoluje striktní režim, který vás nutí zpracovávat potenciálně chybějící hodnoty v odpovědích API – což je zdravé omezení – a kompiluje src/ do dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Tři řádky si zaslouží vysvětlení, protože každý z nich předchází chybě, na kterou jsme narazili při testování této lekce:
"types": ["node"]načítá typy Node.js. Od TypeScriptu 6.0 se balíčky@typesjiž nenačítají automaticky. Bez tohoto řádku vyvoláprocess.envchybu „Cannot find name ‘process’“, i když je nainstalován@types/node."rootDir": "src"nastavuje kořenový adresář zdrojových souborů pro kompilované soubory:src/test-mistral.tsse stanedist/test-mistral.js. Bez toho TypeScript 7 hlásí chybu TS5011, kdykoli vaše zdroje nejsou v kořeni projektu."skipLibCheck": truepřeskočí kontrolu typů v deklaračních souborech závislostí. Toto je také výchozí nastavení vtsconfig.jsongenerovaném příkazemnpx tsc --init. U SDK 3.5.0 a TypeScriptu 7 způsobuje vynechání tohoto nastavení chybu ve vlastních deklaracích SDK, kterou váš kód nemůže opravit.
SDK je publikováno jako ES moduly a obsahuje vlastní typy: není pro něj potřeba žádný balíček @types/. Pokud vašemu editoru chybí automatické doplňování, problém leží ve vašem tsconfig.json, nikoliv v chybějícím balíčku typů.
Konfigurace proměnné prostředí
Nikdy neukládejte klíč API natvrdo do zdrojového kódu. V Node.js je standardním řešením dotenv, který načítá proměnné z místního souboru při spuštění procesu:
npm install dotenv
V kořeni projektu vytvořte soubor .env:
MISTRAL_API_KEY=your-api-key-here
Okamžitě přidejte tento soubor do .gitignore, ještě před prvním committem. Přesně v tuto chvíli dochází k úniku klíčů:
.env
.env.local
Import dotenv/config musí předcházet jakémukoli čtení process.env. Jinak zůstane proměnná nedefinovaná, když instantcujete klienta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Ověření instalace
Než začnete psát obchodní logiku, ověřte celý řetězec – instalaci, klíč, síť – pomocí minimálního skriptu. Vytvořte src/test-mistral.ts a jednoduše požádejte o seznam modelů přístupných vašemu účtu:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Seznam dostupných modelů
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Available models: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Typ modelu neznámý této verzi SDK je označen jako 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Tyto dvě kontroly nejsou jen dekorativní. SDK deklaruje data jako volitelné a každá položka seznamu je buď základní karta modelu, karta doladěného modelu, nebo neznámá hodnota (type: 'UNKNOWN'). Když API přidá nový typ modelu, SDK jej v této formě zachová, místo aby spadlo. Bez těchto dvou testů striktní režim odmítne kompilaci.
Ve vývoji jej spusťte pomocí tsx, který jste nainstalovali dříve; ten překládá za běhu a šetří vám krok sestavení:
npx tsx src/test-mistral.ts
Upozornění: tsx nekontroluje typy; odstraní je a provede kód. Pouze tsc hlásí chyby typování. Pro kontrolu bez kompilace spusťte npx tsc --noEmit. Pro zkompilování a následné spuštění, jak to bude dělat váš build pipeline:
npx tsc && node dist/test-mistral.js
Platný klíč zobrazí počet modelů a prvních pět položek. Odmítnutý klíč zobrazí chybu Status 401 (Invalid API Key): řetězec funguje, chyba je pouze v klíči.
Organizace projektu
Jakmile ověření proběhne úspěšně, strukturovat projekt tak, aby se klíč a klient nerozptýlili po souborech:
mon-projet/
├── src/
│ ├── index.ts # Vstupní bod
│ ├── mistral-client.ts # Inicializace klienta (singleton)
│ └── utils/
├── .env # Proměnné prostředí (ignorováno gitem)
├── .gitignore
├── package.json
└── tsconfig.json
Centralizace inicializace klienta do vyhrazeného modulu zabrání jeho opakovanému vytváření v každém souboru. Ještě důležitější je, že to způsobí selhání aplikace při spuštění, nikoliv až při prvním volání uživatele, pokud chybí klíč:
// 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,
});
Zbytek kódu jednoduše importuje tohoto předpřipraveného klienta:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Všimněte si přípony .js v relativním importu. Při nastavení module: nodenext vyžaduje TypeScript název souboru tak, jak bude existovat po kompilaci, a tsx ví, jak jej namapovat na soubor .ts. Na pořadí importu také záleží: dotenv/config se provede před mistral-client.js, takže je klíč načten, když tento modul kontroluje jeho přítomnost.
Klíčové poznatky
- Nainstalujte TypeScript SDK příkazem
npm install @mistralai/mistralai - Hlavní import je
import { Mistral } from '@mistralai/mistralai' - Před voláním
npx tscnainstalujtetypescript,tsxa@types/nodejako vývojové závislosti - Pro kód zkompilovaný a poté spuštěný Node.js použijte
module: nodenexta"type": "module"; relativní importy mají příponu.js - Pro správu klíče API použijte soubor
.envsdotenv - SDK poskytuje nativní typy TypeScriptu: využijte automatické doplňování a nechte
tsckontrolovat to, cotsxpřeskočí - Centralizujte inicializaci klienta do vyhrazeného modulu