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

Migração entre versões do SDK Mistral

Aula 10 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Porque é que esta lição é importante
  2. Quatro gerações em dois anos
  3. Da 0.x para a 1.x: o cliente Mistral e métodos encadeados
  4. Da 1.x para a 2.x: tudo se move para mistralai.client
  5. Da 2.x para a 3.x: httpx2 e ferramentas integradas
  6. E quanto ao TypeScript?
  7. Como conduzir a migração
  8. Se não puder migrar imediatamente
  9. Pontos-chave

Lição reescrita a 2 de novembro de 2026. A versão anterior referia-se à “passagem da V1 para a V2”, que foi na realidade a transição do cliente legado 0.x para a versão 1.0 em agosto de 2024. Desde então, o SDK Python teve mais dois lançamentos principais: o 2.0 em março de 2026 e o 3.0 em setembro de 2026. Esta lição reconstrói todo o histórico com base nos guias de migração oficiais e nas notas de lançamento. Atualizado a 3 de novembro de 2026: Corrigido o ciclo de streaming em TypeScript, que anteriormente passava o conteúdo string | ContentChunk[] diretamente para process.stdout.write, causando falhas em modo estrito.

Porque é que esta lição é importante

Vai deparar-se com este material em dois cenários: está a retomar um projeto escrito há algum tempo que se recusa a iniciar após uma atualização de dependências, ou está a seguir um tutorial online cujos exemplos já não funcionam. Em ambos os casos, faça sempre a mesma primeira pergunta: para qual geração do SDK foi este código escrito? Quase sempre, uma única linha lho diz: a instrução de importação.

Quatro gerações em dois anos

GeraçãoPython (mistralai)TypeScript (@mistralai/mistralai)Característica de código distintiva
0.xaté 0.4.2 (julho de 2024)até 0.5.0 (junho de 2024)MistralClient, métodos planos: client.chat(...)
1.x1.0.0 (7 ago. 2024) → 1.9.11 (out. 2025)desde ago. 2024from mistralai import Mistral, métodos encadeados: client.chat.complete(...)
2.x2.0.0 (10 mar. 2026)2.0.0 (18 mar. 2026)Python: from mistralai.client import Mistral; TypeScript: apenas módulos ES
3.x3.0.0 (28 set. 2026), 3.7.0 a partir de 1 nov. 20263.0 (out. 2026), 3.5.0 hojePython: cliente HTTP httpx2

Em TypeScript, a importação import { Mistral } from '@mistralai/mistralai' não mudou desde a versão 1.x. Em Python, mudou duas vezes: é aqui que ocorrem a maioria das ruturas.

Da 0.x para a 1.x: o cliente Mistral e métodos encadeados

A versão 1.0 substituiu os dois clientes, MistralClient (síncrono) e MistralAsyncClient (assíncrono), por uma única classe, Mistral. Substituiu também os métodos planos por namespaces: chat agrupa as operações de conversação e é necessário descer um nível para aceder a complete(). As mensagens, que anteriormente eram escritas usando a classe ChatMessage, são agora escritas como dicionários ou utilizando as classes UserMessage, SystemMessage, AssistantMessage e ToolMessage.

# 0.x (legado)
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"}],
)

O streaming segue a mesma lógica, com uma armadilha que muitas vezes custa meia hora de depuração: o fragmento recebido está agora encapsulado e o seu conteúdo é lido através de um nível intermédio .data. O código legado 0.x copiado tal e qual levanta um AttributeError no primeiro fragmento.

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

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

O guia oficial da versão 1.0 fornece a tabela completa. Os mapeamentos mais frequentes são:

0.x1.x e 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 e os seus métodosVariantes _async: client.chat.complete_async, client.chat.stream_async…

Da 1.x para a 2.x: tudo se move para mistralai.client

A versão 2.0 não tocou nos nomes dos métodos: client.chat.complete permanece client.chat.complete. Alterou, sim, o endereço de todo o resto. O SDK tornou-se um pacote de namespace (PEP 420) e todas as importações migraram de mistralai para mistralai.client:

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

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

Note a terceira linha: as classes de erro já não residem entre os modelos, mas em mistralai.client.errors, com MistralError como base comum (da qual herdam SDKError e HTTPValidationError).

Os clientes de fornecedores de cloud juntaram-se ao mesmo namespace. Na versão 1.x, eram distribuídos com o pacote mistralai, mas em módulos separados, mistralai_azure e 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 e 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")

Três outras alterações na versão 2.0 podem afetá-lo. A versão mínima é agora Python 3.10 (a 1.9.11 aceitava Python 3.9). 42 tipos foram renomeados segundo uma convenção regular: {Verb}{Entity}Request para pedidos e {Verb}{Entity}Response para respostas. A única renomeação visível no código comum é Tools, que se tornou ConversationRequestTool. Por fim, as enumerações aceitam agora valores desconhecidos, pelo que um novo valor adicionado pela API já não faz colapsar uma versão antiga do SDK.

Da 2.x para a 3.x: httpx2 e ferramentas integradas

A versão 3.0, lançada a 28 de setembro de 2026, não altera nem as importações nem os métodos comuns. No entanto, três pontos podem quebrar um projeto:

  • O cliente HTTP passa a ser httpx2. Se passar o seu próprio cliente para o SDK (parâmetros client= ou async_client=, por exemplo para um proxy ou cabeçalhos comuns), este tem de ser um cliente httpx2; os pedidos, respostas e erros de transporte brutos são também tipos httpx2.
  • As ferramentas integradas saem das conclusões de chat. client.chat.complete e client.agents.complete já não aceitam as ferramentas web_search, web_search_premium e code_interpreter: estas são utilizadas através da API de Conversações (client.beta.conversations) ou de um agente. A documentação do Mistral explica o porquê: as respostas de conclusão de chat não podem transportar as referências que estas ferramentas devolvem.
  • Os extras mcp e agents dependem agora do MCP 2.2.

A versão 3.0 adiciona também a autenticação por token de conta de serviço: Mistral() lê o token a partir do ficheiro especificado pela variável de ambiente MISTRAL_SA_TOKEN_PATH.

E quanto ao TypeScript?

A passagem do cliente JavaScript legado 0.x para o SDK TypeScript 1.x espelha quase exatamente a transição em Python. A importação muda de uma exportação padrão para uma exportação nomeada, o construtor aceita um objeto de configuração e os métodos tornam-se encadeados:

// 0.x (legado)
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 e 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' }],
});

O streaming passa de client.chatStream(...) para client.chat.stream(...), e, tal como em Python, o conteúdo é lido via 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 can also be a list of fragments: we only write text
  if (typeof content === 'string') process.stdout.write(content);
}

O TypeScript 2.0 (18 de março de 2026) manteve estas importações, mas o SDK é agora publicado apenas como módulos ES: um require('@mistralai/mistralai') em CommonJS já não funciona. A validação em tempo de execução passa para o Zod v4, o que apenas afeta projetos que importam esquemas diretamente do SDK. E os clientes de cloud vivem em pacotes separados: @mistralai/mistralai-azure (MistralAzure) e @mistralai/mistralai-gcp (MistralGCP, anteriormente MistralGoogleCloud).

Como conduzir a migração

Num projeto real, proceda numa ordem definida em vez de corrigir erros à medida que aparecem. Comece por identificar a geração do código através das suas importações e, em seguida, atualize o pacote (pip install --upgrade mistralai ou npm install @mistralai/mistralai@latest): enquanto a versão antiga estiver instalada, está a corrigir às cegas. Prosseda depois da seguinte forma:

  1. Procure importações antigas: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Substitua-as de acordo com os mapeamentos desta lição; não se esqueça dos erros, que se movem para mistralai.client.errors
  3. Atualize as chamadas: métodos encadeados, inputs no plural para embeddings, .data nos ciclos de streaming
  4. Mova as ferramentas integradas (web_search, code_interpreter) das conclusões de chat para a API de Conversações

Por fim, teste cada endpoint que utiliza, um por um: chat, embeddings e streaming têm cada um as suas próprias alterações, e um projeto que inicia não chama necessariamente os três corretamente.

Se não puder migrar imediatamente

Nenhuma destas versões oferece um modo de transição ou aliases de compatibilidade. Se um congelamento de produção o impede de migrar, fixe explicitamente a versão nas suas dependências; caso contrário, a próxima instalação irá buscar a versão mais recente e quebrar a aplicação:

# Python: manter na 1.x
pip install "mistralai<2"

# Python: manter na 2.x
pip install "mistralai>=2,<3"

# npm: manter na 1.x
npm install @mistralai/mistralai@1

Encare esta fixação como um repouso: as novas funcionalidades chegam apenas na versão corrente.

Fontes oficiais: Guia de migração 0.x → 1.0 · Notas de lançamento Python 2.0.0 · Notas de lançamento Python 3.0.0 · Notas de lançamento TypeScript 2.0.0 · Histórico de versões no PyPI · Websearch — ferramentas integradas

Pontos-chave

  • Identifique a geração do código pela sua importação: MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x e 3.x)
  • A 1.0 (ago. 2024) introduziu o cliente Mistral, métodos encadeados e o nível .data no streaming
  • A 2.0 (mar. 2026) moveu todas as importações Python para mistralai.client, os erros para mistralai.client.errors e elevou o mínimo para Python 3.10
  • A 3.0 (set. 2026) muda para httpx2 e reserva web_search e code_interpreter para a API de Conversações e agentes
  • Em TypeScript, a importação não mudou desde a 1.x, mas a 2.0 aceita apenas módulos ES