Executar avaliações na nuvem usando o SDK do Microsoft Foundry

Importante

Itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou ter recursos restritos. Para obter mais informações, consulte Supplemental Terms of Use for Microsoft Azure Previews.

Neste artigo, você aprenderá a executar avaliações na nuvem (versão prévia) para testes de pré-implantação em um conjunto de dados de teste.

Use avaliações de nuvem para a maioria dos cenários, especialmente ao testar em escala, integrar avaliações em pipelines de CI/CD (integração contínua e entrega contínua) ou executar testes de pré-implantação. A execução de avaliações na nuvem elimina a necessidade de gerenciar a infraestrutura de computação local e dá suporte a fluxos de trabalho de teste automatizados em larga escala. Você também pode agendar avaliações para serem executadas de forma recorrente ou configurar uma avaliação contínua para avaliar automaticamente as respostas de agente amostradas na produção.

Os resultados da avaliação de nuvem são armazenados em seu projeto do Foundry. Você pode examinar os resultados no portal, recuperá-los por meio do SDK ou roteá-los para o Application Insights, se conectado. A avaliação de nuvem dá suporte a todos os avaliadores embutidos da Microsoft e aos seus próprios avaliadores personalizados. Os avaliadores são gerenciados no catálogo do avaliador com o mesmo escopo de projeto, controle de acesso baseado em função.

Dica

Para obter exemplos executáveis completos, consulte os exemplos de avaliação do SDK Python em GitHub.

Como funciona a avaliação de nuvem

Para executar uma avaliação na nuvem, crie uma definição de avaliação com o esquema de dados e os critérios de teste (avaliadores) e crie uma execução de avaliação. A execução executa cada avaliador em relação aos seus dados e retorna resultados pontuados que você pode sondar para conclusão.

A avaliação de nuvem dá suporte aos seguintes cenários:

Cenário Quando usar Tipo de fonte de dados Objetivo
Avaliação do conjunto de dados Avalie as respostas pré-computadas em um arquivo JSONL. jsonl —
Avaliação do conjunto de dados CSV Avalie as respostas pré-computadas em um arquivo CSV. csv —
Avaliação do alvo do modelo Forneça consultas e gere respostas de um modelo em runtime para avaliação. azure_ai_target_completions azure_ai_model
Avaliação de alvo do agente Envie consultas e gere respostas de um agente do Foundry (prompt ou hospedado) em tempo de execução para avaliação. azure_ai_target_completions azure_ai_agent
Avaliação da resposta do agente Recupere e avalie as respostas do agente do Foundry através dos IDs de resposta. azure_ai_responses —
Avaliação de dados sintéticos (versão prévia) Gere consultas de teste sintéticas, envie-as para um modelo ou agente e avalie as respostas. azure_ai_synthetic_data_gen_preview azure_ai_model Ou azure_ai_agent
Avaliação da equipe vermelha Realize testes adversariais automatizados em um modelo ou agente. azure_ai_red_team azure_ai_model Ou azure_ai_agent

A maioria dos cenários exige dados de entrada. Você pode fornecer dados de duas maneiras:

Tipo de origem Descrição
file_id Faça referência a um conjunto de dados carregado por ID.
file_content Forneça dados embutidos na solicitação.

Cada avaliação requer um data_source_config que informa ao serviço quais campos esperar em seus dados:

  • custom — Você define um item_schema com seus nomes e tipos de campo. Defina include_sample_schema como true ao usar um alvo, para que os avaliadores possam referenciar respostas geradas.
  • azure_ai_source — O esquema é inferido do serviço. Defina "scenario" para "responses" avaliação de resposta do agente, "synthetic_data_gen_preview" para avaliação de dados sintéticos (versão prévia) ou "red_team" para agrupamento vermelho.

Cada cenário requer avaliadores que definem seus critérios de teste. Para obter diretrizes sobre como selecionar avaliadores, consulte os avaliadores internos.

Pré-requisitos

Nota

Alguns recursos de avaliação têm restrições regionais. Confira as regiões com suporte para obter detalhes.

Introdução

Instale o SDK e configure seu cliente:

pip install "azure-ai-projects>=2.0.0"

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

Preparar dados de entrada

A maioria dos cenários de avaliação exige dados de entrada. Você pode fornecer dados de duas maneiras:

Carregue um arquivo JSONL ou CSV para criar um conjunto de dados com versão em seu projeto do Foundry. Os conjuntos de dados dão suporte ao controle de versão e à reutilização em várias execuções de avaliação. Use essa abordagem para testes de produção e fluxos de trabalho de CI/CD.

Prepare um arquivo JSONL com um objeto JSON por linha contendo os campos de que os avaliadores precisam:

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

Ou prepare um arquivo CSV com cabeçalhos de coluna correspondentes aos campos do avaliador:

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Fornecer dados em linha

Para experimentação rápida com pequenos conjuntos de testes, forneça dados diretamente na solicitação de avaliação usando file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Passe source como campo do "source" na configuração da fonte de dados ao iniciar uma execução. As seções de cenário que seguem utilizam file_id por padrão.

Avaliação do conjunto de dados

Avalie as respostas pré-computadas em um arquivo JSONL usando o tipo de jsonl fonte de dados. Esse cenário é útil quando você já tem saídas de modelo e deseja avaliar sua qualidade.

Dica

Antes de começar, conclua Introdução e Prepare os dados de entrada.

Definir o esquema de dados e os avaliadores

Especifique o esquema que corresponde aos campos JSONL e selecione os avaliadores (critérios de teste) a serem executados. Use o data_mapping parâmetro para conectar campos de seus dados de entrada aos parâmetros do avaliador com {{item.field}} sintaxe. Inclua data_mapping sempre com os campos de entrada necessários para cada avaliador. Seus nomes de campo devem corresponder aos do arquivo JSONL , por exemplo, se os dados tiverem "question" , em vez de "query", usar "{{item.question}}" no mapeamento. Para os parâmetros necessários por avaliador, consulte os avaliadores internos.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

Criar teste e execução

Crie a avaliação e inicie uma execução em relação ao conjunto de dados carregado. A execução roda cada avaliador em todas as linhas do conjunto de dados.

# Create the evaluation
eval_object = client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

Para obter um exemplo executável completo, consulte sample_evaluations_builtin_with_dataset_id.py no GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Avaliação do conjunto de dados CSV

Avalie as respostas pré-computadas em um arquivo CSV usando o tipo de csv fonte de dados. Esse cenário funciona da mesma maneira que a avaliação do conjunto de dados , mas aceita arquivos CSV em vez de JSONL. Use CSV quando os dados já estiverem em formato de planilha ou de tabela.

Dica

Antes de começar, conclua Introdução e Prepare os dados de entrada.

Preparar um arquivo CSV

Crie um arquivo CSV com cabeçalhos de coluna que correspondam aos campos de que os avaliadores precisam. Cada linha representa um caso de teste:

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Carregar e executar

Carregue o arquivo CSV como um conjunto de dados e crie uma avaliação usando o tipo de csv fonte de dados. A definição de esquema e a configuração do avaliador são iguais às da avaliação JSONL; a única diferença está em ""type": "csv"" na fonte de dados.

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Avaliação de objetivo do modelo

Envie queries para um modelo implantado durante o tempo de execução e avalie as respostas usando o tipo de azure_ai_target_completions fonte de dados com um azure_ai_model destino. Seus dados de entrada contêm consultas; o modelo gera respostas que são então avaliadas.

Dica

Antes de começar, conclua Introdução e Prepare os dados de entrada.

Definir o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas para o modelo. Use {{item.query}} para fazer referência a campos de seus dados de entrada. Especifique o modelo para avaliar e parâmetros de amostragem opcionais:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Configurar avaliadores e mapeamentos de dados

Quando o modelo gera respostas em tempo de execução, use data_mapping para fazer referência à saída do modelo. Use {{item.field}} para fazer referência a campos de seus dados de entrada.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Criar teste e execução

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Para obter um exemplo executável completo, consulte sample_model_evaluation.py no GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Dica

Para adicionar outra execução de avaliação, você pode usar o mesmo código.

Avaliação de alvo do agente

Envie consultas a um agente do Foundry em tempo de execução e avalie as respostas usando o tipo de fonte de dados azure_ai_target_completions com o destino azure_ai_agent. Esse cenário é aplicável tanto para agentes de prompt quanto para agentes hospedados.

Dica

Antes de começar, conclua Introdução e Prepare os dados de entrada.

Dica

Os agentes hospedados que usam o protocolo de respostas funcionam com os mesmos exemplos de código mostrados aqui. Para agentes hospedados que usam o protocolo de invocações, o input_messages formato é diferente. Consulte o protocolo invocações do agente hospedado para obter detalhes.

Definir o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas ao agente. Use {{item.query}} para fazer referência a campos de seus dados de entrada. Especifique o agente a ser avaliado pelo nome:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Configurar avaliadores e mapeamentos de dados

Quando o agente gera respostas em tempo de execução {{sample.*}}, use variáveis data_mapping para fazer referência à saída do agente.

Variável Descrição Usar para
{{sample.output_text}} A resposta em texto sem formatação do agente. Avaliadores que esperam uma resposta de cadeia de caracteres (por exemplo, coherence, ). violence
{{sample.output_items}} A saída JSON estruturada do agente, incluindo chamadas de ferramenta. Avaliadores que precisam de contexto de interação completa (por exemplo, task_adherence).
{{item.field}} Um campo dos seus dados de entrada. Campos de entrada como query ou ground_truth.

Dica

O query campo pode conter JSON estruturado, incluindo mensagens do sistema e histórico de conversas. Alguns avaliadores de agente, como task_adherence, usam esse contexto para uma pontuação mais precisa. Para obter detalhes sobre a formatação de consulta, consulte avaliadores de agentes.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Criar teste e execução

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Para obter um exemplo executável completo, consulte sample_agent_evaluation.py no GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Protocolo de invocações de agente hospedado

Os agentes hospedados que usam o protocolo de invocações dão suporte ao mesmo azure_ai_agent tipo de destino, mas usam um formato de forma input_messageslivre. Em vez do formato de modelo estruturado, forneça um objeto JSON que é mapeado diretamente para o corpo da solicitação do /invocations agente. Use marcadores de posição {{item.*}} para substituir campos nos seus dados de entrada.

Se um agente hospedado der suporte aos protocolos de respostas e invocações, o serviço usará o protocolo de invocações como padrão.

Definir o formato e o destino da mensagem

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Criar teste e execução

eval_object = client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

A configuração do avaliador e os mapeamentos de dados são os mesmos que para a avaliação do agente de prompt. Use {{sample.output_text}} para a resposta de texto do agente e {{sample.output_items}} para a saída estruturada completa, incluindo chamadas de ferramenta.

Avaliação da resposta do agente

Recupere e avalie as respostas de agentes do Foundry pelos IDs de respostas usando o tipo de fonte de dados azure_ai_responses. Use esse cenário para avaliar interações específicas do agente depois que elas ocorrerem.

Dica

Antes de começar, conclua Introdução.

Uma ID de resposta é um identificador exclusivo retornado sempre que um agente Foundry gera uma resposta. Você pode coletar IDs de resposta de interações com o agente usando a API de Respostas ou dos logs de rastreamento de seu aplicativo. Forneça as IDs embutidas como conteúdo do arquivo ou carregue-as como um conjunto de dados (consulte Preparar dados de entrada).

Coletar IDs de resposta

Cada chamada à API de Respostas retorna um objeto de resposta com um campo exclusivo id . Colete essas IDs das interações do aplicativo ou gere-as diretamente:

# Generate response IDs by calling a model through the Responses API
response = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

Você também pode coletar IDs de respostas das interações com o agente nos logs de rastreamento do seu aplicativo ou no pipeline de monitoramento. Cada ID de resposta identifica exclusivamente uma resposta armazenada que o serviço de avaliação pode recuperar.

Criar teste e execução

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

Para obter um exemplo executável completo, consulte sample_agent_response_evaluation.py no GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Avaliação de dados sintéticos (versão prévia)

Gere consultas de teste sintéticas, envie-as para um modelo implantado ou agente do Foundry e avalie as respostas usando o tipo de azure_ai_synthetic_data_gen_preview fonte de dados. Use esse cenário quando você não tiver um conjunto de dados de teste – o serviço gera consultas com base em um prompt que você fornece (e/ou a partir das instruções do agente), executa-as em relação ao seu destino e avalia as respostas.

Dica

Antes de começar, conclua Introdução.

Como funciona a avaliação de dados sintéticos

  1. O serviço gera consultas sintéticas com base no seu prompt e nos arquivos de dados de semente opcionais.
  2. Cada consulta é enviada para o destino especificado (modelo ou agente) para gerar uma resposta.
  3. Os avaliadores pontuam cada resposta usando a consulta e a resposta geradas.
  4. As consultas geradas são armazenadas como um conjunto de dados em seu projeto para reutilização.

Parâmetros

Parâmetro Necessário Descrição
samples_count Sim Número máximo de consultas de teste sintéticas a serem geradas.
model_deployment_name Sim Implantação do modelo para uso na geração de consultas sintéticas. Há suporte apenas para modelos com funcionalidade de API de Respostas. Para obter disponibilidade, consulte a disponibilidade da região da API de Respostas.
prompt Não Instruções que descrevem o tipo de consultas a serem geradas. Opcional quando o alvo do agente já tiver instruções configuradas.
output_dataset_name Não Nome do conjunto de dados de saída em que as consultas geradas são armazenadas. Se não for fornecido, o serviço gerará um nome automaticamente.
sources Não Arquivos de dados iniciais (organizados por ID de arquivo) para melhorar a relevância das consultas geradas. Atualmente, há suporte apenas para um arquivo.

Configurar avaliadores e mapeamentos de dados

O gerador de dados sintéticos produz consultas no {{item.query}} campo. O alvo gera respostas disponíveis em {{sample.output_text}}. Mapeie estes campos para seus avaliadores:

data_source_config = {"type": "azure_ai_source", "scenario": "synthetic_data_gen_preview"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Criar teste e execução

Alvo do modelo

Gere consultas sintéticas e avalie um modelo:

eval_object = client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Opcionalmente, você pode adicionar um prompt do sistema para moldar o comportamento do modelo de destino. Quando você usa input_messages com a geração de dados sintéticos, inclua apenas system mensagens de função – o serviço fornece as consultas geradas como mensagens de usuário automaticamente.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

Destino do agente

Gere consultas sintéticas e avalie um agente Foundry.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

Para verificar a conclusão e interpretar os resultados, consulte Obter resultados. A resposta inclui uma output_dataset_id propriedade que contém a ID do conjunto de dados gerado, que você pode usar para recuperar ou reutilizar os dados sintéticos.

Obter resultados

Após a conclusão de uma execução de avaliação, recupere os resultados pontuados e examine-os no portal ou programaticamente.

Sondagem para resultados

As execuções de avaliação são assíncronas. Monitorar o estado da execução até que ele seja concluído e, em seguida, recuperar os resultados.

import time
from pprint import pprint

while True:
    run = client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Interpretar resultados

Para um único exemplo de dados, todos os avaliadores geram o seguinte esquema:

  • Rótulo: um rótulo binário "aprovado" ou "falho", semelhante à saída de um teste de unidade. Use esse resultado para facilitar comparações entre avaliadores.
  • Pontuação: uma pontuação da escala natural de cada avaliador. Alguns avaliadores usam uma rubrica refinada, pontuando em uma escala de 5 pontos (avaliadores de qualidade) ou uma escala de 7 pontos (avaliadores de segurança de conteúdo). Outros, como avaliadores de similaridade textual, usam pontuações F1, que são valores fracionários entre 0 e 1. Qualquer "pontuação" não binária é convertida em "passar" ou "falhar" no campo "rótulo", de acordo com o "limite".
  • Limite: todas as pontuações não binárias são binárias para "passar" ou "falhar" com base em um limite padrão, que o usuário pode substituir na experiência do SDK.
  • Motivo: para melhorar a inteligibilidade, todos os avaliadores LLM-Judge também geram um campo de justificativa para explicar por que uma determinada pontuação é atribuída.
  • Detalhes: (opcional) Para alguns avaliadores, como tool_call_accuracy, pode haver um campo "detalhes" ou sinalizadores que contêm informações adicionais para ajudar os usuários a depurar seus aplicativos.

Saída de exemplo (item único)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Saída de exemplo (agregação)

Para resultados agregados em vários exemplos de dados (um conjunto de dados), a taxa média dos exemplos com um "pass" forma a taxa de aprovação para esse conjunto de dados.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Solucionando problemas

Processo em execução há muito tempo

Seu trabalho de avaliação pode permanecer no estado em execução por um longo período. Isso normalmente ocorre quando a implantação do modelo Azure OpenAI não tem capacidade suficiente, fazendo com que o serviço repita as solicitações.

Resolução:

  1. Cancelar o trabalho de avaliação atual usando client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Aumente a capacidade do modelo no portal Azure.
  3. Execute a avaliação novamente.

Erros de autenticação

Se você receber um erro 401 Unauthorized ou 403 Forbidden, verifique se:

  • Seu DefaultAzureCredential está configurado corretamente (execute az login se estiver usando CLI do Azure).
  • Sua conta tem a função Usuário de IA do Azure no projeto Foundry.
  • A URL do ponto de extremidade do projeto está correta e inclui os nomes da conta e do projeto.

Erros de formato de dados

Se a avaliação falhar com um esquema ou erro de mapeamento de dados:

  • Verifique se o arquivo JSONL tem um objeto JSON válido por linha.
  • Confirme se os nomes de campo em data_mapping correspondem exatamente aos nomes de campo no seu arquivo JSONL (sensível a maiúsculas e minúsculas).
  • Verifique se item_schema as propriedades correspondem aos campos em seu conjunto de dados.

Erros de limite de taxa

As criações de execução de avaliação são limitadas por taxa nos níveis de locatário, assinatura e projeto. Se você receber uma 429 Too Many Requests resposta:

  • Verifique o retry-after cabeçalho na resposta para saber o tempo de espera recomendado.
  • Examine o corpo da resposta para obter detalhes do limite de taxa.
  • Use backoff exponencial ao tentar novamente solicitações que falharam.

Se um trabalho de avaliação falhar com um 429 erro durante a execução:

  • Reduza o tamanho do conjunto de dados de avaliação ou divida-o em lotes menores.
  • Aumente a cota de TPM (tokens por minuto) para sua implantação de modelo no portal do Azure.

Erros da ferramenta de avaliação do agente

Se um avaliador de agente retornar um erro para ferramentas sem suporte:

  • Verifique as ferramentas suportadas para avaliadores de agentes.
  • Como solução alternativa, encapsule ferramentas sem suporte como ferramentas de função definidas pelo usuário para que o avaliador possa avaliá-las.

Conteúdo relacionado

  • Last updated on