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

Avaliações offline: medir antes de implementar

Aula 14 de 16 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Da análise de casos isolados para a escala
  2. O modelo mental
  3. Uma primeira avaliação
  4. Dois tipos de avaliadores
  5. Comparar versões
  6. Definir objetivos
  7. Pontos-chave

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 SDK mistralai-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: o mistralai-evaluations 0.9.1 requer mistralai < 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 TaskContext e produz uma saída — este é o código que está a avaliar
  • Evaluators: funções que recebem um ScorerContext e 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 System regista 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