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 a agentes contra um agente da Foundry ou agente alojado. Utiliza-se um avaliador de rubricas gerado a partir do contexto do seu agente como medida principal, e adiciona-se avaliadores incorporados para a segurança do conteúdo e outros riscos. Especificamente, tu:

• Configura o cliente SDK para avaliação.
• Crie um avaliador de rubricas adaptado ao seu agente e combine-o com avaliadores incorporados.
• 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).

• Papel de utilizador da Foundry no projeto Foundry.

  Importante

  As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta 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 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 avaliam as respostas do seu agente. A medida primária recomendada para avaliação de agentes é um avaliador de rubricas — um conjunto de dimensões ponderadas de pontuação que um juiz LLM aplica a cada resposta, para que possa expressar os critérios exatos que importam (por exemplo, aplicação de políticas, precisão no uso de ferramentas ou clareza da comunicação) e pontuar consistentemente em escala. Para mais detalhes, consulte avaliadores de Rubricas.

Associe a sua rubrica a avaliadores adicionais para obter uma cobertura total do âmbito da sua avaliação:

• 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.
• Avaliadores personalizados — Crie os seus próprios avaliadores quando a rubrica e os materiais incorporados não cobrem os seus critérios.

Pode criar uma rubrica manualmente, ou gerar uma a partir do contexto do agente — o seu nome, instruções e ferramentas. O exemplo seguinte gera uma rubrica e imprime as suas dimensões para que possa consultá-las antes da utilização.

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 um exemplo completo executável, veja sample_rubric_evaluator_generation_all_sources.py sobre GitHub. Para redigir manualmente uma rubrica, veja sample_rubric_evaluator_manual.py.

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, defina os seus critérios de teste. Referencie o avaliador da grelha de avaliação gerado pelo nome. Cada entrada utiliza data_mapping para apontar para campos nos dados de teste e na resposta do agente, e initialization_parameters para transmitir as definições do avaliador:

• {{item.X}} referencia campos dos dados de teste, como query.
• {{sample.output_items}} Faz referência à resposta completa do agente, incluindo chamadas de ferramenta.
• {{sample.output_text}} Refere-se apenas ao texto da mensagem de resposta.
• initialization_parameters={"deployment_name": <model>} fornece o modelo do juiz. Normalmente exigido para avaliadores de juízes de LLM. Para parâmetros por avaliador, veja avaliadores incorporados.

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 adicionar avaliadores incorporados ao lado da rubrica, adicione entradas com a mesma forma mas evaluator_name="builtin.<name>". Por exemplo, adicione Violência (segurança de conteúdo) e Coerência (qualidade de julgamento 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}}",
        },
    )
)

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.

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

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": 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, sob o 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": "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 ao nível da linha

Cada execução de avaliação devolve resultados por linha no seu conjunto de dados de teste, proporcionando uma visão detalhada do 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": "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": { ... }
        }
    ]
}

A properties.dimension_scores matriz apresenta a discriminação por dimensão que o avaliador LLM produziu. A classificação score de cada dimensão está numa 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–1. Para o esquema de saída completo, veja Avaliadores de Rubricas.

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. Reavalie e compare as corridas para medir a melhoria.
4. Repete até que os limiares de qualidade sejam atingidos.

Conteúdo relacionado

• Avaliadores de Rubricas
• Gerar um conjunto de dados de avaliação sintética
• Converter vestígios de agentes em conjuntos de dados de avaliação
• Amostras de avaliação do SDK Python
• Exemplo de geração de avaliador de rubricas (Python)
• Executar a simulação de ataques com IA (red teaming)
• Painel de Monitorização de Agentes
• Referência dos avaliadores de agentes
• Referência da API REST
• Avaliação de traços na nuvem
• Configurar o traçado no Microsoft Foundry