Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
La CLI de evaluaciones de Microsoft 365 Copilot (@microsoft/m365-copilot-eval) incluye un conjunto de evaluadores integrados. Cuando los evaluadores integrados no cubren su escenario, puede crear evaluadores personalizados para puntuar las respuestas de los agentes en función de criterios específicos del dominio, como el cumplimiento normativo, el tono de la marca o un criterio de relevancia personalizado.
Existen dos tipos de evaluadores personalizados y la CLI los distingue automáticamente:
-
Los evaluadores de jueces de LLM (
<name>.pyy<name>.prompty) llaman a un modelo para calificar la respuesta. Necesitan la configuración de Microsoft Foundry y usan la escala del 1 al 5. -
Los evaluadores de solo código (no LLM) (
<name>.pysolo, no<name>.prompty) son comprobaciones de Python puras sin llamada de modelo, por ejemplo, "fallan si la respuesta contiene un término prohibido". No necesitan configuración de Microsoft Foundry y pueden devolver cualquier puntuación numérica.
Para usar sus propios evaluadores personalizados, cree una custom-evaluators/ carpeta en la raíz del proyecto (el directorio desde el que ejecuta la CLI) y agregue una subcarpeta por evaluador. En tiempo de ejecución, la CLI examina <your_project>/custom-evaluators/ automáticamente y carga solo los evaluadores a los que hace referencia el documento de evaluación.
Diseño de carpeta
Cada evaluador personalizado vive en su propia subcarpeta. Un evaluador de jueces de LLM consta de dos archivos; Un evaluador de solo código es simplemente el .py archivo:
<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 presencia de <name>.prompty es el único discriminador: con él, el evaluador es un juez LLM; sin él, es solo código.
Reglas de nomenclatura
- El nombre de la carpeta, el nombre del evaluador y los nombres de base del archivo deben coincidir exactamente.
- Los nombres deben coincidir con el patrón
^[a-zA-Z][a-zA-Z0-9_]*$(un identificador válido: empiece por una letra, seguida de letras, dígitos o caracteres de subrayado). - Los nombres no deben colisionar con los nombres del evaluador integrado (sin distinguir mayúsculas de minúsculas):
Relevance,Coherence,Groundedness,ExactMatchSimilarityCitationsPartialMatchToolCallAccuracyRetrievalQueryy .RetrievalResultPara crear una versión adaptada al dominio de un evaluador integrado, escriba un prefijo en su nombre, por ejemplo,domain_relevanceen lugar derelevance.
Crear un evaluador de jueces de LLM
Un evaluador de jueces de LLM tiene dos archivos: un .prompty archivo que define la solicitud del juez y un .py contenedor que lo ejecuta.
El archivo .prompty
Un .prompty archivo es el aviso del juez de LLM. Tiene la configuración del modelo en el frontmatter YAML encima del --- separador y luego system: y user: secciones debajo. Las variables a las que se hace referencia como {{var}} en el cuerpo se asignan a los argumentos de palabras clave que el envoltorio pasa al flujo rápido.
En el ejemplo siguiente se muestra un archivo mínimo 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}}
Debe declarar un inputs: bloque en el frontmatter que enumere todas las variables que usa su plantilla. Sin él, promptflow filtra todos los argumentos de palabras clave y su plantilla se representa con sustituciones vacías {{var}} : el modelo ve un mensaje en blanco y obtiene un error o una puntuación sin sentido. Cada entrada necesita un type: valor, que normalmente stringes .
Nota
El tiempo de ejecución de promptflow se reserva prompt como parámetro interno, así que evite usar {{prompt}} (y una inputs.prompt declaración) en su plantilla prompty. Use un nombre de variable diferente, como {{user_prompt}}, y haga que su contenedor reenvíe el valor debajo de ese nombre cuando llame al flujo de solicitudes.
El envoltorio .py
El módulo de Python debe exportar una clase. La CLI importa dinámicamente el módulo y crea una instancia de la primera clase de nivel superior que encuentra. La clase debe coincidir con el siguiente contrato:
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>",
# }
...
El marco posee result y threshold: deriva result = "pass" if score >= threshold else "fail" y adjunta threshold, por lo que no los devuelve. La CLI vuelve a escribir la clave en el nombre de la score carpeta del evaluador cuando combina los resultados en la salida unificada, de modo que la puntuación aparece como <folder_name> en los informes JSON, CSV y HTML.
No es necesario envolverlo __call__ en try/except. Si el contenedor genera una excepción, la CLI la captura y emite un error resultado para ese evaluador mientras continúa el resto de la ejecución. Para controlar el mensaje de error usted mismo, devuelva un dictado a través del canal de error dedicado (solo se conserva el error mensaje; se descartan las demás claves):
{ "error": "<explanation>" }
Restricciones de puntuación
Para un evaluador de jueces LLM, score debe ser un entero en el rango [1, 5] (la misma escala de 1 a 5 que los evaluadores LLM incorporados). Los valores flotantes que son matemáticamente enteros (por ejemplo, 4.0) se aceptan y normalizan. Cualquier valor fuera de este rango, un valor no numérico o una clave que falta score produce un error resultado; la ejecución de evaluación continúa con los otros evaluadores.
Absorber parámetros de constructor que no utiliza
El marco siempre pasa threshold y options a __init__ (más model_config para los evaluadores de jueces de LLM). Python requiere que acepte __init__ todas las palabras clave con las que se llama, pero no tiene que nombrar las que ignora. Asigne un nombre a un parámetro solo si lo usa realmente. Absorbe cualquier otra cosa con un **_ cajón de sastre:
# 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",
}
No asigne un nombre a un subconjunto de parámetros sin una solución general. Por ejemplo, def __init__(self, *, options=None) genera TypeError, porque el marco sigue pasando threshold= y nada lo acepta. Agregue **_ (o nombre threshold) para corregirlo.
Convenciones de argumentos de palabras clave
La CLI llama al __call__ método con el siguiente conjunto fijo de argumentos de palabras clave. Los cuatro se pasan a su evaluador (el juez de LLM), no al agente bajo prueba.
| argumento | Qué es | Uso típico en un juez |
|---|---|---|
prompt |
La pregunta o instrucción del usuario enviada al agente. | Compruebe la capacidad de respuesta. |
response |
La respuesta real del agente (la cosa que se está puntuando). | El tema de evaluación. |
expected_response |
Una referencia o respuesta ideal, del expected_response campo. |
Compruebe la precisión con la referencia. |
context |
Fundamentación o material de origen al que la respuesta debe ser fiel, desde el context campo. |
Comprueba la conexión a tierra (sin contradicciones ni alucinaciones). |
El prompt, expected_response, y context los argumentos provienen directamente del elemento actual (o turno) en el documento de evaluación. El response argumento es la salida real del agente, capturada cuando la CLI envía prompt al agente bajo prueba. En particular, context es fundamento solo para el juez: el agente nunca lo ve ni lo recupera.
Los expected_response campos y context son opcionales en el documento de evaluación. Cuando están ausentes, la CLI pasa una cadena vacía. Dado que la CLI siempre pasa los cuatro argumentos, declare los que use y absorba el resto con **_. Un __call__ método que omite uno de los cuatro sin un **_ cajón de sastre general y TypeErrorese evaluador informa un error resultado.
Preparar model_config para load_flow
El promptflow.client.load_flow tiempo de ejecución necesita un type campo en el diccionario de configuración para elegir la clase de conexión correcta (AzureOpenAI versus OpenAI). Lo AzureOpenAIModelConfiguration que le pasa la CLI no lleva ese campo, así que agréguelo antes de llamar :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})
Sin este paso, verá el error Not Support connection type None for embedding api engañoso en el momento de la invocación.
Crear un evaluador de solo código
Un evaluador de solo código es una carpeta con solo <name>.py y ningún <name>.promptyarchivo . La CLI detecta el aviso que falta y trata al evaluador como una comprobación de Python pura. Nunca llama a un modelo, por lo que una ejecución que solo usa evaluadores de código no necesita ninguna configuración de Microsoft Foundry.
Use evaluadores de solo código para comprobaciones deterministas basadas en reglas: exámenes de términos prohibidos, validación de expresiones regulares o formato, límites de longitud, conformidad con el esquema JSON, etc.
La mayoría de los evaluadores de solo código son una comprobación simple de aprobado o suspenso. La forma idiomática de expresar esa comprobación es devolver score: 1 por aprobado y score: 0 por suspenso, y dejar el umbral predeterminado de 1 en su lugar. Luego, el result = "pass" marco deriva cuando score (1) es mayor o igual que threshold (1), y "fail" cuando score (0) es menor que threshold (1).
El __init__ método para un evaluador de solo código omite 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 siguiente tabla resume en qué se diferencian los evaluadores de solo código de los evaluadores de jueces de LLM.
| Aspecto | LLM-judge (.py + .prompty) |
Solo código (.py sólo) |
|---|---|---|
__init__ Argumentos |
model_config, threshold, options |
threshold, options (no model_config) |
score |
Entero 1-5 | Cualquier número, sin abrazadera del 1 al 5 (normalmente 0 o 1) |
| Umbral predeterminado | 3 | 1 |
| Configuración de fundición | Requerido | No es obligatorio |
Contrato de resultado
El marco posee result y threshold para ambos tipos de evaluador. Con éxito, regrese solo {"score", "reason"}; el marco deriva result = "pass" if score >= threshold else "fail" y se adjunta threshold. Para señalar un error, genere una excepción o devuelva {"error": "<msg>"}.
Las puntuaciones deben orientarse de modo que cuanto más alto sea mejor, porque el marco pasa cuando score >= threshold. Con el umbral predeterminado que no es LLM de 1, codifique un resultado booleano como 1 (correcto) o 0 (incorrecto). Establezca el umbral en el documento de evaluación para que coincida con la escala que use su puntuación: no [1, 5] hay restricciones para los evaluadores solo de código. Para un cheque calificado, devuelva un puntaje fraccionario y establezca un umbral fraccionario. Por ejemplo, un evaluador de coincidencia parcial que devuelve una proporción en [0, 1] requeriría threshold: 0.7 una coincidencia del 70%.
Recomendación
Dado que un archivo faltante .prompty convierte silenciosamente un evaluador en uno de solo código, la CLI se protege contra un aviso omitido accidentalmente: si el código de un .pyevaluador -only hace referencia a maquinaria LLM (load_flow, promptflow, model_config, o .prompty), la CLI registra una advertencia que sugiere que es posible que haya olvidado el archivo rápido. La advertencia nunca bloquea la carrera.
Hacer referencia a evaluadores personalizados desde un documento de evaluación
Agregue evaluadores personalizados al evaluators mapa, al igual que los evaluadores integrados. El umbral predeterminado es 3 para los evaluadores de jueces LLM (la escala del 1 al 5) y 1 para los evaluadores solo de código. Establezca el umbral explícitamente si desea un límite diferente:
{
"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 }
}
}
}
]
}
Use evaluators_mode (extend o replace) exactamente como lo haría con los evaluadores integrados para controlar si el evaluador personalizado se ejecuta junto con los valores predeterminados o los reemplaza. Para obtener más información, consulte Configuración de evaluadores.
Modelo de seguridad
Los evaluadores personalizados se ejecutan con los mismos permisos que la propia CLI. Revise el código en cualquier evaluador personalizado antes de agregarlo al proyecto: puede hacer todo lo que Python puede hacer.
Obtenga más información sobre el formato .prompty
El .prompty formato es un estándar abierto de Microsoft para solicitudes de LLM. Para obtener la lista completa de los campos de frontmatter, los parámetros del modelo, la sintaxis de plantilla y los proveedores admitidos, consulte los siguientes recursos:
- prompty.ai - Información general y guías de procedimientos.
- microsoft/prompty - origen y esquema de TypeSpec.
El model.parameters bloque pasa directamente a la API de finalización de chat, por lo que parámetros como temperature, max_tokens, top_p, response_formatseed, y stop están todos disponibles.
Solución de problemas
Use la siguiente tabla para resolver problemas comunes del evaluador personalizado.
| Síntoma | Causa probable y paso siguiente |
|---|---|
Unknown evaluator '<name>' |
Compruebe que la carpeta está en <your_project>/custom-evaluators/<name>/, que los nombres base de archivo coinciden con el nombre de la carpeta y que está ejecutando la CLI desde la raíz del proyecto. |
Custom evaluator '<name>' is missing required file '<name>.py' |
Cada carpeta de evaluador debe contener <name>.py. Se necesita un <name>.prompty archivo solo para los evaluadores de jueces de LLM; omítalo para los de solo código. |
Custom evaluator '<name>' failed to import |
Error de sintaxis de Python o falta una dependencia en el .py archivo. El mensaje de error incluye la excepción subyacente. |
El resultado se muestra error con motivo could not parse score |
El modelo no devolvió un JSON bien formado. Compruebe que el símbolo del sistema lo tenga response_format: { type: json_object } (o un esquema JSON equivalente) y que la plantilla solicite explícitamente la {"score": ..., "reason": ...} forma. |
Para registros más completos, ejecute la CLI con --log-level debug.