Инсталиране на TypeScript SDK за Mistral
На тази страница
Урокът е актуализиран на 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пропуска - Централизирайте инициализацията на клиента в отделен модул