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 integrados da Microsoft e 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 Alvo
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 tempo de execução para avaliação. azure_ai_target_completions azure_ai_model
Avaliação do objetivo do agente Forneça consultas e gere respostas de um agente do Foundry (em 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 utilizando os IDs de resposta. azure_ai_responses —
Avaliação de rastreamento Avalie as interações do agente já capturadas no Application Insights por ID de rastreamento. Use essa abordagem para agentes não Foundry (LangChain e estruturas personalizadas que aderem ao registro em log baseado em OpenTelemetry). azure_ai_traces —
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 Executar 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 Referencie 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. Configure include_sample_schema para true ao usar um destino, para que os avaliadores possam referenciar as respostas geradas.
  • azure_ai_source — O esquema é inferido do serviço. Defina "scenario" para "responses" avaliação de resposta do agente, "traces" para avaliação de rastreamento, "synthetic_data_gen_preview" para avaliação de dados sintéticos (versão prévia), ou "red_team" para red teaming.

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 o campo "source" na configuração da fonte de dados ao criar uma rodada. As seções de cenário a seguir usam 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 avaliação e executar

Crie a avaliação e inicie uma execução em relação ao conjunto de dados carregado. A execução executa cada avaliador em cada linha 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 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 avaliações JSONL, sendo a única diferença "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 Resultados.

Avaliação de objetivos do modelo

Envie consultas para um modelo implantado em tempo de execução e avalie as respostas usando o tipo de fonte de dados azure_ai_target_completions com um destino azure_ai_model. 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 {{sample.output_text}} em 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 avaliação e executar

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 Resultados.

Dica

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

Avaliação do alvo do agente

Envie consultas para um agente do Foundry em tempo de execução e avalie as respostas usando azure_ai_target_completions tipo de fonte de dados com azure_ai_agent como destino. Esse cenário funciona para agentes de prompt e 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 Utilizar para
{{sample.output_text}} A resposta de 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 do agente.

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 avaliação e executar

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 {{item.*}} marcadores de posição para substituir campos dos 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 avaliação e executar

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 instalaçã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 do agente do Foundry por IDs de resposta 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 da Foundry gera uma resposta. Você pode coletar IDs de resposta de interações com agentes usando a API de Respostas ou dos logs de rastreamento do seu aplicativo. Forneça os IDs em linha como conteúdo do arquivo ou faça upload deles 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 resposta de interações do agente nos logs de rastreamento do aplicativo ou no fluxo de monitoramento. Cada ID de resposta identifica exclusivamente uma resposta armazenada que o serviço de avaliação pode recuperar.

Criar avaliação e executar

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 Resultados.

Avaliação de rastreamento

Avalie as interações do agente que já foram capturadas no Application Insights. Use o tipo de azure_ai_traces fonte de dados. Esse cenário é útil para a avaliação pós-implantação do tráfego de produção em ambiente real — você seleciona traços do pipeline de monitoramento e executa avaliadores com base neles sem reproduzir nenhuma solicitação.

Importante

A avaliação de rastreamento é a abordagem recomendada para avaliar agentes não criados com o Microsoft Foundry Agent Service — incluindo LangChain e estruturas personalizadas. Desde que seu agente emita intervalos opentelemetry seguindo as convenções semânticas do GenAI para o Application Insights, a avaliação de rastreamento pode avaliar suas interações usando os mesmos avaliadores disponíveis para agentes do Foundry.

A avaliação de rastreamento dá suporte a dois modos:

  • Por IDs de rastreamento – avalie interações específicas do agente fornecendo seus operation_Id valores do Application Insights.
  • Por filtro de agente – descubra e avalie automaticamente os rastreamentos recentes de um determinado agente, sem coletar manualmente as IDs de rastreamento.

Dica

Antes de começar, conclua Introdução. Esse cenário também requer um recurso do Application Insights conectado ao seu projeto do Foundry.

Requisitos de dados de rastreamento

A avaliação de rastreamento exige que seu agente emita intervalos seguindo as convenções semânticas OpenTelemetry para IA generativa. Especificamente, o serviço de avaliação lê invoke_agent trechos do Application Insights e extrai dados de conversação de seus atributos.

Os seguintes atributos de intervalo são usados:

Atributo Necessário Descrição
gen_ai.operation.name Sim Deve ser igual a "invoke_agent". O serviço ignora todos os outros intervalos.
gen_ai.agent.id Para o modo de filtro do agente Identificador de agente exclusivo (formato: agent-name:version).
gen_ai.agent.name Para o modo de filtro do agente Nome do agente legível por humanos.
gen_ai.input.messages Para entradas de consulta de avaliadores Matriz JSON de mensagens de entrada seguindo o formato de mensagem de convenções semânticas do GenAI. Mensagens com função user ou system mapeiam para query; mensagens com função assistant ou tool mapeiam para response.
gen_ai.output.messages Para entradas de consulta de avaliadores Matriz JSON de mensagens de saída geradas por modelo. Todas as mensagens de saída são mapeadas para response. Se a saída também contiver tipo: tool_call ou tipo: tool_result, ela será mapeada para tool_calls
gen_ai.tool.definitions Opcional Matriz JSON de esquemas de ferramentas disponíveis para o agente. Caso esteja ausente, o serviço tenta inferir definições de ferramentas a partir de mensagens de chamada de ferramentas, mas os esquemas inferidos podem estar incompletos.
gen_ai.conversation.id Opcional Identificador de conversa, passado para os resultados da avaliação para correlação.

Nota

Se gen_ai.input.messages e gen_ai.output.messages estiverem vazios ou ausentes, os avaliadores de qualidade (coerência, fluência, relevância, resolução de intenção) retornarão score=None. Os avaliadores de segurança (violência, automutilação, sexual, ódio/injustiça) ainda podem produzir pontuações com dados parciais, mas podem não produzir resultados significativos.

Para agentes Python criados com o Azure AI Agent Server SDK, adicione o [tracing] extra para habilitar a emissão automática de segmentos:

pip install "azure-ai-agentserver-core[tracing]"

Pré-requisitos para avaliação de rastreamento

Além dos pré-requisitos gerais, a avaliação de traço requer:

  • Um recurso do Application Insights conectado ao projeto do Foundry. Consulte Configurar o rastreamento no Microsoft Foundry.
  • A identidade gerenciada do projeto deve ter a função Log Analytics Reader no recurso do Application Insights e no workspace Log Analytics vinculado.
  • O pacote azure-monitor-query Python (necessário somente se você coletar IDs de rastreamento manualmente).
pip install "azure-ai-projects>=2.0.0" azure-monitor-query

Defina estas variáveis de ambiente:

  • APPINSIGHTS_RESOURCE_ID — A ID do recurso do Application Insights (por exemplo, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — O identificador do agente emitido pela integração de rastreamento (gen_ai.agent.id atributo), usado para filtrar rastreamentos. Formato: agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Opcional) Número de horas para retroceder ao consultar rastros. O padrão é 1.

Opção A: Avaliar por filtro de agente

A abordagem mais simples – permitir que o serviço descubra e avalie automaticamente rastreamentos recentes para um agente específico. Nenhuma coleção de IDs de rastreamento manual é necessária.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

O serviço filtra invoke_agent spans pelo atributo gen_ai.agent.id, amostra até max_traces IDs de rastreamento exclusivas e avalia todos os spans desses rastreios.

Opção B: Avaliar por IDs de rastreamento

Para obter mais controle, colete IDs de rastreamento específicas do Application Insights e avalie-as. Isso é útil quando você deseja avaliar um conjunto de interações coletado (por exemplo, rastreamentos sinalizados por alertas ou amostrados para revisão de qualidade).

Coletar IDs de rastreamento do Application Insights

Consulte o Application Insights em busca de valores operation_Id nos rastreamentos do agente. Cada operation_Id representa uma interação completa do agente:

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Criar avaliação e realizar execução com IDs de rastreamento

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Configurar avaliadores e mapeamentos de dados

Ao avaliar rastreamentos, o serviço extrai automaticamente os dados de conversa dos atributos de intervalo OpenTelemetry. Use estes nomes de campo diretamente no data_mapping (sem os prefixos item. ou sample. usados em outros cenários):

Variável Atributo de origem Descrição
{{item.query}} gen_ai.input.messages (funções de usuário/sistema) A consulta de usuário extraída do rastreamento.
{{item.response}} gen_ai.input.messages (assistente/funções de ferramenta) + gen_ai.output.messages A resposta do agente extraída do rastreamento.
{{item.tool_definitions}} gen_ai.tool.definitions Esquemas de ferramentas disponíveis para o agente. Necessário apenas para avaliadores relacionados à ferramenta
{{item.tool_calls}} Extraído de mensagens do assistente em gen_ai.input.messages / gen_ai.output.messages Chamadas de ferramenta feitas pelo agente durante a interação. Usado por avaliadores de ferramentas. Necessário apenas para avaliadores relacionados à ferramenta 
testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",
        "evaluator_name": "builtin.intent_resolution",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "type": "azure_ai_evaluator",
        "name": "tool_call_accuracy",
        "evaluator_name": "builtin.tool_call_accuracy",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

Para obter um exemplo executável completo, consulte sample_evaluations_builtin_with_traces.py no GitHub. Para verificar a conclusão e interpretar os resultados, consulte 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 em 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 de modelo a ser usada para gerar 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 destino do agente 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 de inicialização (por ID de arquivo) para melhorar a relevância das queries 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 que estão 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 avaliação e executar

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."
                }
            }
        ]
    },
}

Alvo 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 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. Sondar o status de execução até que ele seja concluído e, em seguida, recupere 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 "aprovação" ou "falha", semelhante à saída de um teste unitário. 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 números decimais entre 0 e 1. Qualquer "pontuação" não binária é convertida para "passar" ou "falhar" no campo "rótulo" com base no "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 é dada.
  • 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 "aprovação" 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

Tarefa 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 Azure AI User 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 (com diferenciação entre 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 estão sujeitas a limites de taxa nos níveis de tenant, assinatura e projeto. Se você receber uma 429 Too Many Requests resposta:

  • Verifique o retry-after cabeçalho na resposta para o tempo de espera recomendado.
  • Examine o corpo da resposta para obter detalhes do limite de taxa.
  • Utilize 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 Azure.

Erros da ferramenta avaliadora de agente

Se um avaliador de agente retornar um erro para ferramentas não suportadas:

  • Verifique as ferramentas suportadas para avaliadores de agente.
  • 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