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.
L’interface de ligne de commande des évaluations de Microsoft 365 Copilot inclut@microsoft/m365-copilot-eval un ensemble d’évaluateurs intégrés. Lorsque les évaluateurs intégrés ne couvrent pas votre scénario, vous pouvez créer des évaluateurs personnalisés pour noter les réponses des agents en fonction de critères spécifiques au domaine, tels que la conformité réglementaire, le ton de marque ou une rubrique de pertinence personnalisée.
Il existe deux types d’évaluateurs personnalisés, et l’interface de ligne de commande les distingue automatiquement :
-
Les évaluateurs (
<name>.pyet<name>.prompty) appellent un modèle pour noter la réponse. Ils ont besoin de la configuration de Microsoft Foundry et utilisent l’échelle de 1 à 5. -
Les évaluateurs code-only (non-LLM) (
<name>.pyuniquement, non<name>.prompty) sont des vérifications Python pures sans appel de modèle - par exemple, « fail si la réponse contient un terme interdit ». Ils ne nécessitent aucune configuration Microsoft Foundry et peuvent retourner n’importe quel score numérique.
Pour utiliser vos propres évaluateurs personnalisés, créez un custom-evaluators/ dossier à la racine de votre projet (le répertoire à partir duquel vous exécutez l’CLI) et ajoutez un sous-dossier par évaluateur. Au moment de l’exécution, l’interface de ligne de <your_project>/custom-evaluators/ commande analyse automatiquement et charge uniquement les évaluateurs auxquels votre document d’évaluation fait référence.
Disposition du dossier
Chaque évaluateur personnalisé se trouve dans son propre sous-dossier. Un évaluateur LLM-juge se compose de deux dossiers ; Un évaluateur de code uniquement correspond simplement au .py fichier :
<your_project>/
custom-evaluators/
professional_tone/ # LLM-judge: has a .prompty
professional_tone.prompty # the LLM judge prompt
professional_tone.py # the Python wrapper that runs it
consistency_check/
consistency_check.prompty
consistency_check.py
forbidden_terms/ # code-only: NO .prompty
forbidden_terms.py # pure Python check, no model call
La présence de <name>.prompty est le seul discriminant : avec elle, l’évaluateur est un juge LLM ; sans elle, c’est du code uniquement.
Règles de nommage
- Le nom du dossier, le nom de l’évaluateur et les noms de base des fichiers doivent correspondre exactement.
- Les noms doivent correspondre au modèle
^[a-zA-Z][a-zA-Z0-9_]*$(identificateur valide : commencer par une lettre, suivie de lettres, de chiffres ou de traits de soulignement). - Les noms ne doivent pas entrer en conflit avec les noms d’évaluateurs intégrés (non-respect de la casse) :
Relevance, ,Coherence,PartialMatchCitationsGroundednessToolCallAccuracyExactMatchSimilarityRetrievalQueryet .RetrievalResultPour créer une version adaptée au domaine d’un évaluateur intégré, utilisez le préfixe de son nom, par exemple,domain_relevanceau lieu derelevance.
Rédiger un évaluateur LLM-judge
Un évaluateur LLM-judge a deux fichiers : un .prompty fichier qui définit l’invite du juge et un .py wrapper qui l’exécute.
Fichier .prompty
Un .prompty fichier est l’invite du juge LLM. Il a une configuration de modèle en YAML frontmatter au-dessus du --- séparateur, puis system: et user: les sections en dessous. Les variables référencées comme {{var}} dans le corps correspondent aux arguments de mot clé que votre wrapper transmet au flux prompty.
L’exemple suivant montre un fichier minimal professional_tone.prompty :
---
name: professional_tone
description: Scores professional tone 1-5.
model:
api: chat
parameters:
temperature: 0.0
max_tokens: 400
response_format:
type: json_object
inputs:
user_prompt:
type: string
response:
type: string
---
system:
You score professional tone 1 (hostile) to 5 (consistently professional).
Reply with only: {"score": <int 1-5>, "reason": "<one sentence>"}
user:
# User prompt
{{user_prompt}}
# Agent response
{{response}}
Vous devez déclarer un inputs: bloc dans le frontmatter qui répertorie toutes les variables utilisées par votre modèle. Sans lui, promptflow filtre tous les arguments de mot clé et votre modèle s’affiche avec des substitutions vides {{var}} - le modèle voit une invite vide et vous obtenez une erreur ou un score absurde. Chaque entrée a besoin d’une type: valeur, qui est généralement string.
Remarque
Les réserves prompt d’exécution promptflow en tant que paramètre interne, évitez donc d’utiliser {{prompt}} (et une inputs.prompt déclaration) dans votre modèle prompty. Utilisez un autre nom de variable, tel que {{user_prompt}}, et faites en sorte que votre wrapper transfère la valeur sous ce nom lorsqu’il appelle le flux d’invite.
L’emballage .py
Le module Python doit exporter une classe. L’interface de ligne de commande importe dynamiquement le module et instancie la première classe de premier niveau qu’elle trouve. Le groupe doit correspondre au contrat suivant :
class MyEvaluator:
def __init__(self, *, model_config, threshold, options=None):
# model_config: AzureOpenAIModelConfiguration
# threshold: numeric pass/fail threshold
# options: dict of extra config from the eval document
...
def __call__(
self,
*,
prompt: str = "",
expected_response: str = "",
response: str = "",
context: str = "",
**_, # accept extras for forward compatibility
) -> dict:
# On success, return a flat dict with just:
# {
# "score": <integer 1-5>,
# "reason": "<explanation>",
# }
...
Le framework possède result et threshold: il dérive result = "pass" if score >= threshold else "fail" et attache threshold, donc vous ne les retournez pas. L’interface de ligne de commande réécrit la score clé du nom de dossier de votre évaluateur lorsqu’il fusionne les résultats dans la sortie unifiée, de sorte que le score s’affiche comme <folder_name> dans les rapports JSON, CSV et HTML.
Vous n’avez pas besoin d’envelopper votre __call__ .try/except Si votre wrapper lève une exception, l’interface CLI l’intercepte et émet un error résultat pour cet évaluateur tandis que le reste de l’exécution se poursuit. Pour contrôler vous-même le message d’erreur, renvoyez un dict via le canal d’erreur dédié (seul le error message est conservé ; toutes les autres clés sont supprimées) :
{ "error": "<explanation>" }
Contraintes de score
Pour un évaluateur de LLM, score doit être un entier dans la plage [1, 5] (la même échelle de 1 à 5 que les évaluateurs LLM intégrés). Les valeurs flottantes qui sont mathématiquement des entiers (par exemple, 4.0) sont acceptées et normalisées. Tout élément en dehors de cette plage, une valeur non numérique ou une clé manquante score produit un error résultat ; l’exécution de l’évaluation se poursuit avec les autres évaluateurs.
Absorber les paramètres de constructeur que vous n’utilisez pas
Le cadre passe threshold toujours et options à __init__ (plus model_config pour les évaluateurs de LLM). Python exige que vous __init__ acceptiez chaque mot clé avec lequel il est appelé, mais vous n’avez pas à nommer ceux que vous ignorez. Nommez un paramètre uniquement si vous l’utilisez réellement. Absorbez tout le reste avec un **_ fourre-tout :
# Names only what it uses (options), absorbs the rest (threshold, and so on):
class ForbiddenTermsEvaluator:
def __init__(self, *, options=None, **_):
self._terms = (options or {}).get("terms", [])
# A check that needs no configuration at all - absorb everything:
class NonEmptyEvaluator:
def __init__(self, **_): # ignores model_config, threshold, options
pass
def __call__(self, *, response: str = "", **_) -> dict:
return {
"score": 1 if response.strip() else 0,
"reason": "non-empty" if response.strip() else "empty response",
}
Ne nommez pas un sous-ensemble de paramètres sans « fourre-tout ». Par exemple, def __init__(self, *, options=None) augmente TypeError, car le cadre passe threshold= toujours et rien ne l’accepte. Ajoutez **_ (ou nom threshold) pour résoudre le problème.
Conventions d’arguments de mot clé
L’interface de ligne de commande appelle votre __call__ méthode avec l’ensemble fixe d’arguments de mot clé suivant. Les quatre sont transmis à votre évaluateur (le juge LLM), et non à l’agent testé.
| Argument | Description | Utilisation typique chez un juge |
|---|---|---|
prompt |
Question ou instruction de l’utilisateur envoyée à l’agent. | Vérifiez la réactivité. |
response |
Réponse réelle de l’agent (l’élément noté). | Le sujet de l’évaluation. |
expected_response |
Une référence ou une expected_response réponse idéale, du terrain. |
Vérifiez l’exactitude par rapport à la référence. |
context |
Ancrage ou matériel source auquel la réponse doit être fidèle, du context terrain. |
Vérifiez l’ancrage (pas de contradictions ou d’hallucinations). |
Les promptarguments , expected_responseet context proviennent directement de l’élément actuel (ou du tour) dans votre document d’évaluation. L’argument response est la sortie réelle de l’agent, capturée lorsque l’interface CLI envoie prompt à l’agent testé. En particulier, context l’ancrage n’appartient qu’au juge - l’agent ne le voit ni ne le récupère jamais.
Les expected_response champs et context sont facultatifs dans le document d’évaluation. En l’absence de l’interface de ligne de commande, celle-ci transmet une chaîne vide. Étant donné que l’interface de ligne de commande passe toujours les quatre arguments, déclarez ceux que vous utilisez et absorbez le reste avec **_. Une __call__ méthode qui omet l’une des quatre sans **_ fourre-tout relance TypeError, et cet évaluateur rapporte un error résultat.
Préparer model_config pour load_flow
Le promptflow.client.load_flow runtime a besoin d’un type champ sur le dict de configuration pour choisir la bonne classe de connexion (AzureOpenAI versus OpenAI). Le AzureOpenAIModelConfiguration fait que l’interface de ligne de commande vous passe ne porte pas ce champ, donc ajoutez-le avant d’appeler load_flow:
prepared_config = dict(model_config)
prepared_config.setdefault(
"type",
"azure_openai" if "azure_endpoint" in prepared_config else "openai",
)
self._flow = load_flow(source=prompty_path, model={"configuration": prepared_config})
Sans cette étape, l’erreur Not Support connection type None for embedding api trompeuse apparaît au moment de l’appel.
Créer un évaluateur de code uniquement
Un évaluateur de code uniquement est un dossier avec uniquement <name>.py et pas <name>.promptyde . L’interface CLI détecte le prompty manquant et traite l’évaluateur comme une case activée Python pure. Elle n’appelle jamais un modèle, de sorte qu’une exécution qui utilise uniquement des évaluateurs de code uniquement n’a pas besoin de configuration Microsoft Foundry.
Utilisez des évaluateurs de code uniquement pour les vérifications déterministes basées sur des règles : analyses à terme interdit, validation des expressions régulières ou des formats, limites de longueur, conformité au schéma JSON, etc.
La plupart des évaluateurs de code uniquement sont une simple vérification de réussite/échec de case activée. La façon idiomatique d’exprimer cette case activée est de revenir score: 1 pour réussite et score: 0 pour échec, et de laisser le seuil par défaut en 1 place. Le cadre dérive result = "pass" alors lorsque score (1) est supérieur ou égal à (1), et "fail" lorsque score (0) est inférieur à thresholdthreshold (1).
La __init__ méthode d’un évaluateur de code uniquement omet model_config:
class ForbiddenTermsEvaluator:
def __init__(self, *, threshold, options=None):
self._terms = (options or {}).get("terms", [])
def __call__(self, *, response: str = "", **_) -> dict:
hit = [t for t in self._terms if t.lower() in response.lower()]
# Default threshold is 1, so 1 -> pass, 0 -> fail.
return {
"score": 0 if hit else 1,
"reason": f"Found: {', '.join(hit)}" if hit else "clean",
}
Le tableau suivant résume en quoi les évaluateurs de code uniquement diffèrent des évaluateurs de LLM.
| Aspect | LLM-juge (.py + .prompty) |
Code uniquement (.py uniquement) |
|---|---|---|
__init__ Arguments |
model_config, threshold, options |
threshold, options (Non model_config) |
score |
Nombre entier 1-5 | N’importe quel nombre, pas de pince de 1 à 5 (généralement 0 ou 1) |
| Seuil par défaut | 3 | 1 |
| Configuration de la fonderie | Obligatoire | Non requis |
Contrat de résultat
Le cadre possède result et threshold pour les deux types d’évaluateurs. En cas de succès, revenez juste {"score", "reason"}; le cadre dérive result = "pass" if score >= threshold else "fail" et attache threshold. Pour signaler un échec, levez une exception ou revenez {"error": "<msg>"}.
Les scores doivent être orientés de manière à ce que le plus haut soit le mieux, car le cadre passe lorsque score >= threshold. Avec le seuil non-LLM par défaut de 1, encodez un résultat booléen comme 1 (pass) ou 0 (fail). Définissez le seuil dans le document d’évaluation pour qu’il corresponde à l’échelle utilisée par votre score - il n’y a aucune [1, 5] contrainte pour les évaluateurs de code uniquement. Pour une case activée notée, renvoyez un score fractionnaire et définissez un seuil fractionnaire. Par exemple, un évaluateur de correspondance partielle qui renvoie un ratio [0, 1] nécessiterait threshold: 0.7 une correspondance de 70 %.
Conseil
Étant donné qu’un fichier manquant .prompty transforme silencieusement un évaluateur en un fichier codé uniquement, l’interface CLI se protège contre une invite accidentellement omise : si le code d’un .pyévaluateur -only fait référence à des machines LLM (load_flow, promptflow, model_config, ou ), .promptyl’interface CLI enregistre un avertissement qui suggère que vous avez peut-être oublié le fichier d’invite. L’avertissement ne bloque jamais la course.
Référencer des évaluateurs personnalisés à partir d’un document d’évaluation
Ajoutez des évaluateurs personnalisés à la evaluators carte, comme des évaluateurs intégrés. Le seuil par 3 défaut est pour les évaluateurs LLM-judge (l’échelle de 1 à 5) et 1 pour les évaluateurs de code uniquement. Définissez le seuil explicitement si vous souhaitez une autre limite :
{
"schemaVersion": "1.7.0",
"items": [
{
"prompt": "How do I file an expense report?",
"evaluators": {
"Relevance": {},
"professional_tone": { "threshold": 4 },
"consistency_check": {
"threshold": 3,
"options": { "samples": 5 }
}
}
}
]
}
Utilisez evaluators_mode (extend ou replace) exactement comme vous le feriez avec les évaluateurs intégrés pour contrôler si l’évaluateur personnalisé s’exécute avec les valeurs par défaut ou les remplace. Pour plus d’informations, consultez Configurer les évaluateurs.
Modèle de sécurité
Les évaluateurs personnalisés s’exécutent avec les mêmes autorisations que l’interface de ligne de commande elle-même. Passez en revue le code dans n’importe quel évaluateur personnalisé avant de l’ajouter à votre projet : il peut faire tout ce que Python peut faire.
En savoir plus sur le format .prompty
Le .prompty format est une norme Microsoft ouverte pour les invites LLM. Pour obtenir la liste complète des champs frontmatter, des paramètres de modèle, de la syntaxe de modèle et des fournisseurs pris en charge, consultez les ressources suivantes :
- prompty.ai : vue d’ensemble et guides pratiques.
- microsoft/prompty : schéma source et TypeSpec.
Le model.parameters bloc passe directement à l’API de saisie semi-automatique de chat, donc les paramètres tels que temperature, response_formatseedmax_tokenstop_pet stop sont tous disponibles.
Résolution des problèmes
Utilisez le tableau suivant pour résoudre les problèmes courants liés à l’évaluateur personnalisé.
| Symptôme | Cause probable et prochaine étape |
|---|---|
Unknown evaluator '<name>' |
Vérifiez que le dossier se trouve à <your_project>/custom-evaluators/<name>/, que les noms de base des fichiers correspondent au nom du dossier et que vous exécutez l’interface de ligne de commande à partir de la racine du projet. |
Custom evaluator '<name>' is missing required file '<name>.py' |
Chaque dossier d’évaluateur doit contenir <name>.py. Un <name>.prompty fichier n’est nécessaire que pour les évaluateurs de LLM ; omettez-le pour ceux qui n’ont que du code. |
Custom evaluator '<name>' failed to import |
Une erreur de syntaxe Python ou une dépendance manquante dans votre .py fichier. Le message d’erreur inclut l’exception sous-jacente. |
Le résultat s’affiche error avec raison could not parse score |
Le modèle n’a pas renvoyé de JSON bien formé. Vérifiez que votre prompty a response_format: { type: json_object } (ou un schéma JSON équivalent) et que le modèle demande explicitement la {"score": ..., "reason": ...} forme. |
Pour obtenir des journaux plus riches, exécutez l’interface de ligne de commande avec --log-level debug.