Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Instalar o SDK TypeScript da Mistral

Aula 8 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Por que utilizar o SDK TypeScript?
  2. Pré-requisitos
  3. Instalação
  4. Configuração do TypeScript
  5. Configurar a Variável de Ambiente
  6. Verificar a Instalação
  7. Organizar o Projeto
  8. Pontos-chave

Lição atualizada em 3 de novembro de 2026 após execução dos exemplos com o SDK @mistralai/mistralai 3.5.0 e TypeScript 7.0.2. A versão original não compilava. Executar npx tsc sem o TypeScript instalado transfere o pacote npm abandonado tsc (versão 2.0.4) em vez do compilador. O script de teste estava localizado fora da pasta src declarada em tsconfig.json. O objeto process só é reconhecido com @types/node. Por fim, o modo estrito rejeita models.data.length e model.id sem validação prévia. O tsconfig.json segue agora o cenário «compilar e depois executar com Node.js» do guia TypeScript, e as versões Node.js 18 e 20, que chegaram ao fim de vida, deixaram de ser listadas como suficientes. Fontes: Download TypeScript · Choosing compiler options (TypeScript) · TypeScript 6.0 changes · tsx and TypeScript · SDK supported runtimes · Node.js release schedule.

Por que utilizar o SDK TypeScript?

Se a sua pilha tecnológica assenta no Node.js, Deno ou Bun, o SDK TypeScript da Mistral permite-lhe integrar modelos diretamente nas suas aplicações JavaScript e TypeScript. Evita camadas intermédias em Python ou a escrita de chamadas HTTP personalizadas. Este é o cenário mais comum ao adicionar IA a uma aplicação web existente: uma API Express, um backend Next.js ou um worker Node a processar uma fila de mensagens.

A tipagem estática do TypeScript adiciona uma rede de segurança que compensa logo na primeira hora de desenvolvimento. O seu editor completa os nomes dos parâmetros, poupando-o de adivinhar entre maxTokens e max_tokens; erros de capitalização ou campos inventados surgem na compilação, e não em produção às 3 da manhã; e a documentação dos parâmetros aparece ao passar o rato, sem sair do ficheiro. Esta rede de segurança é ainda mais relevante porque as respostas da API são objetos aninhados, onde é fácil perder um nível.

Pré-requisitos

O SDK destina-se às versões LTS mantidas do Node.js. Em 3 de novembro de 2026, estas são as versões 22, 24 e 26; o Node.js 18 e 20 já não recebem correções de segurança. Verifique a sua versão com node --version antes de prosseguir: o SDK depende de módulos ES e da API nativa fetch. Precisa também de um gestor de pacotes (npm, yarn ou pnpm) e de uma chave de API Mistral criada e disponível como variável de ambiente, conforme abordado em lições anteriores.

Instalação

O SDK oficial é publicado no npm como @mistralai/mistralai:

# Com npm
npm install @mistralai/mistralai

# Com yarn
yarn add @mistralai/mistralai

# Com pnpm
pnpm add @mistralai/mistralai

Configuração do TypeScript

Se utilizar TypeScript — o que recomendamos — instale três ferramentas como dependências de desenvolvimento: o compilador, tsx (que executa ficheiros .ts sem etapa de compilação) e @types/node (que descreve objetos do Node.js como process ao TypeScript):

npm install -D typescript tsx @types/node

Não salte esta etapa. Sem o TypeScript instalado no projeto, npx tsc obtém o pacote tsc do npm — um compilador legado abandonado (2.0.4) — em vez do TypeScript. De seguida, declare o projeto como módulos ES, tal como a documentação do TypeScript exige para código compilado e depois executado pelo Node.js:

npm pkg set type=module

Por fim, crie tsconfig.json. Utiliza as definições que o guia oficial do TypeScript recomenda para este cenário (module: nodenext). Ativa também o modo estrito, que o obriga a lidar com valores potencialmente ausentes nas respostas da API — uma restrição saudável — e compila src/ para dist/:

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

Três linhas merecem explicação, pois cada uma previne um erro detetado durante os testes desta lição:

  • "types": ["node"] carrega os tipos do Node.js. Desde o TypeScript 6.0, os pacotes @types deixaram de ser carregados automaticamente. Sem esta linha, process.env desencadeia o erro “Cannot find name ‘process’”, mesmo com @types/node instalado.
  • "rootDir": "src" define a raiz de origem para os ficheiros compilados: src/test-mistral.ts torna-se dist/test-mistral.js. Sem isto, o TypeScript 7 reporta o erro TS5011 sempre que os seus fontes não estiverem na raiz do projeto.
  • "skipLibCheck": true ignora a verificação de tipos nos ficheiros de declaração de dependências. Esta é também uma definição padrão em tsconfig.json gerado por npx tsc --init. Com o SDK 3.5.0 e o TypeScript 7, omitir isto causa um erro nas próprias declarações do SDK que o seu código não consegue corrigir.

O SDK é publicado como módulos ES e inclui os seus próprios tipos: não é necessário nenhum pacote @types/ para o mesmo. Se o seu editor não tiver preenchimento automático, o problema reside no seu tsconfig.json, e não na falta de um pacote de tipos.

Configurar a Variável de Ambiente

Nunca codifique a chave de API diretamente no seu código-fonte. No Node.js, a solução padrão é dotenv, que carrega variáveis de um ficheiro local no arranque do processo:

npm install dotenv

Crie um ficheiro .env na raiz do seu projeto:

MISTRAL_API_KEY=your-api-key-here

Adicione imediatamente este ficheiro ao seu .gitignore, antes do seu primeiro commit. É exatamente neste momento que as chaves escapam:

.env
.env.local

A importação dotenv/config deve preceder qualquer leitura de process.env. Caso contrário, a variável permanece indefinida quando instancia o cliente:

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

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

Verificar a Instalação

Antes de escrever lógica de negócio, valide toda a cadeia — instalação, chave, rede — com um script mínimo. Crie src/test-mistral.ts e solicite simplesmente a lista de modelos acessíveis à sua conta:

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

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

  // Listar modelos disponíveis
  const models = await client.models.list();
  const liste = models.data ?? [];
  console.log(`Available models: ${liste.length}`);

  for (const model of liste.slice(0, 5)) {
    // Um tipo de modelo desconhecido para esta versão do SDK é marcado como 'UNKNOWN'
    if (model.type === 'UNKNOWN') continue;
    console.log(`  - ${model.id}`);
  }
}

main().catch(console.error);

Estas duas verificações não são decorativas. O SDK declara data como opcional, e cada entrada da lista é quer um cartão de modelo base, quer um cartão de modelo ajustado (fine-tuned), quer um valor desconhecido (type: 'UNKNOWN'). Quando a API adiciona um novo tipo de modelo, o SDK preserva-o nesta forma em vez de falhar. Sem estes dois testes, o modo estrito recusa-se a compilar.

Em desenvolvimento, execute-o com tsx, instalado anteriormente, que transpila em tempo real e poupa-lhe uma etapa de compilação:

npx tsx src/test-mistral.ts

Aviso: tsx não verifica tipos; remove-os e executa. Apenas tsc reporta erros de tipagem. Execute npx tsc --noEmit para verificar sem compilar. Para compilar e depois executar, tal como a sua pipeline de build fará:

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

Uma chave válida apresenta a contagem de modelos e as primeiras cinco entradas. Uma chave rejeitada apresenta um erro Status 401 (Invalid API Key): a cadeia funciona, apenas a chave está incorreta.

Organizar o Projeto

Assim que a verificação for bem-sucedida, estruture o projeto para que a chave e o cliente não se dispersem por vários ficheiros:

mon-projet/
├── src/
│   ├── index.ts          # Ponto de entrada
│   ├── mistral-client.ts # Inicialização do cliente (singleton)
│   └── utils/
├── .env                  # Variáveis de ambiente (ignoradas pelo git)
├── .gitignore
├── package.json
└── tsconfig.json

Centralizar a inicialização do cliente num módulo dedicado evita recriá-lo em todos os ficheiros. Mais importante ainda, faz com que a aplicação falhe no arranque, e não na primeira chamada do utilizador, caso a chave esteja em falta:

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

O restante código simplesmente importa este cliente pré-configurado:

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

Note a extensão .js na importação relativa. Com module: nodenext, o TypeScript exige o nome do ficheiro tal como existirá após a compilação, e tsx sabe mapeá-lo para o ficheiro .ts. A ordem de importação também importa: dotenv/config executa antes de mistral-client.js, pelo que a chave é carregada quando esse módulo verifica a sua presença.

Pontos-chave

  • Instale o SDK TypeScript com npm install @mistralai/mistralai
  • A importação principal é import { Mistral } from '@mistralai/mistralai'
  • Instale typescript, tsx e @types/node como dependências de desenvolvimento antes de chamar npx tsc
  • Utilize module: nodenext e "type": "module" para código compilado e depois executado pelo Node.js; as importações relativas levam a extensão .js
  • Utilize um ficheiro .env com dotenv para gerir a chave de API
  • O SDK fornece tipos TypeScript nativos: aproveite o preenchimento automático e deixe o tsc verificar o que o tsx ignora
  • Centralize a inicialização do cliente num módulo dedicado