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

O Cliente MistralAzure em Python

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Programação com o MistralAzure
  2. Instalação e Configuração
  3. Conclusões de Chat
  4. Streaming
  5. Chamadas Assíncronas
  6. Chamada de Funções
  7. Tratamento de Erros
  8. Medição do Consumo
  9. Pontos-chave

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_endpoint e azure_api_key, tornaram-se server_url e api_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 Azure
  • api_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 resposta
  • top_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 MistralAzure funciona como o cliente padrão, utilizando model="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