Instalacja TypeScript SDK Mistral
Na tej stronie
Lekcja zaktualizowana 3 listopada 2026 r. po przetestowaniu przykładów przy użyciu SDK
@mistralai/mistralaiw wersji 3.5.0 i TypeScript 7.0.2. Oryginalna wersja nie kompilowała się. Uruchomienienpx tscbez zainstalowanego TypeScripta powoduje pobranie porzuconego pakietu npmtsc(wersja 2.0.4) zamiast właściwego kompilatora. Skrypt testowy znajdował się poza folderemsrczadeklarowanym wtsconfig.json. Obiektprocessjest rozpoznawany tylko dzięki@types/node. Wreszcie, tryb ścisły odrzucamodels.data.lengthimodel.idbez wcześniejszej walidacji. Pliktsconfig.jsonstosuje się teraz do scenariusza „kompiluj, a następnie uruchom w Node.js“ z przewodnika TypeScript, a wersje Node.js 18 i 20, które osiągnęły koniec wsparcia (EOL), nie są już wymieniane jako wystarczające. Źródła: Pobierz TypeScript · Wybór opcji kompilatora (TypeScript) · Zmiany w TypeScript 6.0 · tsx i TypeScript · Obsługiwane środowiska wykonawcze SDK · Harmonogram wydań Node.js.
Dlaczego warto używać TypeScript SDK?
Jeśli Twój stos technologiczny opiera się na Node.js, Deno lub Bun, TypeScript SDK od Mistral pozwala integrować modele bezpośrednio z aplikacjami JavaScript i TypeScript. Unikasz dzięki temu pośrednich warstw w Pythonie czy pisania własnych wywołań HTTP. To najczęstszy scenariusz podczas dodawania AI do istniejącej aplikacji webowej: API Express, backend Next.js czy worker Node.js przetwarzający kolejkę wiadomości.
Statyczne typowanie w TypeScript dodaje warstwę bezpieczeństwa, która zwraca się już w pierwszej godzinie pracy. Edytor uzupełnia nazwy parametrów, więc nie musisz zgadywać, czy użyć maxTokens, czy max_tokens; błędy w wielkości liter czy nieistniejące pola wykrywane są podczas kompilacji, a nie w produkcji o 3 nad ranem; dokumentacja parametrów pojawia się po najechaniu kursorem, bez konieczności opuszczania pliku. Ta ochrona jest tym ważniejsza, że odpowiedzi API to zagnieżdżone obiekty, w których łatwo przeoczyć jakiś poziom.
Wymagania wstępne
SDK obsługuje utrzymywane wersje LTS Node.js. Na dzień 3 listopada 2026 r. są to wersje 22, 24 i 26; Node.js 18 i 20 nie otrzymują już poprawek bezpieczeństwa. Sprawdź swoją wersję poleceniem node --version przed kontynuowaniem: SDK wymaga modułów ES i natywnego API fetch. Potrzebujesz również menedżera pakietów (npm, yarn lub pnpm) oraz klucza API Mistral, utworzonego i dostępnego jako zmienna środowiskowa, zgodnie z poprzednimi lekcjami.
Instalacja
Oficjalne SDK jest publikowane w npm jako @mistralai/mistralai:
# Przy użyciu npm
npm install @mistralai/mistralai
# Przy użyciu yarn
yarn add @mistralai/mistralai
# Przy użyciu pnpm
pnpm add @mistralai/mistralai
Konfiguracja TypeScript
Jeśli używasz TypeScript – co rekomendujemy – zainstaluj trzy narzędzia jako zależności deweloperskie: kompilator, tsx (uruchamia pliki .ts bez etapu budowania) oraz @types/node (opisuje dla TypeScript obiekty Node.js, takie jak process):
npm install -D typescript tsx @types/node
Nie pomijaj tego kroku. Bez zainstalowanego TypeScript w projekcie, npx tsc pobierze pakiet tsc z npm – porzucony, przestarzały kompilator (2.0.4) – zamiast właściwego TypeScript. Następnie zadeklaruj projekt jako moduły ES, czego wymaga dokumentacja TypeScript dla kodu kompilowanego, a następnie uruchamianego przez Node.js:
npm pkg set type=module
Na koniec utwórz plik tsconfig.json. Wykorzystuje on ustawienia rekomendowane przez oficjalny przewodnik TypeScript dla tego scenariusza (module: nodenext). Włącza również tryb ścisły, który wymusza obsługę potencjalnie brakujących wartości w odpowiedziach API – co jest zdrowym ograniczeniem – i kompiluje katalog src/ do dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Trzy linie zasługują na wyjaśnienie, ponieważ każda z nich zapobiega błędowi, na który natknęliśmy się podczas testowania tej lekcji:
"types": ["node"]ładuje typy Node.js. Od wersji TypeScript 6.0 pakiety@typesnie są już ładowane automatycznie. Bez tej liniiprocess.envzgłosi błąd „Cannot find name ‘process’“, nawet przy zainstalowanym@types/node."rootDir": "src"ustawia katalog źródłowy dla skompilowanych plików:src/test-mistral.tsstaje siędist/test-mistral.js. Bez tego TypeScript 7 zgłasza błąd TS5011, gdy źródła nie znajdują się w głównym katalogu projektu."skipLibCheck": truepomija sprawdzanie typów w plikach deklaracji zależności. Jest to również domyślne ustawienie wtsconfig.jsongenerowanym przeznpx tsc --init. Przy SDK 3.5.0 i TypeScript 7 pominięcie tego powoduje błąd we własnych deklaracjach SDK, którego Twój kod nie może naprawić.
SDK jest publikowane jako moduły ES i zawiera własne typy: nie jest potrzebny żaden pakiet @types/. Jeśli Twój edytor nie oferuje autouzupełniania, problem leży w Twoim tsconfig.json, a nie w brakującym pakiecie typów.
Konfiguracja zmiennej środowiskowej
Nigdy nie hardkoduj klucza API w kodzie źródłowym. W Node.js standardowym rozwiązaniem jest dotenv, które ładuje zmienne z lokalnego pliku przy starcie procesu:
npm install dotenv
Utwórz plik .env w głównym katalogu projektu:
MISTRAL_API_KEY=twój-klucz-api-tutaj
Dodaj ten plik do .gitignore natychmiast, przed pierwszym commitiem. To właśnie w tym momencie klucze najczęściej wyciekają:
.env
.env.local
Import dotenv/config musi poprzedzać wszelkie odczyty process.env. W przeciwnym razie zmienna pozostanie niezdefiniowana w momencie tworzenia instancji klienta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Weryfikacja instalacji
Zanim przejdziesz do logiki biznesowej, zweryfikuj cały łańcuch – instalację, klucz, sieć – za pomocą minimalnego skryptu. Utwórz plik src/test-mistral.ts i po prostu poproś o listę modeli dostępnych dla Twojego konta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Lista dostępnych modeli
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 nieznany tej wersji SDK jest oznaczony jako 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Te dwa sprawdzenia nie są ozdobnikiem. SDK deklaruje data jako opcjonalne, a każdy wpis na liście to albo karta modelu bazowego, albo modelu dostrojonego, albo nieznana wartość (type: 'UNKNOWN'). Gdy API doda nowy typ modelu, SDK zachowuje go w tej formie zamiast się zawieszać. Bez tych dwóch testów tryb ścisły odmówi kompilacji.
W środowisku deweloperskim uruchom skrypt za pomocą tsx, zainstalowanego wcześniej, który transpiluje kod w locie i oszczędza Ci etapu budowania:
npx tsx src/test-mistral.ts
Ostrzeżenie: tsx nie sprawdza typów; usuwa je i wykonuje kod. Tylko tsc zgłasza błędy typowania. Uruchom npx tsc --noEmit, aby sprawdzić typy bez kompilacji. Aby skompilować, a następnie uruchomić – tak jak zrobi to Twój potok budowania:
npx tsc && node dist/test-mistral.js
Prawidłowy klucz wyświetli liczbę modeli i pierwsze pięć wpisów. Odrzucony klucz wyświetli błąd Status 401 (Invalid API Key): łańcuch działa, winny jest tylko klucz.
Organizacja projektu
Gdy weryfikacja przebiegnie pomyślnie, uporządkuj projekt tak, aby klucz i klient nie były rozproszone po różnych plikach:
mon-projet/
├── src/
│ ├── index.ts # Punkt wejścia
│ ├── mistral-client.ts # Inicjalizacja klienta (singleton)
│ └── utils/
├── .env # Zmienne środowiskowe (ignorowane przez git)
├── .gitignore
├── package.json
└── tsconfig.json
Scentralizowanie inicjalizacji klienta w dedykowanym module pozwala uniknąć jego wielokrotnego tworzenia w każdym pliku. Co ważniejsze, powoduje to, że aplikacja zakończy się niepowodzeniem przy starcie, a nie przy pierwszym wywołaniu użytkownika, jeśli brakuje klucza:
// 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,
});
Reszta kodu po prostu importuje tego gotowego klienta:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Zwróć uwagę na rozszerzenie .js w imporcie względnym. Przy module: nodenext TypeScript wymaga nazwy pliku takiej, jaka będzie istnieć po kompilacji, a tsx wie, jak odwzorować ją na plik .ts. Kolejność importów również ma znaczenie: dotenv/config wykonuje się przed mistral-client.js, więc klucz jest załadowany, gdy ten moduł sprawdza jego obecność.
Kluczowe wnioski
- Zainstaluj TypeScript SDK poleceniem
npm install @mistralai/mistralai - Główny import to
import { Mistral } from '@mistralai/mistralai' - Zainstaluj
typescript,tsxi@types/nodejako zależności deweloperskie przed wywołaniemnpx tsc - Użyj
module: nodenexti"type": "module"dla kodu kompilowanego, a następnie uruchamianego przez Node.js; importy względne muszą mieć rozszerzenie.js - Użyj pliku
.envzdotenvdo zarządzania kluczem API - SDK dostarcza natywne typy TypeScript: wykorzystaj autouzupełnianie i pozwól
tscsprawdzać to, cotsxpomija - Scentralizuj inicjalizację klienta w dedykowanym module