Премини към основното съдържание
Български— Изберете език
Меню

Инсталиране на TypeScript SDK за Mistral

Урок 8 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Защо да използвате TypeScript SDK?
  2. Предварителни изисквания
  3. Инсталация
  4. Конфигурация на TypeScript
  5. Конфигуриране на променливата на средата
  6. Проверка на инсталацията
  7. Организиране на проекта
  8. Ключови изводи

Урокът е актуализиран на 3 ноември 2026 г. след тестване на примерите със SDK @mistralai/mistralai версия 3.5.0 и TypeScript 7.0.2. Оригиналната версия не се компилираше. Изпълнението на npx tsc без инсталиран TypeScript изтегля изоставения npm пакет tsc (версия 2.0.4) вместо компилатора. Тестовият скрипт се намираше извън папката src, декларирана в tsconfig.json. Обектът process се разпознава само с @types/node. Накрая, стриктният режим отхвърля models.data.length и model.id без предварителна валидация. Файлът tsconfig.json сега следва сценария „компилирай, след това изпълни с Node.js“ от ръководството на TypeScript, а Node.js 18 и 20, които достигнаха края на своя жизнен цикъл, вече не са посочени като достатъчни. Източници: Изтегляне на TypeScript · Избор на опции за компилатора (TypeScript) · Промени в TypeScript 6.0 · tsx и TypeScript · Поддържани среди за изпълнение от SDK · График на releases за Node.js.

Защо да използвате TypeScript SDK?

Ако вашият стек разчита на Node.js, Deno или Bun, TypeScript SDK за Mistral Ви позволява да интегрирате моделите директно във Вашите JavaScript и TypeScript приложения. Така избягвате междинни Python слоеве или писането на персонализирани HTTP заявки. Това е най-честият сценарий при добавяне на изкуствен интелект към съществуващо уеб приложение: Express API, Next.js бекенд или Node worker, обработващ опашка със съобщения.

Статичното типизиране на TypeScript добавя защитна мрежа, която се изплаща още в първия час на разработка. Вашият редактор допълва имената на параметрите, вместо да Ви кара да гадавате между maxTokens и max_tokens; грешки в главните/малките букви или измислени полета се откриват по време на компилация, а не в продукцията в 3 сутринта; документацията на параметрите се появява при задържане на курсора, без да напускате файла. Тази защитна мрежа е още по-важна, защото отговорите на API са вложени обекти, в които лесно може да пропуснете ниво.

Предварителни изисквания

SDK е насочен към поддържаните LTS версии на Node.js. Към 3 ноември 2026 г. това са версии 22, 24 и 26; Node.js 18 и 20 вече не получават корекции на сигурността. Проверете Вашата версия с node --version, преди да продължите: SDK разчита на ES модули и нативния fetch API. Също така Ви е необходим мениджър на пакети (npm, yarn или pnpm) и API ключ за Mistral, създаден и наличен като променлива на средата, както бе разгледано в предишните уроци.

Инсталация

Официалният SDK е публикуван в npm като @mistralai/mistralai:

# С npm
npm install @mistralai/mistralai

# С yarn
yarn add @mistralai/mistralai

# С pnpm
pnpm add @mistralai/mistralai

Конфигурация на TypeScript

Ако използвате TypeScript – което препоръчваме – инсталирайте три инструмента като зависимости за разработка: компилатора, tsx (който изпълнява .ts файлове без стъпка на изграждане) и @types/node (който описва обекти на Node.js като process за TypeScript):

npm install -D typescript tsx @types/node

Не пропускайте тази стъпка. Без инсталиран TypeScript в проекта, npx tsc изтегля пакета tsc от npm – изоставен наследен компилатор (2.0.4) – вместо TypeScript. След това декларирайте проекта като ES модули, както изисква документацията на TypeScript за код, който се компилира и след това се изпълнява от Node.js:

npm pkg set type=module

Накрая, създайте tsconfig.json. Той използва настройките, които официалното ръководство на TypeScript препоръчва за този сценарий (module: nodenext). Също така активира стриктен режим, който Ви принуждава да обработвате потенциално липсващи стойности в отговорите на API – здравословно ограничение – и компилира src/ в dist/:

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

Три реда заслужават обяснение, тъй като всеки от тях предотвратява грешка, с която се сблъскахме при тестването на този урок:

  • "types": ["node"] зарежда типовете за Node.js. От TypeScript 6.0 нататък, пакетите @types вече не се зареждат автоматично. Без този ред, process.env предизвиква грешката “Cannot find name ‘process’”, дори при инсталиран @types/node.
  • "rootDir": "src" задава кореновата директория за изходните файлове: src/test-mistral.ts става dist/test-mistral.js. Без него, TypeScript 7 докладва грешка TS5011, когато изходният Ви код не е в корена на проекта.
  • "skipLibCheck": true пропуска проверката на типовете във файловете с декларации на зависимостите. Това също е настройка по подразбиране в tsconfig.json, генериран от npx tsc --init. При SDK 3.5.0 и TypeScript 7, пропускането на това причинява грешка в собствените декларации на SDK, които Вашият код не може да поправи.

SDK е публикуван като ES модули и включва собствените си типове: не е необходим пакет @types/ за него. Ако Вашият редактор няма автоматично довършване, проблемът е във Вашия tsconfig.json, а не в липсващ пакет с типове.

Конфигуриране на променливата на средата

Никога не вграждайте API ключа директно във Вашия изходен код. В Node.js стандартното решение е dotenv, което зарежда променливи от локален файл при стартиране на процеса:

npm install dotenv

Създайте файл .env в корена на Вашия проект:

MISTRAL_API_KEY=your-api-key-here

Добавете този файл във Вашия .gitignore незабавно, преди първия си комит. Това е точният момент, в който ключовете изтичат:

.env
.env.local

Импортирането на dotenv/config трябва да предшества всяко четене на process.env. В противен случай променливата остава неопределена, когато инстанцирате клиента:

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

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

Проверка на инсталацията

Преди да пишете бизнес логика, валидирайте цялата верига – инсталация, ключ, мрежа – с минимален скрипт. Създайте src/test-mistral.ts и просто поискайте списъка с модели, достъпни за Вашия акаунт:

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

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

  // Списък с наличните модели
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Тип модел, непознат за тази версия на SDK, се маркира като 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Тези две проверки не са декоративни. SDK декларира data като опционално, а всеки запис в списъка е или основна карта на модел, карта на фино настроен модел, или неизвестна стойност (type: 'UNKNOWN'). Когато API добави нов тип модел, SDK го запазва в този вид, вместо да се срине. Без тези два теста, стриктният режим отказва да компилира.

По време на разработка го изпълнете с tsx, инсталиран по-рано, който транспилира в реално време и Ви спестява стъпка на изграждане:

npx tsx src/test-mistral.ts

Предупреждение: tsx не проверява типовете; той ги премахва и изпълнява кода. Само tsc докладва грешки в типизирането. Изпълнете npx tsc --noEmit, за да проверите без компилиране. За да компилирате и след това да изпълните, както ще направи Вашата тръба за изграждане:

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

Валиден ключ показва броя на моделите и първите пет записа. Отхвърлен ключ показва грешка Status 401 (Invalid API Key): веригата работи, виновник е само ключът.

Организиране на проекта

След като проверката премине успешно, структурирайте проекта така, че ключът и клиентът да не са разпръснати във файловете:

mon-projet/
├── src/
│   ├── index.ts          # Точка на влизане
│   ├── mistral-client.ts # Инициализация на клиента (singleton)
│   └── utils/
├── .env                  # Променливи на средата (игнорирани от git)
├── .gitignore
├── package.json
└── tsconfig.json

Централизирането на инициализацията на клиента в отделен модул избягва неговото повторно създаване във всеки файл. По-важното е, че това кара приложението да се провали при стартиране, а не при първото повикване от потребителя, ако ключът липсва:

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

Останалата част от кода просто импортира този предварително изграден клиент:

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

Обърнете внимание на разширението .js в относителния импорт. При module: nodenext, TypeScript изисква името на файла такова, каквото ще бъде след компилация, а tsx знае как да го картографира обратно към .ts файла. Редът на импортиране също има значение: dotenv/config се изпълнява преди mistral-client.js, така че ключът е зареден, когато този модул проверява наличието му.

Ключови изводи

  • Инсталирайте TypeScript SDK с npm install @mistralai/mistralai
  • Основният импорт е import { Mistral } from '@mistralai/mistralai'
  • Инсталирайте typescript, tsx и @types/node като зависимости за разработка, преди да извикате npx tsc
  • Използвайте module: nodenext и "type": "module" за код, който се компилира и след това се изпълнява от Node.js; относителните импорти приемат разширението .js
  • Използвайте .env файл с dotenv за управление на API ключа
  • SDK предоставя собствени TypeScript типове: възползвайте се от автоматичното довършване и оставете tsc да проверява това, което tsx пропуска
  • Централизирайте инициализацията на клиента в отделен модул