Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Important
Les éléments marqués comme préversion dans cet article sont actuellement en préversion. Cette préversion est fournie sans contrat de niveau de service et Microsoft ne le recommande pas pour les charges de travail de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les versions préliminaires de Microsoft Azure.
Cette action GitHub action permet l’évaluation hors connexion des agents Microsoft Foundry Agents au sein de vos pipelines CI/CD. Il simplifie le processus d’évaluation hors connexion, ce qui vous permet d’identifier les problèmes potentiels et d’apporter des améliorations avant de publier une mise à jour en production.
Pour utiliser cette action, fournissez un jeu de données avec des requêtes de test et une liste d’évaluateurs. Cette action appelle vos agents avec les requêtes, exécute les évaluations et génère un rapport de synthèse.
Fonctionnalités
- Agent Evaluation : Automatiser l’évaluation de préproduction des agents de Microsoft Foundry dans votre flux de travail CI/CD.
- Évaluateurs : utilisez n'importe quel évaluateur du catalogue des évaluateurs Foundry.
- Analyse statistique : les résultats de l’évaluation incluent des intervalles de confiance et des tests de précision statistique pour déterminer si les modifications sont significatives et non en raison d’une variation aléatoire.
Catégories de l’évaluateur
- Évaluateurs d’agents : évaluateurs pour les processus et les systèmes des flux de travail d’agents.
- Évaluateurs RAG : évaluent les processus de bout en bout et de récupération dans les systèmes RAG.
- Évaluateurs de risque et de sécurité : évaluer les risques et les préoccupations en matière de sécurité dans les réponses.
- Évaluateurs à usage général : évaluation de la qualité, telle que la cohérence et la fluidité.
- Nuanceurs basés sur OpenAI : utilisez des nuanceurs OpenAI, notamment la vérification de chaîne, la similarité du texte, le modèle score/étiquette.
- Évaluateurs personnalisés : définissez vos propres évaluateurs personnalisés à l’aide de code Python ou de modèles LLM-en-tant-que-juge.
Conditions préalables
- Un projet. Pour plus d’informations, consultez Créer un projet.
- Un agent Foundry.
Conseil
La méthode recommandée pour l’authentification consiste à utiliser Microsoft Entra ID, que vous pouvez utiliser pour vous connecter en toute sécurité à vos ressources Azure. Vous pouvez automatiser le processus d’authentification à l’aide de l’action Azure connexion GitHub. Pour plus d’informations, consultez Azure Action de connexion avec OpenID Connect.
Comment configurer des évaluations des agents intelligents
Entrée des évaluations de l’agent IA
Paramètres
| Nom | Obligatoire? | Description |
|---|---|---|
| projet azure-ai-point de terminaison | Oui | Point de terminaison de votre Microsoft Foundry Project. Pour trouver cette valeur, ouvrez votre projet dans le portail Foundry et copiez le point de terminaison à partir de la page Vue d’ensemble . |
| nom-de-déploiement | Oui | Nom d’un déploiement de modèle IA Azure à utiliser pour l’évaluation. Recherchez les déploiements existants sous Modèles + points de terminaison dans le portail Foundry. |
| chemin d’accès aux données | Oui | Chemin d’accès au fichier de données qui contient les évaluateurs et les requêtes d’entrée pour les évaluations. |
| identifiants d'agents | Oui | ID d’un ou de plusieurs agents à évaluer au format agent-name:version (par exemple, my-agent:1 ou my-agent:1,my-agent:2). Plusieurs agents sont séparés par des virgules et comparés aux résultats des tests statistiques. |
| identifiant-agent-de-base | Non | ID de l’agent de base à comparer lors de l’évaluation de plusieurs agents. S’il n’est pas fourni, le premier agent est utilisé. |
Note
Pour rechercher votre ID d’agent et votre version, ouvrez votre projet dans le portail Foundry, accédez à Agents, sélectionnez votre agent et copiez l’ID de l’agent dans le volet d’informations. La version est le numéro de version du déploiement (par exemple). my-agent:1
Fichier de données
Le fichier de données d’entrée doit être un fichier JSON avec la structure suivante :
| Champ | Type | Obligatoire? | Description |
|---|---|---|---|
| Nom | string | Oui | Nom du jeu de données d’évaluation. |
| Évaluateurs | string[] | Oui | Liste des noms d’évaluateurs à utiliser. Veuillez consulter la liste des évaluateurs disponibles dans le catalogue d’évaluateurs de votre projet dans le portail Foundry : Créer> des évaluations > Catalogue d’évaluateurs . |
| Données | object[] | Oui | Tableau d’objets d’entrée avec query et champs évaluateur facultatifs tels que ground_truth, context. Attribuée automatiquement aux évaluateurs ; utilisez data_mapping pour remplacer. |
| openai_graders | Objet | Non | Configuration pour les évaluateurs basés sur OpenAI (label_model, score_model, string_check, etc.). |
| paramètres_évaluateur | Objet | Non | Paramètres d’initialisation spécifiques à l’évaluateur (par exemple, seuils, paramètres personnalisés). |
| cartographie des données | Objet | Non | Mappages de champs de données personnalisés (générés automatiquement à partir de données si elles ne sont pas fournies). |
Exemple de fichier de données de base
{
"name": "test-data",
"evaluators": [
"builtin.fluency",
"builtin.task_adherence",
"builtin.violence"
],
"data": [
{
"query": "Tell me about Tokyo disneyland"
},
{
"query": "How do I install Python?"
}
]
}
Exemples de fichiers de données supplémentaires
| Nom de fichier | Description |
|---|---|
| dataset-tiny.json | Jeu de données avec un petit nombre de requêtes de test et d’évaluateurs. |
| dataset.json | Jeu de données avec tous les types d’évaluateurs pris en charge et suffisamment de requêtes pour le calcul de l’intervalle de confiance et le test statistique. |
| dataset-builtin-evaluators.json | Exemples d'évaluateurs intégrés Foundry (par exemple, cohérence, fluidité, pertinence, fondement, métriques). |
| dataset-openai-graders.json | Exemple d'évaluateurs basés sur OpenAI (modèles d'étiquettes, modèles de score, similarité de texte, vérifications de chaînes de caractères). |
| dataset-custom-evaluators.json | Exemple d’évaluateurs personnalisés avec des paramètres d’évaluateur. |
| dataset-data-mapping.json | Exemple de mappage de données montrant comment remplacer les mappages automatiques de champs avec des noms de colonnes de données personnalisés. |
Flux de travail d’évaluation des agents IA
Pour utiliser l’action GitHub, ajoutez l’action de GitHub à vos flux de travail CI/CD. Spécifiez les critères de déclencheur, tels que lors de la validation, et les chemins d’accès aux fichiers pour déclencher vos flux de travail automatisés.
Conseil
Pour réduire les coûts, n'exécutez pas les évaluations sur chaque commit.
Cet exemple montre comment exécuter l’évaluation de l’agent IA en comparant différents agents en utilisant leurs ID d'agents.
name: "AI Agent Evaluation"
on:
workflow_dispatch:
push:
branches:
- main
permissions:
id-token: write
contents: read
jobs:
run-action:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Azure login using Federated Credentials
uses: azure/login@v2
with:
client-id: ${{ vars.AZURE_CLIENT_ID }}
tenant-id: ${{ vars.AZURE_TENANT_ID }}
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
- name: Run Evaluation
uses: microsoft/ai-agent-evals@v3-beta
with:
# Replace placeholders with values for your Foundry Project
azure-ai-project-endpoint: "<your-ai-project-endpoint>"
deployment-name: "<your-deployment-name>"
agent-ids: "<your-ai-agent-ids>"
data-path: ${{ github.workspace }}/path/to/your/data-file
Évaluations de l'agent IA : résultats
Les résultats de l’évaluation sont générés dans la section récapitulative de chaque action d’évaluation d’IA GitHub exécutée sous Actions dans GitHub. Le rapport affiche les scores d’évaluation pour chaque métrique, intervalles de confiance et, lorsque vous évaluez plusieurs agents, comparaison statistique jumelée qui indique si les différences sont significatives ou dans une variation aléatoire.
La capture d’écran suivante montre un exemple de rapport comparant deux agents.
Utiliser l’extension d’évaluation azd comme barrière qualité
Vous pouvez utiliser l’extension d’évaluation (azd) de Azure Developer CLI pour exécuter une évaluation enregistrée et bloquer une demande de tirage lorsque son taux de réussite est inférieur à un seuil. Ce flux de travail utilise GitHub OpenID Connect (OIDC), de sorte qu'il ne stocke pas de clé secrète client.
Préparer le référentiel
Avant de configurer le flux de travail, vérifiez que vous disposez des éléments suivants :
- Un abonnement Azure et un projet Foundry qui contient la cible d’évaluation.
- Accès administrateur pour configurer GitHub Actions variables, secrets, environnements et règles de protection.
- Définition d’évaluation enregistrée et jeu de données d’évaluation déterministe.
- L'interface Azure Developer CLI (
azd), version 1.33.0 ou ultérieure, requise par l’extension d'évaluation. Pour obtenir des instructions d’installation, consultez Installer l’interface CLI Azure développeur. - Extension
azure.ai.evaluations, qui fournit les commandes d’évaluation. Le paquet Foundryazd(microsoft.foundry) ne l’inclut pas.
Installez l’extension azure.ai.evaluations et vérifiez que les commandes d’évaluation sont disponibles. Dans votre flux de travail, exécutez les mêmes commandes dans une étape après avoir installé azd. Pour plus d’informations sur les extensions Foundry, consultez Installer les extensions Foundry de l’Azure Developer CLI.
azd ext install azure.ai.evaluations
azd ai eval --help
Configurer GitHub OIDC et les privilèges minimum
Créez une application Microsoft Entra ou une identité managée attribuée par l’utilisateur et ajoutez des informations d'identification d'identité fédérées pour le jeton émis pour le workflow. Utilisez ces valeurs fixes :
| Champs des informations d’identification fédérées | Value |
|---|---|
| Issuer | https://token.actions.githubusercontent.com |
| Public visé | api://AzureADTokenExchange |
| Subject | La revendication sub exacte dans le jeton OIDC GitHub |
Un référentiel dans une organisation ou une entreprise qui utilise un sujet personnalisé immuable peut avoir un sujet avec cette forme :
repository_owner_id:<owner-id>:repository_id:<repo-id>:pull_request
Référence : Référence OpenID Connect
Ne copiez pas les ID de propriétaire ou de référentiel d’un autre référentiel. Demandez un jeton dans votre workflow, décodez sa charge utile sans imprimer le jeton et inspectez uniquement les revendications iss, aud et sub. Configurez les informations d’identification fédérées pour qu’elles correspondent exactement aux revendications réelles. Le sujet standard de GitHub pour un travail qui utilise un environnement peut avoir un format différent, et une organisation ou une entreprise peut personnaliser la revendication de sujet.
Pour la configuration de l’identité de charge de travail Microsoft Entra, consultez S’authentifier auprès d’Azure à partir de GitHub Actions par OpenID Connect.
Attribuez uniquement ces rôles à l’identité :
- Utilisateur Foundry dans l’étendue du projet Foundry.
-
Contributeur au niveau de l'étendue du groupe de ressources dédié, si vous effectuez le rapprochement avec
azd up.
Important
Les rôles Foundry RBAC ont été récemment renommés. Foundry User, Foundry Owner, Propriétaire du compteFoundry et Foundry Project Manager ont été précédemment nommés Azure utilisateur IA, Azure propriétaire d’IA, propriétaire Azure compte IA et Azure gestionnaire Project IA. Il se peut que vous voyiez encore les anciens noms à certains endroits pendant le déploiement de ce changement de nom. Les ID de rôle et les autorisations de base ne sont pas modifiés par ce changement de nom.
Le rôle de groupe de ressources est requis lorsque vous effectuez un rapprochement avec azd up, car azd up enregistre un déploiement Azure Resource Manager lorsqu’il est approvisionné. N’attribuez pas Contributor à la portée de l’abonnement.
Protéger et configurer l’environnement de production
Créez un environnement de GitHub protégé nommé live-evaluation. Ajoutez les réviseurs requis et limitez les branches de déploiement en fonction de votre référentiel.
Pour plus d’informations, consultez Gestion d’environnements pour le déploiement.
Stockez les valeurs de flux de travail comme suit. N’ajoutez pas AZURE_CLIENT_SECRET ; OIDC le remplace.
| Nom | Stockage GitHub | Purpose |
|---|---|---|
AZURE_CLIENT_ID |
live-evaluation secret d’environnement |
ID client de l’application Microsoft Entra ou de l’identité gérée. |
AZURE_TENANT_ID |
live-evaluation secret d'environnement |
ID de locataire Microsoft Entra. |
AZURE_SUBSCRIPTION_ID |
live-evaluation secret d’environnement |
Abonnement qui contient le groupe de ressources dédié. |
AZURE_AI_PROJECT_ENDPOINT |
live-evaluation secret d’environnement |
Point de terminaison du projet Foundry utilisé par l’extension d’évaluation. |
AZURE_LOCATION |
live-evaluation variable d’environnement |
Région Azure pour l’environnement azd. |
AZURE_RESOURCE_GROUP |
live-evaluation variable d’environnement |
Groupe de ressources dédié utilisé pour les métadonnées de rapprochement. |
AZD_EVAL_LIVE_PR_GATE |
Variable du dépôt | Définissez sur la valeur exacte true pour activer le travail actif. |
Gardez AZD_CONFIG_DIR sous RUNNER_TEMP, et authentifiez-vous de manière non interactive :
azd auth login `
--client-id $env:AZURE_CLIENT_ID `
--tenant-id $env:AZURE_TENANT_ID `
--federated-credential-provider github `
--no-prompt
Référence : référence Azure Developer CLI
Le travail doit avoir les autorisations contents: read et id-token: write. Contrôlez-le de sorte que seules les demande de tirage du même référentiel ou une répartition manuelle à partir de la branche par défaut puissent entrer dans l’environnement protégé. Les pull requests du fork doivent ignorer le job, et le flux de travail ne doit pas utiliser pull_request_target.
on:
pull_request:
workflow_dispatch:
permissions:
contents: read
id-token: write
jobs:
live-evaluation:
if: >-
vars.AZD_EVAL_LIVE_PR_GATE == 'true' &&
((github.event_name == 'pull_request' &&
github.event.pull_request.head.repo.full_name == github.repository) ||
(github.event_name == 'workflow_dispatch' &&
github.ref_name == github.event.repository.default_branch))
environment:
name: live-evaluation
Référence : Référence des contextes GitHub Actions
Épinglez chaque GitHub Action à un SHA complet du commit examiné.
Fournir un modèle d’infrastructure inerte lorsque azd up en requiert un
Si vous rapprochez un projet d’évaluation uniquement avec azd up au lieu de azd ai eval create, le projet ne provisionne pas de ressources de charge de travail. Si azd up --no-prompt signale qu’il ne peut pas trouver ou compiler infra/main.bicep, ajoutez ce fichier avec ce déploiement imbriqué inerte :
targetScope = 'resourceGroup'
resource reconciliationMarker 'Microsoft.Resources/deployments@2022-09-01' = {
name: 'azd-eval-hero-reconciliation'
properties: {
mode: 'Incremental'
template: {
'$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
contentVersion: '1.0.0.0'
resources: []
}
}
}
Le modèle interne ne contient aucune ressource de charge de travail. Le marqueur crée uniquement un enregistrement de déploiement Azure Resource Manager.
Pour plus d’informations, consultez Déploiement de Microsoft.Resources
Exécuter l’évaluation exacte
Conservez le cycle de vie dans cet ordre :
- Rapprochez la définition d’évaluation archivée. Exécutez
azd up --no-promptquand le projet provisionne l’infrastructure. Pour un projet d’évaluation uniquement, exécutezazd ai eval create ci-f1-quality --no-promptà la place. Cette commande enregistre les jeux de données déclarés, les évaluateurs et l’évaluation sans provisionner aucune infrastructure. - Exécutez
azd ai eval run start --eval ci-f1-quality --no-prompt --no-wait -o json. - Lisez
.run_idà partir du JSON capturé sans écrire la valeur dans le journal. - Exécutez
azd ai eval run show <run-id> --eval ci-f1-quality --wait --fail-on pass-rate=0.8 --no-prompt -o json. - Exportez cette exécution exacte avec
azd ai eval run output export <run-id> --eval ci-f1-quality --format json --output-file <runner-temp-file> --no-prompt. - Validez l’état terminé, les totaux agrégés, les lignes exportées et les éléments de preuve sur liste autorisée avant le chargement.
Capturez la sortie standard brute et l’erreur standard dans RUNNER_TEMP. Stockez l’ID d’exécution en mémoire ou dans un fichier temporaire du runner, et utilisez-le uniquement comme argument positionnel pour les commandes output export et show.
Utilisez une étape GitHub Actions distincte pour chaque phase de cycle de vie. En cas de réussite, imprimez uniquement une ligne de commande et un résumé nettoyés, comme la réconciliation terminée, l’exécution acceptée avec son ID masqué, son état final et son nombre, le résultat du contrôle, le nombre de lignes exportées et l’aperçu des éléments de preuve sur liste autorisée.
Pour --fail-on pass-rate=0.8, le taux de réussite est le nombre de cas de test réussis divisé par le nombre total de cas de test. Les lignes en échec, en erreur, ignorées ou non réussies sont comptabilisées par rapport à l’exécution. Une exécution valide terminée en dessous du seuil est une non-conformité qualité. La CLI azd regroupe le code de sortie d’une extension, de sorte que la commande se ferme avec le code 1 pour une violation de qualité et pour une défaillance opérationnelle. Une violation de qualité imprime la raison du contrôle qualité et le message evaluation quality gate not met. Les échecs d’authentification, les erreurs réseau, les résultats malformés ou incomplets et les incohérences d’exportation sont des défaillances opérationnelles.
Charger uniquement la preuve figurant sur la liste d’autorisation
Créez un document de preuve à partir du résultat validé au lieu de charger la sortie brute de l’interface CLI ou du service. Conservez uniquement l’état d’agrégation, le nombre et le seuil, ainsi que les champs suivants pour chaque exemple révisé : query, , response, ground_truth, scoreet passed.
{
"status": "completed",
"counts": {
"passed": 2,
"failed": 0,
"errored": 0
},
"threshold": 0.8,
"samples": [
{
"query": "<allowlisted query>",
"response": "<allowlisted response>",
"ground_truth": "<allowlisted ground truth>",
"score": 1.0,
"passed": true
}
]
}
Avant le chargement, vérifiez que le répertoire d’artefacts contient uniquement le fichier de preuves attendu. N’imprimez jamais ni ne téléversez de jetons JWT, de points de terminaison, d’ID d’exécution, d’informations d’identification, d’informations utilisateur, de chaînes de requête d’URL ou de charges utiles brutes d’authentification, de CLI ou de service.
Conservez les fichiers bruts dans le stockage temporaire de l’exécuteur, masquez les diagnostics d’échec capturés et supprimez les fichiers dans un chemin de nettoyage always() ou finally.
Vérifier la passerelle
Exécutez le workflow manuellement à partir de la branche par défaut avant d’activer le blocage des demandes de tirage. Confirmez que :
- L’authentification OIDC réussit sans secret client.
- L’étape de réconciliation inscrit l’évaluation enregistrée.
- Le démarrage asynchrone est accepté sans afficher l’ID d’exécution.
- La commande
showsignalecompletedet applique le seuil de taux de réussite0.8. - L’exportation contient uniquement des lignes de cette exécution précise.
- L’artefact chargé contient uniquement le schéma de preuve de la liste d’autorisation.
- Les fichiers temporaires bruts du runner sont supprimés en cas de réussite et d’échec.
Résoudre les problèmes liés à la porte
| Symptôme | Résolution |
|---|---|
| Microsoft Entra ID rejette le jeton fédéré. | Comparez les revendications réelles iss, aud et sub du jeton avec les informations d’identification fédérées. Ne supposez pas un sujet d’environnement et ne copiez pas les ID d’un autre référentiel. |
azd up signale l’absence d’un abonnement, d’un emplacement ou d’un groupe de ressources. |
Configurez AZURE_SUBSCRIPTION_ID, AZURE_LOCATION et AZURE_RESOURCE_GROUP dans l’environnement protégé, et transmettez-les à la tâche. |
azd up ne peut pas trouver ou compiler infra/main.bicep. |
Ajoutez le modèle d’infrastructure inerte décrit dans cet article, ou rapprochez plutôt un projet d’évaluation uniquement à azd ai eval create. |
azd ai eval n’est pas une commande reconnue. |
Exécutez azd ext install azure.ai.evaluations, puis exécutez azd ext list pour confirmer que l’extension est installée. Le microsoft.foundry package ne l’inclut pas. |
| Le rapprochement retourne une erreur d’autorisation. | Affectez l’utilisateur Foundry uniquement sur le projet Foundry et, si vous utilisez azd up, Contributeur uniquement sur le groupe de ressources dédié. Laissez le temps nécessaire à la propagation de nouvelles attributions de rôles. |
La commande se termine avec le code 1 et affiche evaluation quality gate not met. |
Traitez le résultat comme une régression de qualité. Passez en revue les décomptes assainis et les exemples d’éléments probants figurant sur liste d’autorisation. |
La commande s’arrête avec le code 1 sans ce message. |
Traitez le résultat comme une défaillance opérationnelle. Inspectez uniquement les diagnostics expurgés pour l’authentification, le réseau, le résultat malformé, l’exécution incomplète ou les erreurs d’exportation. |
| Une pull request issue d’un fork tente de demander un jeton OIDC. | Exiger une vérification du head du même dépôt, laisser AZD_EVAL_LIVE_PR_GATE désactivé par défaut et ne pas utiliser pull_request_target. |
Après vérification, supprimez les ressources de test jetables et les attributions de rôles dont vous n’avez plus besoin. Supprimez les informations d’identification fédérées temporaires et conservez le groupe de ressources dédié uniquement si le quality gate continue de l’utiliser.