Gerar um conjunto de dados de avaliação sintética (versão prévia)

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

Quando seu agente ainda não tem tráfego de produção, você ainda pode criar um conjunto de dados de avaliação relevante. O serviço de geração de dados Microsoft Foundry sintetiza os dados de avaliação do material que você já tem: instruções de um agente, um prompt embutido ou um documento de referência que você carrega. Dois tipos de tarefa estão disponíveis:

• O QnA simples (turno único) produz pares de perguntas e respostas para avaliação em nível de turno.
• Semente de simulação (múltiplos turnos) produz descrições de cenário que alimentam o fluxo Simular conversas para avaliação de múltiplos turnos.

Você pode avaliar conjuntos de dados de Q&A simples diretamente. Os conjuntos de dados iniciais para simulação primeiro alimentam um simulador que assume o papel do usuário ao interagir com o agente-alvo. Em seguida, os avaliadores de nível de conversa pontuam as conversas geradas.

Três tipos de origem de entrada estão disponíveis e você pode combiná-los em um único trabalho para uma cobertura mais rica:

• Definição do agente — geração de semente a partir das instruções ou do prompt de um agente implementado.
• Prompt—forneça um prompt de texto inline que descreva o domínio ou oriente o nível de dificuldade.
• Arquivo de referência – carregue um documento (por exemplo, uma política, especificação ou exportação de base de dados de conhecimento) e gere perguntas baseadas em seu conteúdo.

Geração sintética e geração baseada em rastreamento são complementares: conjuntos de dados sintéticos abrangem casos de borda e cenários de pré-lançamento, enquanto conjuntos de dados baseados em rastreamento refletem o comportamento real de produção. Usar ambos fornece o sinal de avaliação mais forte. Veja Como converter rastreamentos de agentes em conjuntos de dados de avaliação.

Quando usar a geração sintética

Use a geração sintética quando:

• Você está em pré-lançamento e ainda não tem rastros de produção.
• Seu agente tem baixo tráfego e uma janela de rastreamento não produz amostras distintas suficientes.
• Você precisa de uma linha de base de regressão estável que não descompasse com a alteração do comportamento de produção.
• Você quer ampliar a cobertura de casos extremos que o agente ainda não encontrou em produção.
• Você está iterando nas instruções de um agente e deseja um conjunto de dados de smoke-test rápido.

Escolher um tipo de origem

Você pode combinar fontes em um único trabalho. Um padrão comum é combinar um arquivo de referência (para embasamento) com um prompt (para orientar o tom ou o nível de dificuldade).

Pré-requisitos

• SDK do Python versão 2.5.0 ou posterior: pip install "azure-ai-projects>=2.5.0" azure-identity.
• Uma URL de endpoint de um projeto do Microsoft Foundry no formato https://<your-resource>.services.ai.azure.com/api/projects/<your-project>.
• Função de Usuário do Foundry ou superior no projeto.
• Uma implantação de modelo Azure OpenAI que dá suporte à API de Respostas. Tanto a receita simulation_seed quanto a receita simple_qna usam este modelo para sintetizar linhas de saída. Para obter a lista de modelos compatíveis, consulte suporte a modelos da API de Respostas do Azure OpenAI.
• Uma região com suporte. Para a lista, consulte regiões com suporte para geração de dados.

Gerar um conjunto de dados do portal

1. No portal, abra a guia Geração de Dados . Selecione Criar conjunto de dados e, em seguida, selecione Gerar sintético.
2. Em Gerar dados sintéticos, defina o uso do conjunto de dados como Avaliação.
3. Definir tipo de tarefa. Selecione QnA simples (turno único) para pares de perguntas e respostas ou semente de simulação (várias voltas) para descrições de cenário usadas na simulação de conversa.
4. Selecione um modelo de gerador.
5. Forneça uma ou mais entradas de origem: agente, prompt ou arquivo de referência.
6. Defina o número máximo de exemplos e o nome do arquivo de saída.
7. Selecione Gerar.
8. Acompanhe o status do trabalho de geração do conjunto de dados na guia Geração de Dados .
9. Quando o trabalho for concluído, visualize as linhas geradas na guia Dados .

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

Este fluxo inicia a geração com base nas instruções de um agente implantado. O serviço obtém o prompt do agente e usa o modelo que você configurou para sintetizar pares de perguntas e respostas a partir dele.

Primeiro, crie um AIProjectClient usando o endpoint do projeto e DefaultAzureCredential. Você 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(),
);

Em seguida, envie um trabalho SimpleQnA cuja fonte seja uma referência a um agente. Se você já tiver um agente implantado, ignore a chamada create_version e passe seus 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. Visualize-o na guia Dados no portal para verificar as linhas geradas antes de avaliar.

Gerar um conjunto de dados de um prompt (SDK)

Se você ainda não tiver um agente já implantado ou quiser gerar dados a partir de um trecho autocontido do material de origem, passe o texto como um PromptDataGenerationJobSource. Essa abordagem é útil para documentos de política, conteúdo de perguntas frequentes 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 seção anterior.

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

Para material de origem mais longo, carregue um documento como um arquivo Azure OpenAI e faça referência a ele por ID. Essa opção funciona melhor quando o conhecimento de domínio do agente reside em uma especificação, exportação de base de dados de conhecimento ou documento de política, pois as perguntas geradas permanecem fundamentadas nesse conteúdo.

O arquivo deve estar no processed estado antes que o serviço de geração de dados possa usá-lo e ele precisa conter pelo menos 1 KB de conteúdo.

As extensões de arquivo de referência com suporte 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 inicial de simulação (SDK)

As tarefas de inicialização da simulação produzem um conjunto de dados com descrições de cenários que alimentam o fluxo Simular conversas. As linhas geradas podem conter id, categorye test_case_descriptiondesired_num_turns. Somente test_case_description é necessário.

O formato do trabalho é idêntico ao 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 a seguir usa uma definição de agente como a origem. Para usar um prompt ou arquivo de referência em vez disso, troque a classe de origem conforme mostrado em Gerar um conjunto de dados de um prompt (SDK) ou gere um conjunto de dados de arquivos de referência (SDK) e substitua SimulationSeedDataGenerationJobOptions por SimpleQnADataGenerationJobOptions.

Este exemplo parte do pressuposto de que existe um agente implantado chamado retail-agent. Se você ainda não tiver um, crie-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 de result usando o padrão de tratamento da 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 dá suporte aos campos a seguir. Somente test_case_description é necessário; os outros campos são opcionais.

Linha de exemplo (test_case_description abreviada para 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
}

Visualizar as linhas geradas na guia Dados antes de executar a simulação de conversa. Linhas com valores pouco claros test_case_description tendem a produzir conversas simuladas de baixa qualidade.

Executar uma avaliação no conjunto de dados gerado

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

• Conjuntos de dados simples de Q&A usam o esquema padrão query e ground_truth e funcionam diretamente com as APIs de avaliação. Para obter o fluxo completo, consulte Avaliar modelos e agentes na nuvem. Para obter exemplos completos de ponta a ponta executáveis, consulte sample_synthetic_data_agent_evaluation.py e sample_synthetic_data_model_evaluation.py no GitHub.
• Os conjuntos de dados iniciais de simulação abastecem o fluxo Simular conversas. Passe a ID do conjunto de dados gerada como a origem da execução de simulação. O simulador usa o test_case_description de cada linha para interpretar o papel do usuário e, quando fornecido, usa desired_num_turns como orientação. Os avaliadores no nível da conversa avaliam a conversa resultante, em vez da linha inicial.

Gerenciar trabalhos de geração de dados

Use project_client.beta.datasets APIs de gerenciamento de trabalho para listar, inspecionar, cancelar e excluir 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 obter mais contexto, consulte Gerenciar trabalhos de geração de dados.

Limitações

• Se o projeto do Foundry estiver conectado à sua própria conta de armazenamento, o acesso à rede pública deverá ser habilitado nessa conta de armazenamento para a criação bem-sucedida do conjunto de dados.

Práticas recomendadas

• Espelhe o prompt de sistema de produção. Ao gerar a partir de uma definição de agente ou de um prompt, use instruções que correspondam ao que o agente de produção realmente executa. Esse desvio aqui enfraquece o sinal da avaliação.
• Combine um arquivo de referência com um prompt para obter cobertura fundamentada. As âncoras de arquivo geraram perguntas no conteúdo real do domínio; o prompt orienta o tom, a dificuldade ou a ênfase do tópico.
• Gere um pequeno lote primeiro. Comece no valor mínimo de max_samples15, revise as linhas manualmente na guia Dados e, em seguida, aumente esse valor quando a qualidade do resultado parecer adequada.
• Regenerar quando as instruções do agente forem alteradas. Um conjunto de dados gerado a partir de uma versão do prompt de um agente fica obsoleto quando o prompt é alterado significativamente. Execute o trabalho novamente e versione a nova saída.
• Combine a geração sintética e a geração baseada em rastreamento para obter a cobertura mais abrangente. Dados sintéticos preenchem lacunas antes do lançamento e para casos extremos; os rastros de produção refletem como seu agente realmente se comporta. Use ambas as fontes em vez de tratá-las como alternativas. Veja Como converter rastreamentos de agentes em conjuntos de dados de avaliação.
• Escreva valores baseados em cenários test_case_description para sementes de simulação. O simulador reproduz o lado do usuário da conversa com base neste texto. Descrições que explicitem o objetivo do usuário, as restrições e quaisquer casos extremos que você queira contemplar produzem conversas simuladas de melhor qualidade.

Conteúdo relacionado

• Converta rastros de agentes em conjuntos de dados para avaliação
• Avaliar seu agente
• Executar avaliações de nuvem
• Simular conversas
• Avaliar conversas na nuvem
• Configurar o rastreamento para seu agente
• Amostra de avaliação de dados sintéticos + agente (Python)
• Dados sintéticos + exemplo de avaliação de modelo (Python)