Installieren Sie das Mistral TypeScript SDK

Lektion aktualisiert am 3. November 2026 nach dem Ausführen der Beispiele mit dem SDK @mistralai/mistralai Version 3.5.0 und TypeScript 7.0.2. Die ursprüngliche Version kompilierte nicht. Das Ausführen von npx tsc ohne installiertes TypeScript lädt das verlassene npm-Paket tsc (Version 2.0.4) statt des Compilers herunter. Das Testskript befand sich außerhalb des in tsconfig.json deklarierten src-Ordners. Das process-Objekt wird nur mit @types/node erkannt. Schließlich lehnt der strenge Modus models.data.length und model.id ohne vorherige Validierung ab. Die tsconfig.json folgt nun dem Szenario „zuerst kompilieren, dann mit Node.js ausführen” der TypeScript-Richtlinien, und Node.js-Versionen 18 und 20, die ihr Lebensende erreicht haben, werden nicht mehr als ausreichend aufgeführt. Quellen: TypeScript herunterladen · Compileroptionen wählen (TypeScript) · TypeScript 6.0-Änderungen · tsx und TypeScript · Unterstützte Laufzeitumgebungen des SDK · Node.js-Veröffentlichungsplan.

Warum das TypeScript SDK verwenden?

Wenn Ihre Technologiebasis auf Node.js, Deno oder Bun basiert, ermöglicht das Mistral TypeScript SDK die direkte Integration von Modellen in Ihre JavaScript- und TypeScript-Anwendungen. Sie vermeiden Zwischenschichten aus Python oder das Schreiben eigener HTTP-Aufrufe. Dies ist der häufigste Szenario beim Hinzufügen von KI zu einer bestehenden Webanwendung: eine Express-API, ein Next.js-Backend oder ein Node-Worker, der eine Nachrichtenwarteschlange verarbeitet.

Die statische Typisierung von TypeScript bietet ein Sicherheitsnetz, das sich innerhalb der ersten Entwicklungsstunde auszahlt. Ihr Editor vervollständigt Parameternamen, sodass Sie nicht zwischen maxTokens und max_tokens raten müssen; Fehler bei der Groß-/Kleinschreibung oder erfundene Felder werden zur Kompilierzeit erkannt, nicht um 3 Uhr morgens in der Produktion; und die Parameterdokumentation erscheint beim Hovern, ohne dass Sie den Datei verlassen müssen. Dieses Sicherheitsnetz ist noch wichtiger, da API-Antworten verschachtelte Objekte sind, bei denen es leicht ist, ein Level zu übersehen.

Voraussetzungen

Das SDK richtet sich an gepflegte LTS-Versionen von Node.js. Stand dem 3. November 2026 sind dies Versionen 22, 24 und 26; Node.js 18 und 20 erhalten keine Sicherheitsupdates mehr. Prüfen Sie Ihre Version mit node --version, bevor Sie fortfahren: Das SDK nutzt ES-Module und die native fetch-API. Sie benötigen zudem einen Paketmanager (npm, yarn oder pnpm) und einen Mistral-API-Schlüssel, der erstellt wurde und als Umgebungsvariable verfügbar ist, wie in vorherigen Lektionen behandelt.

Installation

Das offizielle SDK wird auf npm als @mistralai/mistralai veröffentlicht:

# Mit npm
npm install @mistralai/mistralai

# Mit yarn
yarn add @mistralai/mistralai

# Mit pnpm
pnpm add @mistralai/mistralai

TypeScript-Konfiguration

Wenn Sie TypeScript verwenden – was wir empfehlen – installieren Sie drei Tools als Abhängigkeiten für die Entwicklung: den Compiler, tsx (der .ts-Dateien ohne Build-Schritt ausführt) und @types/node (der Node.js-Objekte wie process für TypeScript beschreibt):

npm install -D typescript tsx @types/node

Überspringen Sie diesen Schritt nicht. Ohne TypeScript, das im Projekt installiert ist, holt npx tsc das Paket tsc von npm – einen verlassenen Legacy-Compiler (Version 2.0.4) – statt TypeScript. Erklären Sie anschließend das Projekt als ES-Module, wie die TypeScript-Dokumentation für Code verlangt, der dann von Node.js ausgeführt wird:

npm pkg set type=module

Erstellen Sie schließlich tsconfig.json. Es verwendet die Einstellungen, die die offizielle TypeScript-Richtlinie für dieses Szenario empfiehlt (module: nodenext). Es aktiviert zudem den strengen Modus, der Sie zwingt, potenziell fehlende Werte in API-Antworten zu behandeln – eine gesunde Einschränkung – und kompiliert src/ in dist/:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "skipLibCheck": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

Drei Zeilen verdienen eine Erklärung, da jede einen Fehler verhindert, den wir während des Tests dieser Lektion festgestellt haben:

• "types": ["node"] lädt die Typen von Node.js. Seit TypeScript 6.0 werden @types-Pakete nicht mehr automatisch geladen. Ohne diese Zeile löst process.env den Fehler “Name ‘process’ nicht gefunden” aus, auch wenn @types/node installiert ist.
• "rootDir": "src" setzt den Quellordner für die kompilierten Dateien: src/test-mistral.ts wird zu dist/test-mistral.js. Ohne diese Angabe meldet TypeScript 7 den Fehler TS5011, wenn Ihre Quellen nicht im Projektroot liegen.
• "skipLibCheck": true überspringt die Typüberprüfung von Deklarationsdateien von Abhängigkeiten. Dies ist auch die Standardeinstellung in der tsconfig.json, die von npx tsc --init generiert wird. Mit SDK 3.5.0 und TypeScript 7 führt das Weglassen dies zu einem Fehler in den eigenen Deklarationen des SDK, den Ihr Code nicht beheben kann.

Das SDK wird als ES-Module veröffentlicht und bündelt seine eigenen Typen: Es wird kein @types/-Paket für es benötigt. Wenn Ihr Editor keine Autovervollständigung bietet, liegt das Problem in Ihrer tsconfig.json, nicht in einem fehlenden Typenpaket.

Konfigurieren Sie die Umgebungsvariable

Hardcodieren Sie den API-Schlüssel niemals in Ihren Quellcode. Die Standardlösung in Node.js ist dotenv, das Variablen beim Prozessstart aus einer lokalen Datei lädt:

npm install dotenv

Erstellen Sie eine .env-Datei im Projektroot:

MISTRAL_API_KEY=your-api-key-here

Fügen Sie diese Datei sofort zu Ihrem .gitignore hinzu, bevor Sie Ihre erste Commit-Vorgang durchführen. Dies ist der genaue Moment, in dem Schlüssel auslaufen:

.env
.env.local

Der Import dotenv/config muss vor jedem Lesen von process.env stehen. Andernfalls bleibt die Variable undefiniert, wenn Sie den Client initialisieren:

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

Installation verifizieren

Bevor Sie Geschäftslogik schreiben, validieren Sie die gesamte Kette – Installation, Schlüssel, Netzwerk – mit einem minimalen Skript. Erstellen Sie src/test-mistral.ts und fordern Sie einfach die Liste der Modelle an, die für Ihr Konto zugänglich sind:

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

async function main() {
  const client = new Mistral({
    apiKey: process.env.MISTRAL_API_KEY,
  });

  // Liste der verfügbaren Modelle abrufen
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Verfügbare Modelle: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Ein Modelltyp, der von dieser SDK-Version unbekannt ist, wird als 'UNKNOWN' markiert
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Diese beiden Prüfungen sind nicht dekorativ. Das SDK deklariert data als optional, und jeder Eintrag in der Liste ist entweder eine Basis-Modellkarte, eine Feinabstimmungs-Modellkarte oder ein unbekannter Wert (type: 'UNKNOWN'). Wenn die API einen neuen Modelltyp hinzufügt, behält das SDK ihn in dieser Form bei, anstatt abzustürzen. Ohne diese beiden Tests verweigert der strenge Modus die Kompilierung.

In der Entwicklung führen Sie es mit tsx aus, das Sie zuvor installiert haben, was die Transpilation auf der fly durchführt und Ihnen einen Build-Schritt spart:

npx tsx src/test-mistral.ts

Warnung: tsx überprüft keine Typen; es entfernt sie und führt aus. Nur tsc meldet Typfehler. Führen Sie npx tsc --noEmit aus, um zu prüfen, ohne zu kompilieren. Um zu kompilieren und dann auszuführen, wie Ihre Build-Pipeline es tun wird:

npx tsc && node dist/test-mistral.js

Ein gültiger Schlüssel zeigt die Modellanzahl und die ersten fünf Einträge an. Ein abgelehnter Schlüssel zeigt einen Status 401-Fehler (Invalid API Key) an: Die Kette funktioniert, nur der Schlüssel ist defekt.

Projektstrukturieren

Sobald die Verifizierung erfolgreich war, strukturieren Sie das Projekt so, dass Schlüssel und Client nicht über Dateien verstreut werden:

mon-projet/
├── src/
│   ├── index.ts          # Einstiegspunkt
│   ├── mistral-client.ts # Client-Initialisierung (Singleton)
│   └── utils/
├── .env                  # Umgebungsvariablen (im Git ignoriert)
├── .gitignore
├── package.json
└── tsconfig.json

Die Zentralisierung der Client-Initialisierung in einem dedizierten Modul vermeidet die Neuerstellung in jeder Datei. Noch wichtiger ist, dass die Anwendung beim Start fehlschlägt, anstatt beim ersten Aufruf eines Benutzers, wenn der Schlüssel fehlt:

// src/mistral-client.ts
import { Mistral } from '@mistralai/mistralai';

if (!process.env.MISTRAL_API_KEY) {
  throw new Error('Die Variable MISTRAL_API_KEY ist erforderlich.');
}

export const mistral = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

Der Rest des Codes importiert diesen vorbereiteten Client einfach:

// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';

Beachten Sie die .js-Erweiterung im relativen Import. Mit module: nodenext erfordert TypeScript den Dateinamen, wie er nach der Kompilierung existiert, und tsx weiß, ihn auf die .ts-Datei abzubilden. Die Import-Reihenfolge ist ebenfalls wichtig: dotenv/config führt vor mistral-client.js aus, sodass der Schlüssel geladen wird, wenn dieses Modul auf seine Anwesenheit prüft.

Kernaussagen

• Installieren Sie das TypeScript SDK mit npm install @mistralai/mistralai
• Der Hauptimport ist import { Mistral } from '@mistralai/mistralai'
• Installieren Sie typescript, tsx und @types/node als Abhängigkeiten für die Entwicklung, bevor Sie npx tsc aufrufen
• Verwenden Sie module: nodenext und "type": "module" für Code, der von Node.js kompiliert und ausgeführt wird; relative Imports benötigen die .js-Erweiterung
• Verwenden Sie eine .env-Datei mit dotenv, um den API-Schlüssel zu verwalten
• Das SDK bietet native TypeScript-Typen: Nutzen Sie die Autovervollständigung und lassen Sie tsc prüfen, was tsx überspringt
• Zentralisieren Sie die Client-Initialisierung in einem dedizierten Modul