Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Įdiekite „Mistral“ TypeScript SDK

Paskaita 8 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Kodėl verta naudoti TypeScript SDK?
  2. Būtinos sąlygos
  3. Diegimas
  4. TypeScript konfigūracija
  5. Aplinkos kintamojo konfigūravimas
  6. Diegimo patikrinimas
  7. Projekto organizavimas
  8. Svarbiausi punktai

Pamoka atnaujinta 2026 m. lapkričio 3 d. po pavyzdžių paleidimo naudojant @mistralai/mistralai SDK 3.5.0 ir TypeScript 7.0.2. Originali versija nekompiliavosi. Paleidus npx tsc neįdiegus TypeScript, atsisiunčiamas apleistas tsc npm paketas (2.0.4 versija) vietoj kompiliatoriaus. Testavimo scenarijus buvo už tsconfig.json faile deklaruoto src aplanko ribų. process objektas atpažįstamas tik su @types/node. Galiausiai, griežtas režimas (strict mode) atmeta models.data.length ir model.id be išankstinio patikrinimo. tsconfig.json dabar 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 @types paketai nebėra įkeliami automatiškai. Be šios eilutės, process.env iššaukia klaidą „Cannot find name ‘process’“, net jei @types/node įdiegtas.
  • "rootDir": "src" nustato šaltinių šakninį aplanką kompiliuotiems failams: src/test-mistral.ts tampa dist/test-mistral.js. Be jo, TypeScript 7 praneša klaidą TS5011, kai šaltiniai nėra projekto šaknyje.
  • "skipLibCheck": true praleidžia priklausomybių deklaracijų failų tipų tikrinimą. Tai taip pat yra numatytoji nustatymo reikšmė tsconfig.json faile, sugeneruotame npx 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, įdiek typescript, tsx ir @types/node kaip kūrimo priklausomybes
  • Naudok module: nodenext ir "type": "module", kai kodas kompiliuojamas, o tada paleidžiamas su „Node.js“; santykiniai importai turi turėti .js plėtinį
  • Naudok .env failą su dotenv, kad valdytum API raktą
  • SDK pateikia vietinius TypeScript tipus: išnaudok automatinį užbaigimą ir leisk tsc patikrinti tai, ką tsx praleidžia
  • Centralizuok kliento inicializavimą atskirame modulyje