Asenna Mistral TypeScript SDK
Tällä sivulla
Oppiaine päivitetty 3. marraskuuta 2026 sen jälkeen, kun esimerkit oli ajettu
@mistralai/mistralaiSDK:n versiolla 3.5.0 ja TypeScriptin versiolla 7.0.2. Alkuperäinen versio ei kääntynyt. Komennonnpx tscsuorittaminen ilman asennettua TypeScriptia lataa hylätyntsc-npm-paketin (versio 2.0.4) varsinaisen kääntäjän sijaan. Testiskripti sijaitsitsconfig.json-tiedostossa määritellynsrc-kansion ulkopuolella.process-objekti tunnistetaan vain, jos@types/nodeon asennettu. Lopuksi tiukka tila hylkää lausekkeetmodels.data.lengthjamodel.idilman ennakkotarkistusta.tsconfig.jsonnoudattaa 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.envaiheuttaa virheen “Cannot find name ‘process’”, vaikka@types/nodeolisi asennettu."rootDir": "src"asettaa lähdekoodin juurikansion käännetyille tiedostoille:src/test-mistral.tsmuuttuu muotoondist/test-mistral.js. Ilman tätä TypeScript 7 ilmoittaa virheen TS5011 aina, kun lähdetiedostosi eivät ole projektin juuressa."skipLibCheck": trueohittaa riippuvuuksien määritystiedostojen tyyppitarkistuksen. Tämä on myös oletusasetusnpx tsc --init-komennolla luodussatsconfig.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,tsxja@types/nodekehitysriippuvuuksina ennen komennonnpx tsckutsumista - Käytä asetuksia
module: nodenextja"type": "module"koodille, jonka Node.js kääntää ja suorittaa; suhteelliset tuonnit ottavat.js-päätteen - Käytä
.env-tiedostoadotenv:n kanssa API-avaimen hallintaan - SDK tarjoaa natiivit TypeScript-tyypit: hyödynnä automaattista täydennystä ja anna
tsc:n tarkistaa se, minkätsxohittaa - Keskitä asiakasohjelman alustus omaan moduuliinsa