Évaluer les conversations de modèle et d’agent déployées avec Microsoft Sdk Foundry (préversion)

Évaluez les conversations de production complètes capturées dans Application Insights pour examiner des interactions spécifiques ou un exemple de trafic de l’agent déployé.

Prerequisites

Les exemples utilisent le client sdk configuré dans Configurer le client sdk.

Évaluer les conversations par ID à partir de traces

Évaluez des conversations spécifiques à partir d’Application Insights en fournissant leurs ID de conversation. Utilisez cette option pour identifier la cause première des problèmes ou valider les correctifs pour des interactions spécifiques. Par exemple, vous pouvez examiner une conversation marquée par une alerte ou vérifier un correctif pour un problème connu.

Où trouver des ID de conversation

Recherchez les ID de conversation dans :

  • Interface utilisateur des journaux de traces Application Insights — Accédez aux traces pertinentes et repérez le champ conversation_id dans les détails de trace.
  • Sortie de journalisation de votre application : si vous définissez conversation_id explicitement lors de la création de réponses de l’agent, récupérez-la à partir de vos journaux d’activité.
  • Contexte de trace OpenTelemetry — conversation_id peut également provenir de l’en-tête traceparent si votre agent utilise la propagation standard du contexte de trace.

Note

Les définitions d’outils sont automatiquement récupérées à partir des traces ou obtenues auprès du registre des agents. Vous n’avez pas besoin de les fournir dans la demande.

Paramètres de recherche d’ID de conversation

Paramètre Obligatoire Description
conversation_ids Oui Tableau des identifiants de conversation à évaluer.
lookback_hours Non Nombre d’heures à remonter depuis end_time. La valeur par défaut est de sept jours (168 heures).
end_time Non Fin de la fenêtre de recherche (format ISO 8601). La valeur par défaut est l’heure actuelle. 
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

  • L’ingestion des données Application Insights peut entraîner un délai entre le moment où les traces sont générées et quand elles sont disponibles pour l’évaluation. Si la requête ne trouve pas de traces, patientez quelques minutes et réessayez.
  • La période rétrospective maximale est de 7 jours (168 heures). Pour accéder à des traces plus anciennes, utilisez start_time et end_time dans vos limites de rétention App Insights.

Pour obtenir un exemple d’exécution complet, consultez sample_multiturn_trace_evaluation_by_id.py sur GitHub.

Évaluer les conversations échantillonées par filtre d’agent

Évaluez un ensemble échantillonné de conversations à partir d’Application Insights en filtrant le nom de l’agent. Utilisez cette option pour évaluer la qualité globale de l’agent sur l’ensemble du trafic de production. Par exemple, exécutez des évaluations de qualité régulières ou surveillez la dégradation de la qualité en production.

L’agent que vous spécifiez pour le filtrage peut faire partie d’une conversation multi-agent. Le filtre correspond à n’importe quelle conversation où cet agent a participé.

Note

Les définitions d’outils sont automatiquement récupérées à partir des traces ou obtenues auprès du registre des agents. Vous n’avez pas besoin de les fournir dans la demande.

Champs d’identité de l’agent

Spécifiez l’agent à filtrer à l’aide de l’un des formats suivants :

Formats Example Description
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Deux champs distincts. Si agent_version est omis, utilisez la dernière version.
agent_id "agent_id": "my-agent:1" Chaîne unique au format "name:version".

Stratégies de filtre

Strategy Description
random_sampling (Par défaut) Échantillon aléatoire uniforme de jusqu’à max_traces conversations.
smart_filtering Heuristique gérée par le service privilégiant les traces « intéressantes » — conversations présentant des problèmes potentiels, des cas limites ou des anomalies.

Parameters

Paramètre Obligatoire Description
agent_name Oui Nom de l’agent par lequel filtrer les traces.
agent_version Non La version de l’agent. En cas d’omission, utilise la dernière version.
agent_id Non Alternative à agent_name + agent_version. Chaîne unique au format "name:version".
start_time Oui Début de la fenêtre de temps (secondes d’époque Unix, UTC).
end_time Oui Fin de la fenêtre de temps (secondes d’époque Unix, UTC). Ajoutez une marge de +600 secondes pour éviter un retard d’ingestion.
max_traces Non Nombre maximal de conversations à échantillonner. La valeur par défaut est 1 000.
filter_strategy Non "random_sampling" (valeur par défaut) ou "smart_filtering" (heuristique gérée par le service qui biaise vers des traces intéressantes).

Important

La fenêtre de temps (end_time - start_time) doit être d’au moins 15 minutes (900 secondes). Cette exigence existe, car les requêtes au niveau des conversations appliquent un délai d’inactivité de 5 minutes à chaque extrémité afin d’éviter les conversations partielles.

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

L’intervalle de temps de requête App Insights est actuellement limité à un maximum de 7 jours (168 heures). Vous ne pouvez pas accéder aux traces datant de plus de 7 jours sans indiquer explicitement start_time et end_time dans les limites de rétention d’App Insights.

Étapes suivantes

  • Last updated on