Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
A CLI de Avaliações do Microsoft 365 Copilot (@microsoft/m365-copilot-eval) inclui um conjunto de avaliadores integrados. Quando os avaliadores internos não abrangem seu cenário, você pode criar avaliadores personalizados para pontuar as respostas do agente em relação a critérios específicos do domínio, como conformidade regulatória, tom da marca ou uma rubrica de relevância personalizada.
Existem dois tipos de avaliadores personalizados, e a CLI os distingue automaticamente:
-
Os avaliadores do juiz LLM (
<name>.pye<name>.prompty) chamam um modelo para pontuar a resposta. Eles precisam da configuração do Microsoft Foundry e usam a escala de 1 a 5. -
Avaliadores somente código (não LLM) (
<name>.pysomente, não<name>.prompty) são verificações Python puras sem chamada de modelo - por exemplo, "falhe se a resposta contiver um termo proibido". Eles não precisam de nenhuma configuração do Microsoft Foundry e podem retornar qualquer pontuação numérica.
Para usar seus próprios avaliadores personalizados, crie uma custom-evaluators/ pasta na raiz do seu projeto (o diretório a partir do qual você executa a CLI) e adicione uma subpasta por avaliador. Em tempo de execução, a CLI verifica <your_project>/custom-evaluators/ automaticamente e carrega apenas os avaliadores aos quais seu documento de avaliação faz referência.
Layout da pasta
Cada avaliador personalizado reside em sua própria subpasta. Um avaliador de juiz LLM consiste em dois arquivos; Um avaliador somente de código é apenas o .py arquivo:
<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
A presença de <name>.prompty é o único discriminador: com ele, o avaliador é um juiz LLM; sem ele, é apenas código.
Regras de nomenclatura
- O nome da pasta, o nome do avaliador e os nomes base dos arquivos devem corresponder exatamente.
- Os nomes devem corresponder ao padrão
^[a-zA-Z][a-zA-Z0-9_]*$(um identificador válido: começar com uma letra, seguida de letras, dígitos ou sublinhados). - Os nomes não devem colidir com nomes de avaliadores internos (que não diferenciam maiúsculas de minúsculas):
Relevance,Coherence,Groundedness,CitationsExactMatchToolCallAccuracyPartialMatchSimilarityRetrievalQuerye .RetrievalResultPara criar uma versão personalizada de domínio de um avaliador interno, prefixe seu nome, por exemplo,domain_relevanceem vez derelevance.
Autor: um avaliador de juiz LLM
Um avaliador LLM-judge tem dois arquivos: um .prompty arquivo que define o prompt do juiz e um .py wrapper que o executa.
O arquivo .prompty
Um .prompty arquivo é o prompt do juiz LLM. Ele tem configuração de modelo em frontmatter YAML acima do --- separador, then system: e user: seções abaixo dele. As variáveis referenciadas como no corpo são mapeadas para {{var}} os argumentos de palavra-chave que o wrapper passa para o fluxo imediato.
O exemplo a seguir mostra um arquivo 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}}
Você deve declarar um inputs: bloco no frontmatter que lista todas as variáveis que seu modelo usa. Sem ele, o fluxo de prompt filtra todos os argumentos de palavra-chave e seu modelo é renderizado com substituições vazias {{var}} - o modelo vê um prompt em branco e você obtém um erro ou uma pontuação sem sentido. Cada entrada precisa de um type: valor, que normalmente stringé .
Observação
O runtime do promptflow é reservado prompt como um parâmetro interno, portanto, evite usar {{prompt}} (e uma inputs.prompt declaração) em seu modelo prompty. Use um nome de variável diferente, como {{user_prompt}}, e faça com que o wrapper encaminhe o valor com esse nome quando chamar o fluxo imediato.
O wrapper .py
O módulo Python deve exportar uma classe. A CLI importa dinamicamente o módulo e instancia a primeira classe de nível superior que encontra. A classe deve corresponder ao seguinte 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>",
# }
...
A estrutura possui result e threshold: deriva e anexa result = "pass" if score >= threshold else "fail"threshold, para que você não os devolva. A CLI reescreve a score chave no nome da pasta do avaliador quando mescla os resultados na saída unificada, para que a pontuação apareça como <folder_name> nos relatórios JSON, CSV e HTML.
Você não precisa envolver seu __call__ arquivo .try/except Se o wrapper gerar uma exceção, a CLI a capturará e emitirá um error resultado para esse avaliador enquanto o restante da execução continua. Para controlar a mensagem de erro por conta própria, retorne um dict por meio do canal de erro dedicado (somente a error mensagem é mantida; todas as outras chaves são descartadas):
{ "error": "<explanation>" }
Restrições de pontuação
Para um avaliador de juiz de LLM, score deve ser um número inteiro no intervalo [1, 5] (a mesma escala de 1 a 5 que os avaliadores de LLM integrados). Valores flutuantes que são matematicamente inteiros (por exemplo, 4.0) são aceitos e normalizados. Qualquer coisa fora desse intervalo, um valor não numérico ou uma chave ausente score produz um error resultado; a execução de avaliação continua com os outros avaliadores.
Absorva os parâmetros do construtor que você não usa
A estrutura sempre passa threshold e options para __init__ (mais model_config para avaliadores de juízes LLM). O Python exige que você __init__ aceite todas as palavras-chave com as quais é chamado, mas você não precisa nomear as que ignora. Nomeie um parâmetro somente se você realmente usá-lo. Absorva qualquer outra coisa com um apanha-tudo **_ :
# 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",
}
Não nomeie um subconjunto de parâmetros sem um genérico. Por exemplo, def __init__(self, *, options=None) raises TypeError, porque o framework ainda passa threshold= e nada o aceita. Adicione **_ (ou nome threshold) para corrigi-lo.
Convenções de argumento de palavra-chave
A CLI chama seu __call__ método com o seguinte conjunto fixo de argumentos de palavra-chave. Todos os quatro são passados para o seu avaliador (o juiz do LLM), não para o agente em teste.
| Argumento | O que é | Uso típico em um juiz |
|---|---|---|
prompt |
A pergunta ou instrução do usuário enviada ao agente. | Verifique a capacidade de resposta. |
response |
A resposta real do agente (a coisa que está sendo pontuada). | O assunto da avaliação. |
expected_response |
Uma referência ou resposta ideal, do expected_response campo. |
Verifique a precisão em relação à referência. |
context |
Fundamento ou material de origem à qual a resposta deve ser fiel, do context campo. |
Verifique o aterramento (sem contradições ou alucinações). |
Os promptargumentos , expected_responsee context vêm diretamente do item atual (ou turno) em seu documento de avaliação. O response argumento é a saída real do agente, capturada quando a CLI envia prompt para o agente em teste. Em particular, context é fundamento apenas para o juiz - o agente nunca o vê ou recupera.
Os expected_response campos e context são opcionais no documento de avaliação. Quando eles estão ausentes, a CLI passa uma cadeia de caracteres vazia. Como a CLI sempre passa todos os quatro argumentos, declare os que você usa e absorva o restante com **_. Um __call__ método que omite um dos quatro sem um **_ catch-all raises TypeError, e esse avaliador relata um error resultado.
Preparar model_config para load_flow
O promptflow.client.load_flow runtime precisa de um type campo no ditado de configuração para escolher a classe de conexão correta (AzureOpenAI versus OpenAI). O AzureOpenAIModelConfiguration que a CLI passa para você não carrega esse campo, portanto, adicione-o antes de chamar 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})
Sem essa etapa, você verá o erro Not Support connection type None for embedding api enganoso no momento da invocação.
Criar um avaliador somente código
Um avaliador somente código é uma pasta com only <name>.py e no <name>.prompty. A CLI detecta o prompt ausente e trata o avaliador como um marcar Python puro. Ele nunca chama um modelo, portanto, uma execução que usa apenas avaliadores somente código não precisa de nenhuma configuração do Microsoft Foundry.
Use avaliadores somente de código para verificações determinísticas baseadas em regras: verificações de prazo proibido, validação de regex ou formato, limites de comprimento, conformidade com esquema JSON e assim por diante.
A maioria dos avaliadores somente de código são uma simples marcar de aprovação/reprovação. A maneira idiomática de expressar essa marca é retornar score: 1 para aprovado e score: 0 para reprovado e deixar o limite padrão de 1 em vigor. A estrutura então deriva result = "pass" quando score (1) é maior ou igual a threshold (1) e "fail" quando score (0) é menor que threshold (1).
O __init__ método para um avaliador somente 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",
}
A tabela a seguir resume como os avaliadores somente de código diferem dos avaliadores de juízes LLM.
| Aspecto | LLM-judge (.py + .prompty) |
Somente código (.py somente) |
|---|---|---|
__init__ argumentos |
model_config, threshold, options |
threshold, options (não model_config) |
score |
Inteiro 1-5 | Qualquer número, sem grampo 1-5 (normalmente 0 ou 1) |
| Limite padrão | 3 | 1 |
| Configuração de fundição | Obrigatório | Não é necessário |
Contrato de resultado
A estrutura possui result e threshold para ambos os tipos de avaliador. Em caso de sucesso, retorne apenas {"score", "reason"}; a estrutura deriva e anexa result = "pass" if score >= threshold else "fail"threshold. Para sinalizar uma falha, crie uma exceção ou retorne {"error": "<msg>"}.
As pontuações devem ser orientadas para que maior seja melhor, porque a estrutura passa quando score >= threshold. Com o limite padrão não LLM de 1, codifique um resultado booleano como 1 (aprovado) ou 0 (reprovado). Defina o limite no documento de avaliação para corresponder a qualquer escala que sua pontuação usa. Não há restrição [1, 5] para avaliadores somente de código. Para uma verificação com marcação, retorne uma pontuação fracionária e defina um limite fracionário. Por exemplo, um avaliador de correspondência parcial que retorna uma proporção em exigiria threshold: 0.7 uma correspondência de [0, 1] 70%.
Dica
Como um arquivo ausente .prompty transforma silenciosamente um avaliador em um somente código, a CLI protege contra um prompt omitido acidentalmente: se o código de um .pyavaliador somente -only fizer referência ao mecanismo LLM (load_flow, promptflow, model_config, ou .prompty), a CLI registra um aviso que sugere que você pode ter esquecido o arquivo prompty. O aviso nunca bloqueia a execução.
Referenciar avaliadores personalizados a partir de um documento de avaliação
Adicione avaliadores personalizados ao evaluators mapa, assim como avaliadores integrados. O limite é padrão para 3 avaliadores de juízes de LLM (a escala de 1 a 5) e 1 para avaliadores somente de código. Defina o limite explicitamente se quiser um corte 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 ou replace) exatamente como faria com avaliadores internos para controlar se o avaliador personalizado é executado ao lado dos padrões ou os substitui. Para obter mais informações, consulte Configurar avaliadores.
Modelo de segurança
Os avaliadores personalizados são executados com as mesmas permissões que a própria CLI. Revise o código em qualquer avaliador personalizado antes de adicioná-lo ao seu projeto - ele pode fazer qualquer coisa que o Python pode fazer.
Saiba mais sobre o formato .prompty
O .prompty formato é um padrão aberto da Microsoft para prompts de LLM. Para obter a lista completa de campos de formatação, parâmetros de modelo, sintaxe de modelo e provedores compatíveis, consulte os seguintes recursos:
- prompty.ai - Visão geral e guias de instruções.
- microsoft/prompty - esquema de origem e TypeSpec.
O model.parameters bloco passa direto para a API de conclusões de Chat, portanto, parâmetros como temperature, max_tokens, top_p, response_formatseed, , e stop estão disponíveis.
Solução de problemas
Use a tabela a seguir para resolver problemas comuns do avaliador personalizado.
| Sintoma | Causa provável e próxima etapa |
|---|---|
Unknown evaluator '<name>' |
Verifique se a pasta está em <your_project>/custom-evaluators/<name>/, se os nomes de base de arquivos correspondem ao nome da pasta e se você está executando a CLI na raiz do projeto. |
Custom evaluator '<name>' is missing required file '<name>.py' |
Cada pasta do avaliador deve conter <name>.py. Um <name>.prompty arquivo é necessário apenas para avaliadores de juízes de LLM; omita-o para os de somente código. |
Custom evaluator '<name>' failed to import |
Um erro de sintaxe do Python ou uma dependência ausente no arquivo .py . A mensagem de erro inclui a exceção subjacente. |
O resultado mostra error com razão could not parse score |
O modelo não retornou JSON bem formado. Verifique se o prompt tem response_format: { type: json_object } (ou um esquema JSON equivalente) e se o modelo pede explicitamente a {"score": ..., "reason": ...} forma. |
Para logs mais ricos, execute a CLI com --log-level debug.