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 a um agente contra um agente do Foundry ou agente hospedado usando avaliadores internos para 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.

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).
• Função de Usuário do Azure AI no projeto Foundry.

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:

Para obter mais avaliadores internos, consulte:

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

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 Adesão à 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 GPT em seu projeto. Esse é o modelo avaliador usado para avaliar 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. Serve como um container 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.

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}")

Interpretar resultados

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

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": "Task Adherence",
            "passed": 1,
            "failed": 2
        },
        ... // remaining testing criteria
    ]
}

Saída de 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": "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
    ]
}

Integre-se ao fluxo de trabalho

• Pipeline de CI/CD: use a avaliação como um portão de qualidade no pipeline de implantação. Para obter uma integração detalhada, consulte Execute avaliações com 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. Reavaliar e comparar execuções para analisar o aprimoramento.
4. Repita até que os limites de qualidade sejam atendidos.

Conteúdo relacionado

• Exemplos de Avaliação do SDK do Python
• Executar o agrupamento vermelho de IA
• Painel de Monitoramento do Agente
• Referência de avaliadores de agente
• Referência da API REST
• Configurar o rastreamento no Microsoft Foundry