Ir al contenido principal
Español— Elegir un idioma
Menú

Primera llamada y streaming en TypeScript

Lección 9 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Envía tu primera solicitud
  2. Streaming
  3. Conversaciones de varios turnos
  4. Ajuste de la generación y gestión de errores
  5. Puntos clave

Lección actualizada el 3 de noviembre de 2026 tras compilar los ejemplos en modo estricto con el SDK @mistralai/mistralai 3.5.0 y TypeScript 7.0.2. El SDK tipa content como string | ContentChunk[]: las conversaciones de varios turnos y los bucles de streaming no compilaban sin una comprobación typeof content === 'string'. El ejemplo de configuración combinaba anteriormente temperature y topP, algo que la documentación de la API desaconseja modificar simultáneamente. La gestión de errores utiliza ahora la clase MistralError del SDK, y la ruta de Express valida la pregunta antes de llamar a la API. Fuentes: Mistral TypeScript SDK (README) · parámetros de finalización de chat.

Envía tu primera solicitud

Ahora que el SDK está instalado, pasemos a la práctica. El método chat.complete() del SDK de TypeScript es exactamente equivalente al del SDK de Python: mismos parámetros, misma estructura de respuesta, salvo por las convenciones de nomenclatura. Si has seguido las lecciones de Python, estás en terreno conocido; lo único nuevo es la sintaxis asíncrona de JavaScript.

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();

Los signos de interrogación en response.choices[0]?.message?.content no están ahí por adornar: en los tipos del SDK, message y content son opcionales, y choices[0] no existe si la lista vuelve vacía. El acceso seguro devuelve undefined en lugar de lanzar una excepción. Ten también en cuenta que content no siempre es una cadena: el SDK lo tipa como string | ContentChunk[] porque una respuesta puede llegar como una lista de fragmentos (texto, razonamiento thinking, referencias, etc.).

Comprensión de la respuesta

La estructura de la respuesta es idéntica a la del SDK de Python. Analizarla te ayuda a entender qué estás pagando y por qué se detuvo una respuesta. El siguiente ejemplo extrae el texto, el motivo de parada y el recuento de tokens uno a uno; escribirlo hará que tu editor sugiera cada campo, demostrando que el tipado está haciendo su trabajo.

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 de la respuesta
  const texte = response.choices[0]?.message?.content;

  // Motivo de parada
  const finRaison = response.choices[0]?.finishReason;

  // Estadí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}`);
}

Fíjate en las mayúsculas: mientras que Python expone max_tokens, finish_reason y prompt_tokens, TypeScript usa maxTokens, finishReason y promptTokens. Este es el error número uno al portar manualmente un ejemplo de Python, y el compilador lo señalará de inmediato.

Streaming

El streaming es esencial para las interfaces web: sin él, el usuario contempla una pantalla congelada durante varios segundos; con él, el texto aparece palabra a palabra y la latencia percibida se desploma. El SDK de TypeScript expone el flujo como un generador asíncrono, que iteras con 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();
}

Dos detalles merecen tu atención. El contenido reside en chunk.data, no directamente en chunk: este es el contenedor de eventos del SDK desde la versión 1.0. Y la comprobación typeof content === 'string' filtra tanto los fragmentos sin contenido, que ensuciarían tu salida con undefined, como el contenido en forma de lista de fragmentos, que process.stdout.write no acepta: sin ella, el modo estricto se niega a compilar.

Exposición del flujo mediante Express

Un flujo que nunca sale de la terminal no sirve de nada. Aquí tienes cómo retransmitirlo a un navegador usando Server-Sent Events desde una API de Express. La pregunta se valida antes de cualquier llamada para evitar enviar una solicitud vacía a la API. Los tres encabezados abren entonces el canal, cada fragmento se envía de vuelta como JSON en un evento data:, y un marcador [DONE] señala al cliente que cierre la conexión.

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'));

Conversaciones de varios turnos

La gestión del historial sigue el mismo principio que en Python: el modelo no tiene memoria, así que mantienes un array de mensajes y reenvías todo el conjunto en cada turno. En TypeScript, declarar un tipo Message explícito evita introducir un rol inexistente o un objeto mal formado, un error que la API devolvería otherwise como un 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();

La comprobación typeof contenu === 'string' no es un lujo: el campo content de la respuesta puede ser una lista de fragmentos, mientras que tu tipo Message espera una cadena. Observa luego la tercera pregunta: «¿Cómo añado restricciones?» solo tiene sentido porque los dos intercambios anteriores siguen en el array. Pon a prueba el ejercicio eliminando la línea que añade la respuesta del asistente al historial, y verás cómo el modelo pierde el hilo en el segundo turno.

Ajuste de la generación y gestión de errores

Los parámetros avanzados son idénticos a los del SDK de Python; solo cambia la capitalización. Una temperature baja para un entregable estructurado y un maxTokens calibrado a la longitud esperada producen respuestas más predecibles. Establece temperature o topP, no ambos: esta es la recomendación de la documentación de la API, que aconseja una temperature entre 0 y 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,
});

Por último, cualquier llamada de red puede fallar: clave no válida, cuota superada, interrupción del servicio. Envuelve siempre la llamada en un try/catch y comprueba el tipo de error antes de leer sus propiedades; de lo contrario, TypeScript se negará a compilar. Todos los errores HTTP devueltos por la API heredan de MistralError, que expone statusCode y body; los errores de red (ConnectionError, RequestTimeoutError, etc.) no heredan de ella, pero siguen siendo instancias 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) {
    // Respuesta de error de la API: clave rechazada 401, límite alcanzado 429...
    console.error(`Mistral API Error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof Error) {
    // Sin respuesta de la API: red caída, tiempo de espera superado...
    console.error(`Error: ${error.message}`);
  }
}

Puntos clave

  • client.chat.complete() es asíncrono: usa await
  • El streaming utiliza for await...of sobre el resultado de client.chat.stream()
  • El tipado de TypeScript detecta errores de parámetros en tiempo de compilación
  • La integración SSE con Express es sencilla para interfaces web en tiempo real
  • El historial de conversación se gestiona con un array tipado Message[]
  • content es una cadena o una lista de fragmentos: comprueba typeof content === 'string' antes de usarlo como texto
  • Los errores HTTP del SDK heredan de MistralError (statusCode, body)