Partager via

Comment exécuter des évaluations en ligne avec le SDK Azure AI Foundry

  • Article

Important

Les éléments marqués (préversion) dans cet article sont actuellement en préversion publique. Cette préversion est fournie sans contrat de niveau de service, nous la déconseillons dans des charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Dans cet article, vous apprendrez à exécuter des évaluations en ligne de manière continue avec le SDK Azure AI Foundry. Les évaluations dans les environnements de préproduction sont essentielles pour garantir que votre application est sécurisée, performante et qu’elle produit des résultats de qualité supérieure. Toutefois, l’évaluation ne s’arrête pas une fois que votre application est déployée. En production, différents éléments peuvent changer, tels que les types de requêtes que les utilisateurs envoient à votre application, ce qui peut influencer les performances de votre application. Pour maintenir un degré élevé d’observabilité dans votre application d’IA générative de production, il est important de suivre (trace) et d’évaluer en permanence les données de votre application. Ainsi, vous pouvez maintenir la confiance dans la sécurité, la qualité et les performances de votre application.

Fonctionnement de l’évaluation en ligne

Dans cette section, vous découvrirez le fonctionnement de l’évaluation en ligne, comment elle s’intègre à Azure Monitor Application Insights, et comment l’utiliser pour exécuter des évaluations continues sur les données de trace de vos applications d’IA générative.

Une fois que votre application est équipée pour envoyer des données de trace à Application Insights, configurez une planification d’évaluation en ligne pour évaluer ces données en continu. L’évaluation en ligne est un service qui utilise le calcul Azure AI pour exécuter en continu un ensemble d’évaluateurs configurable. Une fois que vous avez configuré une planification d’évaluation en ligne avec le SDK Azure AI Foundry, elle s’exécute selon une planification configurable. Chaque fois que le travail planifié s’exécute, il effectue les étapes suivantes :

  1. Interrogez les données de trace d’application à partir de la ressource Application Insights connectée à l’aide d’une requête Kusto (KQL) fournie.
  2. Exécutez chaque évaluateur sur les données de trace et calculez chaque métrique (par exemple, niveau de base : 3).
  3. Réécrire les scores d’évaluation dans chaque trace à l’aide de conventions sémantiques standardisées.

Remarque

L’évaluation en ligne prend en charge les mêmes métriques qu’Azure AI Evaluation. Pour plus d’informations sur le fonctionnement de l’évaluation et les métriques d’évaluation prises en charge, consultez Évaluer votre application d’IA générative avec le SDK Azure AI Evaluation.

Par exemple, supposons que vous disposez d’une application de conversation déployée qui reçoit de nombreuses questions sur les clients quotidiennement. Vous souhaitez évaluer en permanence la qualité des réponses de votre application. Vous configurez une planification d’évaluation en ligne avec une périodicité quotidienne. Vous configurez les évaluateurs : de base, de cohérenceet de résilience. Chaque jour, le service calcule les scores d’évaluation de ces métriques et écrit les données dans Application Insights pour chaque trace collectée pendant la fenêtre de temps de périodicité (dans cet exemple, les 24 dernières heures). Ensuite, les données peuvent être interrogées à partir de chaque trace et rendues accessibles dans Azure AI Foundry et Azure Monitor Application Insights.

Les résultats de l’évaluation réécrits dans chaque trace dans Application Insights suivent les conventions suivantes. Une étendue unique est ajoutée à chaque trace pour chaque métrique d’évaluation :

Propriété Table Application Insights Champs d’un operation_ID donné Exemple de valeur
Métrique d’évaluation traces, AppTraces customDimensions[“event.name”] gen_ai.evaluation.relevance
Evaluation_metric_score traces, AppTraces customDimensions[“gen_ai.evaluation.score”] 3
Commentaire de métrique d’évaluation (le cas échéant) traces, AppTraces message {“comment”: “I like the response”}

Maintenant que vous comprenez le fonctionnement de l’évaluation en ligne et comment elle se connecte à Azure Monitor Application Insights, l’étape suivante consiste à configurer le service.

Configurer l’évaluation en ligne

Dans cette section, vous apprendrez à configurer une planification d’évaluation en ligne pour surveiller en permanence votre application d’IA générative déployée. Le SDK Azure AI Foundry propose ces fonctionnalités. Une API Python et prend en charge toutes les fonctionnalités disponibles dans les évaluations locales. Suivez les étapes suivantes pour soumettre votre planification d’évaluations en ligne sur vos données à l’aide d’évaluateurs intégrés ou personnalisés.

Remarque

Les évaluations ne sont prises en charge que dans les mêmes régions que les métriques de sécurité et de risque assistés par l’IA.

Prérequis

Effectuez les étapes préalables suivantes pour configurer votre environnement et l’authentification sur les ressources nécessaires :

  1. Un abonnement Azure.
  2. Un groupe de ressources dans une région prise en charge par l’évaluation.
  3. Une nouvelle identité managée affectée par l'utilisateur(-trice) dans le même groupe de ressources et la même région. Prenez note de clientId; vous en aurez besoin plus tard.
  4. Un Azure AI Hub dans le même groupe de ressources et la même région.
  5. Un projet Azure AI dans ce hub, consultez Créer un projet dans le portail Azure AI Foundry.
  6. Une ressource Azure Monitor Application Insights.
  7. Accédez à la page hub dans le portail Azure et ajoutez une ressource Application Insights, consultez Mettre à jour Azure Application Insights et Azure Container Registry.
  8. Déploiement Azure OpenAI avec le modèle GPT prenant en charge chat completion, par exemple gpt-4.
  9. Connection String pour que le projet Azure AI crée facilement AIProjectClient un objet. Vous pouvez obtenir la chaîne de connexion du projet sous Détails du projet à partir de la page Vue d’ensembledu projet.
  10. Accédez à votre ressource Application Insights dans le portail Azure et utilisez l’onglet Contrôle d’accès (IAM) pour ajouter le rôle Log Analytics Contributor à l’identité managée affectée par l’utilisateur que vous avez créée précédemment.
  11. Attachez l'identité managée affectée par l'utilisateur(-trice) à votre projet.
  12. Accédez à vos Azure AI Services dans le portail Azure et utilisez l’onglet Contrôle d’accès (IAM ) pour ajouter le rôle Cognitive Services OpenAI Contributor à l’identité managée affectée par l’utilisateur(-trice) que vous avez créée précédemment.

Instructions d'installation

Installer Azure CLI et se connecter

Vous installez l'interface Azure CLI et vous vous connectez depuis votre environnement de développement local, afin de pouvoir utiliser vos informations d'identification pour appeler le service Azure OpenAI.

Dans la plupart des cas, vous pouvez installer Azure CLI à partir de votre terminal à l’aide de la commande suivante :

winget install -e --id Microsoft.AzureCLI

Vous pouvez suivre les instructions Comment installer l’interface de ligne de commande Azure si ces commandes ne fonctionnent pas pour votre système d’exploitation ou configuration particulier.

Après avoir installé Azure CLI, connectez-vous à l’aide de la commande az login et connectez-vous à l’aide du navigateur :

az login

Alternativement, vous pouvez vous connecter manuellement via le navigateur avec un code d'appareil.

az login --use-device-code

Créer un environnement Python

Tout d’abord, vous devez créer un environnement Python à utiliser pour installer le package dont vous avez besoin pour ce didacticiel. N’installez pas de packages dans votre installation globale de Python. Vous devez toujours utiliser un environnement virtuel ou conda lors de l’installation de packages Python. Sinon, vous pouvez interrompre votre installation globale de Python.

Si nécessaire, installez Python

Nous vous recommandons d’utiliser Python 3.10 ou version ultérieure, mais l’utilisation d’au moins Python 3.8 est requise. Si vous n’avez pas installé une version appropriée de Python, vous pouvez suivre les instructions du didacticiel Python VS Code pour le moyen le plus simple d’installer Python sur votre système d’exploitation.

Créer un environnement virtuel

Si Python 3.10, ou une version ultérieure est déjà installé, vous pouvez créer un environnement virtuel à l’aide des commandes suivantes :

py -3 -m venv .venv
.venv\scripts\activate

L'activation de l'environnement Python signifie que lorsque vous exécutez python ou pip depuis la ligne de commande, vous utilisez alors l'interpréteur Python contenu dans le dossier .venv de votre application.

Remarque

Vous pouvez utiliser la commande deactivate pour quitter l’environnement virtuel Python et la réactiver ultérieurement si nécessaire.

Vous pouvez également créer un environnement Python à l’aide de conda :

conda create -n online-evaluation
conda activate online-evaluation

Installez les packages nécessaires :

pip install azure-identity azure-ai-projects azure-ai-ml

Conseil

Vous pouvez éventuellement utiliser pip install azure-ai-evaluation si vous souhaitez qu’une expérience de code extraie l’ID de l’évaluateur pour les évaluateurs intégrés dans le code. Pour en savoir plus, voir Spécification d’évaluateurs à partir de la Bibliothèque d’évaluateurs.

Configurer le traçage votre application d'IA générative

Avant de configurer l’évaluation en ligne, vérifiez que vous avez d’abord configuré le suivi pour votre application d’IA générative.

Utilisation du nom de service dans les données de trace

Pour identifier votre application avec un ID unique dans Application Insights, vous pouvez utiliser la propriété OpenTelemetry du nom de service dans vos données de trace. Cela est particulièrement utile si vous journaliser des données de plusieurs applications vers la même ressource Application Insights et que vous souhaitez les différencier. Par exemple, supposons que vous disposez de deux applications : App-1 et App-2, avec le suivi configuré pour journaliser les données vers la même ressource Application Insights. Vous souhaitez peut-être configurer App-1 pour être évalué en continu par Pertinence et App-2 à évaluer en continu par de base. Vous pouvez utiliser le nom du service pour différencier les applications de vos configurations d’évaluation en ligne.

Pour configurer la propriété de nom de service, vous pouvez le faire directement dans votre code d’application en suivant les étapes, consultez Utilisation de plusieurs fournisseurs de suivi avec différentes de ressources. Vous pouvez également définir la variable d’environnement OTEL_SERVICE_NAME avant de déployer votre application. Pour en savoir plus sur l’utilisation du nom du service, consultez Variables d’environnement OTEL et Conventions sémantiques des ressources de service.

Pour plus d’informations sur l’utilisation du nom de service pour différencier vos applications d’IA générative, consultez Suivi.

Interroger les données de traçage stockées dans Application Insights

À l’aide du langage de requête Kusto (KQL), vous pouvez interroger les données de trace de votre application d’IA générative à partir d’Application Insights à utiliser pour l’évaluation en ligne continue. Si vous utilisez le package de traçage Azure AI pour suivre votre application d’IA générative, vous pouvez utiliser la requête Kusto suivante :

Important

La requête KQL utilisée par le service d’évaluation en ligne doit générer les colonnes suivantes : operation_Id, operation_ParentId et gen_ai_response_id. En outre, chaque évaluateur a ses propres exigences en matière de données d’entrée. La requête KQL doit générer ces colonnes à utiliser comme entrées pour les évaluateurs eux-mêmes. Pour obtenir la liste des exigences en matière de données pour les évaluateurs, consultez Exigences en matière de données pour les évaluateurs intégrés.

let gen_ai_spans = (
    dependencies
    | where isnotnull(customDimensions["gen_ai.system"])
    | extend response_id = tostring(customDimensions["gen_ai.response.id"])
    | project id, operation_Id, operation_ParentId, timestamp, response_id
);
let gen_ai_events = (
    traces
    | where message in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
        or tostring(customDimensions["event.name"]) in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
    | project 
        id = operation_ParentId, 
        operation_Id, 
        operation_ParentId, 
        user_input = iff(
            message == "gen_ai.user.message" or tostring(customDimensions["event.name"]) == "gen_ai.user.message", 
            parse_json(iff(message == "gen_ai.user.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        system = iff(
            message == "gen_ai.system.message" or tostring(customDimensions["event.name"]) == "gen_ai.system.message", 
            parse_json(iff(message == "gen_ai.system.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        llm_response = iff(
            message == "gen_ai.choice", 
            parse_json(tostring(parse_json(tostring(customDimensions["gen_ai.event.content"])).message)).content, 
            iff(tostring(customDimensions["event.name"]) == "gen_ai.choice", parse_json(parse_json(message).message).content, "")
        )
    | summarize 
        operation_ParentId = any(operation_ParentId), 
        Input = maxif(user_input, user_input != ""), 
        System = maxif(system, system != ""), 
        Output = maxif(llm_response, llm_response != "") 
    by operation_Id, id
);
gen_ai_spans
| join kind=inner (gen_ai_events) on id, operation_Id
| project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id

Si vous utilisez la variable d’environnement OTEL_SERVICE_NAME dans votre application d’IA générative pour définir le nom du service, vous pouvez rechercher cloud_RoleName dans votre planification d’évaluation en ligne en ajoutant la ligne suivante à votre requête Kusto (KQL) :

| where cloud_RoleName == "service_name"

Si vous le souhaitez, vous pouvez utiliser l’échantillon d’opérateur ou prendre l’opérateur dans votre requête Kusto afin qu’il retourne uniquement un sous-ensemble de traces. Étant donné que les évaluations assistées par l’IA peuvent être coûteuses à grande échelle, cette approche peut vous aider à contrôler les coûts en évaluant uniquement un échantillon aléatoire (ou n traces) de vos données.

Mise en place d’une évaluation en ligne avec le SDK Azure AI Project

Vous pouvez soumettre un travail planifié d’évaluation en ligne avec le SDK Azure AI Project via une API Python. Consultez le script ci-dessous pour savoir comment configurer l’évaluation en ligne avec des évaluateurs de performances et de qualité (assistés par l’IA). Pour afficher la liste complète des évaluateurs pris en charge, consultez Évaluer avec le KIT de développement logiciel (SDK) Azure AI Evaluation. Pour savoir comment utiliser des évaluateurs personnalisés, consultez évaluateurs personnalisés.

Commencez par importer les packages requis et configurer les variables requises :

from azure.ai.projects import AIProjectClient 
from azure.identity import DefaultAzureCredential 
from azure.ai.projects.models import ( 
    ApplicationInsightsConfiguration,
    EvaluatorConfiguration,
    EvaluationSchedule,
    RecurrenceTrigger,
)
from azure.ai.evaluation import CoherenceEvaluator 

# This sample includes the setup for an online evaluation schedule using the Azure AI Project SDK and Azure AI Evaluation SDK
# The schedule is configured to run daily over the collected trace data while running two evaluators: CoherenceEvaluator and RelevanceEvaluator
# This sample can be modified to fit your application's requirements

# Name of your online evaluation schedule
SAMPLE_NAME = "online_eval_name"

# Connection string to your Azure AI Foundry project
# Currently, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
PROJECT_CONNECTION_STRING = "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"

# Your Application Insights resource ID
APPLICATION_INSIGHTS_RESOURCE_ID = "appinsights_resource_id"

# Kusto Query Language (KQL) query to query data from Application Insights resource
# This query is compatible with data logged by the Azure AI Inferencing Tracing SDK (linked in documentation)
# You can modify it depending on your data schema
# The KQL query must output these required columns: operation_ID, operation_ParentID, and gen_ai_response_id
# You can choose which other columns to output as required by the evaluators you are using
KUSTO_QUERY = "let gen_ai_spans=(dependencies | where isnotnull(customDimensions[\"gen_ai.system\"]) | extend response_id = tostring(customDimensions[\"gen_ai.response.id\"]) | project id, operation_Id, operation_ParentId, timestamp, response_id); let gen_ai_events=(traces | where message in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") or tostring(customDimensions[\"event.name\"]) in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") | project id= operation_ParentId, operation_Id, operation_ParentId, user_input = iff(message == \"gen_ai.user.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.user.message\", parse_json(iff(message == \"gen_ai.user.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), system = iff(message == \"gen_ai.system.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.system.message\", parse_json(iff(message == \"gen_ai.system.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), llm_response = iff(message == \"gen_ai.choice\", parse_json(tostring(parse_json(tostring(customDimensions[\"gen_ai.event.content\"])).message)).content, iff(tostring(customDimensions[\"event.name\"]) == \"gen_ai.choice\", parse_json(parse_json(message).message).content, \"\")) | summarize operation_ParentId = any(operation_ParentId), Input = maxif(user_input, user_input != \"\"), System = maxif(system, system != \"\"), Output = maxif(llm_response, llm_response != \"\") by operation_Id, id); gen_ai_spans | join kind=inner (gen_ai_events) on id, operation_Id | project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id"

Ensuite, définissez un client et un déploiement Azure OpenAI GPT (tel que GPT-4) qui sera utilisé pour exécuter votre planification d’évaluation en ligne. Connectez-vous également à votre ressource Application Insights :

# Connect to your Azure AI Foundry Project
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=PROJECT_CONNECTION_STRING
)

# Connect to your Application Insights resource 
app_insights_config = ApplicationInsightsConfiguration(
    resource_id=APPLICATION_INSIGHTS_RESOURCE_ID,
    query=KUSTO_QUERY
)

# Connect to your Azure OpenAI Service resource. You must use a GPT model deployment for this example.
deployment_name = "gpt-4"
api_version = "2024-08-01-preview"

# This is your Azure OpenAI Service connection name, which can be found in your Azure AI Foundry project under the 'Models + Endpoints' tab.
default_connection = project_client.connections._get_connection(
    "aoai_connection_name"
)

model_config = {
    "azure_deployment": deployment_name,
    "api_version": api_version,
    "type": "azure_openai",
    "azure_endpoint": default_connection.properties["target"]
}

Ensuite, configurez les évaluateurs que vous souhaitez utiliser :

# RelevanceEvaluator
# id for each evaluator can be found in your Azure AI Foundry registry - please see documentation for more information
# init_params is the configuration for the model to use to perform the evaluation
# data_mapping is used to map the output columns of your query to the names required by the evaluator
relevance_evaluator_config = EvaluatorConfiguration(
    id="azureml://registries/azureml-staging/models/Relevance-Evaluator/versions/4",
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

# CoherenceEvaluator
coherence_evaluator_config = EvaluatorConfiguration(
    id=CoherenceEvaluator.id,
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

Enfin, définissez la périodicité et créez la planification :

Remarque : dans les étapes préalables, vous avez créé une identité managée affectée par l’utilisateur pour authentifier la planification d’évaluation en ligne à votre ressource Application Insights. Le AzureMSIClientId dans le paramètre properties de la classe EvaluationSchedule est la clientId de cette identité.

# Frequency to run the schedule
recurrence_trigger = RecurrenceTrigger(frequency="day", interval=1)

# Dictionary of evaluators
evaluators = {
    "relevance": relevance_evaluator_config,
    "coherence" : coherence_evaluator_config
}

name = SAMPLE_NAME
description = f"{SAMPLE_NAME} description"
# AzureMSIClientId is the clientID of the User-assigned managed identity created during set-up - see documentation for how to find it
properties = {"AzureMSIClientId": "your_client_id"}

# Configure the online evaluation schedule
evaluation_schedule = EvaluationSchedule(
    data=app_insights_config,
    evaluators=evaluators,
    trigger=recurrence_trigger,
    description=description,
    properties=properties)

# Create the online evaluation schedule 
created_evaluation_schedule = project_client.evaluations.create_or_replace_schedule(name, evaluation_schedule)
print(f"Successfully submitted the online evaluation schedule creation request - {created_evaluation_schedule.name}, currently in {created_evaluation_schedule.provisioning_state} state.")

Effectuer des opérations selon une planification d’évaluation en ligne

Vous pouvez obtenir, répertorier et désactiver les planifications d’évaluation en ligne en ajoutant le code suivant à votre script de configuration d’évaluation en ligne :

Avertissement : attendez un certain temps (environ 30 secondes) entre la création d’une planification d’évaluation en ligne et l’exécution de l’API get_schedule().

Obtenez une planification d’évaluation en ligne :

name = "<my-online-evaluation-name>"
get_evaluation_schedule = project_client.evaluations.get_schedule(name)

Liste de toutes les planifications d’évaluation en ligne :

count = 0
for evaluation_schedule in project_client.evaluations.list_schedule():
    count += 1
        print(f"{count}. {evaluation_schedule.name} "
        f"[IsEnabled: {evaluation_schedule.is_enabled}]")
        print(f"Total evaluation schedules: {count}")

Désactiver (suppression réversible) la planification d’évaluation en ligne :

name = "<my-online-evaluation-name>"
project_client.evaluations.disable_schedule(name)

Contenu connexe