Przejdź do głównej treści
Polski— Wybierz język
Menu

Instalacja TypeScript SDK Mistral

Lekcja 8 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego warto używać TypeScript SDK?
  2. Wymagania wstępne
  3. Instalacja
  4. Konfiguracja TypeScript
  5. Konfiguracja zmiennej środowiskowej
  6. Weryfikacja instalacji
  7. Organizacja projektu
  8. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 r. po przetestowaniu przykładów przy użyciu SDK @mistralai/mistralai w wersji 3.5.0 i TypeScript 7.0.2. Oryginalna wersja nie kompilowała się. Uruchomienie npx tsc bez zainstalowanego TypeScripta powoduje pobranie porzuconego pakietu npm tsc (wersja 2.0.4) zamiast właściwego kompilatora. Skrypt testowy znajdował się poza folderem src zadeklarowanym w tsconfig.json. Obiekt process jest rozpoznawany tylko dzięki @types/node. Wreszcie, tryb ścisły odrzuca models.data.length i model.id bez wcześniejszej walidacji. Plik tsconfig.json stosuje 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 @types nie są już ładowane automatycznie. Bez tej linii process.env zgł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.ts staje 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": true pomija sprawdzanie typów w plikach deklaracji zależności. Jest to również domyślne ustawienie w tsconfig.json generowanym przez npx 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, tsx i @types/node jako zależności deweloperskie przed wywołaniem npx tsc
  • Użyj module: nodenext i "type": "module" dla kodu kompilowanego, a następnie uruchamianego przez Node.js; importy względne muszą mieć rozszerzenie .js
  • Użyj pliku .env z dotenv do zarządzania kluczem API
  • SDK dostarcza natywne typy TypeScript: wykorzystaj autouzupełnianie i pozwól tsc sprawdzać to, co tsx pomija
  • Scentralizuj inicjalizację klienta w dedykowanym module