Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Instalace TypeScript SDK pro Mistral

Lekce 8 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Proč používat TypeScript SDK?
  2. Předpoklady
  3. Instalace
  4. Konfigurace TypeScriptu
  5. Konfigurace proměnné prostředí
  6. Ověření instalace
  7. Organizace projektu
  8. Klíčové poznatky

Lekce aktualizována 3. listopadu 2026 po spuštění příkladů se SDK @mistralai/mistralai verze 3.5.0 a TypeScriptem 7.0.2. Původní verze nešla zkompilovat. Spuštění npx tsc bez nainstalovaného TypeScriptu stáhne zastaralý balíček npm tsc (verze 2.0.4) místo kompilátoru. Testovací skript se nacházel mimo složku src deklarovanou v tsconfig.json. Objekt process je rozpoznán pouze s @types/node. Nakonec striktní režim odmítá models.data.length a model.id bez předchozí validace. Soubor tsconfig.json nyní 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 @types již nenačítají automaticky. Bez tohoto řádku vyvolá process.env chybu „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.ts se stane dist/test-mistral.js. Bez toho TypeScript 7 hlásí chybu TS5011, kdykoli vaše zdroje nejsou v kořeni projektu.
  • "skipLibCheck": true přeskočí kontrolu typů v deklaračních souborech závislostí. Toto je také výchozí nastavení v tsconfig.json generovaném příkazem npx 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 tsc nainstalujte typescript, tsx a @types/node jako vývojové závislosti
  • Pro kód zkompilovaný a poté spuštěný Node.js použijte module: nodenext a "type": "module"; relativní importy mají příponu .js
  • Pro správu klíče API použijte soubor .env s dotenv
  • SDK poskytuje nativní typy TypeScriptu: využijte automatické doplňování a nechte tsc kontrolovat to, co tsx přeskočí
  • Centralizujte inicializaci klienta do vyhrazeného modulu