Avaliar conversas de modelo e agente implantados com o SDK do Microsoft Foundry (versão prévia)

Avalie as conversas completas de produção capturadas no Application Insights para investigar interações específicas ou analisar amostras de tráfego de agentes implantados.

Pré-requisitos

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

Avaliar conversas pelo ID a partir de rastreamentos

Avalie conversas específicas do Application Insights fornecendo suas IDs de conversa. Use esta opção para identificar a causa raiz de problemas ou verificar as correções em interações específicas. Por exemplo, você 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 de logs de rastreamento do Application Insights — Navegue para rastreamentos interessantes e localize o campo conversation_id nos detalhes do rastreamento.
  • Saída de log do aplicativo – se você definir conversation_id explicitamente ao criar respostas do agente, recupere-a de seus logs.
  • Contexto de rastreamento OpenTelemetry — O conversation_id também pode ser derivado do cabeçalho traceparent se o agente usar a propagação padrão do contexto de rastreamento.

Note

As definições de ferramenta são recuperadas automaticamente dos rastreamentos ou consultadas do registro do agente. Você não precisa fornecê-los na solicitação.

Parâmetros para pesquisa de ID de conversa

Parâmetro Obrigatório Descrição
conversation_ids Yes Matriz de IDs de conversa a serem avaliadas.
lookback_hours Não Horas para pesquisar retroativamente a partir de end_time. O valor padrão é sete dias (168 horas).
end_time Não Fim da janela de pesquisa (formato ISO 8601). O valor padrão é o horário 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 quando os rastreamentos são gerados e quando eles estão disponíveis para avaliação. Se a consulta não encontrar rastreamentos, aguarde alguns minutos e tente novamente.
  • O período retrospectivo máximo é de 7 dias (168 horas). Para acessar rastreamentos mais antigos, use start_time e end_time dentro dos limites de retenção do App Insights.

Para obter um exemplo executável completo, consulte sample_multiturn_trace_evaluation_by_id.py no GitHub.

Avaliar conversas amostradas por filtro de agente

Avalie um conjunto de conversas de exemplo do Application Insights filtrando o nome do agente. Use essa opção para avaliar a qualidade geral do agente em todo o tráfego de produção. Por exemplo, execute avaliações regulares de qualidade ou monitore a degradação da qualidade na produção.

O agente especificado para filtragem pode fazer parte de uma conversa com vários agentes. O filtro corresponde a qualquer conversa em que o agente participou.

Note

As definições de ferramenta são recuperadas automaticamente dos rastreamentos ou consultadas do registro do agente. Você não precisa fornecê-los na solicitação.

Campos de identidade do agente

Especifique o agente a ser filtrado usando um destes formatos:

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

Estratégias de filtro

Strategy Descrição
random_sampling (Padrão) Amostra aleatória uniforme de até max_traces conversas.
smart_filtering Heurística gerenciada pelo serviço que prioriza rastros "interessantes": conversas com possíveis problemas, casos de borda ou anomalias.

Parameters

Parâmetro Obrigatório Descrição
agent_name Yes O nome do agente pelo qual filtrar rastreamentos.
agent_version Não A versão do agente. Se não for especificado, usa a versão mais recente.
agent_id Não Alternativa a agent_name + agent_version. Cadeia de caracteres única no formato "name:version".
start_time Yes Início da janela de tempo (segundos de época do Unix, UTC).
end_time Yes Fim da janela de tempo (segundos de época unix, UTC). Adicione uma margem de +600 segundos para evitar atrasos na ingestão.
max_traces Não Número máximo de conversas a serem selecionadas como amostra. O valor padrão é 1,000.
filter_strategy Não "random_sampling" (padrão) ou "smart_filtering" (heurística gerenciada pelo serviço que favorece rastreamentos interessantes).

Importante

A janela de tempo (end_time - start_time) deve ser de pelo menos 15 minutos (900 segundos). Esse requisito existe porque as consultas em nível de 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 tempo de consulta do App Insights está atualmente limitado a um máximo de 7 dias (168 horas). Você não pode acessar rastreamentos com mais de 7 dias sem informar explicitamente start_time e end_time, dentro dos limites de retenção do App Insights.

Próximas Etapas 

  • Last updated on