Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die Microsoft 365 Copilot Evaluations-CLI (@microsoft/m365-copilot-eval) enthält eine Reihe integrierter Evaluatoren. Wenn die integrierten Bewerter Ihr Szenario nicht abdecken, können Sie benutzerdefinierte Bewerter erstellen, um Agent-Antworten anhand domänenspezifischer Kriterien zu bewerten, z. B. Einhaltung gesetzlicher Vorschriften, Markenton oder eine benutzerdefinierte Relevanzrubrik.
Es gibt zwei Arten von benutzerdefinierten Auswertungen, und die CLI unterscheidet automatisch zwischen ihnen:
-
LLM-Judge-Evaluatoren (
<name>.pyund<name>.prompty) rufen ein Modell auf, um die Antwort zu bewerten. Sie benötigen eine Microsoft Foundry-Konfiguration und verwenden die Skala von 1 bis 5. -
Nur-Code-Evaluatoren (Nicht-LLM) (
<name>.pynur, nein<name>.prompty) sind reine Python-Prüfungen ohne Modellaufruf – zum Beispiel "Fehler, wenn die Antwort einen unzulässigen Begriff enthält". Sie benötigen keine Microsoft Foundry-Konfiguration und können eine beliebige numerische Bewertung zurückgeben.
Wenn Sie Ihre eigenen benutzerdefinierten Auswertungen verwenden möchten, erstellen Sie einen custom-evaluators/ Ordner im Stammverzeichnis Ihres Projekts (das Verzeichnis, in dem Sie die CLI ausführen), und fügen Sie einen Unterordner pro Auswertung hinzu. Zur Laufzeit scannt <your_project>/custom-evaluators/ die CLI automatisch und lädt nur die Auswertungen, auf die Ihr Bewertungsdokument verweist.
Ordnerlayout
Jede benutzerdefinierte Auswertung befindet sich in einem eigenen Unterordner. Ein LLM-Richtergutachter besteht aus zwei Akten; Eine Nur-Code-Auswertung ist genau die Datei .py :
<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
Das Vorhandensein von <name>.prompty ist das einzige Unterscheidungsmerkmal: Damit ist der Bewerter ein LLM-Juror; ohne es ist es nur ein Code.
Benennungsregeln
- Der Ordnername, der Evaluatorname und die Dateibasisnamen müssen genau übereinstimmen.
- Namen müssen mit dem Muster
^[a-zA-Z][a-zA-Z0-9_]*$übereinstimmen (ein gültiger Bezeichner: Beginnen Sie mit einem Buchstaben, gefolgt von Buchstaben, Ziffern oder Unterstrichen). - Namen dürfen nicht mit den Namen der integrierten Auswertung kollidieren (Groß-/Kleinschreibung wird nicht beachtet):
Relevance,Coherence,Groundedness,CitationsExactMatchToolCallAccuracyPartialMatchSimilarityRetrievalQueryund .RetrievalResultUm eine auf die Domäne zugeschnittene Version eines integrierten Evaluators zu erstellen,domain_relevancestellen Sie seinem Namen das Präfix voran, z. B. anstelle vonrelevance.
Verfassen eines LLM-Richtergutachters
Ein LLM-Richterauswertungator verfügt über zwei Dateien: eine .prompty Datei, die die Richtereingabeaufforderung definiert, und einen .py Wrapper, der sie ausführt.
Die Datei ".prompty"
Eine .prompty Akte ist die Aufforderung des LLM-Richters. Es hat eine Modellkonfiguration in der YAML-Frontmaterie über dem --- Trennzeichen, dann system: und user: Abschnitte darunter. Variablen{{var}}, auf die wie in der Körperzuordnung zu den Schlüsselwort (keyword)-Argumenten verwiesen wird, die Ihr Wrapper an den Prompt-Flow übergibt.
Das folgende Beispiel zeigt eine minimale professional_tone.prompty Datei:
---
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}}
Sie müssen einen inputs: Block in der Frontmaterie deklarieren, der jede Variable auflistet, die Ihre Vorlage verwendet. Ohne sie filtert promptflow alle Schlüsselwort-(Schlüsselwort)-Argumente heraus, und Ihre Vorlage wird mit leeren {{var}} Ersetzungen gerendert. Das Modell sieht eine leere Eingabeaufforderung, und Sie erhalten eine Fehler- oder Nonsense-Bewertung. Jede Eingabe benötigt einen type: Wert, der typischerweise stringist.
Hinweis
Die promptflow-Laufzeitreserven prompt sind ein interner Parameter. Vermeiden Sie daher die Verwendung {{prompt}} (und eine inputs.prompt Deklaration) in Ihrer Promptvorlage. Verwenden Sie einen anderen Variablennamen, z. B {{user_prompt}}. , und lassen Sie den Wrapper den Wert unter diesem Namen weiterleiten, wenn der Prompt-Flow aufgerufen wird.
Der .py Wrapper
Das Python-Modul muss eine Klasse exportieren. Die CLI importiert das Modul dynamisch und instanziiert die erste gefundene Klasse der obersten Ebene. Die Klasse muss mit dem folgenden Vertrag übereinstimmen:
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>",
# }
...
Das Framework besitzt result und threshold: es leitet result = "pass" if score >= threshold else "fail" und fügt thresholdan, sodass Sie sie nicht zurückgeben. Die CLI schreibt den score Schlüssel beim Zusammenführen der Ergebnisse in die einheitliche Ausgabe in den Ordnernamen Ihres Bewerters um, sodass die Punktzahl wie <folder_name> in den JSON-, CSV- und HTML-Berichten angezeigt wird.
Sie müssen Ihre __call__/tryexcept. Wenn Ihr Wrapper eine Ausnahme auslöst, fängt die CLI diese ab und gibt ein error Ergebnis für diese Auswertung aus, während der Rest der Ausführung fortgesetzt wird. Um die Fehlermeldung selbst zu steuern, geben Sie ein Diktat über den dedizierten Fehlerkanal zurück (nur die error Nachricht wird beibehalten; alle anderen Schlüssel werden fallen gelassen):
{ "error": "<explanation>" }
Einschränkungen der Bewertung
Für einen LLM-Richter-Bewerter score muss es sich um eine ganze Zahl im Bereich [1, 5] handeln (dieselbe Skala von 1 bis 5 wie bei den integrierten LLM-Bewertern). Gleitkommawerte, bei denen es sich um mathematisch ganze Zahlen handelt (z. B 4.0. ), werden akzeptiert und normalisiert. Alles außerhalb dieses Bereichs, ein nicht numerischer Wert oder ein fehlender score Schlüssel führt zu einem error Ergebnis. Der Bewertungslauf wird mit den anderen Auswertungen fortgesetzt.
Constructorparameter absorbieren, die Sie nicht verwenden
Der Rahmen geht immer und thresholdoptions zu __init__ (plus model_config für LLM-Richterevaluatoren). Python erfordert, dass Sie __init__ jedes Schlüsselwort (Keyword) akzeptieren, mit dem es aufgerufen wird, aber Sie müssen keine Namen nennen, die Sie ignorieren. Nennen Sie einen Parameter nur, wenn Sie ihn tatsächlich verwenden. Nimm alles andere mit einem **_ Catch-All auf:
# 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",
}
Benennen Sie keine Teilmenge von Parametern ohne ein Catch-All. Erhöht TypeErrorzum Beispiel def __init__(self, *, options=None) , weil das Framework immer noch besteht threshold= und nichts es akzeptiert. Fügen Sie (oder benennen) thresholdhinzu **_ , um das Problem zu beheben.
Konventionen für Schlüsselwortargumente
Die CLI ruft Ihre __call__ Methode mit dem folgenden festen Satz von Schlüsselwort (keyword)-Argumenten auf. Alle vier werden an Ihren Bewerter (den LLM-Richter) übergeben, nicht an den zu prüfenden Agenten.
| Argument | Beschreibung | Typische Verwendung bei einem Richter |
|---|---|---|
prompt |
Die Frage oder Anweisung des Benutzers, die an den Agent gesendet wurde. | Überprüfen Sie die Reaktionsfähigkeit. |
response |
Die tatsächliche Antwort des Agenten (das Ding, das bewertet wird). | Das Thema der Bewertung. |
expected_response |
Eine Referenz oder ideale Antwort aus der expected_response Praxis. |
Überprüfen Sie die Genauigkeit anhand der Referenz. |
context |
Erdungs- oder Quellenmaterial, dem die Antwort treu sein sollte, aus dem context Feld. |
Überprüfe die Bodenständigkeit (keine Widersprüche oder Halluzinationen). |
Die promptArgumente , expected_response, und context stammen direkt aus dem aktuellen Element (oder Turn) in Ihrem Bewertungsdokument. Das response Argument ist die tatsächliche Ausgabe des Agents, die erfasst wird, wenn die CLI an den zu testenden Agenten sendet prompt . Insbesondere context ist die Grundlage nur für den Richter - der Agent sieht oder ruft sie nie ab.
Die expected_response Felder "und context " sind im Bewertungsdokument optional. Wenn sie nicht vorhanden sind, übergibt die CLI eine leere Zeichenfolge. Da die CLI immer alle vier Argumente übergibt, deklarieren Sie die von Ihnen verwendeten und absorbieren Sie den Rest mit **_. Eine __call__ Methode, die eine der vier ohne **_ Catch-All auslässt TypeError, erhöht und dieser Bewerter meldet ein error Ergebnis.
Vorbereiten model_config für load_flow
Die promptflow.client.load_flow Laufzeit benötigt ein type Feld im Konfigurationsdiktat , um die richtige Verbindungsklasse auszuwählen (AzureOpenAI versus OpenAI). Das AzureOpenAIModelConfiguration Feld, das die CLI Ihnen übergibt, enthält dieses Feld nicht, also fügen Sie es hinzu, bevor Sie Folgendes aufrufen 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})
Ohne diesen Schritt wird der irreführende Fehler Not Support connection type None for embedding api zum Zeitpunkt des Aufrufs angezeigt.
Erstellen einer Nur-Code-Evaluatorin
Eine Nur-Code-Auswertung ist ein Ordner mit nur <name>.py und ohne <name>.prompty. Die CLI erkennt die fehlende Prompty und behandelt den Evaluator als reine Python-Prüfung. Er ruft nie ein Modell auf, sodass eine Ausführung, die nur Code-Evaluatoren verwendet, keine Microsoft Foundry-Konfiguration benötigt.
Verwenden Sie Nur-Code-Evaluatoren für deterministische, regelbasierte Prüfungen: Scans nach verbotenen Begriffen, RegEx- oder Formatvalidierung, Längenbeschränkungen, JSON-Schema-Konformität und so weiter.
Die meisten reinen Code-Evaluatoren sind eine einfache Pass/Fail-Prüfung. Die idiomatische Art, diese Prüfung auszudrücken, besteht darin score: 1 , für bestanden und score: 0 nicht bestanden zurückzukehren und den Standardschwellenwert von 1 beizubehalten. Das Framework leitet result = "pass" dann ab, wann score (1) größer oder gleich threshold (1) ist und "fail" wenn score (0) kleiner als threshold (1) ist.
Die __init__ Methode für eine Nur-Code-Auswertung lässt Folgendes aus 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",
}
In der folgenden Tabelle wird zusammengefasst, wie sich Nur-Code-Evaluatoren von LLM-Jud-Evaluatoren unterscheiden.
| Aspekt | LLM-Richter (.py + .prompty) |
Nur Code (.py nur) |
|---|---|---|
__init__ Argumente |
model_config, threshold, options |
threshold, options (no model_config) |
score |
Ganzzahl 1-5 | Beliebige Zahl, keine 1-5-Klemme (normalerweise 0 oder 1) |
| Standardschwellenwert | 3 | 1 |
| Foundry Konfiguration | Erforderlich | Nicht erforderlich |
Ergebnisvertrag
Das Framework besitzt result und threshold für beide Arten von Bewertern. Bei Erfolg nur {"score", "reason"}zurückgeben ; das Framework leitet result = "pass" if score >= threshold else "fail" ab und fügt an threshold. Um einen Fehler zu melden, lösen Sie eine Ausnahme aus, oder geben Sie zurück {"error": "<msg>"}.
Die Punktzahlen müssen so ausgerichtet sein, dass höher besser ist, da der Rahmen besteht, wenn score >= threshold. Mit dem standardmäßigen Nicht-LLM-Schwellenwert von 1codieren Sie ein boolesches Ergebnis als 1 (pass) oder 0 (fail). Legen Sie den Schwellenwert im Bewertungsdokument so fest, dass er der von Ihrer Bewertung verwendeten Skala entspricht – es gibt keine [1, 5] Einschränkungen für Nur-Code-Evaluatoren. Geben Sie für eine benotete Prüfung eine bruchteilige Punktzahl zurück, und legen Sie einen Bruchwert fest. Beispielsweise würde ein Evaluator für partielle Übereinstimmungen, der ein Verhältnis in [0, 1] zurückgibt threshold: 0.7 , eine Übereinstimmung von 70 % erfordern.
Tipp
Da eine fehlende .prompty Datei einen Evaluator stillschweigend in einen reinen Code-Evaluator verwandelt, schützt die CLI vor einer versehentlich ausgelassenen Prompty: Wenn der Code eines .pyNur-Evaluators auf LLM-Maschinen verweist (load_flow, promptflow, model_configoder .prompty), protokolliert die CLI eine Warnung, die darauf hindeutet, dass Sie die Prompty-Datei möglicherweise vergessen haben. Die Warnung blockiert niemals die Ausführung.
Verweisen auf benutzerdefinierte Auswertungen aus einem Bewertungsdokument
Fügen Sie der evaluators Karte benutzerdefinierte Auswertungen hinzu, genau wie integrierte Auswertungen. Der Schwellenwert ist standardmäßig für LLM-Richterbewerter (die Skala 1-5) und 1 für Nur-Code-Bewerter festgelegt3. Legen Sie den Schwellenwert explizit fest, wenn Sie einen anderen Grenzwert wünschen:
{
"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 }
}
}
}
]
}
Verwenden Sie evaluators_mode (extend oder replace) genau wie bei integrierten Evaluatoren, um zu steuern, ob die benutzerdefinierte Evaluator neben den Standardwerten ausgeführt wird oder diese ersetzt. Weitere Informationen finden Sie unter Konfigurieren von Evaluatoren.
Sicherheitsmodell
Benutzerdefinierte Auswertungen werden mit denselben Berechtigungen wie die CLI selbst ausgeführt. Überprüfen Sie den Code in einer beliebigen benutzerdefinierten Auswertung, bevor Sie ihn Ihrem Projekt hinzufügen – er kann alles, was Python kann.
Weitere Informationen zum Prompty-Format
Das .prompty Format ist ein offener Microsoft-Standard für LLM-Eingabeaufforderungen. Eine vollständige Liste der Frontmatter-Felder, Modellparameter, Vorlagensyntax und unterstützten Anbieter finden Sie in den folgenden Ressourcen:
- prompty.ai – Übersicht und Anleitungen.
- microsoft/prompty – Quell- und TypeSpec-Schema.
Der model.parameters Block wird direkt an die Chat Completions-API weitergeleitet, sodass Parameter wie temperature, max_tokens, top_p, response_formatseed, und stop alle verfügbar sind.
Problembehandlung
Verwenden Sie die folgende Tabelle, um häufige Probleme mit benutzerdefinierten Evaluatoren zu beheben.
| Symptom | Wahrscheinliche Ursache und nächster Schritt |
|---|---|
Unknown evaluator '<name>' |
Vergewissern Sie sich, dass sich der Ordner unter <your_project>/custom-evaluators/<name>/befindet, ob die Dateibasisnamen mit dem Ordnernamen übereinstimmen und ob Sie die CLI aus dem Projektstamm ausführen. |
Custom evaluator '<name>' is missing required file '<name>.py' |
Jeder Evaluator-Ordner muss enthalten <name>.py. Eine <name>.prompty Datei wird nur für LLM-Richterevaluatoren benötigt; lassen Sie sie für reine Code-Evaluatoren weg. |
Custom evaluator '<name>' failed to import |
Ein Python-Syntaxfehler oder eine fehlende Abhängigkeit in Ihrer .py Datei. Die Fehlermeldung enthält die zugrunde liegende Ausnahme. |
Ergebnis wird mit Grund angezeigt errorcould not parse score |
Das Modell hat keinen wohlgeformten JSON-Code zurückgegeben. Stellen Sie sicher, dass Ihre Eingabeaufforderung über response_format: { type: json_object } (oder ein entsprechendes JSON-Schema) verfügt und dass die Vorlage explizit nach dem {"score": ..., "reason": ...} Shape fragt. |
Für umfangreichere Protokolle führen Sie die CLI mit --log-level debugaus.