Avaliar conversas de modelos e agentes implementados com o Microsoft Foundry SDK (pré-visualização)

Avaliar conversas completas de produção captadas no Application Insights para investigar interações específicas ou amostrar o tráfego de agentes implementados.

Pré-requisitos

Os exemplos utilizam o cliente SDK configurado em Configurar o cliente SDK.

Avaliar conversas pelo ID com base em rastos

Avalie conversas específicas do Application Insights fornecendo os seus IDs de conversa. Utilize esta opção para identificar a causa raiz dos problemas ou validar correções em interações específicas. Por exemplo, pode investigar uma conversa sinalizada por um alerta ou verificar uma correção para um problema conhecido.

Onde encontrar IDs de conversa

Encontre IDs de conversa em:

  • IU dos registos de rastreio do Application Insights — Vá para rastreios interessantes e localize o campo conversation_id nos detalhes do rastreio.
  • Saída de registo da sua aplicação — Se definir conversation_id explicitamente ao criar respostas de agentes, recupere-a dos seus registos.
  • Contexto de rastreio OpenTelemetry — O conversation_id também pode ser derivado do cabeçalho traceparent se o seu agente usar a propagação padrão de contexto de rastreio.

Note

As definições das ferramentas são automaticamente obtidas a partir dos rastreios ou através de consulta ao registo do agente. Não precisas de os fornecer no pedido.

Parâmetros para a procura do ID da conversa

Parâmetro Obrigatório Descrição
conversation_ids Sim Matriz de IDs de conversa para avaliar.
lookback_hours No Horas para procurar de volta a partir de end_time. O valor predefinido é de sete dias (168 horas).
end_time No Fim da janela de pesquisa (formato ISO 8601). Predefinido para a hora atual. 
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

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

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

Note

  • A ingestão de dados do Application Insights pode causar um atraso entre o momento em que os traços são gerados e o momento em que estão disponíveis para avaliação. Se a consulta não encontrar rastos, espere alguns minutos e tente novamente.
  • O período máximo retroativo é 7 dias (168 horas). Para aceder a vestígios mais antigos, utilize start_time e end_time dentro dos limites de retenção do App Insights.

Para um exemplo completo e executável, veja sample_multiturn_trace_evaluation_by_id.py no GitHub.

Avalie conversas amostradas por filtro de agente

Avalie um conjunto amostrado de conversas do Application Insights filtrando pelo nome do agente. Use esta opção para avaliar a qualidade global do agente em todo o tráfego de produção. Por exemplo, realizar avaliações regulares de qualidade ou monitorizar a degradação da qualidade na produção.

O agente que especificar para a filtragem pode fazer parte de uma conversa entre vários agentes. O filtro corresponde a qualquer conversa em que esse agente tenha participado.

Note

As definições das ferramentas são automaticamente obtidas a partir dos rastreios ou através de consulta ao registo do agente. Não precisas de os fornecer no pedido.

Campos de identidade do agente

Especifique o agente a filtrar usando um destes formatos:

Format Example Descrição
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" São dois campos separados. Se agent_version for omitido, use a versão mais recente.
agent_id "agent_id": "my-agent:1" Cadeia única no formato "name:version".

Estratégias de filtro

Strategy Descrição
random_sampling (Padrão) Amostra aleatória uniforme até max_traces conversas.
smart_filtering Heurística gerida pelo serviço que privilegia rastreios "interessantes" — conversas com potenciais problemas, casos extremos ou anomalias.

Parameters

Parâmetro Obrigatório Descrição
agent_name Sim O nome do agente pelo qual filtrar os rastreios.
agent_version No A versão do agente. Se omitido, usa a versão mais recente.
agent_id No Alternativa a agent_name + agent_version. Uma única cadeia de caracteres no formato "name:version".
start_time Sim Início da janela temporal (segundos da época Unix, UTC).
end_time Sim Fim da janela temporal (segundos da época Unix, UTC). Reduza +600 segundos para evitar atraso na ingestão.
max_traces No Número máximo de conversas a amostrar. Por predefinição, é 1 000.
filter_strategy No "random_sampling" (predefinido) ou "smart_filtering" (heurística gerida pelo serviço que dá prioridade a rastreios interessantes).

Importante

A janela temporal (end_time - start_time) deve ser de pelo menos 15 minutos (900 segundos). Este requisito existe porque as consultas ao nível da conversa aplicam um buffer de inatividade de 5 minutos em cada extremidade para evitar conversas parciais.

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

Note

O período de consulta App Insights está atualmente limitado a um máximo de 7 dias (168 horas). Não pode aceder a vestígios com mais de 7 dias sem fornecer explicitamente start_time e end_time dentro dos limites de retenção do App Insights.

Passos seguintes

  • Last updated on