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

Primeira Chamada e Streaming em TypeScript

Aula 9 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Envie o Seu Primeiro Pedido
  2. Streaming
  3. Conversas Multi-Turno
  4. Ajustar a Geração e Tratar Erros
  5. Pontos-chave

Lição atualizada a 3 de novembro de 2026 após compilar exemplos em modo estrito com o SDK @mistralai/mistralai 3.5.0 e TypeScript 7.0.2. O SDK tipifica content como string | ContentChunk[]: conversas multi-turno e loops de streaming falhavam na compilação sem uma verificação typeof content === 'string'. O exemplo de configuração combinava anteriormente temperature e topP, o que a documentação da API desaconselha modificar em conjunto. O tratamento de erros utiliza agora a classe MistralError do SDK, e a rota Express valida a pergunta antes de chamar a API. Fontes: Mistral TypeScript SDK (README) · parâmetros de conclusão de chat.

Envie o Seu Primeiro Pedido

Agora que o SDK está instalado, vamos à prática. O método chat.complete() do SDK TypeScript é o equivalente exato do SDK Python: mesmos parâmetros, mesma estrutura de resposta, exceto pelas convenções de nomenclatura. Se seguiu as lições de Python, está em terreno familiar; apenas a sintaxe assíncrona do JavaScript é nova.

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

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

async function main() {
  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: [
      {
        role: 'user',
        content: 'Explain the concept of a closure in JavaScript in three sentences.',
      },
    ],
  });

  console.log(response.choices[0]?.message?.content);
}

main();

Os pontos de interrogação em response.choices[0]?.message?.content não são apenas decorativos: nos tipos do SDK, message e content são opcionais, e choices[0] não existe se a lista vier vazia. O acesso seguro devolve undefined em vez de lançar uma exceção. Note também que content nem sempre é uma string: o SDK tipifica-o como string | ContentChunk[] porque uma resposta pode chegar como uma lista de fragmentos (texto, raciocínio thinking, referências, etc.).

Compreender a Resposta

A estrutura da resposta é idêntica à do SDK Python. Analisá-la ajuda a entender pelo que está a pagar e porque é que uma resposta parou. O exemplo seguinte extrai o texto, o motivo da paragem e a contagem de tokens um a um; ao digitá-lo, o seu editor sugerirá cada campo, provando que a tipagem está a fazer o seu trabalho.

async function analyserReponse() {
  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: [
      { role: 'user', content: 'What is the capital of France?' },
    ],
    maxTokens: 100,
  });

  // Texto da resposta
  const texte = response.choices[0]?.message?.content;

  // Motivo da paragem
  const finRaison = response.choices[0]?.finishReason;

  // Estatísticas de tokens
  const tokensEntree = response.usage?.promptTokens;
  const tokensSortie = response.usage?.completionTokens;

  console.log(`Response: ${texte}`);
  console.log(`Tokens: ${tokensEntree} input + ${tokensSortie} output`);
  console.log(`Stop: ${finRaison}`);
}

Note a capitalização: onde o Python expõe max_tokens, finish_reason e prompt_tokens, o TypeScript usa maxTokens, finishReason e promptTokens. Este é o erro número um ao portar manualmente um exemplo de Python — e o compilador sinalizá-lo-á imediatamente.

Streaming

O streaming é essencial para interfaces web: sem ele, o utilizador encara um ecrã congelado durante vários segundos; com ele, o texto aparece palavra por palavra e a latência percebida colapsa. O SDK TypeScript expõe o stream como um gerador assíncrono, que percorre com for await...of:

async function streamReponse() {
  const stream = await client.chat.stream({
    model: 'mistral-small-latest',
    messages: [
      {
        role: 'user',
        content: 'Describe the five main design patterns in JavaScript.',
      },
    ],
  });

  for await (const chunk of stream) {
    const content = chunk.data.choices[0]?.delta.content;
    if (typeof content === 'string') {
      process.stdout.write(content);
    }
  }
  console.log();
}

Dois detalhes merecem a sua atenção. O conteúdo reside em chunk.data, não diretamente em chunk: este é o wrapper de eventos do SDK desde a versão 1.0. E a verificação typeof content === 'string' filtra tanto fragmentos sem conteúdo, que sujariam a sua saída com undefined, como conteúdo em lista de fragmentos, que process.stdout.write não aceita: sem ela, o modo estrito recusa-se a compilar.

Expor o Stream via Express

Um stream que nunca sai do terminal não serve para nada. Eis como retransmiti-lo para um navegador usando Server-Sent Events a partir de uma API Express. A pergunta é validada antes de qualquer chamada para evitar enviar um pedido vazio à API. Os três cabeçalhos abrem então o canal, cada fragmento é enviado de volta como JSON num evento data:, e um marcador [DONE] sinaliza ao cliente para fechar a ligação.

import express from 'express';
import { Mistral } from '@mistralai/mistralai';

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

app.get('/api/chat', async (req, res) => {
  const question = typeof req.query.q === 'string' ? req.query.q : '';
  if (!question) {
    res.status(400).json({ error: 'Missing q parameter' });
    return;
  }

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const stream = await client.chat.stream({
    model: 'mistral-small-latest',
    messages: [{ role: 'user', content: question }],
  });

  for await (const chunk of stream) {
    const content = chunk.data.choices[0]?.delta.content;
    if (typeof content === 'string' && content) {
      res.write(`data: ${JSON.stringify({ text: content })}\n\n`);
    }
  }

  res.write('data: [DONE]\n\n');
  res.end();
});

app.listen(3000, () => console.log('Server on port 3000'));

Conversas Multi-Turno

A gestão do histórico segue o mesmo princípio que em Python: o modelo não tem memória, por isso mantém um array de mensagens e reenvia tudo a cada turno. Em TypeScript, declarar um tipo Message explícito impede que insira um papel inexistente ou um objeto mal formado — um erro que a API devolveria otherwise como um 400.

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

type Message = {
  role: 'system' | 'user' | 'assistant';
  content: string;
};

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

const historique: Message[] = [
  {
    role: 'system',
    content: 'You are an expert TypeScript assistant. Respond in English.',
  },
];

async function poserQuestion(question: string): Promise<string> {
  historique.push({ role: 'user', content: question });

  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: historique,
  });

  const contenu = response.choices[0]?.message?.content;
  const reponse = typeof contenu === 'string' ? contenu : '';
  historique.push({ role: 'assistant', content: reponse });

  return reponse;
}

async function main() {
  console.log(await poserQuestion('What is a generic type?'));
  console.log(await poserQuestion('Show me a concrete example.'));
  console.log(await poserQuestion('How do I add constraints?'));
}

main();

A verificação typeof contenu === 'string' não é um luxo: o campo content da resposta pode ser uma lista de fragmentos, enquanto o seu tipo Message espera uma string. Observe depois a terceira pergunta: “How do I add constraints?” só faz sentido porque as duas trocas anteriores ainda estão no array. Leve o exercício mais longe removendo a linha que adiciona a resposta do assistente ao histórico, e verá o modelo perder o fio à meada no segundo turno.

Ajustar a Geração e Tratar Erros

Os parâmetros avançados são idênticos aos do SDK Python — apenas muda a capitalização. Uma temperature baixa para um entregável estruturado e um maxTokens calibrado para o comprimento esperado produzem respostas mais previsíveis. Defina temperature ou topP, não ambos: esta é a recomendação da documentação da API, que aconselha uma temperature entre 0 e 0.7.

const response = await client.chat.complete({
  model: 'mistral-large-latest',
  messages: [
    { role: 'user', content: 'Propose an architecture for a B2B SaaS.' },
  ],
  temperature: 0.5,
  maxTokens: 1000,
});

Finalmente, qualquer chamada de rede pode falhar: chave inválida, quota excedida, indisponibilidade. Envolva sempre a chamada num try/catch e verifique o tipo de erro antes de ler as suas propriedades, caso contrário o TypeScript recusará a compilação. Todos os erros HTTP devolvidos pela API herdam de MistralError, que expõe statusCode e body; erros de rede (ConnectionError, RequestTimeoutError, etc.) não herdam dele, mas permanecem instâncias de Error.

import * as errors from '@mistralai/mistralai/models/errors';

try {
  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
  console.log(response.choices[0]?.message?.content);
} catch (error) {
  if (error instanceof errors.MistralError) {
    // Resposta de erro da API: 401 chave recusada, 429 limite atingido...
    console.error(`Mistral API Error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof Error) {
    // Sem resposta da API: rede em baixo, tempo limite excedido...
    console.error(`Error: ${error.message}`);
  }
}

Pontos-chave

  • client.chat.complete() é assíncrono — use await
  • O streaming usa for await...of no resultado de client.chat.stream()
  • A tipagem do TypeScript deteta erros de parâmetros em tempo de compilação
  • A integração SSE com Express é direta para interfaces web em tempo real
  • O histórico de conversação é gerido com um array tipado Message[]
  • content é uma string ou uma lista de fragmentos: teste typeof content === 'string' antes de o usar como texto
  • Os erros HTTP do SDK herdam de MistralError (statusCode, body)