Gerar um conjunto de dados de avaliação sintética (pré-visualização)

Este artigo aborda a geração de dados sintéticos. Para todas as opções de preparação de conjuntos de dados e os nomes de campos padrão, consulte Conjuntos de dados de avaliação no Microsoft Foundry e Esquema do conjunto de dados de avaliação.

Quando o seu agente ainda não tem tráfego de produção, pode ainda criar um conjunto de dados de avaliação significativo. O serviço de geração de dados da Microsoft Foundry sintetiza dados de avaliação a partir de material que já possui: instruções de um agente, um prompt inline ou um documento de referência que carrega. Estão disponíveis dois tipos de tarefas:

• O QnA simples (turno único) produz pares de perguntas e respostas para avaliação ao nível do turno.
• A semente de simulação (multi-turno) produz descrições de cenários que alimentam o fluxo de conversas Simulate para avaliação em múltiplos turnos.

Pode avaliar conjuntos de dados simples de perguntas e respostas diretamente. Numa primeira fase, os conjuntos de dados iniciais de simulação alimentam um simulador que simula o papel do utilizador perante o agente-alvo. Os avaliadores ao nível da conversa avaliam então as conversas geradas.

Estão disponíveis três tipos de fontes de entrada, e pode combiná-los num único trabalho para uma cobertura mais rica:

• Definição de agente — geração de sementes a partir das instruções ou prompt de um agente implementado.
• Prompt—forneça um prompt de texto incorporado que descreva o domínio ou ajuste o nível de dificuldade.
• Ficheiro de referência — carregue um documento (por exemplo, uma política, especificação ou exportação de base de conhecimento) e gere perguntas fundamentadas no seu conteúdo.

A geração sintética e a geração baseada em traços são complementares: os conjuntos de dados sintéticos cobrem casos extremos e cenários pré-lançamento, enquanto os conjuntos de dados baseados em traços refletem o comportamento real da produção. Usar ambos fornece o sinal de avaliação mais forte. Veja Converter rastreios de agentes em conjuntos de dados para avaliação.

Quando usar geração sintética

Use geração sintética quando:

• Estás em pré-lançamento e ainda não tens vestígios de produção.
• O teu agente tem pouco tráfego e uma janela de rastreamento não fornece amostras distintas suficientes.
• Precisas de uma base de regressão estável que não se altere com as mudanças no comportamento de produção.
• Queres expandir a cobertura de casos extremos que o agente não encontrou em produção.
• Estás a aperfeiçoar as instruções de um agente e pretendes um conjunto de dados para um teste rápido de validação.

Escolha um tipo de fonte

Podes combinar fontes num único trabalho. Um padrão comum consiste em combinar um ficheiro de referência (para contextualização) com um prompt (para orientar o tom ou o nível de dificuldade).

Pré-requisitos

• versão do SDK do Python 2.5.0 ou posterior: pip install "azure-ai-projects>=2.5.0" azure-identity.
• Um URL do ponto final de um projeto do Microsoft Foundry no formato https://<your-resource>.services.ai.azure.com/api/projects/<your-project>.
• Função de utilizador da Foundry ou superior no projeto.
• Uma implementação de modelo Azure OpenAI que suporta a API Responses. Tanto a receita simple_qna como a receita simulation_seed usam este modelo para sintetizar linhas de saída. Para a lista de modelos suportados, consulte suporte de modelos da API Responses do Azure OpenAI.
• Uma região apoiada. Para a lista, veja Regiões suportadas para geração de dados.

Gerar um conjunto de dados a partir do portal

1. No portal, abra o separador Data Generation . Selecione Criar conjunto de dados e depois selecione Gerar sintético.
2. Em Gerar dados sintéticos, defina a utilização do conjunto de dados para Avaliação.
3. Definir Tipo de Tarefa. Selecione QnA Simples (turno único) para pares de pergunta e resposta, ou Semente de Simulação (múltiplos turnos) para descrições de cenários usadas na simulação de conversa.
4. Selecione um modelo de Gerador.
5. Forneça uma ou mais entradas de origem: Agente, Prompt ou Ficheiro de referência.
6. Defina o número máximo de amostras e o nome do ficheiro de saída.
7. Selecione Gerar.
8. Acompanhe o estado do trabalho de geração de conjunto de dados no separador Data Generation .
9. Quando o trabalho terminar, pré-visualize as linhas geradas no separador Dados.

Gerar um conjunto de dados a partir de uma definição de agente (SDK)

Este fluxo inicia a geração a partir das instruções de um agente implementado. O serviço recolhe o prompt do agente e usa o seu modelo configurado para sintetizar pares de perguntas e respostas a partir dele.

Primeiro, crie um AIProjectClient usando o endpoint do seu projeto e DefaultAzureCredential. Pode encontrar todas as operações de geração de dados em project_client.beta.datasets.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

credential = DefaultAzureCredential()
project_client = AIProjectClient(
    endpoint="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>",
    credential=credential,
)

npm install @azure/ai-projects @azure/identity

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

const projectEndpoint =
  "https://<your-resource>.services.ai.azure.com/api/projects/<your-project>";
const projectClient = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

Depois, submeta uma SimpleQnA tarefa cuja origem seja uma referência de agente. Se já tiver um agente implementado, ignore a chamada create_version e passe os valores name e version existentes para AgentDataGenerationJobSource.

import time
from azure.ai.projects.models import (
    AgentDataGenerationJobSource,
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    DatasetDataGenerationJobOutput,
    PromptAgentDefinition,
    SimpleQnADataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"
poll_interval_seconds = 10

# 1. Reference (or create) a prompt agent whose instructions seed generation.
agent = project_client.agents.create_version(
    agent_name="retail-agent",
    definition=PromptAgentDefinition(
        model=MODEL_NAME,
        instructions=(
            "You are a customer support assistant for Contoso Retail. "
            "Answer questions about the product catalog, loyalty program, store hours, "
            "and the return policy. If a question falls outside this scope, say you "
            "don't have that information."
        ),
    ),
)

# 2. Define a SimpleQnA evaluation job sourced from the agent definition.
job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="retail-agent-eval-set",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            AgentDataGenerationJobSource(
                description="Agent definition used to seed QnA generation.",
                agent_name=agent.name,
                agent_version=agent.version,
            ),
        ],
        options=SimpleQnADataGenerationJobOptions(
            # Service requires max_samples to be between 15 and 1000.
            max_samples=15,
            # simple_qna requires model_options.
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="retail-agent-eval-set"),
    ),
)

# 3. Submit and wait for completion.
poller = project_client.beta.datasets.begin_create_generation_job(job=job)
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)
result = poller.result()

# 4. Resolve the generated dataset.
output_name = ""
output_version = ""
for output in (result.outputs if result is not None else None) or []:
    if isinstance(output, DatasetDataGenerationJobOutput):
        output_name = output.name or ""
        output_version = output.version or ""
        break

dataset = project_client.datasets.get(name=output_name, version=output_version)
print(f"Generated dataset: {dataset.name} v{dataset.version} (id: {dataset.id})")

A tarefa produz um conjunto de dados versionado com campos query e ground_truth de turno único. Faça uma pré-visualização no separador de Dados do portal para verificar as linhas geradas antes de avaliar.

Gerar um conjunto de dados a partir de um prompt (SDK)

Se ainda não tiver um agente implementado, ou se quiser gerar dados a partir de um excerto autónomo de material de origem, passe o texto como um PromptDataGenerationJobSource. Esta abordagem é útil para documentos de políticas, conteúdos de FAQ ou especificações curtas.

import time
from azure.ai.projects.models import (
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    PromptDataGenerationJobSource,
    SimpleQnADataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"
poll_interval_seconds = 10

job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="contoso-refund-eval-set",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            PromptDataGenerationJobSource(
                description="Contoso refund policy",
                prompt=(
                    "Contoso offers a full refund within 30 days of purchase for any product "
                    "returned in its original condition. After 30 days, store credit may be "
                    "issued at the discretion of customer support. Digital goods are "
                    "non-refundable once downloaded."
                ),
            ),
        ],
        options=SimpleQnADataGenerationJobOptions(
            max_samples=15,
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="contoso-refund-eval-set"),
    ),
)

poller = project_client.beta.datasets.begin_create_generation_job(job=job)
# Optional: While SDK is polling, periodically print the job status until the job is complete
print("Periodically check job status:")
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)
result = poller.result()

const modelName = "gpt-4.1-mini";
const jobName = "contoso-refund-eval-set";

const generationPoller = projectClient.beta.datasets.createGenerationJob({
  inputs: {
    name: jobName,
    scenario: "evaluation",
    sources: [
      {
        type: "prompt",
        description: "Contoso refund policy",
        prompt:
          "Contoso offers a full refund within 30 days of purchase for " +
          "any product returned in its original condition. After 30 " +
          "days, store credit may be issued at the discretion of " +
          "customer support. Digital goods are non-refundable once " +
          "downloaded.",
      },
    ],
    options: {
      type: "simple_qna",
      max_samples: 15,
      model_options: { model: modelName },
    },
    output_options: { name: jobName },
  },
});

// Creating a data generation job is a long-running operation. Once
// `submitted()` resolves, the job is queued and its id is available on
// the poller state.
await generationPoller.submitted();
console.log(`Created data generation job (id: ${generationPoller.operationState?.jobId})`);

const result = await generationPoller.pollUntilDone();
console.log(`Job status: ${result.status}`);

Resolva o conjunto de dados usando o mesmo padrão mostrado na secção anterior.

Gerar um conjunto de dados a partir de ficheiros de referência (SDK)

Para conteúdos de origem mais extensos, carregue um documento como um ficheiro do Azure OpenAI e faça-lhe referência pelo respetivo ID. Esta opção funciona melhor quando o conhecimento do domínio do agente reside numa especificação, exportação de base de conhecimento ou documento de política, porque as perguntas geradas permanecem fundamentadas nesse conteúdo.

O ficheiro deve estar no processed estado antes de o serviço de geração de dados o poder usar, e precisa de conter pelo menos 1 KB de conteúdo.

Extensões de ficheiros de referência suportadas são: .txt, .md, .csv, .json.xml, .html, .pdf, .png, .jpg, .jpeg.gif.tiff.tif.svg.

import io
import time
from azure.ai.projects.models import (
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    FileDataGenerationJobSource,
    SimpleQnADataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"
REFERENCE_DOCUMENT = open("retail-agent-reference.md", "rb").read()
poll_interval_seconds = 10

# 1. Upload the reference document via the Azure OpenAI Files API.
openai_client = project_client.get_openai_client()
seed_file = openai_client.files.create(
    file=("retail-agent-reference.md", io.BytesIO(REFERENCE_DOCUMENT)),
    purpose="user_data",
)

# 2. Wait for the file to finish processing.
while seed_file.status not in ("processed", "error"):
    time.sleep(2)
    seed_file = openai_client.files.retrieve(file_id=seed_file.id)
if seed_file.status != "processed":
    raise RuntimeError(f"File failed to process: {seed_file.status}")

# 3. Submit a SimpleQnA job that references the uploaded file.
job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="retail-agent-file-eval-set",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            FileDataGenerationJobSource(
                description="Contoso Retail product catalog and policy reference.",
                id=seed_file.id,
            ),
        ],
        options=SimpleQnADataGenerationJobOptions(
            max_samples=15,
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="retail-agent-file-eval-set"),
    ),
)

poller = project_client.beta.datasets.begin_create_generation_job(job=job)
# Optional: While SDK is polling, periodically print the job status until the job is complete
print("Periodically check job status:")
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)
result = poller.result()

Gerar um conjunto de dados de inicialização para simulação (SDK)

As tarefas de inicialização da simulação geram um conjunto de dados com descrições de cenários que alimentam o fluxo Simular conversas. As linhas geradas podem conter id, category, test_case_description, e desired_num_turns. Só test_case_description é obrigatório.

A forma do trabalho é idêntica à do Simple Q&A. As únicas diferenças são a classe de opções (SimulationSeedDataGenerationJobOptions) e o valor do tipo de fio (simulation_seed). O exemplo seguinte utiliza uma definição de agente como fonte. Para usar um prompt ou ficheiro de referência em vez disso, troque a classe de origem conforme mostrado em Gerar um conjunto de dados a partir de um prompt (SDK) ou Gerar um conjunto de dados a partir de ficheiros de referência (SDK), e substitua SimulationSeedDataGenerationJobOptions por SimpleQnADataGenerationJobOptions.

Este exemplo assume um agente implantado chamado retail-agent. Se ainda não tiveres um, cria-o primeiro com o create_version padrão mostrado em Gerar um conjunto de dados a partir de uma definição de agente (SDK).

from azure.ai.projects.models import (
    AgentDataGenerationJobSource,
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    SimulationSeedDataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"

job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="retail-agent-simulation-seeds",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            AgentDataGenerationJobSource(
                description="Agent definition used to seed simulation scenarios.",
                agent_name="retail-agent",
                agent_version="1",
            ),
        ],
        options=SimulationSeedDataGenerationJobOptions(
            max_samples=15,
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="retail-agent-simulation-seeds"),
    ),
)

poller = project_client.beta.datasets.begin_create_generation_job(job=job)
result = poller.result()

Resolva o conjunto de dados gerado a partir result utilizando o padrão de gestão de saída mostrado em Gerar um conjunto de dados a partir de uma definição de agente (SDK).

Esquema de conjunto de dados gerado

O esquema de semente de simulação suporta os seguintes campos. Apenas test_case_description é obrigatório; os outros campos são opcionais.

Exemplo de linha (test_case_description abreviada para maior legibilidade):

{
  "id": "1",
  "category": "Basic support & empathy",
  "test_case_description": "A mildly frustrated customer says they've been charged different amounts across recent months and asks for an explanation and refund. The agent must acknowledge the confusion without blame, note it can't see the actual account, and offer concrete generic next steps (what to check, how to contact billing support). Multi-turn behavior to evaluate: whether the agent stays consistent about its limitations across turns, and whether it keeps offering practical options rather than vague sympathy...",
  "desired_num_turns": 4
}

Visualize as linhas geradas no separador Dados antes de executar a simulação de conversa. Linhas com valores pouco claros test_case_description tendem a produzir conversas simuladas de menor qualidade.

Execute uma avaliação contra o conjunto de dados gerado

O percurso de avaliação depende do tipo de tarefa:

• Conjuntos de dados simples de Q&A utilizam o esquema padrão e e funcionam diretamente com as APIs de avaliação. Para o fluxo completo, consulte Avaliar modelos e agentes na cloud. Para exemplos completos executáveis de ponta a ponta, veja sample_synthetic_data_agent_evaluation.py e sample_synthetic_data_model_evaluation.py no GitHub.
• Os conjuntos de dados iniciais da simulação alimentam o fluxo Simular conversas. Passe o ID do conjunto de dados gerado como fonte da simulação. O simulador utiliza o test_case_description de cada linha para assumir o papel do utilizador e, quando este é fornecido, utiliza o desired_num_turns como orientação. Os avaliadores de conversação classificam a conversa resultante em vez da linha inicial.

Gerir trabalhos de geração de dados

Use project_client.beta.datasets APIs de gestão de trabalhos para listar, inspecionar, cancelar e eliminar trabalhos de geração sintética.

from azure.ai.projects.models import DataGenerationJobScenario

# List recent evaluation jobs.
for job in project_client.beta.datasets.list_generation_jobs(
    limit=20,
    order="desc",
    scenario=DataGenerationJobScenario.EVALUATION,
):
    print(f"{job.id}  {job.status:<12}  {job.inputs.name}")

# Inspect a specific job's status.
job = project_client.beta.datasets.get_generation_job(job_id="job_...")
print(f"{job.id}  {job.status}")

# Cancel a running job.
project_client.beta.datasets.cancel_generation_job(job_id="job_...")

# Delete a job record (produced datasets are not deleted).
project_client.beta.datasets.delete_generation_job(job_id="job_...")

// List recent evaluation jobs.
for await (const job of projectClient.beta.datasets.listGenerationJobs({
  limit: 20,
})) {
  console.log(`${job.id}  ${job.status}  ${job.inputs?.name}`);
}

// Inspect a specific job's status.
const job = await projectClient.beta.datasets.getGenerationJob("job_...");
console.log(`${job.id}  ${job.status}`);

// Cancel a running job.
await projectClient.beta.datasets.cancelGenerationJob("job_...");

// Delete a job record (produced datasets are not deleted).
await projectClient.beta.datasets.deleteGenerationJob("job_...");

Para mais contexto, consulte Gerir trabalhos de geração de dados.

Limitações

• Se o seu projeto Foundry estiver ligado à sua própria conta de armazenamento, o acesso público à rede deve estar ativado nessa conta de armazenamento para criar um conjunto de dados bem-sucedido.

Melhores práticas

• Espelha o teu prompt do sistema de produção. Quando geras a partir de uma definição de agente ou de um prompt, usa instruções que correspondam ao que o teu agente de produção realmente executa. O desvio aqui enfraquece o sinal de avaliação.
• Combine um ficheiro de referência com um prompt para cobertura fundamentada. Os âncoras de ficheiro geravam perguntas em conteúdo real do domínio; O enunciado orienta o tom, a dificuldade ou a ênfase do tema.
• Gera primeiro um pequeno lote. Comece com o mínimo max_samples de 15, reveja manualmente as linhas no separador Data e, em seguida, aumente quando a qualidade do resultado lhe parecer correta.
• Regenerar quando as instruções do agente mudarem. Um conjunto de dados gerado a partir de uma versão do prompt de um agente torna-se obsoleto quando o prompt muda significativamente. Reexecute o trabalho e faça a versão da nova saída.
• Combine geração sintética e baseada em traços para obter a cobertura mais forte. Dados sintéticos preenchem lacunas antes do lançamento e para casos extremos; As marcas de produção refletem como o seu agente realmente se comporta. Use ambas as fontes em conjunto em vez de as tratar como alternativas. Veja Converter rastreios de agentes em conjuntos de dados para avaliação.
• Escreva valores focados test_case_description em cenários para sementes de simulação. O simulador reproduz o lado do utilizador da conversa com base neste texto. Descrições que definem o objetivo do utilizador, as suas limitações e quaisquer casos excecionais que pretenda abordar produzem conversas simuladas de maior qualidade.

Conteúdo relacionado

• Converter vestígios de agentes em conjuntos de dados de avaliação
• Avalie o seu agente
• Executar avaliações na cloud
• Simule conversas
• Avaliar conversas na cloud
• Configura o rastreio para o teu agente
• Dados sintéticos + amostra de avaliação de agentes (Python)
• Dados sintéticos + amostra de avaliação de modelos (Python)