Conjuntos de dados: Criar conjuntos de avaliação e iterar
Nesta página
Lição reescrita em 2 de novembro de 2026 com base na página Datasets da Mistral e no SDK
mistralai3.7.0: um registo contém umpayloadde formato livre eproperties; os conjuntos de dados são preenchidos via entrada manual, importação de ficheiros ou spans do Explorer, e são passados tal como estão para avaliações offline. O métodoimport_from_explorerda versão anterior já não existe. Fontes: Datasets · Explore traces.
O elo final no ciclo de iteração
Um conjunto de dados é a coleção de casos de teste que impulsiona uma avaliação offline. Ele confere memória ao seu processo de qualidade: cada incidente observado em produção pode tornar-se um caso de teste, e cada nova versão da aplicação é medida contra ele. Sem um conjunto de dados estável, está a comparar impressões; com um, está a comparar números.
Estrutura do registo
No Studio, cada registo contém um payload — um objeto JSON onde define as chaves — e properties, que são metadados não passados para a tarefa avaliada. Durante uma avaliação, o payload torna-se o registo de entrada exatamente como está (ctx.input_record).
{"payload": {"ticket": "My October invoice lists the same subscription twice.", "category": "billing"}, "properties": {"source": "incident-2026-10-14"}}
Esta linha representa também o formato de importação JSONL para conjuntos de dados do Studio: um objeto por linha, contendo payload e properties.
Fontes de dados
Pode preencher um conjunto de dados de várias formas:
- Entrada manual, no Studio ou via API, registo a registo
- Importação de ficheiro JSONL usando o formato acima
- A partir do Explorer: um único span, ou até 500 spans selecionados, tornam-se registos (Lição 12)
- A partir do Playground do Studio ou de outro conjunto de dados
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
datasets = client.beta.observability.datasets
# Create the dataset
dataset = datasets.create(
name="Support tickets — reference set",
description="Manually validated ticket classification cases",
)
print(f"Dataset: {dataset.id} ({dataset.slug})")
# Add records
cases = [
{"ticket": "I haven't been able to log in since this morning.", "category": "access"},
{"ticket": "The PDF export crashes whenever the report exceeds 50 pages.", "category": "bug"},
]
for payload in cases:
datasets.create_record(
dataset_id=dataset.id,
payload=payload,
properties={"origin": "manual entry"},
)
Para grandes volumes, import_from_file importa um ficheiro JSONL já carregado (pelo seu file_id), e import_from_spans ingere spans de traço: estas importações executam como tarefas em segundo plano, e pode acompanhar o seu progresso com fetch_task.
Revisão e exportação
list_records itera pelos registos página a página (page_size, page), e export_to_jsonl gera uma exportação cuja resposta fornece o URL de descarga (file_url):
page = datasets.list_records(dataset_id=dataset.id, page_size=50, page=1)
export = datasets.export_to_jsonl(dataset_id=dataset.id)
print(export.file_url)
Avaliar num conjunto de dados do Studio
Uma avaliação offline lê um conjunto de dados do Studio pelo seu slug ou ID:
from mistralai.evaluations import Dataset, Evaluation, Evaluator, Project
run = await client.evaluation.run(
project=Project(name="Ticket sorting"),
evaluation=Evaluation(name="Reference set"),
dataset=Dataset(slug="support-tickets-reference-set"),
task=tache,
evaluators=[Evaluator(name="exactitude", scorer=exactitude)],
)
Aqui, client é o cliente SDK de avaliação, e tache e exactitude estão definidos na Lição 14. Passe exatamente um de slug ou id; selecionar um conjunto de dados pelo seu slug nunca cria um novo. Tenha em mente duas regras: uma execução lê os registos presentes no arranque, até 10.000 — um conjunto de dados não é uma instantânea, por isso modificá-lo apenas afeta execuções subsequentes — e se os registos forem adicionados ou removidos durante a leitura, a execução falha antes de começar em vez de executar num conjunto inconsistente.
Melhores práticas de gestão
Mantenha um conjunto de referência estável. Um conjunto de dados que muda a cada execução torna a comparação impossível. Crie um conjunto de referência que só modifica deliberadamente e mantenha conjuntos de trabalho separados ao lado dele.
Alimente-o a partir da produção. Os casos mais úteis são aqueles que realmente causaram problemas: um span detetado no Explorer, onde corrige a saída esperada, vale mais do que dez casos inventados.
Documente a proveniência. As properties (origem, data, incidente relacionado) não são vistas pela tarefa, mas dir-lhe-ão, daqui a seis meses, porque é que um caso existe.
Equilibre os seus dados. Um conjunto de dados contendo apenas casos fáceis lisonjeia o seu sistema; um contendo apenas armadilhas desencoraja-o. Aponte para a distribuição real do seu tráfego, mais um punhado de casos limite reconhecidos.
Pontos-chave
- Um registo de conjunto de dados = um
payload(entrada da tarefa) eproperties(metadados) - Entrada manual, importação JSONL, spans do Explorer, Playground: múltiplas fontes para um único conjunto de dados
- O SDK expõe
create,create_record,import_from_file,import_from_spans,list_recordseexport_to_jsonl - As avaliações leem um conjunto de dados via
Dataset(slug=...)ouDataset(id=...), até 10.000 registos - Um conjunto de dados não é uma instantânea: mantenha um conjunto de referência estável para comparar versões