Avaliações offline: medir antes de implementar
Nesta página
Lição reescrita em 2 de novembro de 2026 com base na documentação Offline evaluations da Mistral: as “Campaigns” da versão anterior e os seus métodos
campaigns.*deixaram de existir. A avaliação em larga escala utiliza agora o SDKmistralai-evaluations, que executa uma tarefa num conjunto de dados, pontua-a com avaliadores e publica os resultados no Studio. Fontes: Offline evaluations · Evaluators · Goals. Atualização de 3 de novembro: omistralai-evaluations0.9.1 requermistralai< 3 e substitui o SDK 3.x por uma versão 2.x quando instalado em conjunto; a lição recomenda a utilização de um ambiente dedicado (dependências no PyPI).
Da análise de casos isolados para a escala
Um juiz validado em vinte conversas não lhe diz nada sobre a sua aplicação como um todo. Para decidir se um novo prompt, modelo ou configuração é melhor do que o atual, deve medi-lo contra um conjunto de casos representativo e consistente e comparar os resultados. É este o papel das avaliações offline.
Estas estão reservadas a organizações Enterprise e requerem Python 3.12 ou superior:
pip install mistralai-evaluations
Instale-o num ambiente separado. A versão 0.9.1, a mais recente em 3 de novembro de 2026, requer o mistralai 2.x (mistralai>=2.7.1,<3). Num ambiente que já contenha o SDK 3.x, o pip desinstala-o e instala uma versão 2.x, sem outro aviso além das linhas de saída: verificado com mistralai 3.7.0, substituído por 2.10.1. Um ambiente virtual dedicado para avaliações previne regressões na sua aplicação.
O modelo mental
O SDK segue um fluxo simples:
Dataset → Task → Evaluators → Results
- Dataset: uma lista de registos (dicionários) ou um conjunto de dados do Studio
- Task: uma função, preferencialmente assíncrona, que recebe um
TaskContexte produz uma saída — este é o código que está a avaliar - Evaluators: funções que recebem um
ScorerContexte pontuam cada saída - Results: estatísticas e pontuações por registo, apresentadas no terminal e publicadas no Studio
Uma primeira avaliação
import asyncio
import os
from mistralai.evaluations import (
Evaluation, Evaluator, Goal, Mistral, Project, ScorerContext, System, TaskContext,
)
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
dataset = [
{"ticket": "I haven't been able to log in since this morning.", "categorie": "acces"},
{"ticket": "My October invoice charges the same subscription twice.", "categorie": "facturation"},
{"ticket": "The PDF export crashes as soon as the report exceeds 50 pages.", "categorie": "bug"},
]
async def tache(ctx: TaskContext) -> str:
response = await client.chat.complete_async(
model=str(ctx.system.params["model"]),
messages=[
{"role": "system", "content": str(ctx.system.params["system_prompt"])},
{"role": "user", "content": ctx.input_record["ticket"]},
],
)
return str(response.choices[0].message.content)
def exactitude(ctx: ScorerContext) -> int:
return 1 if ctx.input_record["categorie"] == str(ctx.output).strip().lower() else 0
async def main():
run = await client.evaluation.run(
project=Project(name="Tri des tickets"),
evaluation=Evaluation(name="Exactitude du classement"),
system=System(name="small-prompt-v1", params={
"model": "mistral-small-latest",
"system_prompt": "Classe le ticket : acces, facturation ou bug. Réponds par le seul mot.",
}),
dataset=dataset,
task=tache,
evaluators=[
Evaluator(
name="exactitude",
description="1 si la catégorie prédite est la bonne, 0 sinon.",
scorer=exactitude,
goal=Goal.gte(0.8),
),
],
)
run.show(level="records")
asyncio.run(main())
Os resultados aparecem no terminal e são publicados no Studio em Observability > Evaluate > Evaluations. O SDK calcula a média, o mínimo, o máximo e o desvio padrão para cada avaliador.
Prefira uma tarefa assíncrona para processos de longa duração: uma tarefa síncrona é executada no loop de eventos que também envia sinais de heartbeat para a execução no Studio, e uma chamada bloqueada durante vários minutos pode fazer com que a execução seja marcada como cancelada.
Dois tipos de avaliadores
Um avaliador associa um nome, uma descrição opcional, uma função de pontuação e, se necessário, um objetivo. A função pode ser:
- Baseada em regras: um cálculo direto na saída — exato, rápido e gratuito;
- Um juiz LLM: uma função que chama um modelo para pontuar o que é difícil de codificar — utilidade, precisão factual, tom.
JUDGE_PROMPT = """Tu es un correcteur exigeant. Note de 0 à 5 l'utilité de la réponse
pour la request ci-dessous. Réponds par le seul chiffre.
Demande : {request}
Réponse : {response}
"""
def judge_utility(ctx: ScorerContext) -> int:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": JUDGE_PROMPT.format(
request=ctx.input_record["ticket"], response=ctx.output)}],
temperature=0,
)
raw = str(response.choices[0].message.content).strip()
return int(raw[0]) if raw[:1].isdigit() else 0
Pode misturar livremente ambos os tipos numa única execução: passe-os juntos na lista evaluators. Um avaliador também pode devolver uma string ou um booleano; o SDK produz então uma distribuição de frequências em vez de médias.
Comparar versões
O objeto System captura a configuração da tarefa: modelo, temperatura, prompt de sistema ou qualquer outra definição, num dicionário de forma livre. Cada execução regista o seu System, e o Studio permite-lhe comparar execuções lado a lado. Para decidir entre dois prompts ou dois modelos, execute novamente a mesma avaliação com dois objetos System diferentes, sem tocar no código da tarefa.
Definir objetivos
Um objetivo transforma uma pontuação num veredicto PASS ou FAIL: Goal.gte(0.8) exige uma média de pelo menos 0.8, Goal.lte(...) define um teto e Goal.between(...) define um intervalo. Cada objetivo visa a média por predefinição, ou outra estatística com metric ("min", "max", "std"): Goal.gte(0.8, metric="min") exige que todos os registos atinjam 0.8. É isto que torna uma avaliação numa salvaguarda: uma nova versão que faça descer uma pontuação abaixo do seu objetivo não vai para produção.
Pontos-chave
- As avaliações offline (
mistralai-evaluations, Python 3.12+, organizações Enterprise) substituem as antigas Campaigns - Dataset, task, evaluators, results:
client.evaluation.run(...)encadeia tudo e publica no Studio - Os evaluators são funções: regras exatas ou juízes LLM, livremente combinados
- O
Systemregista a configuração avaliada e permite a comparação de versões - Os objetivos (
Goal.gte,Goal.lte,Goal.between) fornecem veredictos PASS ou FAIL