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

Migración entre versiones del SDK de Mistral

Lección 10 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Por qué importa esta lección
  2. Cuatro generaciones en dos años
  3. De 0.x a 1.x: el cliente Mistral y los métodos encadenados
  4. De 1.x a 2.x: todo se mueve bajo mistralai.client
  5. De 2.x a 3.x: httpx2 y herramientas integradas
  6. ¿Y qué pasa con TypeScript?
  7. Cómo llevar a cabo la migración
  8. Si no puedes migrar de inmediato
  9. Puntos clave

Lección reescrita el 2 de noviembre de 2026. La versión anterior hablaba de «pasar de V1 a V2», lo cual correspondía en realidad a la transición del cliente heredado 0.x a la versión 1.0 en agosto de 2024. Desde entonces, el SDK de Python ha tenido dos lanzamientos mayores más: la 2.0 en marzo de 2026 y la 3.0 en septiembre de 2026. Esta lección reconstruye la historia completa basándose en las guías de migración oficiales y las notas de lanzamiento. Actualizado el 3 de noviembre de 2026: se ha corregido el bucle de streaming en TypeScript, que anteriormente pasaba contenido string | ContentChunk[] directamente a process.stdout.write, lo que causaba fallos en modo estricto.

Por qué importa esta lección

Te encontrarás con este material en dos escenarios: estás retomando un proyecto escrito hace tiempo que se niega a arrancar tras una actualización de dependencias, o estás siguiendo un tutorial en línea cuyos ejemplos ya no funcionan. En ambos casos, hazte la misma primera pregunta: ¿para qué generación del SDK se escribió este código? Casi siempre, una sola línea te lo dice: la sentencia de importación.

Cuatro generaciones en dos años

GeneraciónPython (mistralai)TypeScript (@mistralai/mistralai)Característica de código distintiva
0.xhasta 0.4.2 (julio de 2024)hasta 0.5.0 (junio de 2024)MistralClient, métodos planos: client.chat(...)
1.x1.0.0 (7 de ago de 2024) → 1.9.11 (oct de 2025)desde ago de 2024from mistralai import Mistral, métodos encadenados: client.chat.complete(...)
2.x2.0.0 (10 de mar de 2026)2.0.0 (18 de mar de 2026)Python: from mistralai.client import Mistral; TypeScript: solo módulos ES
3.x3.0.0 (28 de sep de 2026), 3.7.0 a fecha de 1 de nov de 20263.0 (oct de 2026), 3.5.0 hoyPython: cliente HTTP httpx2

En TypeScript, la importación import { Mistral } from '@mistralai/mistralai' no ha cambiado desde la 1.x. En Python, ha cambiado dos veces: ahí es donde se producen la mayoría de las roturas.

De 0.x a 1.x: el cliente Mistral y los métodos encadenados

La versión 1.0 sustituyó los dos clientes, MistralClient (síncrono) y MistralAsyncClient (asíncrono), por una única clase, Mistral. También reemplazó los métodos planos por espacios de nombres: chat agrupa las operaciones de conversación y hay que bajar un nivel más para llegar a complete(). Los mensajes, que antes se escribían usando la clase ChatMessage, ahora se escriben como diccionarios o utilizando las clases UserMessage, SystemMessage, AssistantMessage y ToolMessage.

# 0.x (heredado)
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage

client = MistralClient(api_key="...")
response = client.chat(
    model="mistral-small-latest",
    messages=[ChatMessage(role="user", content="Hello")],
)

# 1.x
from mistralai import Mistral

client = Mistral(api_key="...")
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Hello"}],
)

El streaming sigue la misma lógica, con una trampa que suele costar media hora de depuración: el fragmento recibido ahora está envuelto y su contenido se lee a través de un nivel intermedio .data. El código heredado 0.x copiado tal cual lanza un AttributeError en el primer fragmento.

# 0.x
for chunk in client.chat_stream(model=..., messages=...):
    print(chunk.choices[0].delta.content)

# 1.x y posteriores
for chunk in client.chat.stream(model=..., messages=...):
    print(chunk.data.choices[0].delta.content)

La guía oficial de la 1.0 proporciona la tabla completa. Las correspondencias más frecuentes son:

0.x1.x y posteriores
client.chat / client.chat_streamclient.chat.complete / client.chat.stream
client.completions (FIM)client.fim.complete
client.embeddings(model=..., input=[...])client.embeddings.create(model=..., inputs=[...])
client.list_models()client.models.list()
client.files.create(...)client.files.upload(...)
client.jobs.create(...)client.fine_tuning.jobs.create(...)
MistralAsyncClient y sus métodosVariantes _async: client.chat.complete_async, client.chat.stream_async…

De 1.x a 2.x: todo se mueve bajo mistralai.client

La versión 2.0 no tocó los nombres de los métodos: client.chat.complete sigue siendo client.chat.complete. Cambió la dirección de todo lo demás. El SDK se convirtió en un paquete de espacio de nombres (PEP 420) y todas las importaciones migraron de mistralai a mistralai.client:

# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError

# 2.x y posteriores
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Observa la tercera línea: las clases de error ya no viven entre los modelos, sino en mistralai.client.errors, con MistralError como base común (de la que heredan SDKError y HTTPValidationError).

Los clientes de proveedores de nube se unieron al mismo espacio de nombres. En la 1.x, se distribuían con el paquete mistralai pero en módulos separados, mistralai_azure y mistralai_gcp:

# 1.x
from mistralai_azure import MistralAzure
client = MistralAzure(azure_endpoint="https://your-endpoint.inference.ai.azure.com", azure_api_key="your-azure-key")

from mistralai_gcp import MistralGoogleCloud
client = MistralGoogleCloud(region="europe-west4", project_id="my-project")

# 2.x y posteriores
from mistralai.azure.client import MistralAzure
client = MistralAzure(server_url="https://your-endpoint.inference.ai.azure.com", api_key="your-azure-key")

from mistralai.gcp.client import MistralGCP  # pip install "mistralai[gcp]"
client = MistralGCP(region="europe-west4", project_id="my-project")

Otros tres cambios en la 2.0 pueden afectarte. La versión mínima es ahora Python 3.10 (la 1.9.11 aceptaba Python 3.9). Se renombraron 42 tipos según una convención regular: {Verbo}{Entidad}Request para solicitudes y {Verbo}{Entidad}Response para respuestas. El único renombrado visible en el código habitual es Tools, que pasó a ser ConversationRequestTool. Por último, las enumeraciones ahora aceptan valores desconocidos, por lo que un nuevo valor añadido por la API ya no hace colapsar una versión antigua del SDK.

De 2.x a 3.x: httpx2 y herramientas integradas

La versión 3.0, lanzada el 28 de septiembre de 2026, no cambia ni las importaciones ni los métodos comunes. Sin embargo, tres puntos pueden romper un proyecto:

  • El cliente HTTP pasa a ser httpx2. Si pasas tu propio cliente al SDK (parámetros client= o async_client=, por ejemplo para un proxy o cabeceras comunes), debe ser un cliente httpx2; las solicitudes, respuestas y errores de transporte brutos también son tipos httpx2.
  • Las herramientas integradas abandonan las completaciones de chat. client.chat.complete y client.agents.complete ya no aceptan las herramientas web_search, web_search_premium y code_interpreter: se usan a través de la API de Conversaciones (client.beta.conversations) o un agente. La documentación de Mistral explica por qué: las respuestas de completado de chat no pueden llevar las referencias que devuelven estas herramientas.
  • Los extras mcp y agents dependen ahora de MCP 2.2.

La versión 3.0 también añade autenticación mediante token de cuenta de servicio: Mistral() lee el token del archivo especificado por la variable de entorno MISTRAL_SA_TOKEN_PATH.

¿Y qué pasa con TypeScript?

Pasar del cliente JavaScript heredado 0.x al SDK de TypeScript 1.x refleja casi exactamente la transición de Python. La importación cambia de una exportación por defecto a una con nombre, el constructor toma un objeto de configuración y los métodos se vuelven encadenados:

// 0.x (heredado)
import MistralClient from '@mistralai/mistralai';
const client = new MistralClient(process.env.MISTRAL_API_KEY);
const response = await client.chat({
  model: 'mistral-small-latest',
  messages: [{ role: 'user', content: 'Hello' }],
});

// 1.x y posteriores
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
  model: 'mistral-small-latest',
  messages: [{ role: 'user', content: 'Hello' }],
});

El streaming pasa de client.chatStream(...) a client.chat.stream(...), y, al igual que en Python, el contenido se lee mediante chunk.data:

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

for await (const chunk of stream) {
  const content = chunk.data.choices[0]?.delta.content;
  // content también puede ser una lista de fragmentos: solo escribimos texto
  if (typeof content === 'string') process.stdout.write(content);
}

TypeScript 2.0 (18 de marzo de 2026) mantuvo estas importaciones, pero el SDK se publica ahora solo como módulos ES: un require('@mistralai/mistralai') en CommonJS ya no funciona. La validación en tiempo de ejecución pasa a Zod v4, lo que solo afecta a los proyectos que importan esquemas directamente desde el SDK. Y los clientes de nube viven en paquetes separados: @mistralai/mistralai-azure (MistralAzure) y @mistralai/mistralai-gcp (MistralGCP, anteriormente MistralGoogleCloud).

Cómo llevar a cabo la migración

En un proyecto real, procede en un orden definido en lugar de corregir errores según aparecen. Empieza identificando la generación del código mediante sus importaciones y luego actualiza el paquete (pip install --upgrade mistralai o npm install @mistralai/mistralai@latest): mientras la versión antigua esté instalada, estás arreglando cosas a ciegas. A continuación, procede así:

  1. Busca las importaciones antiguas: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Sustitúyelas según las correspondencias de esta lección; no olvides los errores, que se mueven a mistralai.client.errors
  3. Actualiza las llamadas: métodos encadenados, inputs en plural para embeddings, .data en los bucles de streaming
  4. Mueve las herramientas integradas (web_search, code_interpreter) de las completaciones de chat a la API de Conversaciones

Por último, prueba cada punto final que uses, uno por uno: chat, embeddings y streaming tienen cada uno sus propios cambios, y que un proyecto arranque no significa necesariamente que llame correctamente a los tres.

Si no puedes migrar de inmediato

Ninguna de estas versiones ofrece un modo de transición ni alias de compatibilidad. Si una congelación de producción te impide migrar, fija explícitamente la versión en tus dependencias; de lo contrario, la siguiente instalación traerá la última versión y romperá la aplicación:

# Python: permanecer en 1.x
pip install "mistralai<2"

# Python: permanecer en 2.x
pip install "mistralai>=2,<3"

# npm: permanecer en 1.x
npm install @mistralai/mistralai@1

Trata esta fijación como un respiro: las nuevas funcionalidades llegan solo a la versión actual.

Fuentes oficiales: Guía de migración 0.x → 1.0 · Notas de lanzamiento de Python 2.0.0 · Notas de lanzamiento de Python 3.0.0 · Notas de lanzamiento de TypeScript 2.0.0 · Historial de versiones en PyPI · Websearch — herramientas integradas

Puntos clave

  • Identifica la generación del código por su importación: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x y 3.x)
  • La 1.0 (ago de 2024) introdujo el cliente Mistral, los métodos encadenados y el nivel .data en streaming
  • La 2.0 (mar de 2026) movió todas las importaciones de Python bajo mistralai.client, los errores bajo mistralai.client.errors y subió el mínimo a Python 3.10
  • La 3.0 (sep de 2026) cambia a httpx2 y reserva web_search y code_interpreter para la API de Conversaciones y los agentes
  • En TypeScript, la importación no ha cambiado desde la 1.x, pero la 2.0 solo acepta módulos ES