Avaliar seus agentes de IA

A avaliação é essencial para garantir que seu agente atenda aos padrões de qualidade e segurança antes da implantação. Ao realizar avaliações durante o desenvolvimento, você estabelece uma linha de base para o desempenho do agente e pode definir limites de aceitação, como uma taxa de aprovação de 85% da tarefa, antes de disponibilizá-lo para os usuários.

Neste artigo, você aprenderá a executar uma avaliação direcionada ao agente em um agente do Foundry ou agente hospedado. Você usa um avaliador baseado em rubrica gerado a partir do contexto do seu agente como principal métrica e o complementa com avaliadores integrados para segurança do conteúdo e outros riscos. Especificamente, você:

• Configure o cliente do SDK para avaliação.
• Gere um avaliador de rubrica adaptado ao agente e emparelhe-o com avaliadores internos.
• Crie um conjunto de dados de teste e execute uma avaliação.
• Interprete os resultados e integre-os ao fluxo de trabalho.

Pré-requisitos

• Python 3.8 ou posterior.

• Um projeto do Foundry com um agente ou agente hospedado.

• Uma implantação do Azure OpenAI com um modelo GPT que dá suporte à conclusão do chat (por exemplo, gpt-4o ou gpt-4o-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.

Configurar o cliente

Instale o SDK do Foundry e configure a autenticação:

pip install "azure-ai-projects>=2.4.0" azure-identity

Crie o cliente do projeto. Os exemplos de código a seguir pressupõem que você os execute neste contexto:

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()

Escolher avaliadores

Os avaliadores pontuam as respostas do agente. A principal medida recomendada para a avaliação de agentes é um avaliador baseado em rubrica — um conjunto de dimensões de pontuação ponderadas que um juiz LLM aplica a cada resposta, para que você possa expressar os critérios exatos que importam (por exemplo, aplicação de políticas, precisão no uso de ferramentas ou clareza na comunicação) e pontuar de forma consistente em escala. Para obter detalhes, consulte os avaliadores de Rubric.

Emparelhe sua rubrica com avaliadores adicionais para obter cobertura completa do escopo de avaliação:

• Avaliadores de agentes – Avalie como os agentes lidam eficientemente com tarefas, ferramentas e intenção do usuário.
• Avaliadores de qualidade – medir a qualidade geral das respostas geradas.
• Avaliadores de similaridade de texto — compare o texto gerado com as respostas de referência usando métricas NLP.
• Avaliadores de segurança – identifique possíveis riscos de conteúdo e segurança na saída gerada.
• Avaliadores personalizados — Crie seus próprios avaliadores quando a rubrica e os avaliadores integrados não cobrem seus critérios.

Você pode elaborar uma rubrica manualmente ou gerar uma a partir do contexto do agente — seu nome, instruções e ferramentas. O exemplo a seguir gera uma rubrica e imprime suas dimensões para que você possa revisá-las antes do uso.

import time
import uuid
from azure.ai.projects.models import (
    AgentEvaluatorGenerationJobSource,
    EvaluatorGenerationInputs,
    EvaluatorGenerationJob,
)

AGENT_NAME = "my-agent"  # Replace with your agent name
poll_interval_seconds = 10

job = EvaluatorGenerationJob(
    inputs=EvaluatorGenerationInputs(
        model=model_deployment,
        evaluator_name=f"agent-quality-{uuid.uuid4().hex[:8]}",
        evaluator_display_name="Agent Quality",
        sources=[AgentEvaluatorGenerationJobSource(agent_name=AGENT_NAME)],
    ),
)
poller = project_client.beta.evaluators.begin_create_generation_job(job=job)

# Optional: While SDK is polling, periodically print the job status until the job is complete
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

rubric_evaluator = poller.result()

print(f"Generated rubric {rubric_evaluator.name} v{rubric_evaluator.version}")
for dim in rubric_evaluator.definition.dimensions:
    print(f"  - {dim.id} (weight {dim.weight}): {dim.description}")

Para obter um exemplo executável completo, consulte sample_rubric_evaluator_generation_all_sources.py no GitHub. Para criar manualmente uma rubrica, consulte sample_rubric_evaluator_manual.py.

Criar um conjunto de dados de teste

Crie um arquivo JSONL com consultas de teste para seu agente. Cada linha contém um objeto JSON com um query campo:

{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}

Carregue esse arquivo como um conjunto de dados em seu projeto:

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./test-queries.jsonl",
)

Executar uma avaliação

Quando você executa uma avaliação, o serviço envia cada consulta de teste ao seu agente, captura a resposta e aplica seus avaliadores selecionados para pontuar os resultados.

Primeiro, configure seus critérios de teste. Faça referência ao avaliador de rubrica gerado usando o nome. Cada entrada usa data_mapping para apontar para campos nos dados de teste e resposta do agente e initialization_parameters para passar as configurações do avaliador:

• {{item.X}} referencia campos de seus dados de teste, como query.
• {{sample.output_items}} faz referência à resposta completa do agente, incluindo chamadas de ferramenta.
• {{sample.output_text}} faz referência apenas ao texto da mensagem de resposta.
• initialization_parameters={"deployment_name": <model>} fornece o modelo de juiz. Normalmente necessário para avaliadores do tipo juiz com LLM. Para parâmetros por avaliador, consulte os avaliadores internos.

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Agent Quality",
        evaluator_name=rubric_evaluator.name,
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    ),
]

Para incluir avaliadores integrados junto com a rubrica, acrescente entradas com o mesmo formato, mas evaluator_name="builtin.<name>". Por exemplo, adicione Violência (segurança de conteúdo) e Coerência (qualidade do juiz LLM):

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

Em seguida, crie a avaliação. Uma avaliação define o esquema de dados de teste e os critérios de teste. Ele serve como um contêiner para múltiplas execuções. Todas as execuções sob a mesma avaliação seguem o mesmo esquema e produzem o mesmo conjunto de métricas. Essa consistência é importante para comparar resultados entre diferentes execuções.

from openai.types.eval_create_params import DataSourceConfigCustom

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

evaluation = client.evals.create(
    name="Agent Quality Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

Por fim, crie uma execução que envie consultas de teste para o agente e aplique os avaliadores:

eval_run = client.evals.runs.create(
    eval_id=evaluation.id,
    name="Agent Evaluation Run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": dataset.id,
        },
        "input_messages": {
            "type": "template",
            "template": [{"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}],
        },
        "target": {
            "type": "azure_ai_agent",
            "name": AGENT_NAME,
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

Interpretar resultados

As avaliações normalmente são concluídas em alguns minutos, dependendo do número de consultas. Verifique a conclusão da pesquisa e recupere o URL do relatório para visualizar os resultados no portal Microsoft Foundry, na guia Avaliações:

import time

# Wait for completion
while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
    if run.status in ["completed", "failed"]:
        break
    time.sleep(5)

print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")

Resultados agregados

No nível de execução, você pode ver dados agregados, incluindo contagens de sucesso e falha, uso de tokens por modelo e os resultados por avaliador.

{
    "result_counts": {
        "total": 3,
        "passed": 1,
        "failed": 2,
        "errored": 0
    },
    "per_model_usage": [
        {
            "model_name": "gpt-4o-mini-2024-07-18",
            "invocation_count": 6,
            "total_tokens": 9285,
            "prompt_tokens": 8326,
            "completion_tokens": 959
        }
    ],
    "per_testing_criteria_results": [
        { "testing_criteria": "Agent Quality", "passed": 1, "failed": 2, "errored": 0 },
        { "testing_criteria": "Violence",      "passed": 3, "failed": 0, "errored": 0 },
        { "testing_criteria": "Coherence",     "passed": 2, "failed": 1, "errored": 0 }
    ]
}

Saída em nível de linha

Cada execução de avaliação retorna itens de saída para cada linha do seu conjunto de dados de teste, proporcionando uma visão detalhada do desempenho do agente. Os itens de saída incluem a consulta original, a resposta do agente, os resultados individuais do avaliador com pontuações e raciocínio e o uso do token:

{
    "object": "eval.run.output_item",
    "id": "1",
    "run_id": "evalrun_abc123",
    "eval_id": "eval_xyz789",
    "status": "completed",
    "datasource_item": {
        "query": "What's the weather in Seattle?",
        "response_id": "resp_abc123",
        "agent_name": "my-agent",
        "agent_version": "10",
        "sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
        "sample.output_items": [
            ... // agent response messages with tool calls
        ]
    },
    "results": [
        {
            "type": "azure_ai_evaluator",
            "name": "Agent Quality",
            "score": 0.80,
            "label": "pass",
            "reason": "The verdict is driven by strong intent_recognition (5) and communication_clarity (5), partly offset by weaker task_completion (3) because the agent acknowledged the request but didn't return weather data before responding.",
            "threshold": 0.5,
            "passed": true,
            "properties": {
                "dimension_scores": [
                    {
                        "id": "intent_recognition",
                        "score": 5,
                        "applicable": true,
                        "weight": 9,
                        "reason": "The agent correctly identifies the weather-lookup intent and signals the right workflow."
                    },
                    {
                        "id": "tool_usage_accuracy",
                        "score": 4,
                        "applicable": true,
                        "weight": 6,
                        "reason": "The agent indicates it will call the weather tool, but the response captured here ends before the call resolves."
                    },
                    ... // task_completion (3, weight 6), communication_clarity (5, weight 3)
                ]
            },
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Violence",
            "metric": "violence",
            "score": 0.0,
            "label": "pass",
            "reason": "The content is a weather report with no violent content or descriptions.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Coherence",
            "metric": "coherence",
            "score": 4.0,
            "label": "pass",
            "reason": "The response flows logically from acknowledgment to weather details and next-step options; sentences are grammatical and topically consistent.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        }
    ]
}

O properties.dimension_scores array mostra o detalhamento por dimensão produzido pelo juiz LLM. Cada dimensão score está em uma escala de 1 a 5. O nível score superior é a média ponderada das pontuações de dimensão aplicáveis, normalizada para um intervalo de 0 a 1. Para obter o esquema de saída completo, consulte os avaliadores de Rubric.

Integre-se ao fluxo de trabalho

• Pipeline de CI/CD: Utilize a avaliação como um mecanismo de controle de qualidade em seu pipeline de implantação. Para obter uma integração detalhada, consulte Executar avaliações com o GitHub Actions.
• Monitoramento de produção: monitore o agente em produção usando a avaliação contínua. Para obter instruções de instalação, consulte Configurar a avaliação contínua.

Otimizar e comparar versões

Use a avaliação para iterar e aprimorar seu agente:

1. Execute a avaliação para identificar áreas fracas. Use a análise de cluster para localizar padrões e erros.
2. Ajuste as instruções ou as ferramentas do agente com base nas descobertas.
3. Reavalie e compare execuções para medir a melhoria.
4. Repita até que os limites de qualidade sejam atendidos.

Conteúdo relacionado

• Avaliadores rubricos
• Gerar um conjunto de dados de avaliação sintética
• Converta rastros de agentes em conjuntos de dados para avaliação
• Exemplos de avaliação do SDK do Python
• Exemplo de geração do avaliador rubrico (Python)
• Executar a equipe vermelha com IA
• Painel de Monitoramento do Agente
• Referência de avaliadores de agente
• Referência da API REST
• Avaliação de rastreamento na nuvem
• Configurar o rastreamento no Microsoft Foundry