Execute avaliações na cloud usando o Microsoft Foundry SDK

Importante

Os itens marcados (pré-visualização) neste artigo encontram-se atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para cargas de trabalho em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

Neste artigo, aprende como executar avaliações na cloud (pré-visualização) para testes de pré-implementação num conjunto de dados de teste.

Use avaliações na cloud para a maioria dos cenários — especialmente ao testar em escala, integrar avaliações em pipelines de integração contínua e entrega contínua (CI/CD), ou realizar testes pré-implementação. Executar avaliações na cloud elimina a necessidade de gerir a infraestrutura de computação local e suporta fluxos de trabalho de testes automatizados em grande escala. Também pode agendar avaliações para serem realizadas de forma recorrente, ou configurar uma avaliação contínua para avaliar automaticamente as respostas dos agentes amostrados em produção.

Os resultados das avaliações na cloud são armazenados no seu projeto Foundry. Pode rever os resultados no portal, recuperá-los através do SDK ou encaminhá-los para o Application Insights se estiver ligado. A avaliação na cloud suporta todos os avaliadores pré-definidos curados pela Microsoft e os seus próprios avaliadores personalizados. Os avaliadores são geridos no catálogo de avaliadores com o mesmo âmbito de projeto e controlo de acesso baseado em funções.

Dica

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

Como funciona a avaliação na cloud

Para executar uma avaliação na cloud, cria-se uma definição de avaliação com o seu esquema de dados e critérios de teste (avaliadores), depois cria-se uma execução de avaliação. A execução executa cada avaliador com base nos seus dados e devolve resultados pontuados que pode consultar para conclusão.

A avaliação na cloud suporta os seguintes cenários:

Cenário Quando usar Tipo de fonte de dados Alvo
Avaliação do conjunto de dados Avalie respostas pré-computadas num ficheiro JSONL. jsonl —
Avaliação de conjuntos de dados CSV Avalie respostas pré-computadas num ficheiro CSV. csv —
Avaliação de alvos do modelo Fornecer consultas e gerar respostas a partir de um modelo em tempo de execução para avaliação. azure_ai_target_completions azure_ai_model
Avaliação do alvo do agente Fornecer consultas e gerar respostas por meio de um agente Foundry (seja por prompt ou alojado) durante o tempo de execução para avaliação. azure_ai_target_completions azure_ai_agent
Avaliação da resposta do agente Recuperar e avaliar as respostas dos agentes da Foundry por identificadores de resposta. azure_ai_responses —
Avaliação de traços Avalie as interações dos agentes já captadas no Application Insights por ID de traço. Use esta abordagem para agentes não-Foundry (LangChain e frameworks personalizados que cumprem registos baseados em OpenTelemetry). azure_ai_traces —
Avaliação de dados sintéticos (pré-visualização) Gerar consultas de teste sintéticas, enviá-las para um modelo ou agente e avaliar as respostas. azure_ai_synthetic_data_gen_preview azure_ai_model ou azure_ai_agent
Avaliação da equipa vermelha Execute testes adversários automatizados contra um modelo ou agente. azure_ai_red_team azure_ai_model ou azure_ai_agent

A maioria dos cenários requer dados de entrada. Pode fornecer dados de duas formas:

Tipo de fonte Descrição
file_id Consulte um conjunto de dados carregado por ID.
file_content Forneça os dados diretamente no pedido.

Cada avaliação requer um data_source_config que diga ao serviço que campos esperar nos seus dados:

  • custom — Define um item_schema com os nomes e tipos dos seus campos. Definido include_sample_schema como true ao usar um alvo, para que os avaliadores possam consultar as respostas geradas.
  • azure_ai_source — O esquema é inferido a partir do serviço. Defina "scenario" para "responses" avaliação de resposta do agente, "traces"avaliação de traços, "synthetic_data_gen_preview"avaliação de dados sintéticos (pré-visualização) ou "red_team" para red teaming.

Cada cenário requer avaliadores que definam os seus critérios de avaliação. Para orientações sobre a seleção de avaliadores, consulte avaliadores incorporados.

Pré-requisitos

Nota

Algumas funcionalidades de avaliação têm restrições regionais. Consulte as regiões suportadas para mais detalhes.

Introdução

Instala o SDK e configura o teu 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 os dados de entrada

A maioria dos cenários de avaliação requer dados de entrada. Pode fornecer dados de duas formas:

Carregue um ficheiro JSONL ou CSV para criar um conjunto de dados versionado no seu projeto Foundry. Os conjuntos de dados suportam versionamento e reutilização em múltiplas execuções de avaliação. Use esta abordagem para testes de produção e fluxos de trabalho CI/CD.

Prepare um ficheiro JSONL com um objeto JSON por linha contendo os campos de que os seus 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 ficheiro CSV com cabeçalhos de coluna que correspondam 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 teste, forneça os dados diretamente no pedido 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 "source" na configuração da sua fonte de dados ao criar uma execução. As secções de cenário que se seguem usam file_id por defeito.

Avaliação do conjunto de dados

Avaliar respostas pré-computadas num ficheiro JSONL usando o tipo de jsonl fonte de dados. Este cenário é útil quando já tem resultados do modelo e quer avaliar a sua qualidade.

Dica

Antes de começar, complete o Início e Prepare os dados de entrada.

Defina o esquema de dados e os avaliadores

Especifique o esquema que corresponde aos seus campos JSONL e selecione os avaliadores (critérios de teste) a executar. Use o data_mapping parâmetro para ligar campos dos seus dados de entrada aos parâmetros do avaliador com {{item.field}} sintaxe. Inclua data_mapping sempre com os campos de entrada exigidos para cada avaliador. Os nomes dos seus campos devem corresponder aos do seu ficheiro JSONL — por exemplo, se os seus dados tiverem "question" em vez de "query", use "{{item.question}}" no mapeamento. Para os parâmetros exigidos por avaliador, consulte avaliadores incorporados.

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 depois inicie uma execução com o seu 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 um exemplo completo executável, veja sample_evaluations_builtin_with_dataset_id.py em GitHub. Para verificar a conclusão e interpretar resultados, consulte Obter resultados.

Avaliação de conjuntos de dados CSV

Avalie respostas pré-computadas num ficheiro CSV usando o csv tipo de fonte de dados. Este cenário funciona da mesma forma que a avaliação de conjuntos de dados , mas aceita ficheiros CSV em vez de JSONL. Usa CSV quando os teus dados já estiverem em formato de folha de cálculo ou tabular.

Dica

Antes de começar, complete o Início e Prepare os dados de entrada.

Preparar um ficheiro CSV

Crie um ficheiro CSV com cabeçalhos de coluna que correspondam aos campos que os seus 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

Carrega o ficheiro CSV como um conjunto de dados e depois cria uma avaliação usando o tipo de csv fonte de dados. A definição do esquema e a configuração do avaliador são as mesmas que nas avaliações JSONL — a única diferença está na "type": "csv" 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, veja Obter resultados.

Avaliação de alvos do modelo

Envie consultas para um modelo implementado em tempo de execução e avalie as respostas usando o azure_ai_target_completions tipo de fonte de dados com um azure_ai_model alvo. Os seus dados de entrada contêm consultas; O modelo gera respostas que são depois avaliadas.

Dica

Antes de começar, complete o Início e Prepare os dados de entrada.

Defina o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas para o modelo. Usa {{item.query}} para referenciar campos a partir dos teus dados de entrada. Especifique o modelo a 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}} in data_mapping para referenciar a saída do modelo. Usa {{item.field}} para referenciar campos a partir dos teus 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 um exemplo completo executável, veja sample_model_evaluation.py em GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Dica

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

Avaliação do alvo do agente

Envie consultas a um agente Foundry em tempo de execução e avalie as respostas usando o azure_ai_target_completions tipo de fonte de dados com um azure_ai_agent alvo. Este cenário funciona tanto para agentes rápidos como agentes alojados.

Dica

Antes de começar, complete o Início e Prepare os dados de entrada.

Dica

Os agentes alojados que utilizam o protocolo de respostas trabalham com os mesmos exemplos de código apresentados aqui. Para agentes hospedados que utilizam o protocolo de invocações, o input_messages formato é diferente. Consulte o protocolo de invocações de agentes hospedados para mais detalhes.

Defina o modelo de mensagem e o destino

O input_messages modelo controla como as consultas são enviadas ao agente. Usa {{item.query}} para referenciar campos a partir dos teus dados de entrada. Especifique o agente a avaliar 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, use {{sample.*}} variáveis em data_mapping para referenciar a saída do agente:

Variável Descrição Utilização para
{{sample.output_text}} A resposta do agente em texto simples. Avaliadores que esperam uma resposta em cadeia (por exemplo, coherence, violence).
{{sample.output_items}} A saída JSON estruturada do agente, incluindo chamadas de ferramenta. Avaliadores que necessitam de contexto completo de interação (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 agentes, como task_adherence, usam este contexto para uma pontuação mais precisa. Para detalhes sobre formatação de consultas, 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 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 um exemplo completo executável, veja sample_agent_evaluation.py em GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Protocolo de invocações de agentes hospedados

Agentes alojados que utilizam o protocolo de invocações suportam o mesmo azure_ai_agent tipo de alvo, mas utilizam um formato livre input_messages . Em vez do formato estruturado do modelo, forneça um objeto JSON que se mapeie diretamente para o corpo do pedido do /invocations agente. Use {{item.*}} marcadores de posição para substituir campos a partir dos seus dados de entrada.

Se um agente hospedado suportar tanto os protocolos de resposta como de invocação, o serviço passa a usar por defeito o protocolo de invocações.

Defina 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 configuração do avaliador e os mapeamentos de dados são os mesmos que para a avaliação rápida do agente. 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

Recuperar e avaliar as respostas dos agentes Foundry por IDs de resposta usando o azure_ai_responses tipo de fonte de dados. Use este cenário para avaliar interações específicas com agentes depois de ocorrerem.

Dica

Antes de começar, conclua Get started.

Um ID de resposta é um identificador único devolvido cada vez que um agente da Foundry gera uma resposta. Pode recolher IDs de resposta das interações com agentes usando a API de Respostas ou a partir dos registos de rastreamento da sua aplicação. Forneça os IDs em linha como conteúdo do ficheiro, ou carregue-os como um conjunto de dados (ver Preparar dados de entrada).

Recolha IDs de resposta

Cada chamada à API de Respostas devolve um objeto de resposta com um campo único id . Recolha estes IDs das interações da sua aplicação, ou gere-os 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

Também pode recolher IDs de resposta das interações com agentes nos registos de rastreamento ou pipeline de monitorização da sua aplicação. Cada ID de resposta identifica de forma única 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 um exemplo completo executável, veja sample_agent_response_evaluation.py em GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Avaliação de rastreamento

Avalie interações com agentes que já foram captadas em Application Insights. Use o tipo de fonte de dados azure_ai_traces. Este cenário é útil para a avaliação pós-implementação do tráfego real de produção — seleciona traços do seu pipeline de monitorização e executa avaliadores contra eles sem repetir quaisquer pedidos.

Importante

A avaliação de traços é a abordagem recomendada para avaliar agentes não construídos com o Microsoft Foundry Agent Service — incluindo LangChain e frameworks personalizados. Desde que o seu agente emita spans OpenTelemetry de acordo com as convenções semânticas GenAI para o Application Insights, a avaliação de traços pode analisar as suas interações usando os mesmos avaliadores disponíveis para agentes Foundry.

A avaliação de traços suporta dois modos:

  • Por IDs de rastreamento — Avalie interações específicas entre agentes fornecendo os seus operation_Id valores a partir do Application Insights.
  • Por filtro de agente — Descobre e avalia automaticamente os vestígios recentes de um determinado agente, sem recolher manualmente os identificadores dos traços.

Dica

Antes de começar, conclua Get started. Este cenário também requer um recurso Application Insights ligado ao seu projeto Foundry.

Requisitos de dados de rastreio

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

São utilizados os seguintes atributos de amplitude:

Atributo Obrigató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 agente Identificador único do agente (formato: agent-name:version).
gen_ai.agent.name Para o modo de filtro agente Nome de agente legível por humanos.
gen_ai.input.messages Para avaliadores, entradas de consulta Array de mensagens JSON de entrada seguindo o formato de mensagem das convenções semânticas 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 avaliadores: entradas de consulta Array JSON de mensagens de saída geradas pelo modelo. Todas as mensagens de saída correspondem a response. Se a saída também contiver type: tool_call ou type: tool_result, mapeia para tool_calls
gen_ai.tool.definitions Opcional Array JSON de esquemas de ferramentas disponíveis para o agente. Se ausente, o serviço tenta inferir definições de ferramentas a partir de mensagens de chamada de ferramenta, 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 em falta, os avaliadores de qualidade (coerência, fluência, relevância, resolução de intenção) devolverão score=None. Os avaliadores de segurança (violência, autoagressão, sexualidade, ódio/injustiça) ainda podem produzir pontuações com dados parciais, mas podem não produzir resultados significativos.

Para agentes Python construídos com o SDK do Azure AI Agent Server, adicione a extensão [tracing] para permitir a emissão automática de spans:

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

Pré-requisitos para a avaliação de traços

Para além dos pré-requisitos gerais, a avaliação de traços exige:

  • Um recurso de Application Insights ligado ao seu projeto Foundry. Veja Configurar Rastreio em Microsoft Foundry.
  • A identidade gerida do projeto deve ter o papel Leitor de Log Analytics tanto no recurso Application Insights como no seu espaço de trabalho Log Analytics associado.
  • O pacote azure-monitor-query Python (só necessário se recolheres IDs de rastreio manualmente).
pip install "azure-ai-projects>=2.0.0" azure-monitor-query

Defina estas variáveis de ambiente:

  • APPINSIGHTS_RESOURCE_ID — O ID do recurso 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 traços. Formato: agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Opcional) Número de horas retróativas ao consultar os rastreamentos. Por padrão, define-se para 1.

Opção A: Avaliar por filtro de agente

A abordagem mais simples — deixe o serviço descobrir e avaliar automaticamente vestígios recentes para um agente específico. Não é necessária a recolha manual de ID de rastreamento.

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 os intervalos pelo atributo gen_ai.agent.id, amostra até max_traces IDs de rastreamento únicos e avalia todos os intervalos desses rastreamentos.

Opção B: Avaliar por IDs de rastreamento

Para maior controlo, recolha IDs de rastreio específicos do Application Insights e avalie-os. Isto é útil quando se quer avaliar um conjunto selecionado de interações (por exemplo, traços sinalizados por alertas ou amostrados para revisão de qualidade).

Recolha IDs de rastreio a partir do Application Insights

Consulte o Application Insights para operation_Id obter valores dos vestígios do seu agente. Cada um 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 executar com IDs de rastreio

# 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 vestígios, o serviço extrai automaticamente os dados de conversa dos atributos do OpenTelemetry span. Use estes nomes de campo diretamente em data_mapping (sem os prefixos item. ou sample. usados noutros cenários):

Variável Atributo fonte Descrição
{{item.query}} gen_ai.input.messages (funções de utilizador/sistema) A consulta do utilizador extraída do rastreio.
{{item.response}} gen_ai.input.messages (funções de assistente/ferramenta) + gen_ai.output.messages A resposta do agente extraída do rastreio.
{{item.tool_definitions}} gen_ai.tool.definitions Esquemas de ferramentas disponíveis para o agente. Apenas necessário para avaliadores que lidam com ferramentas
{{item.tool_calls}} Extraído de mensagens de 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 de ferramentas 
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 um exemplo completo executável, veja sample_evaluations_builtin_with_traces.py em GitHub. Para verificar a conclusão e interpretar os resultados, consulte Obter resultados.

Avaliação de dados sintéticos (pré-visualização)

Gerar consultas de teste sintéticas, enviá-las para um modelo implementado ou agente Foundry, e avaliar as respostas usando o tipo de azure_ai_synthetic_data_gen_preview fonte de dados. Use este cenário quando não tem um conjunto de dados de teste — o serviço gera consultas com base num prompt que fornece (e/ou nas instruções do agente), executa-as contra o seu alvo e avalia as respostas.

Dica

Antes de começar, conclua Get started.

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

  1. O serviço gera consultas sintéticas baseadas no seu prompt e em ficheiros de dados de inicialização opcionais.
  2. Cada consulta é enviada ao alvo especificado (modelo ou agente) para gerar uma resposta.
  3. Os avaliadores avaliam cada resposta usando a consulta e resposta geradas.
  4. As consultas geradas são armazenadas como um conjunto de dados no seu projeto para reutilização.

Parâmetros

Parâmetro Obrigatório Descrição
samples_count Sim Número máximo de consultas de teste sintéticas a gerar.
model_deployment_name Sim Implementação de modelos para gerar consultas sintéticas. Apenas modelos com capacidade Responses API são suportados. Para disponibilidade, consulte Disponibilidade de regiões da API de Respostas.
prompt Não Instruções que descrevem o tipo de consultas a gerar. Opcional quando o agente alvo tem instruções configuradas.
output_dataset_name Não Nome para o conjunto de dados de saída onde as consultas geradas são armazenadas. Se não for fornecido, o serviço gera automaticamente um nome.
sources Não Ficheiros de dados de sementes (por ID de ficheiro) para melhorar a relevância das consultas geradas. Atualmente, apenas um ficheiro é suportado.

Configurar avaliadores e mapeamentos de dados

O gerador de dados sintéticos produz consultas no campo {{item.query}}. O alvo gera respostas disponíveis em {{sample.output_text}}. Mapeie estes campos para os 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

Gerar consultas sintéticas e avaliar 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,
)

Pode, opcionalmente, adicionar um prompt do sistema para moldar o comportamento do modelo-alvo. Quando usar input_messages com geração de dados sintéticos, inclua apenas system mensagens de função — o serviço fornece automaticamente as consultas geradas como mensagens do utilizador.

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

Agente alvo

Gerar consultas sintéticas e avaliar um agente da 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 o ID do conjunto de dados gerado, que pode usar para recuperar ou reutilizar os dados sintéticos.

Obtenha resultados

Após a conclusão da avaliação, recolha os resultados pontuados e reveja-os no portal ou programaticamente.

Inquérito para resultados

As execuções de avaliação são assíncronas. Verifique continuamente o estado da execução até que esta termine, depois 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 apresentam o seguinte esquema:

  • Rótulo: um rótulo binário de "passar" ou "falhar", semelhante à saída de um teste unitário. Use este resultado para facilitar comparações entre avaliadores.
  • Pontuação: uma pontuação da escala natural de cada avaliador. Alguns avaliadores utilizam uma rubrica detalhada, avaliando numa escala de 5 pontos (avaliadores de qualidade) ou numa escala de 7 pontos (avaliadores de segurança de conteúdos). Outros, como os avaliadores de similaridade textual, usam pontuações F1, que são flutuantes entre 0 e 1. Qualquer "pontuação" não binária é binarizada para "passar" ou "reprovar" no campo "label" com base no "limiar".
  • Limiar: quaisquer pontuações não-binárias são binarizadas para "passar" ou "falhar" com base num limiar padrão, que o utilizador pode ultrapassar na experiência SDK.
  • Razão: Para melhorar a inteligibilidade, todos os avaliadores de juízes LLM também produzem um campo de raciocínio para explicar porque é atribuída uma certa pontuação.
  • Detalhes: (opcional) Para alguns avaliadores, como o tool_call_accuracy, pode haver um campo "detalhes" ou flags que contêm informação adicional para ajudar os utilizadores a depurar as suas aplicações.

Exemplo de saída (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
}

Exemplo de saída (agregado)

Para os resultados agregados de múltiplos exemplos de dados (um conjunto de dados), a média dos exemplos que têm "aprovação" constitui a taxa de aprovação desse 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
    }
  ]
}

Resolução de problemas

Trabalho em execução há muito tempo

O seu trabalho de avaliação pode permanecer no estado em Execução por um período prolongado. Isto acontece normalmente quando a implementação do modelo Azure OpenAI não tem capacidade suficiente, levando o serviço a tentar novamente os pedidos.

Resolução:

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

Erros de autenticação

Se receber um 401 Unauthorized ou 403 Forbidden erro, verifique que:

  • O teu DefaultAzureCredential está configurado corretamente (executa az login se usares CLI do Azure).
  • A tua conta tem o papel Azure AI User no projeto Foundry.
  • A URL do endpoint do projeto está correta e inclui tanto os nomes da conta como do projeto.

Erros de formato de dados

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

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

Erros de limite de taxa

As criações executadas pela avaliação são limitadas por taxas ao nível do tenant, subscrição e projeto. Se receber uma 429 Too Many Requests resposta:

  • Verifique o retry-after cabeçalho na resposta para o tempo de espera recomendado.
  • Consulte o corpo de resposta para detalhes do limite de taxa.
  • Usa o recuo exponencial ao tentar novamente pedidos falhados.

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

  • Reduza o tamanho do seu conjunto de dados de avaliação ou divida-o em lotes mais pequenos.
  • Aumente a quota de tokens por minuto (TPM) para a implementação do seu modelo no portal Azure.

Erros na ferramenta avaliadora de agentes

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

  • Verifique as ferramentas suportadas para avaliadores de agentes.
  • Como solução alternativa, envolva ferramentas não suportadas como ferramentas de função definidas pelo utilizador para que o avaliador as possa avaliar.

Conteúdo relacionado

  • Last updated on