Įdiekite „Mistral“ TypeScript SDK
Šiame puslapyje
Pamoka atnaujinta 2026 m. lapkričio 3 d. po pavyzdžių paleidimo naudojant
@mistralai/mistralaiSDK 3.5.0 ir TypeScript 7.0.2. Originali versija nekompiliavosi. Paleidusnpx tscneįdiegus TypeScript, atsisiunčiamas apleistastscnpm paketas (2.0.4 versija) vietoj kompiliatoriaus. Testavimo scenarijus buvo užtsconfig.jsonfaile deklaruotosrcaplanko ribų.processobjektas atpažįstamas tik su@types/node. Galiausiai, griežtas režimas (strict mode) atmetamodels.data.lengthirmodel.idbe išankstinio patikrinimo.tsconfig.jsondabar atitinka oficialaus TypeScript vadovo „kompiliuok, tada paleisk su Node.js“ scenarijų; Node.js 18 ir 20, kurių gyvavimo ciklas baigėsi, nebelaikomi tinkamais. Šaltiniai: Atsisiųsti TypeScript · Kompiliatoriaus parinkčių pasirinkimas (TypeScript) · TypeScript 6.0 pakeitimai · tsx ir TypeScript · SDK palaikomos vykdymo aplinkos · Node.js leidimų grafikas.
Kodėl verta naudoti TypeScript SDK?
Jei tavo technologijų stackas remiasi „Node.js“, „Deno“ arba „Bun“, „Mistral“ TypeScript SDK leidžia tiesiogiai integruoti modelius į tavo JavaScript ir TypeScript programas. Išvengi tarpinių Python sluoksnių arba poreikio rašyti individualius HTTP užklausų kodą. Tai dažniausias scenarijus, kai dirbtinį intelektą nori pridėti prie esamos žiniatinklio programos: „Express“ API, „Next.js“ serverinės dalies arba „Node“ darbuotojo, apdorojančio žinučių eilę.
TypeScript statinis tipizavimas suteikia saugumo tinklą, kuris atperka save jau per pirmąją kūrimo valandą. Redaktorius užbaigia parametrų pavadinimus, tau nereikia spėlioti, ar rašyti maxTokens, ar max_tokens; raidžių dydžio klaidos arba sugalvoti laukai aptinkami kompiliacijos metu, o ne gamyboje 3 val. ryto; parametrų dokumentacija atsiranda užvedus pelę, neišeinant iš failo. Šis saugumo tinklas ypač svarbus, nes API atsakymai yra įdėtieji objektai, kuriuose lengva praleisti lygmenį.
Būtinos sąlygos
SDK skirtas palaikomoms LTS „Node.js“ versijoms. 2026 m. lapkričio 3 d. tai yra 22, 24 ir 26 versijos; „Node.js“ 18 ir 20 nebegauna saugumo pataisymų. Prieš tęsdamas patikrink savo versiją komanda node --version: SDK remiasi ES moduliais ir vietine fetch API. Tau taip pat reikia paketų tvarkyklės (npm, yarn arba pnpm) ir „Mistral“ API rakto, sukurto ir pasiekiamo kaip aplinkos kintamasis, kaip aptarta ankstesnėse pamokose.
Diegimas
Oficialus SDK publikuojamas npm kaip @mistralai/mistralai:
# Naudojant npm
npm install @mistralai/mistralai
# Naudojant yarn
yarn add @mistralai/mistralai
# Naudojant pnpm
pnpm add @mistralai/mistralai
TypeScript konfigūracija
Jei naudoji TypeScript – ką ir rekomenduojame – įdiek tris įrankius kaip kūrimo priklausomybes: kompiliatorių, tsx (kuris paleidžia .ts failus be kompiliavimo žingsnio) ir @types/node (kuris aprašo „Node.js“ objektus, tokius kaip process, TypeScript kalbai):
npm install -D typescript tsx @types/node
Nepraleisk šio žingsnio. Jei projekte neįdiegtas TypeScript, npx tsc iš npm atsisiųs tsc paketą – apleistą senovinį kompiliatorių (2.0.4) – vietoj tikrojo TypeScript. Toliau deklaruok projektą kaip ES modulius, kaip reikalauja TypeScript dokumentacija kodui, kuris pirmiausia kompiliuojamas, o tada paleidžiamas su „Node.js“:
npm pkg set type=module
Galiausiai sukurk tsconfig.json. Jame naudojamos nuostatos, kurias oficialus TypeScript vadovas rekomenduoja šiam scenarijui (module: nodenext). Jame taip pat įjungiamas griežtas režimas (strict mode), kuris verčia tvarkyti galimai trūkstamas reikšmes API atsakymuose – tai sveika apribojimas – ir kompiliuoja src/ į dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Trys eilutės nusipelno paaiškinimo, nes kiekviena jų užkerta kelią klaidai, su kuria susidūrėme testuodami šią pamoką:
"types": ["node"]įkelia „Node.js“ tipus. Nuo TypeScript 6.0 versijos@typespaketai nebėra įkeliami automatiškai. Be šios eilutės,process.enviššaukia klaidą „Cannot find name ‘process’“, net jei@types/nodeįdiegtas."rootDir": "src"nustato šaltinių šakninį aplanką kompiliuotiems failams:src/test-mistral.tstampadist/test-mistral.js. Be jo, TypeScript 7 praneša klaidą TS5011, kai šaltiniai nėra projekto šaknyje."skipLibCheck": truepraleidžia priklausomybių deklaracijų failų tipų tikrinimą. Tai taip pat yra numatytoji nustatymo reikšmėtsconfig.jsonfaile, sugeneruotamenpx tsc --init. Su SDK 3.5.0 ir TypeScript 7, praleidus šią nuostatą, kyla klaida paties SDK deklaracijose, kurios tavo kodas negali ištaisyti.
SDK publikuojamas kaip ES moduliai ir turi savo tipus: jam nereikia jokio @types/ paketo. Jei redaktoriuje neveikia automatinis užbaigimas, problema slypi tavo tsconfig.json, o ne trūkstamame tipų pakete.
Aplinkos kintamojo konfigūravimas
Niekada nekoduok API rakto tiesiai į savo šaltinio kodą. „Node.js“ standartinis sprendimas yra dotenv, kuris įkelia kintamuosius iš vietinio failo proceso paleidimo metu:
npm install dotenv
Sukurk .env failą savo projekto šaknyje:
MISTRAL_API_KEY=your-api-key-here
Nedelsiant, prieš pirmąjį įsipareigojimą (commit), įtrauk šį failą į .gitignore. Būtent šiuo momentu raktai nuteka:
.env
.env.local
dotenv/config importavimas turi vykti prieš bet kokį process.env skaitymą. Priešingu atveju kintamasis lieka neapibrėžtas kuriant kliento instanciją:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Diegimo patikrinimas
Prieš rašydami verslo logiką, patikrinkite visą grandinę – diegimą, raktą, tinklą – naudodami minimalų scenarijų. Sukurk src/test-mistral.ts ir tiesiog paprašyk sąrašo modelių, prieinamų tavo paskyrai:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Išvardyti prieinamus modelius
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Available models: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Šiai SDK versijai nežinomas modelio tipas pažymimas kaip 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Šie du patikrinimai nėra dekoratyviniai. SDK deklaruoja data kaip nebūtiną, o kiekvienas sąrašo įrašas yra arba bazinė modelio kortelė, arba suderinto modelio kortelė, arba nežinoma reikšmė (type: 'UNKNOWN'). Kai API prideda naują modelio tipą, SDK jį išsaugo šia forma vietoj to, kad „lūžtų“. Be šių dviejų testų griežtas režimas atsisako kompiliuoti.
Kūrimo metu paleisk jį su tsx, kurį įdiegei anksčiau; jis transliuoja kodą realiuoju laiku ir sutaupo kompiliavimo žingsnį:
npx tsx src/test-mistral.ts
Įspėjimas: tsx netikrina tipų; jis juos pašalina ir vykdo kodą. Tik tsc praneša apie tipizavimo klaidas. Norėdami patikrinti nekompiliuodami, paleisk npx tsc --noEmit. Norėdami pirmiausia sukompiliuoti, o tada paleisti, kaip darys tavo kūrimo vamzdynas:
npx tsc && node dist/test-mistral.js
Galiojantis raktas parodo modelių skaičių ir pirmuosius penkis įrašus. Atmestas raktas parodo Status 401 klaidą (Invalid API Key): grandinė veikia, kaltas tik raktas.
Projekto organizavimas
Kai patikrinimas pavyksta, sutvarkyk projektą taip, kad raktas ir klientas nebūtų išbarstyti po visus failus:
mon-projet/
├── src/
│ ├── index.ts # Įvesties taškas
│ ├── mistral-client.ts # Kliento inicializavimas (vienetinis objektas)
│ └── utils/
├── .env # Aplinkos kintamieji (ignoruojami git)
├── .gitignore
├── package.json
└── tsconfig.json
Kliento inicializavimo centralizavimas atskirame modulyje leidžia išvengti jo kūrimo kiekviename faile. Svarbiausia tai, kad tai priverčia programą žlugti paleidimo metu, o ne pirmojo vartotojo užklausos metu, jei trūksta rakto:
// 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,
});
Likęs kodas tiesiog importuoja šį paruoštą klientą:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Atkreipk dėmesį į .js plėtinį santykinio importavimo metu. Naudojant module: nodenext, TypeScript reikalauja failo pavadinimo tokio, koks jis bus po kompiliacijos, o tsx žino, kaip jį susieti su .ts failu. Importavimo tvarka taip pat svarbi: dotenv/config įvykdomas prieš mistral-client.js, todėl raktas būna įkeltas tuo metu, kai tas modulis tikrina jo buvimą.
Svarbiausi punktai
- Įdiek TypeScript SDK komanda
npm install @mistralai/mistralai - Pagrindinis importavimas yra
import { Mistral } from '@mistralai/mistralai' - Prieš kviesdamas
npx tsc, įdiektypescript,tsxir@types/nodekaip kūrimo priklausomybes - Naudok
module: nodenextir"type": "module", kai kodas kompiliuojamas, o tada paleidžiamas su „Node.js“; santykiniai importai turi turėti.jsplėtinį - Naudok
.envfailą sudotenv, kad valdytum API raktą - SDK pateikia vietinius TypeScript tipus: išnaudok automatinį užbaigimą ir leisk
tscpatikrinti tai, kątsxpraleidžia - Centralizuok kliento inicializavimą atskirame modulyje