Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
L'interfaccia della riga di comando di Microsoft 365 Copilot Evaluations (@microsoft/m365-copilot-eval) include un set di analizzatori integrati. Quando i valutatori predefiniti non coprono lo scenario, è possibile creare valutatori personalizzati per assegnare un punteggio alle risposte degli agenti in base a criteri specifici del dominio, ad esempio la conformità alle normative, il tono del marchio o una rubrica di pertinenza personalizzata.
Esistono due tipi di analizzatori personalizzati e l'interfaccia della riga di comando li distingue automaticamente:
-
I valutatori dei giudici LLM (
<name>.py<name>.promptye ) chiamano un modello per assegnare un punteggio alla risposta. Hanno bisogno della configurazione di Microsoft Foundry e usano la scala da 1 a 5. -
Gli analizzatori di solo codice (non LLM) (
<name>.pysolo, no<name>.prompty) sono controlli Python puri senza chiamata di modello, ad esempio "fail se la risposta contiene un termine non consentito". Non è necessaria alcuna configurazione di Microsoft Foundry e possono restituire qualsiasi punteggio numerico.
Per usare analizzatori personalizzati, creare una custom-evaluators/ cartella nella radice del progetto (la directory da cui si esegue l'interfaccia della riga di comando) e aggiungere una sottocartella per ogni analizzatore. In fase di esecuzione, l'interfaccia della riga di <your_project>/custom-evaluators/ comando esegue automaticamente la scansione e carica solo gli analizzatori a cui fa riferimento il documento di valutazione.
Layout cartella
Ogni analizzatore personalizzato si trova nella propria sottocartella. Un valutatore di giudici LLM è composto da due file; Un analizzatore di solo codice è solo il .py file:
<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 presenza di <name>.prompty è l'unico discriminatore: con esso, il valutatore è un giudice LLM; senza di esso, è solo codice.
Regole di denominazione
- Il nome della cartella, il nome dell'analizzatore e i nomi di base dei file devono corrispondere esattamente.
- I nomi devono corrispondere al modello
^[a-zA-Z][a-zA-Z0-9_]*$(un identificatore valido: inizia con una lettera, seguita da lettere, cifre o caratteri di sottolineatura). - I nomi non devono entrare in conflitto con i nomi degli analizzatori predefiniti (senza distinzione tra maiuscole e minuscole):
Relevance,Coherence,Groundedness,Similarity,RetrievalQueryExactMatchPartialMatchToolCallAccuracyCitationse .RetrievalResultPer creare una versione personalizzata per il dominio di un analizzatore predefinito, anteponine il nome, ad esempio,domain_relevanceanzichérelevance.
Crea un valutatore LLM
Un valutatore arbitrale LLM ha due file: un .prompty file che definisce il prompt arbitrale e un .py wrapper che lo esegue.
File .prompty
Un .prompty file è il prompt del giudice LLM. Ha una configurazione del modello nella parte introduttiva YAML sopra il --- separatore, quindi system: e user: sezioni sotto di esso. Le variabili a cui viene fatto riferimento, come {{var}} nel corpo, sono mappate agli argomenti delle parole chiave che il wrapper passa al flusso prompty.
L'esempio seguente mostra un file minimo 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}}
Devi dichiarare un inputs: blocco nella parte introduttiva che elenca ogni variabile utilizzata dal tuo template. Senza di esso, promptflow filtra tutti gli argomenti delle parole chiave e il template viene visualizzato con sostituzioni vuote {{var}} : il modello vede un prompt vuoto e si ottiene un errore o un punteggio senza senso. Ogni input richiede un type: valore, che in genere stringè .
Nota
Il runtime promptflow viene riservato prompt come parametro interno, quindi evita di usare {{prompt}} (e una inputs.prompt dichiarazione) nel modello prompty. Usa un nome di variabile diverso, ad esempio {{user_prompt}}, e fai in modo che il wrapper inoltri il valore sotto quel nome quando chiama il flusso prompty.
Wrapper .py
Il modulo Python deve esportare una classe. L'interfaccia della riga di comando importa dinamicamente il modulo e crea un'istanza della prima classe di primo livello trovata. La classe deve corrispondere al seguente contratto:
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>",
# }
...
Il framework possiede result e : deriva result = "pass" if score >= threshold else "fail" e allega threshold, quindi non li thresholdrestituisci. L'interfaccia della riga di comando riscrive la chiave con il score nome della cartella del valutatore quando unisce i risultati nell'output unificato, in modo che il punteggio venga visualizzato come <folder_name> nei report JSON, CSV e HTML.
Non hai bisogno di avvolgere il tuo __call__ .try/except Se il wrapper genera un'eccezione, l'interfaccia della riga di comando la rileva ed genera un error risultato per il valutatore mentre il resto dell'esecuzione continua. Per controllare il messaggio di errore manualmente, restituire un dict attraverso il canale di errore dedicato (viene mantenuto solo il error messaggio, tutte le altre chiavi vengono eliminate):
{ "error": "<explanation>" }
Vincoli del punteggio
Per un valutatore LLM, score deve essere un numero intero nell'intervallo [1, 5] (la stessa scala 1-5 dei valutatori LLM integrati). I valori float che sono numeri interi dal punto di vista matematico (ad esempio, 4.0) vengono accettati e normalizzati. Qualsiasi elemento esterno a questo intervallo, un valore non numerico o una chiave mancante score produce un error risultato. L'esecuzione della valutazione continua con gli altri analizzatori.
Assorbe i parametri del costruttore non utilizzati
Il framework passa threshold sempre e options a __init__ (più model_config per i valutatori LLM-giudici). Python richiede di __init__ accettare ogni parola chiave con cui viene chiamato, ma non è necessario nominare quelle che si ignorano. Assegnare un nome a un parametro solo se viene effettivamente utilizzato. Assorbi qualsiasi altra cosa con un **_ catch-all:
# 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",
}
Non nominare un sottoinsieme di parametri senza un catch-all. Ad esempio, def __init__(self, *, options=None) genera TypeError, perché il framework passa threshold= ancora e nulla lo accetta. Aggiungi **_ (o nomina threshold) per risolverlo.
Convenzioni degli argomenti per parole chiave
L'interfaccia della riga di comando chiama il __call__ metodo con il seguente set fisso di argomenti delle parole chiave. Tutti e quattro vengono passati al tuo valutatore (il giudice LLM), non all'agente in esame.
| Argomento | Che cos'è | Uso tipico in un giudice |
|---|---|---|
prompt |
La domanda o le istruzioni dell'utente inviate all'agente. | Controlla la reattività. |
response |
Risposta effettiva dell'agente (la cosa a cui viene assegnato il punteggio). | L'oggetto della valutazione. |
expected_response |
Un riferimento o una expected_response risposta ideale, dal campo. |
Verificare l'accuratezza rispetto al riferimento. |
context |
Fondamento o materiale di partenza a cui la risposta dovrebbe essere fedele, dal context campo. |
Controlla il radicamento (senza contraddizioni o allucinazioni). |
Gli promptargomenti , expected_response, e context provengono direttamente dall'elemento corrente (o turno) nel documento di valutazione. L'argomento response è l'output effettivo dell'agente, acquisito quando l'interfaccia della riga di comando invia prompt all'agente sottoposto a test. In particolare, context è un fondamento solo per il giudice - l'agente non lo vede o non lo recupera mai.
I expected_response campi and context sono facoltativi nel documento di valutazione. Quando sono assenti, l'interfaccia della riga di comando passa una stringa vuota. Poiché l'interfaccia della riga di comando passa sempre tutti e quattro gli argomenti, dichiara quelli che usi e assorbi il resto con **_. Un __call__ metodo che omette uno dei quattro senza un **_ catch-all genera TypeErrore che l'analizzatore riporta un error risultato.
Preparare model_config per load_flow
Il promptflow.client.load_flow runtime necessita di un type campo sul dict di configurazione per selezionare la classe di connessione corretta (AzureOpenAI versus OpenAI). Il AzureOpenAIModelConfiguration CLI che ti passa non contiene quel campo, quindi aggiungilo prima di chiamare 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})
Senza questo passaggio, viene visualizzato l'errore Not Support connection type None for embedding api fuorviante in fase di chiamata.
Creare un analizzatore di solo codice
Un analizzatore di solo codice è una cartella con solo <name>.py e nessun elemento .<name>.prompty L'interfaccia della riga di comando rileva il prompt mancante e considera l'analizzatore come un puro controllo Python. Non chiama mai un modello, quindi un'esecuzione che usa solo analizzatori di solo codice non richiede la configurazione di Microsoft Foundry.
Usa analizzatori di solo codice per controlli deterministici basati su regole: analisi di termini proibiti, regex o convalida del formato, limiti di lunghezza, conformità dello schema JSON e così via.
La maggior parte degli analizzatori di solo codice è un semplice controllo pass/fail. Il modo idiomatico per esprimere questo controllo è restituire score: 1 per pass e score: 0 for fail e lasciare invariata la soglia predefinita di 1 . Il quadro deriva result = "pass" quindi quando score (1) è maggiore o uguale a threshold (1) e "fail" quando score (0) è minore di threshold (1).
Il __init__ metodo per un analizzatore di solo codice omette: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",
}
La tabella seguente riepiloga le differenze tra gli analizzatori di solo codice e gli analizzatori LLM.
| Aspetto | Giudice LLM (.py + .prompty) |
Solo codice (.py solo) |
|---|---|---|
__init__ Argomenti |
model_config, threshold, options |
threshold, options (non )model_config |
score |
Numero intero 1-5 | Qualsiasi numero, nessun morsetto da 1 a 5 (in genere 0 o 1) |
| Soglia predefinita | 3 | 1 |
| Configurazione di Foundry | Obbligatorio | Non obbligatorio |
Contratto di risultato
Il framework possiede result e threshold per entrambi i tipi di valutatore. In caso di successo, ritorna solo {"score", "reason"}; la struttura deriva result = "pass" if score >= threshold else "fail" e allega threshold. Per segnalare un errore, generare un'eccezione o restituire {"error": "<msg>"}.
I punteggi devono essere orientati in modo che più alto sia meglio, perché il framework passa quando score >= threshold. Con la soglia predefinita non LLM di 1, codifica un risultato booleano come 1 (pass) o 0 (fail). Imposta la soglia nel documento eval in modo che corrisponda a qualsiasi scala utilizzata dal tuo punteggio: non [1, 5] ci sono vincoli per gli analizzatori di solo codice. Per un controllo valutato, restituire un punteggio frazionario e impostare una soglia frazionaria. Ad esempio, un analizzatore di corrispondenza parziale che restituisce un rapporto imposterà [0, 1]threshold: 0.7 la richiesta di una corrispondenza del 70%.
Suggerimento
Poiché un file mancante .prompty trasforma silenziosamente un analizzatore in uno di solo codice, l'interfaccia della riga di comando protegge da un prompt accidentalmente omesso: se il codice di un .pyanalizzatore -only fa riferimento a macchinari LLM (load_flow, promptflow, model_configo .prompty), l'interfaccia a riga di comando registra un avviso che suggerisce che potresti aver dimenticato il file prompty. L'avviso non blocca mai la corsa.
Riferimento a valutatori personalizzati da un documento di valutazione
Aggiungere analizzatori personalizzati alla evaluators mappa, proprio come gli analizzatori predefiniti. Per impostazione predefinita, la soglia è 3 per gli analizzatori LLM-judge (la scala 1-5) e 1 per gli analizzatori solo codice. Impostare la soglia in modo esplicito se si vuole un limite diverso:
{
"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 }
}
}
}
]
}
Usare evaluators_mode (extend o replace) esattamente come si farebbe con gli analizzatori predefiniti per controllare se l'analizzatore personalizzato viene eseguito insieme alle impostazioni predefinite o le sostituisce. Per altre informazioni, vedere Configurare gli analizzatori.
Modello di sicurezza
Gli analizzatori personalizzati vengono eseguiti con le stesse autorizzazioni dell'interfaccia della riga di comando stessa. Rivedi il codice in qualsiasi analizzatore personalizzato prima di aggiungerlo al progetto: può fare tutto ciò che Python.
Altre informazioni sul formato .prompty
Il .prompty formato è uno standard Microsoft aperto per i prompt LLM. Per l'elenco completo dei campi introduttivi, dei parametri del modello, della sintassi del modello e dei provider supportati, vedere le seguenti risorse:
- prompty.ai - panoramica e guide pratiche.
- microsoft/prompty - origine e schema TypeSpec.
Il model.parameters blocco passa direttamente all'API Completamento della chat, quindi parametri come temperature, max_tokens, top_p, response_format, seed, e stop sono tutti disponibili.
Risoluzione dei problemi
Usare la tabella seguente per risolvere i problemi comuni dell'analizzatore personalizzato.
| Sintomo | Causa probabile e passaggio successivo |
|---|---|
Unknown evaluator '<name>' |
Verifica che la cartella si trovi in <your_project>/custom-evaluators/<name>/, che i nomi di base del file corrispondano al nome della cartella e che tu stia eseguendo l'interfaccia della riga di comando dalla radice del progetto. |
Custom evaluator '<name>' is missing required file '<name>.py' |
Ogni cartella dell'analizzatore deve contenere <name>.pyfile . Un <name>.prompty file è necessario solo per i valutatori LLM-judge; omettilo per quelli che fanno solo codice. |
Custom evaluator '<name>' failed to import |
Un errore di sintassi di Python o una dipendenza mancante nel file .py . Il messaggio di errore include l'eccezione sottostante. |
Il risultato viene visualizzato error con motivo could not parse score |
Il modello non ha restituito un JSON ben formato. Verifica che il prompt abbia (o uno schema JSON equivalente) e che il modello richieda response_format: { type: json_object } esplicitamente la {"score": ..., "reason": ...} forma. |
Per log più completi, esegui l'interfaccia della riga di comando con --log-level debug.