O Cliente MistralAzure em Python
Nesta página
Programação com o MistralAzure
O seu endpoint Azure está implementado e a responder; agora precisa de escrever o código que o utilizará de forma fiável. Esta lição detalha o cliente Python MistralAzure: inicialização, os padrões que utilizará no dia a dia — chamadas simples, streaming, execução assíncrona e chamada de funções — e as poucas especificidades que distinguem a Azure da API direta.
Instalação e Configuração
Atualizado a 2 de novembro de 2026 — Mistral SDK 2 e versões posteriores. Desde a versão 2.0 do SDK Python (março de 2026), o cliente Azure é importado de
mistralai.azure.client, e os seus parâmetros da versão 1,azure_endpointeazure_api_key, tornaram-seserver_urleapi_key. O código nesta lição segue a versão atual (3.7.0, 1 de novembro de 2026). Fontes: notas de lançamento v2.0.0 · Mistral na Azure.
O cliente Azure está incluído no pacote mistralai; não são necessárias dependências adicionais.
pip install mistralai
A inicialização requer dois parâmetros:
import os
from mistralai.azure.client import MistralAzure
client = MistralAzure(
server_url=os.environ["AZUREAI_ENDPOINT"],
api_key=os.environ["AZUREAI_API_KEY"]
)
server_url— O URL do seu endpoint Azureapi_key— A chave de autenticação do endpoint
Um terceiro parâmetro opcional, api_version, tem como valor predefinido 2024-05-01-preview. O SDK adiciona este valor automaticamente a cada pedido como um parâmetro de URL.
Conclusões de Chat
A partir daqui, a experiência espelha a do cliente padrão. Utilize uma mensagem de sistema para definir o papel do modelo, uma mensagem de utilizador para a pergunta e leia a resposta em choices[0].message.content.
response = client.chat.complete(
model="azureai",
messages=[
{"role": "system", "content": "Você é um assistente técnico especializado em Python."},
{"role": "user", "content": "Como implemento um decorador de cache?"}
]
)
print(response.choices[0].message.content)
Os parâmetros de geração comportam-se exatamente como na API direta da Mistral. Se uma resposta for demasiado imprevisível ou prolixa, corrija-a aqui, e não no prompt.
response = client.chat.complete(
model="azureai",
messages=[
{"role": "user", "content": "Gere um haiku sobre computação em nuvem."}
],
temperature=0.7,
max_tokens=150,
top_p=0.95
)
temperature— Controla a criatividade (0,0 = determinístico, 1,0 = criativo)max_tokens— Limita o comprimento da respostatop_p— Amostragem de núcleo (nucleus sampling)
Streaming
Para respostas que abrangem várias centenas de palavras, uma chamada padrão deixa o utilizador a olhar para um ecrã congelado durante vários segundos. O streaming elimina esta espera percecionada, apresentando o texto à medida que é gerado. Este é o modo predefinido sempre que está envolvida uma interface humana.
stream = client.chat.stream(
model="azureai",
messages=[
{"role": "user", "content": "Explique como funciona um balanceador de carga."}
]
)
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
print(content, end="", flush=True)
print() # Nova linha no final
Note a verificação if content: alguns fragmentos chegam vazios e, sem esta precaução, imprimiriam None no ecrã.
Chamadas Assíncronas
Num servidor web — FastAPI, Django async — uma chamada bloqueante ocupa um worker durante toda a duração da geração, frequentemente vários segundos por pedido. O cliente assíncrono cede o controlo durante a espera, permitindo que um único processo trate dezenas de pedidos simultâneos.
import asyncio
from mistralai.azure.client import MistralAzure
client = MistralAzure(
server_url=os.environ["AZUREAI_ENDPOINT"],
api_key=os.environ["AZUREAI_API_KEY"]
)
async def generate_response(prompt: str) -> str:
response = await client.chat.complete_async(
model="azureai",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
# Execução
result = asyncio.run(generate_response("O que é o Kubernetes?"))
print(result)
Chamada de Funções
A chamada de funções comporta-se de forma idêntica à API direta. Você descreve as ferramentas disponíveis, o modelo decide se deve chamar uma delas e o seu código executa efetivamente a função; o modelo apenas formula a intenção e os argumentos.
import json
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Obter o estado do tempo para uma cidade",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Nome da cidade"}
},
"required": ["city"]
}
}
}
]
response = client.chat.complete(
model="azureai",
messages=[{"role": "user", "content": "Qual é o estado do tempo em Paris?"}],
tools=tools,
tool_choice="auto"
)
# Verificar se o modelo pretende chamar uma função
if response.choices[0].message.tool_calls:
tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
print(f"Função chamada: {tool_call.function.name}")
print(f"Argumentos: {args}")
Tratamento de Erros
Em produção, três famílias de erros recorrem e exigem respostas diferentes. Um 429 sinaliza um limite de taxa e requer uma nova tentativa com espera exponencial (exponential backoff). Um 401 indica uma chave inválida ou expirada: tentar novamente é inútil, pelo que deve falhar imediatamente com uma mensagem clara. Um 404 aponta quase sempre para uma variável AZUREAI_ENDPOINT mal configurada. Distinguir estes casos poupa-lhe horas a depurar um erro de digitação num URL.
import time
from mistralai.azure.client import MistralAzure
def robust_call(client, messages, max_retries=3):
"""Chamada com nova tentativa exponencial e tratamento de erros."""
for attempt in range(max_retries):
try:
return client.chat.complete(
model="azureai",
messages=messages
)
except Exception as e:
error_str = str(e)
if "429" in error_str:
wait = 2 ** attempt
print(f"Limite de taxa — nova tentativa em {wait}s")
time.sleep(wait)
elif "401" in error_str:
raise ValueError("Chave de API inválida ou expirada") from e
elif "404" in error_str:
raise ValueError("Endpoint não encontrado — verifique AZUREAI_ENDPOINT") from e
else:
if attempt == max_retries - 1:
raise
time.sleep(1)
raise RuntimeError("Falha após todas as novas tentativas")
Medição do Consumo
Cada resposta inclui um objeto usage que detalha os tokens consumidos. Leia isto sistematicamente: é a única medida fiável para estimar custos e detetar um prompt de sistema que tenha inchado devido a edições repetidas.
response = client.chat.complete(
model="azureai",
messages=[{"role": "user", "content": "Olá"}]
)
usage = response.usage
print(f"Tokens do prompt : {usage.prompt_tokens}")
print(f"Tokens da resposta : {usage.completion_tokens}")
print(f"Total de tokens : {usage.total_tokens}")
Pontos-chave
- O cliente
MistralAzurefunciona como o cliente padrão, utilizandomodel="azureai" - O streaming (
chat.stream) é recomendado para interfaces de utilizador - As chamadas assíncronas (
complete_async) são essenciais para servidores web - A chamada de funções e o modo JSON funcionam de forma idêntica à API direta
- Implemente sempre uma nova tentativa exponencial para lidar com erros
429