Avalie os seus agentes de IA

A avaliação é essencial para garantir que o seu agente cumpre os padrões de qualidade e segurança antes da implementação. Ao realizar avaliações durante o desenvolvimento, estabelece uma base para o desempenho do seu agente e pode definir limiares de aceitação, como uma taxa de aprovação de 85% de tarefas, antes de o disponibilizar aos utilizadores.

Neste artigo, aprende como realizar uma avaliação direcionada ao agente contra um agente da Foundry ou agente hospedado , utilizando avaliadores incorporados para qualidade, segurança e comportamento do agente. Especificamente, tu:

• Configura o cliente SDK para avaliação.
• Escolha avaliadores quanto à qualidade, segurança e comportamento dos agentes.
• Crie um conjunto de dados de teste e faça uma avaliação.
• Interpreta os resultados e integra-os no teu fluxo de trabalho.

Pré-requisitos

• Python 3.8 ou posterior.
• Um projeto Foundry com um agente ou agente hospedado.
• Uma implementação Azure OpenAI com um modelo GPT que suporta a conclusão de chat (por exemplo, gpt-4o ou gpt-4o-mini).
• Utilizador de IA do Azure função 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 seguintes exemplos de código assumem que os executa 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()

Escolha avaliadores

Os avaliadores são funções que avaliam as respostas do seu agente. Alguns avaliadores usam modelos de IA como juízes, enquanto outros usam regras ou algoritmos. Para avaliação de agentes, considere este conjunto:

Para mais avaliadores integrados, veja:

• Avaliadores de agentes — Avaliar a eficácia com que os agentes lidam com tarefas, ferramentas e intenção do utilizador.
• Avaliadores de qualidade — Meçam a qualidade global das respostas geradas.
• Avaliadores de similaridade de texto — Compare o texto gerado com respostas de referência usando métricas de PLN.
• Avaliadores de segurança — Identificar potenciais riscos de conteúdo e segurança na produção gerada.

Para construir os seus próprios avaliadores, consulte Avaliadores personalizados.

Criar um conjunto de dados de teste

Crie um ficheiro JSONL com consultas de teste para o 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 este ficheiro como um conjunto de dados no seu projeto:

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

Faça uma avaliação

Quando realiza uma avaliação, o serviço envia cada consulta de teste ao seu agente, recolhe a resposta e aplica os avaliadores selecionados para pontuar os resultados.

Primeiro, configure os seus avaliadores. Cada avaliador precisa de um mapeamento de dados que lhe indique onde encontrar entradas:

• {{item.X}} Referências a campos dos teus dados de teste, como query.
• {{sample.output_items}} Faz referência à resposta completa do agente, incluindo invocações de ferramentas.
• {{sample.output_text}} Refere-se apenas ao texto da mensagem de resposta.

Avaliadores assistidos por IA, como Adesão às Tarefas e Coerência, requerem um nome de implementação do modelo em initialization_parameters. O valor deve corresponder a um nome de implementação GPT no seu projeto — este é o modelo de avaliação utilizado para classificar respostas. Alguns avaliadores podem exigir campos adicionais, como ground_truth definições de ferramentas. Para 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}}",
        },
    },
]

De seguida, faça a avaliação. Uma avaliação define o esquema de dados de teste e os critérios de teste. Serve como um contentor para múltiplas corridas. Todas as execuções sob a mesma avaliação seguem o mesmo esquema e produzem o mesmo conjunto de métricas. Esta consistência é importante para comparar resultados entre as sequências.

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,
)

Finalmente, crie uma execução que envie as suas consultas de teste ao 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 terminam em poucos minutos, dependendo do número de consultas. Verifique a conclusão e recupere o URL do relatório para visualizar os resultados no portal Microsoft Foundry, no separador 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

Ao nível da execução, pode ver dados agregados, incluindo contagens de passagens e reprovações, utilização 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 ao nível da linha de dados

Cada execução de avaliação devolve itens de saída por linha no seu conjunto de dados de teste, proporcionando visibilidade detalhada sobre o desempenho do seu agente. Os itens de saída incluem a consulta original, resposta do agente, resultados individuais dos avaliadores com pontuações e raciocínio, e utilização de tokens:

{
    "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
    ]
}

Integra no teu fluxo de trabalho

• Pipeline CI/CD: Use a avaliação como uma porta de qualidade no seu pipeline de implementação. Para integração detalhada, veja Execute avaliações com GitHub Actions.
• Monitorização da produção: Monitorize o seu agente em produção utilizando avaliação contínua. Para instruções de configuração, consulte Configurar avaliação contínua.

Otimizar e comparar versões

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

1. Faça uma avaliação para identificar áreas fracas. Use a análise de clusters para encontrar padrões e erros.
2. Ajusta as instruções ou ferramentas do agente com base nos resultados.
3. Reavaliar e comparar as execuções para medir a melhoria.
4. Repete até que os limiares de qualidade sejam atingidos.

Conteúdo relacionado

• Amostras de avaliação do SDK do Python
• Executar exercícios de red teaming com IA
• Painel de Monitorização de Agentes
• Referência para avaliadores de agentes
• Referência da API REST
• Configurar o traçado no Microsoft Foundry