Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Asenna Mistral TypeScript SDK

Oppitunti 8 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miksi käyttää TypeScript SDK:ta?
  2. Esivaatimukset
  3. Asennus
  4. TypeScript-määritykset
  5. Ympäristömuuttujan määrittäminen
  6. Asennuksen vahvistaminen
  7. Projektin organisointi
  8. Keskeiset asiat

Oppiaine päivitetty 3. marraskuuta 2026 sen jälkeen, kun esimerkit oli ajettu @mistralai/mistralai SDK:n versiolla 3.5.0 ja TypeScriptin versiolla 7.0.2. Alkuperäinen versio ei kääntynyt. Komennon npx tsc suorittaminen ilman asennettua TypeScriptia lataa hylätyn tsc-npm-paketin (versio 2.0.4) varsinaisen kääntäjän sijaan. Testiskripti sijaitsi tsconfig.json-tiedostossa määritellyn src-kansion ulkopuolella. process-objekti tunnistetaan vain, jos @types/node on asennettu. Lopuksi tiukka tila hylkää lausekkeet models.data.length ja model.id ilman ennakkotarkistusta. tsconfig.json noudattaa nyt TypeScript-oppaan skenaariota “käännä ja suorita Node.js:llä”, eikä elinkaarensa päättäneitä Node.js-versioita 18 ja 20 enää listata riittäviksi. Lähteet: Lataa TypeScript · Kääntäjävalintojen valitseminen (TypeScript) · TypeScript 6.0:n muutokset · tsx ja TypeScript · SDK:n tukemat ajonaikaiset ympäristöt · Node.js:n julkaisuaikataulu.

Miksi käyttää TypeScript SDK:ta?

Jos pinosi perustuu Node.js:ään, Denoon tai Buniin, Mistralin TypeScript SDK:n avulla voit integroida mallit suoraan JavaScript- ja TypeScript-sovelluksiisi. Vältyt välikäsinä toimivilta Python-kerroksilta tai omien HTTP-kutsujen kirjoittamiselta. Tämä on yleisin skenaario lisättäessä tekoälyä olemassa olevaan verkkosovellukseen: Express-API, Next.js-backend tai viestijonoa käsittelevä Node-työntekijä.

TypeScriptin staattinen tyypitys tarjoaa turvaverkon, joka maksaa itsensä takaisin jo ensimmäisen kehittämistunnin aikana. Editorisi täydentää parametrinimet sen sijaan, että joutuisit arvailemaan vaihtoehtoja maxTokens ja max_tokens välillä; kirjainkokovirheet tai keksityt kentät aiheuttavat virheen käännösvaiheessa, eivät tuotannossa kello 3 yöllä; ja parametrien dokumentaatio ilmestyy näkyviin vihjeenä ilman, että sinun tarvitsee poistua tiedostosta. Tämä turvaverkko on sitäkin tärkeämpi, koska API-vastaukset ovat pesiytyneitä objekteja, joista tason ohittaminen on helppoa.

Esivaatimukset

SDK kohdistuu ylläpidettyihin Node.js:n LTS-versioihin. 3. marraskuuta 2026 mennessä nämä ovat versiot 22, 24 ja 26; Node.js 18 ja 20 eivät enää saa tietoturvapäivityksiä. Tarkista versionsi komennolla node --version ennen jatkamista: SDK luottaa ES-moduuleihin ja natiiviin fetch-APIin. Tarvitset myös paketinhallintatyökalun (npm, yarn tai pnpm) sekä Mistral API -avaimen, joka on luotu ja saatavilla ympäristömuuttujana, kuten aiemmissa oppitunneissa on käsitelty.

Asennus

Virallinen SDK julkaistaan npm:ssä nimellä @mistralai/mistralai:

# npm:llä
npm install @mistralai/mistralai

# yarnilla
yarn add @mistralai/mistralai

# pnpm:llä
pnpm add @mistralai/mistralai

TypeScript-määritykset

Jos käytät TypeScriptiä – mitä suosittelemme – asenna kolme työkalua kehitysriippuvuuksina: kääntäjä, tsx (joka suorittaa .ts-tiedostoja ilman erillistä käännösvaihetta) ja @types/node (joka kuvailee Node.js-objekteja, kuten process, TypeScriptille):

npm install -D typescript tsx @types/node

Älä ohita tätä vaihetta. Ilman projektiin asennettua TypeScriptia npx tsc hakee npm:stä tsc-paketin – hylätyn legacy-kääntäjän (2.0.4) – varsinaisen TypeScriptin sijaan. Määritä seuraavaksi projekti ES-moduuliksi, kuten TypeScriptin dokumentaatio edellyttää koodille, joka käännetään ja jonka Node.js suorittaa:

npm pkg set type=module

Luo lopuksi tsconfig.json. Se käyttää asetuksia, joita virallinen TypeScript-opas suosittelee tähän skenaarioon (module: nodenext). Se ottaa myös käyttöön tiukan tilan, joka pakottaa sinut käsittelemään API-vastauksissa mahdollisesti puuttuvia arvoja – tämä on terveellinen rajoite – ja kääntää kansion src/ kansioon dist/:

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

Kolme riviä ansaitsee selityksen, sillä kukin niistä estää virheen, jonka kohtasimme tätä oppituntia testatessamme:

  • "types": ["node"] lataa Node.js-tyypit. TypeScript 6.0:sta lähtien @types-paketteja ei enää ladata automaattisesti. Ilman tätä riviä process.env aiheuttaa virheen “Cannot find name ‘process’”, vaikka @types/node olisi asennettu.
  • "rootDir": "src" asettaa lähdekoodin juurikansion käännetyille tiedostoille: src/test-mistral.ts muuttuu muotoon dist/test-mistral.js. Ilman tätä TypeScript 7 ilmoittaa virheen TS5011 aina, kun lähdetiedostosi eivät ole projektin juuressa.
  • "skipLibCheck": true ohittaa riippuvuuksien määritystiedostojen tyyppitarkistuksen. Tämä on myös oletusasetus npx tsc --init-komennolla luodussa tsconfig.json-tiedostossa. SDK:n versiolla 3.5.0 ja TypeScript 7:n kanssa tämän pois jättäminen aiheuttaa virheen SDK:n omissa määrityksissä, jota koodisi ei voi korjata.

SDK julkaistaan ES-moduulina ja se sisältää omat tyypit: sille ei tarvita erillistä @types/-pakettia. Jos editorissasi ei ole automaattista täydennystä, vika on tsconfig.json-tiedostossasi, ei puuttuvassa tyypityspaketissa.

Ympäristömuuttujan määrittäminen

Älä koskaan kovakoodaa API-avainta lähdekoodiisi. Node.js:ssä standardiratkaisu on dotenv, joka lataa muuttujat paikallisesta tiedostosta prosessin käynnistyessä:

npm install dotenv

Luo .env-tiedosto projektisi juureen:

MISTRAL_API_KEY=your-api-key-here

Lisää tämä tiedosto .gitignore-tiedostoosi välittömästi, ennen ensimmäistä commitia. Avaimet vuotavat juuri tässä vaiheessa:

.env
.env.local

dotenv/config-tuonnin on edellettävä kaikkia process.env:n lukemisia. Muuten muuttuja pysyy määrittelemättömänä, kun alustat asiakasohjelman:

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

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

Asennuksen vahvistaminen

Ennen liiketoimintalogiikan kirjoittamista validoitu koko ketju – asennus, avain, verkko – minimaalisella skriptillä. Luo src/test-mistral.ts ja pyydä yksinkertaisesti luetteloa tilillesi saatavilla olevista malleista:

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

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

  // Listaa saatavilla olevat mallit
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Tämä SDK-versio tuntematon mallityyppi merkitään 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Nämä kaksi tarkistusta eivät ole koristeellisia. SDK määrittelee data:n valinnaiseksi, ja jokainen luettelon merkintä on joko perusmallikortti, hienosäädetty mallikortti tai tuntematon arvo (type: 'UNKNOWN'). Kun API lisää uuden mallityypin, SDK säilyttää sen tässä muodossa kaatumisen sijaan. Ilman näitä kahta testiä tiukka tila kieltäytyy kääntämästä koodia.

Kehitysvaiheessa suorita se tsx:llä, jonka asensit aiemmin; se transpiloi koodin lennossa ja säästää sinut erilliseltä käännösvaiheelta:

npx tsx src/test-mistral.ts

Varoitus: tsx ei tarkista tyyppejä; se riisuu ne ja suorittaa koodin. Vain tsc ilmoittaa tyypitysvirheet. Suorita npx tsc --noEmit tarkistaaksesi tyypit kääntämättä. Kääntääksesi ja suorittaaksesi, kuten build-putkesi tekee:

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

Kelvollinen avain näyttää mallien määrän ja viisi ensimmäistä merkintää. Hylätty avain näyttää virheen Status 401 (Invalid API Key): ketju toimii, vika on vain avaimessa.

Projektin organisointi

Kun vahvistus on onnistunut, jäsennä projekti niin, että avain ja asiakasohjelma eivät hajaannu eri tiedostoihin:

mon-projet/
├── src/
│   ├── index.ts          # Sisääntulopiste
│   ├── mistral-client.ts # Asiakasohjelman alustus (singleton)
│   └── utils/
├── .env                  # Ympäristömuuttujat (git-ignoreoitu)
├── .gitignore
├── package.json
└── tsconfig.json

Asiakasohjelman alustuksen keskittäminen omaan moduuliinsa estää sen uudelleenluonnin jokaisessa tiedostossa. Vielä tärkeämpää on, että tämä saa sovelluksen epäonnistumaan käynnistyksessä, jos avain puuttuu, eikä vasta ensimmäisen käyttäjäkutsun yhteydessä:

// 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,
});

Loppukoodi tuo vain tämän valmiin asiakasohjelman:

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

Huomaa .js-pääte suhteellisessa tuonnissa. Kun käytössä on module: nodenext, TypeScript vaatii tiedostonimeä sellaisena kuin se on kääntämisen jälkeen, ja tsx osaa mapata sen .ts-tiedostoon. Tuontijärjestyksellä on myös väliä: dotenv/config suoritetaan ennen mistral-client.js:ää, joten avain on ladattu, kun tuo moduuli tarkistaa sen olemassaolon.

Keskeiset asiat

  • Asenna TypeScript SDK komennolla npm install @mistralai/mistralai
  • Pääasiallinen tuonti on import { Mistral } from '@mistralai/mistralai'
  • Asenna typescript, tsx ja @types/node kehitysriippuvuuksina ennen komennon npx tsc kutsumista
  • Käytä asetuksia module: nodenext ja "type": "module" koodille, jonka Node.js kääntää ja suorittaa; suhteelliset tuonnit ottavat .js-päätteen
  • Käytä .env-tiedostoa dotenv:n kanssa API-avaimen hallintaan
  • SDK tarjoaa natiivit TypeScript-tyypit: hyödynnä automaattista täydennystä ja anna tsc:n tarkistaa se, minkä tsx ohittaa
  • Keskitä asiakasohjelman alustus omaan moduuliinsa