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

Neste artigo, você aprenderá a executar avaliações na nuvem para teste 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

Uma avaliação de nuvem tem três etapas:

  1. Defina o que avaliar. Descreva sua forma de dados (o data_source_config) e os avaliadores (critérios de teste) que a pontuam.
  2. Crie a avaliação. Envie a definição usando openai_client.evals.create().
  3. Execute-o e leia os resultados. Inicie uma execução usando openai_client.evals.runs.create(), faça consultas até que ela seja concluída e leia os resultados com pontuação. Consulte Obter resultados para o esquema de resultados.

O restante desta seção percorre as entradas até a etapa 1: escolha um cenário e escolha os avaliadores.

Escolha o ponto de partida

Conjunto de dados existente

Use esse caminho quando você já tiver consultas e respostas coletadas em um arquivo (ou consultas mais a verdade dos fatos) e quiser que elas sejam marcadas pelo Foundry. O JSONL oferece suporte tanto a linhas em nível de turno quanto a entradas em nível de conversa; o CSV aceita apenas nível de turno.

Cenário Quando usar Tipo de fonte de dados
Avaliação do conjunto de dados por turno Cada linha corresponde a um par de query/response, opcionalmente, com context ou ground_truth. jsonl Ou csv
Avaliação do conjunto de dados no nível da conversa (versão prévia) Cada linha é uma conversa expressa como uma messages matriz. jsonl

Dados no Foundry ou Application Insights

Use esse caminho quando o agente já estiver em execução e você quiser avaliar o que realmente aconteceu. Em vez de mover os dados para fora, você direciona o Foundry aos dados onde eles já estão armazenados — pelo ID de resposta do Foundry ou pelo ID de rastreamento ou de conversa do Application Insights.

Cenário Quando usar Tipo de fonte de dados
Avaliação da resposta do agente Seu agente é executado no Foundry, e você tem IDs das respostas para atribuir pontuação. azure_ai_responses
Avaliação de rastreamento por turno (prévia) Seu agente emite rastreamentos do OpenTelemetry no Application Insights, incluindo os de frameworks que não são do Foundry, como LangChain, ou de agentes personalizados instrumentados com OpenTelemetry. Cada rastreamento recebe uma pontuação de forma independente. azure_ai_trace_data_source_preview
Avaliação de rastreamento em nível de conversa (versão prévia) As mesmas fontes de rastreamento, mas avalie conversas completas — por ID da conversa ou por filtro de agente com amostragem. azure_ai_trace_data_source_preview

Entradas sem respostas

Use este caminho quando tiver os dados de entrada, mas ainda não tiver respostas. O Foundry gera respostas em relação a um modelo ou agente de destino no momento da avaliação e, então, as pontua. Escolha uma linha com base em se sua entrada são consultas (enviadas como turnos individuais) ou descrições de cenário (usadas para conduzir uma interação no nível da conversa).

Cenário Quando usar Fonte/destino de dados
Conclusões de destino do modelo Você tem consultas e deseja avaliar as respostas de uma implantação de modelo. azure_ai_target_completions → azure_ai_model
Conclusões no destino do agente Você tem consultas e deseja avaliar as respostas de um agente do Foundry. azure_ai_target_completions → azure_ai_agent
Simulação de conversa (versão prévia) Você tem descrições de cenário (sem consultas); o Foundry simula um usuário conduzindo uma interação no nível da conversa com o agente. azure_ai_target_completions → azure_ai_agent

Ainda não há dados

Use este caminho ao criar um novo modelo ou agente e ainda não tiver coletado nenhum dado de entrada. O Foundry gera os dados de teste do zero — escolha consultas sintéticas para uma cobertura ampla da qualidade ou prompts adversariais para testes de segurança.

Cenário Quando usar Fonte/destino de dados
Avaliação de dados sintéticos (versão prévia) Você quer uma cobertura de qualidade maior do que a que você escreveria manualmente. Foundry gera consultas de teste, envia-as para o alvo e avalia as respostas. azure_ai_synthetic_data_gen_preview azure_ai_model→ ouazure_ai_agent
Avaliação da equipe vermelha Você quer testes adversariais automatizados — o Foundry gera prompts de jailbreak e de conteúdo nocivo e avalia como o sistema-alvo responde. azure_ai_red_team azure_ai_model→ ouazure_ai_agent

Escolher avaliadores

Cada cenário associa avaliadores a campos em seus dados por meio de mapeamentos de coluna. Os campos disponíveis dependem da fonte de dados. Cenários de conjunto de dados expõem seus campos de item personalizados, enquanto cenários gerados por destino também expõem a resposta do modelo ou agente por meio de um esquema de exemplo. As subseções de cada cenário, mais adiante neste artigo, mostram os mapeamentos das colunas para cada caso.

Para obter uma visão geral dos avaliadores disponíveis e como escolhê-los, consulte avaliadores internos e avaliadores personalizados.

Pré-requisitos

  • Um projeto do Foundry.

  • Uma implantação Azure OpenAI com um modelo GPT que dá suporte à conclusão do chat (por exemplo, gpt-5-mini).

  • função de usuário do Foundry no projeto Foundry.

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • Opcionalmente, você pode usar sua própria conta de armazenamento para executar avaliações.

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.2.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
openai_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 ou cenários que exigem dados embutidos, como avaliação de resposta do agente, forneça dados diretamente na solicitação de avaliação usando file_content. Para avaliações de resposta do agente, file_content é o único tipo de origem com suporte.

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.

Suporte ao tipo de origem por cenário

Nem todos os cenários dão suporte a ambos os tipos de origem. A matriz a seguir mostra com quais tipos de origem cada cenário é compatível.

Cenário file_id file_content
Conjunto de dados (jsonl) Sim Sim
CSV (csv) Sim Sim
Modelo ou alvo do agente Sim Sim
Resposta do agente (azure_ai_responses) Não Sim
Rastreamento (azure_ai_traces) N/A N/A
Dados sintéticos (versão prévia) N/A N/A

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": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "model": 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 no conjunto de dados.

# Create the evaluation
eval_object = openai_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 = openai_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. Em seguida, 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. A única diferença está na fonte de dados "type": "csv".

# 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": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = openai_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 = openai_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

Enviar consultas para um modelo implantado em runtime. Avalie as respostas usando a fonte de dados do tipo azure_ai_target_completions com um destino azure_ai_model. Seus dados de entrada contêm consultas. O modelo gera respostas, que você avalia.

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": {
            "model": 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 = openai_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 = openai_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, use o mesmo código.

Avaliação do alvo do agente

Envie consultas a um agente do Foundry em tempo de execução e avalie as respostas usando o tipo de fonte de dados azure_ai_target_completions com um destino azure_ai_agent. 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 gerar respostas em tempo de execução, use variáveis {{sample.*}} em data_mapping para referenciar a saída do agente:

Variável Descrição Usar 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 ferramentas. 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": {
            "model": 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": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Criar avaliação e executar

eval_object = openai_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 = openai_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 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 = openai_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 = openai_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 utilizados na 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 as IDs diretamente no conteúdo do arquivo.

Importante

As avaliações de respostas do agente (azure_ai_responses) aceitam apenas file_content para fornecer IDs de resposta. O tipo de origem file_id não é compatível e retorna o erro 400 Bad Request.

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 = openai_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 das interações do agente nos logs de rastreamento do seu aplicativo ou no pipeline de monitoramento. Cada ID de resposta identifica exclusivamente uma resposta armazenada que o serviço de avaliação pode recuperar.

Criar 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": {
            "model": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = openai_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 = openai_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 rastros (versão preliminar)

Avalie as interações do agente que o Application Insights já capturou. 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 real. Você seleciona rastreamentos do seu pipeline de monitoramento e executa avaliadores neles sem reexecutar 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 spans OpenTelemetry seguindo as convenções semânticas do GenAI para o Application Insights, a avaliação de rastreamento pode analisar suas interações usando os mesmos avaliadores disponíveis para agentes Foundry.

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

  • Por IDs de rastreamento – avalie interações específicas do agente fornecendo seus valores operation_Id 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.

Amostragem inteligente

A avaliação de traces oferece suporte à amostragem inteligente, que seleciona um subconjunto representativo de traces a serem avaliados, em vez de avaliar cada trace capturado. Habilite esse recurso ativando o botão Intelligent sampling no portal Foundry ao configurar uma execução de avaliação de rastreamento. A amostragem inteligente reduz o custo da avaliação, ao mesmo tempo que preserva a diversidade dos rastros — garantindo que casos de borda, caminhos de erro e diferentes padrões de conversa sejam incluídos no conjunto avaliado.

Como funciona a amostragem inteligente

O algoritmo de amostragem usa uma abordagem de diversidade do tipo MinHash "farthest-first", executada em vários estágios:

  1. Eliminação exata de duplicação – remove rastreamentos duplicados do pool.
  2. Filtros rígidos – remove sessões interrompidas, rastreamentos truncados e chamadas de ferramentas malformadas que não são adequadas para avaliação.
  3. Agregação – Combina sinais de nível de rastreamento em uma representação unificada.
  4. Seleção mais distante do MinHash – calcula hashes sensíveis à localidade (assinaturas MinHash) do texto do usuário para estimar a similaridade entre rastreamentos e, em seguida, seleciona iterativamente o rastreamento mais diferente do pool restante. Cada nova seleção maximiza a distância em relação a todos os rastreamentos selecionados anteriormente.

Essa abordagem produz uma diversidade léxica significativamente maior e uma cobertura de vocabulário mais ampla em comparação com a amostragem aleatória, o que significa que o conjunto avaliado representa melhor toda a gama de interações do agente - incluindo casos raros, difíceis e novos que a amostragem aleatória tende a perder.

A amostragem inteligente é particularmente eficaz para:

  • Avaliação e parâmetros de comparação – maximiza a cobertura da distribuição de entrada para que as pontuações de avaliação reflitam a diversidade do mundo real.
  • Geração de rubricas - produz rubricas mais focadas e acionáveis, expondo diversos padrões de conversa.
  • Configuração do conjunto de dados do Finetuning – seleciona rastreamentos que ajudam os modelos a aprender com mais eficiência.

O algoritmo é executado inteiramente na computação local sem chamadas de API extras, portanto, ele não incorre em custos extras de inferência de modelo além da própria avaliação.

Exemplo de amostragem inteligente

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# Compute time window in unix seconds
# Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
now_unix = int(time.time())
end_time = now_unix + 600
start_time = now_unix - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

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 type: tool_call ou type: tool_result, ela será mapeada para tool_calls.
gen_ai.tool.definitions Opcional Matriz JSON de esquemas de ferramentas disponíveis para o agente. Se estiver ausente, o serviço tentará 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 ausentes, os avaliadores de qualidade (coerência, fluência, relevância, resolução da intenção) retornam 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 os agentes Python criados com o SDK do Servidor de Agente de IA do Azure, adicione o [tracing] extra para habilitar a emissão automática de intervalos:

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:

pip install "azure-ai-projects>=2.2.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 = openai_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 = openai_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 intervalos por meio do atributo gen_ai.agent.id, gera amostras até max_traces IDs de rastreamento únicos e avalia todos os intervalos desses rastreamentos.

Opção B: Avaliar por IDs de rastreamento

Para obter mais controle, colete IDs de rastreamento específicas do Application Insights e avalie-as. Esse método é útil quando você deseja avaliar um conjunto selecionado de interações, como rastros 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 dos 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 = openai_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 = openai_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 (funções de assistente/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": {
            "model": 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": {
            "model": 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)

Use o tipo de fonte de dados azure_ai_synthetic_data_gen_preview para gerar consultas de teste sintéticas, enviá-las para um modelo implantado ou agente do Foundry e avaliar as respostas. 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 no 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 você não fornecer um nome, o serviço gerará um 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": {
            "model": 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 = openai_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 = openai_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 = openai_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.

Avaliação em nível de conversa (prévia)

Avalie conversas completas para avaliar a qualidade do agente em interações inteiras do usuário - não apenas respostas individuais. Use a avaliação no nível da conversa para identificar problemas de qualidade, como resolução incompleta de tarefas, frustração do usuário e regressões em chamadas de ferramentas que a avaliação no nível do rodada não detecta.

Por exemplo, considere um agente de suporte em que o usuário vai ficando frustrado ao longo de várias interações:

Turno 1 — Usuário: "Preciso redefinir minha senha." Agente: "Encontrei sua conta. Enviarei um link de redefinição."

Turno 2 — Usuário: "Não recebi o e-mail." Atendente: "Reenviei o link." Verifique o spam."

Turno 3 — Usuário: "Ainda nada. Você pode simplesmente redefini-lo diretamente?" Agente: "Enviei outro link de redefinição."

Um avaliador em nível de turno atribui pontuação apenas à última resposta — que é educada e adota uma ação —, por isso ela recebe uma boa pontuação. Um avaliador em nível de conversa, que classifica a satisfação do cliente ao longo de toda a conversa, sinaliza que o agente repetiu a mesma ação malsucedida três vezes sem tentar uma alternativa, sem resolver o problema do usuário.

A avaliação em nível de conversa difere da avaliação em nível de turno de várias maneiras:

Aspecto De nível de rodada Nível de conversa
Âmbito Pares de consulta-resposta individuais Conversas completas com múltiplas interações
Métricas Qualidade e segurança de cada resposta Resultados em nível de conversa e satisfação do usuário
Formato dos dados JSONL com campos query e response JSONL com matriz messages que contém a conversa completa
Caso de uso Testando respostas de modelo individual Testando experiências completas com agentes

A avaliação em nível de conversa dá suporte a quatro opções de fonte de dados:

Opção Quando usar Tipo de fonte de dados
De conjunto de dados ou em linha Você tem rastros locais de conversa ou dados de teste jsonl com file_id ou file_content
Por ID da conversa Você deseja avaliar conversas específicas do App Insights azure_ai_trace_data_source_preview por trace_source
Por filtro de agente com amostragem Você deseja avaliar a qualidade geral do agente em todo o tráfego de produção amostrado azure_ai_trace_data_source_preview por trace_source
Conversas simuladas Você deseja gerar conversas de teste sintéticas azure_ai_target_completions por conversation_gen_preview

Escolher um nível de avaliação

O parâmetro evaluation_level da execução determina se os avaliadores avaliam turnos individuais ou conversas completas:

Valor Behavior
"turn" Os avaliadores pontuam cada turno de forma independente.
"conversation" Os avaliadores pontuam toda a conversa como um todo.
(omitido) O padrão é "turn".

Importante

Compatibilidade do avaliador: cada avaliador dá suporte a níveis de avaliação específicos. Verifique o campo de supported_evaluation_levels avaliador no catálogo de avaliadores.

  • Avaliadores apenas de turno (por exemplo, fluency, relevance) não podem ser usados com evaluation_level="conversation".
  • Atualmente, todos os avaliadores de nível de conversa oferecem suporte aos níveis "turn" e "conversation".

Erros comuns

Erro Cause Solução
Nível de avaliação incompatível Usando evaluation_level="conversation" com um avaliador apenas de rodada Remova o avaliador apenas de rodada ou altere para evaluation_level="turn"

Preparar dados de conversa

Crie um arquivo JSONL em que cada linha contenha uma conversa completa no messages campo. Cada mensagem deve incluir um role (usuário, assistente ou sistema) e content. Para obter um exemplo completo, consulte os exemplos de avaliação de conversação no SDK:

 {"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": "Your current balance is $1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}]}

Você também pode incluir definições de ferramentas e chamadas de ferramenta se o agente usar ferramentas:

{"messages": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris"}]}
{"messages": [{"role": "user", "content": "How do I reverse a string in Python?"}, {"role": "assistant", "content": "You can reverse a string in Python by using slicing: string[::-1]"}]}
{"messages": [{"role": "user", "content": "What are the main causes of climate change?"}, {"role": "assistant", "content": "The main causes of climate change are the increase in greenhouse gases in the atmosphere, primarily due to human activities such as burning fossil fuels and deforestation."}]}
{"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_account_balance", "arguments": "{\"account_id\": \"ACCT-7890\"}"}}]}, {"role": "tool", "tool_call_id": "call_abc123", "content": "{ \"balance\": 1234.56, \"currency\": \"USD\" }"}, {"role": "assistant", "content": "Your current balance is 1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}], "tool_definitions": [{"name": "get_account_balance", "description": "Retrieves the current balance for a customer account", "parameters": {"type": "object", "properties": {"account_id": {"type": "string"}}, "required": ["account_id"]}}]}
{"messages": [{"role": "user", "content": "Explain the theory of relativity in simple terms."}, {"role": "assistant", "content": "Einstein's theory of relativity shows that space and time are interconnected and relative to the observer's frame of reference."}]}
{"messages": [{"role": "user", "content": "What's the weather in Seattle?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_002", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Seattle, WA\"}"}}]}, {"role": "tool", "tool_call_id": "call_002", "content": "{ \"temperature\": 55, \"condition\": \"Cloudy\" }"}, {"role": "assistant", "content": "It's currently 55F and cloudy in Seattle."}], "tool_definitions": [{"name": "get_weather", "description": "Get the current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]}
{"messages": [{"role": "user", "content": "What is the tallest mountain in the world?"}, {"role": "assistant", "content": "Mount Everest is the tallest mountain in the world."}]}
{"messages": [{"role": "user", "content": "Is 4 x 2 = 16?"}, {"role": "assistant", "content": "No, 4 x 2 = 8."}]}
{"messages": [{"role": "user", "content": "What is the best Italian desert?"}, {"role": "assistant", "content": "Tiramisu is a popular Italian dessert."}]}
{"messages": [{"role": "user", "content": "What is the chemical formula for water?"}, {"role": "assistant", "content": "The chemical formula for water is H2O."}]}

Definir o esquema de dados e os avaliadores

Especifique o esquema para seus dados de conversa, "mensagens" e selecione os avaliadores projetados para avaliação em nível de conversa. Os avaliadores no nível da conversa avaliam toda a interação, em vez de cada turno individual.

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

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
                "tool_definitions": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Criar avaliação e executar

Preparação: baixe sample_data_multiturn_conversations.jsonl

from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileID,
)

# Upload conversation data
data_id = project_client.datasets.upload_file(
    name="multiturn-conversation-data",
    version="1",
    file_path="./sample_data_multiturn_conversations.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run with evaluation_level set to "conversation"
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="multiturn-conversation-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
    extra_body={"evaluation_level": "conversation"},
)

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

Avaliar conversas pelo ID a partir de rastreamentos

Avalie conversas específicas do Application Insights fornecendo suas IDs de conversa. Use esta opção para identificar a causa raiz de problemas ou verificar as correções em interações específicas. Por exemplo, você pode investigar uma conversa sinalizada por um alerta ou verificar uma correção para um problema conhecido.

Onde encontrar IDs de conversa

Encontre IDs de conversa em:

  • IU de logs de rastreamento do Application Insights — Navegue para rastreamentos interessantes e localize o campo conversation_id nos detalhes do rastreamento.
  • Saída de log do aplicativo – se você definir conversation_id explicitamente ao criar respostas do agente, recupere-a de seus logs.
  • Contexto de rastreamento OpenTelemetry — O conversation_id também pode ser derivado do cabeçalho traceparent se o agente usar a propagação padrão do contexto de rastreamento.

Nota

As definições de ferramenta são recuperadas automaticamente dos rastreamentos ou consultadas do registro do agente. Você não precisa fornecê-los na solicitação.

Parâmetros para pesquisa de ID de conversa

Parâmetro Necessário Descrição
conversation_ids Sim Matriz de IDs de conversa a serem avaliadas.
lookback_hours Não Horas para pesquisar retroativamente a partir de end_time. O valor padrão é sete dias (168 horas).
end_time Não Fim da janela de pesquisa (formato ISO 8601). Usa como padrão a hora atual. 
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

Nota

  • A ingestão de dados do Application Insights pode causar um atraso entre quando os rastreamentos são gerados e quando eles estão disponíveis para avaliação. Se a consulta não encontrar rastreamentos, aguarde alguns minutos e tente novamente.
  • O período retrospectivo máximo é de 7 dias (168 horas). Para acessar rastreamentos mais antigos, use start_time e end_time dentro dos limites de retenção do App Insights.

Avaliar conversas amostradas por filtro de agente

Avalie um conjunto de conversas de exemplo do Application Insights filtrando o nome do agente. Use essa opção para avaliar a qualidade geral do agente em todo o tráfego de produção. Por exemplo, execute avaliações regulares de qualidade ou monitore a degradação da qualidade na produção.

O agente especificado para filtragem pode fazer parte de uma conversa com vários agentes. O filtro corresponde a qualquer conversa em que o agente participou.

Nota

As definições de ferramenta são recuperadas automaticamente dos rastreamentos ou consultadas do registro do agente. Você não precisa fornecê-los na solicitação.

Campos de identidade do agente

Especifique o agente a ser filtrado usando um destes formatos:

Formato Example Descrição
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Dois campos separados. Se agent_version for omitido, use a versão mais recente.
agent_id "agent_id": "my-agent:1" Cadeia de caracteres única no formato "name:version".

Estratégias de filtro

Strategy Descrição
random_sampling (Padrão) Amostra aleatória uniforme de até conversas max_traces.
smart_filtering Heurística gerenciada pelo serviço que prioriza rastros "interessantes": conversas com possíveis problemas, casos de borda ou anomalias.

Parâmetros

Parâmetro Necessário Descrição
agent_name Sim O nome do agente pelo qual filtrar rastreamentos.
agent_version Não A versão do agente. Se não for especificado, usa a versão mais recente.
agent_id Não Alternativa a agent_name + agent_version. Cadeia de caracteres única no formato "name:version".
start_time Sim Início da janela de tempo (segundos de época do Unix, UTC).
end_time Sim Fim da janela de tempo (segundos de época unix, UTC). Adicione uma margem de mais de 600 segundos para evitar atrasos na ingestão.
max_traces Não Número máximo de conversas a serem selecionadas como amostra. O valor padrão é 1,000.
filter_strategy Não "random_sampling" (padrão) ou "smart_filtering" (heurística gerenciada pelo serviço que favorece rastreamentos interessantes).

Importante

A janela de tempo (end_time - start_time) deve ser de pelo menos 15 minutos (900 segundos). Esse requisito existe porque as consultas em nível de conversa aplicam um buffer de inatividade de 5 minutos em cada extremidade para evitar conversas parciais.

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

Nota

O período de tempo de consulta do App Insights está atualmente limitado a um máximo de 7 dias (168 horas). Você não pode acessar rastreamentos com mais de 7 dias sem informar explicitamente start_time e end_time, dentro dos limites de retenção do App Insights.

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

Simulação de conversa

Gere conversas simuladas a partir de descrições de cenário e avalie-as no nível da conversa. Use esse cenário para testar o comportamento do agente em situações controladas antes da implantação. O serviço gera conversas realistas com base em suas descrições de cenário e, em seguida, as avalia.

Essa abordagem é útil para:

  • Teste de pré-implantação: validar o comportamento do agente em diversos cenários sem tráfego real do usuário.
  • Cobertura de casos extremos: cenários de teste que raramente ocorrem naturalmente, mas que são importantes de serem tratados adequadamente.
  • Teste de regressão: verifique se as atualizações do agente não prejudicam o desempenho em cenários conhecidos.
  • Teste em escala: gere muitas conversas rapidamente para testar sob estresse as capacidades do agente.

Como funciona a simulação de conversa

  1. Você fornece um conjunto de dados de descrições de cenário – cada linha descreve uma situação que o usuário simulado tenta realizar.
  2. O serviço usa um modelo de simulador para desempenhar a função do usuário, interagindo com seu agente com base no cenário.
  3. Cada cenário gera uma ou mais conversas completas.
  4. Os avaliadores de nível de conversa avaliam as conversas geradas.
  5. Seu projeto armazena as conversas e os resultados da avaliação.

Preparar dados de cenário

Crie um arquivo JSONL em que cada linha descreve um cenário para o usuário simulado. O esquema requer id, test_case_descriptione desired_num_turns. Inclua detalhes sobre a meta, o contexto e as restrições do usuário. Para obter um exemplo completo, consulte os exemplos de avaliação de conversação no SDK.


{"id": "contoso_refund_timeline", "test_case_description": "Customer returned an item to Contoso Electronics 5 days ago and hasn't received their refund yet. They want to know how long Contoso refunds take.", "desired_num_turns": 10}
{"id": "contoso_store_hours_lookup", "test_case_description": "Customer wants to know what time the Contoso Electronics store closes today. Simple single-fact question with possibly one clarifying turn about which location.", "desired_num_turns": 3}

Parâmetros

Parâmetro Necessário Descrição
num_conversations Não Número de conversas a serem geradas por cenário. O valor padrão é 5, com limite no servidor de 5.
max_turns Não Número máximo de turnos (trocas) por conversa. O valor padrão é 10, com limite no servidor de 20.
model Sim Implantação de modelo a ser usada para simular o usuário. Por exemplo, gpt-4.1.
sampling_params Não Parâmetros de amostragem para o modelo de simulador, incluindo temperature, top_pe max_completion_tokens.
data_mapping Não Mapeia campos do seu cenário JSONL para parâmetros de simulação. Mapeamentos comuns: test_case_description, , id. desired_num_turns

Definir avaliadores

Selecione os avaliadores projetados para avaliação em nível de conversa. As conversas simuladas são mapeadas automaticamente para os avaliadores.

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator, PromptAgentDefinition

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_AGENT_NAME", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Simulation uses the same "custom" eval group type as dataset evaluation (S1),
    # since the generated conversations follow the same messages schema.
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Criar avaliação e executar

Preparação: baixe sample_data_simulation_scenarios.jsonl.

# Create (or update) an agent to simulate against
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=model_deployment_name,
        instructions="You are a helpful customer service agent. Be empathetic and solution-oriented.",
    ),
)

# Upload scenario data
scenarios_id = project_client.datasets.upload_file(
    name="simulation-scenarios",
    version="1",
    file_path="./sample_data_simulation_scenarios.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Simulation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a simulation run
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="conversation-simulation-run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": scenarios_id,
        },
        "target": {
            "type": "azure_ai_agent",
            "name": agent.name,
            "version": agent.version,
        },
        "item_generation_params": {
            "type": "conversation_gen_preview",
            "model": model_deployment_name,
            "num_conversations": 2,
            "max_turns": 5,
            "sampling_params": {
                "temperature": 0.7,
                "top_p": 1.0,
                "max_completion_tokens": 800,
            },
            "data_mapping": {
                "test_case_description": "test_case_description",
                "id": "id",
                "desired_num_turns": "desired_num_turns",
            },
        },
    },
    extra_body={"evaluation_level": "conversation"},
)

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

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. Acompanhe o status da execução até que ela seja concluída e, em seguida, recupere os resultados:

import time
from pprint import pprint

while True:
    run = openai_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(
    openai_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 é binária 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 (agregar)

Para resultados agregados sobre 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 período prolongado. Essa condição 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. Cancele o trabalho de avaliação atual usando openai_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:

  • O seu DefaultAzureCredential está configurado corretamente. Se você estiver usando CLI do Azure, execute az login.
  • Sua conta tem a função De usuário do Foundry 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 (diferencia maiúsculas de minúsculas).
  • Verifique se item_schema as propriedades correspondem aos campos em seu conjunto de dados.

Erro HTTP 400 ao usar file_id com avaliações de resposta do agente

As avaliações de resposta do agente (azure_ai_responses) dão suporte apenas a dados embutidos por meio de file_content. Se você fornecer IDs de resposta usando file_id, a solicitação retornará um 400 Bad Request erro.

Resolução: Mude para file_content e forneça os identificadores de resposta na mesma linha.

Erros de limitação de fluxo

Os níveis de locatário, assinatura e projeto limitam a criação de execuções de avaliação. 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 a implantação de modelo no portal do 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