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

Conjuntos de dados: Criar conjuntos de avaliação e iterar

Aula 15 de 16 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. O elo final no ciclo de iteração
  2. Estrutura do registo
  3. Fontes de dados
  4. Revisão e exportação
  5. Avaliar num conjunto de dados do Studio
  6. Melhores práticas de gestão
  7. Pontos-chave

Lição reescrita em 2 de novembro de 2026 com base na página Datasets da Mistral e no SDK mistralai 3.7.0: um registo contém um payload de formato livre e properties; 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étodo import_from_explorer da 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) e properties (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_records e export_to_jsonl
  • As avaliações leem um conjunto de dados via Dataset(slug=...) ou Dataset(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