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 executar 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% na execução de tarefas, antes de liberá-lo para os usuários.

Neste artigo, você aprenderá a executar uma avaliação voltada para o agente em um agente do Foundry ou um agente hospedado utilizando avaliadores internos para analisar qualidade, segurança e comportamento do agente. Especificamente, você:

• Configure o cliente do SDK para avaliação.
• Escolha os avaliadores quanto à qualidade, à segurança e ao comportamento do agente.
• Crie um conjunto de dados de teste e execute uma avaliação.
• Interprete os resultados e integre-os ao fluxo de trabalho.

Dica

Para avaliação de uso geral de modelos e aplicativos de IA generativos, incluindo avaliadores personalizados, fontes de dados diferentes e opções adicionais do SDK, consulte Executar avaliações do SDK.

Pré-requisitos

• Python 3.8 ou posterior.
• Um projeto do Foundry com um agente ou agente hospedado.
• Uma implantação Azure OpenAI com um modelo GPT que dá suporte à conclusão do chat (por exemplo, gpt-4o ou gpt-4o-mini).
• Usuário de IA do Azure no projeto Foundry.

Nota

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

Configurar o cliente

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

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

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 são funções que avaliam as respostas do agente. Alguns avaliadores usam modelos de IA como juízes, enquanto outros usam regras ou algoritmos. Para avaliação do agente, considere este conjunto:

Avaliador	O que ele mede
Adesão à tarefa	O agente segue as instruções do sistema?
Coerência	A resposta é lógica e bem estruturada?
Violência	A resposta contém conteúdo violento?

Para obter mais avaliadores internos, consulte:

• Avaliadores de agente – Avaliem como os agentes lidam de maneira eficiente com tarefas, ferramentas e intenções dos usuários.
• 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.

Para criar seus próprios avaliadores, consulte Avaliadores personalizados.

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 avaliadores. Cada avaliador precisa de um mapeamento de dados que informe onde encontrar entradas:

• {{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.

Os avaliadores assistidos por IA, como Aderência à Tarefa e Coerência, exigem um nome de implantação do modelo em initialization_parameters. O valor deve corresponder a um nome de implantação do GPT em seu projeto — este é o modelo de avaliação usado para pontuar as respostas. Alguns avaliadores podem exigir campos adicionais, como ground_truth ou definições de ferramenta. Para obter mais informações, consulte a documentação do avaliador.

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "Task Adherence",
        "evaluator_name": "builtin.task_adherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Violence",
        "evaluator_name": "builtin.violence",
        "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 dentro da mesma avaliação estão em conformidade com o mesmo esquema e produzem o mesmo conjunto de métricas. Essa consistência é importante para comparar resultados entre diferentes testes.

data_source_config = {
    "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 suas 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": "my-agent",  # Replace with your agent name
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

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

Dica

Este exemplo funciona para agentes de prompt e agentes hospedados que utilizam o protocolo de resposta. Para agentes hospedados que usam o protocolo de invocações, o input_messages formato é diferente – forneça um objeto JSON de forma livre em vez do modelo estruturado. Para obter detalhes e exemplos de código, consulte o protocolo invocações do agente hospedado no guia de avaliação de nuvem.

Dica

Para avaliar as interações do agente que já ocorreram utilizando rastreamentos do Application Insights, consulte Análise de rastreamento no guia de avaliação da nuvem.

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 números de aprovação e reprovação, uso de tokens por modelo, e 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": "Task Adherence",
            "passed": 1,
            "failed": 2
        },
        ... // remaining testing criteria
    ]
}

Saída em nível de linha

Cada execução de avaliação retorna itens de saída para cada linha no 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": "Task Adherence",
            "metric": "task_adherence",
            "label": "pass",
            "reason": "Agent followed system instructions correctly",
            "threshold": 3,
            "passed": true,
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        ... // remaining evaluation results
    ]
}

Integrar-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 "Como 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 melhorar 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

• Amostras de avaliação do SDK Python
• Executar a equipe vermelha com IA
• Painel de Monitoramento do Agente
• Referência de avaliadores de agentes
• Referência da API REST
• Avaliação de rastreamento na nuvem
• Configurar o rastreamento no Microsoft Foundry