Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Este artigo fornece uma referência completa da linha de comando para o runevals comando, que faz parte do @microsoft/m365-copilot-eval pacote.
Sinopse
runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir
Descrição
O runevals comando avalia os agentes do Microsoft 365 Copilot enviando prompts de teste e pontuando as respostas usando a avaliação na nuvem do Microsoft Foundry e métricas internas. A ferramenta oferece suporte à avaliação em lote de arquivos JSON, prompts embutidos e testes interativos.
A CLI v1 usa a tag npm latest . A CLI v2 usa preview e também avalia as respostas do Copilot que usam plug-ins. Na v2, uma execução sem uma ID de agente configurada avalia o chat do Microsoft 365 Copilot. Para obter exemplos de configuração de visualização e esquema v2, consulte Avaliadores de chamada de ferramentas.
Opções
-V, --version
Produza o número da versão da ferramenta CLI.
Exemplo:
runevals --version
Saída:
1.15.0
--log-level [level]
Defina o nível de detalhamento de log. Níveis disponíveis: debug, info, warningerror, .
-
Padrão: quando você usa o sinalizador sem um valor, o padrão
infoé . - debug: informações detalhadas de depuração, incluindo payloads de API.
- info: Informações gerais sobre o progresso da avaliação.
- warning: Somente mensagens de aviso.
- error: Somente mensagens de erro.
Exemplos:
# Info level (default when flag is present)
runevals --log-level
# Debug level
runevals --log-level debug
# Error level only
runevals --log-level error
Aviso
O debug nível pode incluir cargas de API brutas e dados de resposta na saída do console. A redação é baseada em padrão e pode não capturar todas as PII ou credenciais. Não compartilhe a saída de depuração publicamente sem revisão manual.
--prompts <prompts...>
Especifique um ou mais prompts diretamente na linha de comando para testes rápidos sem criar um arquivo.
Exemplos:
# Single prompt
runevals --prompts "What is Microsoft 365?"
# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"
--expected <responses...>
Forneça as respostas esperadas para acompanhar os prompts especificados com --prompts. O número de respostas deve corresponder ao número de prompts.
Exemplo:
runevals --prompts "What is Microsoft Graph?" \
--expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."
Vários prompts e respostas:
runevals --prompts "What is Teams?" "What is SharePoint?" \
--expected "Teams is a collaboration platform" "SharePoint is a content management system"
--prompts-file <file>
Especifique um arquivo JSON personalizado contendo prompts de teste. Esse arquivo substitui a descoberta automática.
Exemplo:
runevals --prompts-file ./tests/my-custom-tests.json
Formato do arquivo:
[
{
"prompt": "Test question",
"expected_response": "Expected answer"
}
]
Para obter o esquema completo do conjunto de dados, consulte Esquema do conjunto de dados e design de teste.
-o, --output <file>
Especifique o caminho e o formato do arquivo de saída. O formato é determinado pela extensão do arquivo.
Formatos com suporte:
-
.html- Relatório HTML (padrão, abre automaticamente no navegador) -
.json- Resultados JSON -
.csv- Planilha CSV
Exemplos:
# HTML output
runevals --output ./reports/results.html
# JSON output
runevals --output ./results/eval-results.json
# CSV output
runevals --output ./data/scores.csv
Comportamento padrão:
Sem --output, o comando salva os resultados em ./.evals/YYYY-MM-DD_HH-MM-SS.html.
-i, --interactive
Entre no modo interativo para entrada manual de prompt e teste.
Exemplo:
runevals --interactive
No modo interativo, você é solicitado a inserir prompts um de cada vez, para que possa fazer testes exploratórios.
--m365-agent-id <id>
Substitua o ID do agente para avaliar um agente específico. Esse parâmetro é útil ao testar vários agentes ou quando o ID do agente não pode ser detectado automaticamente.
Exemplo:
runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"
Formatos de ID do agente:
- Escopo pelo usuário:
U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - Escopo do locatário:
T_agent-name.declarativeAgent
Para cenários de plug-in de visualização v2, omita essa opção e remova M365_AGENT_ID um legado AGENT_ID do shell e dos arquivos de ambiente carregados.
--list-tools <agent-id> (Versão prévia v2)
Liste identificadores de consentimento e identidades de avaliador prontas para cópia para ações de um agente declarativo. Essa opção não é compatível com plug-ins autônomos. As ferramentas descobertas dinamicamente podem não aparecer; Confirmar suas identidades após diagnostics.tool_calls uma avaliação.
npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"
Para obter nomes de consentimento de plug-in autônomo e a identidade do avaliador de três partes, consulte Localizar nomes de chamada de ferramenta.
--evaluate-only <file>
Repontue as respostas salvas e os diagnósticos disponíveis sem executar prompts. Cada item ou turno deve incluir um response. Configure um juiz se você selecionar avaliadores baseados em LLM; A autenticação de execução do Microsoft 365 não é necessária.
runevals --evaluate-only results\captured-responses.json --output results\rescored.html
A repontuação da chamada de ferramenta requer visualização da CLI v2 e evidências de chamada de ferramenta retidas. Para obter detalhes, consulte Avaliação de diagnóstico e resposta salva.
--env <environment>
Especifique a configuração de ambiente a ser carregada. Este parâmetro carrega env/.env.<environment>.
Padrão: dev (carrega env/.env.dev)
Exemplos:
# Load env/.env.dev (default)
runevals --env dev
# Load env/.env.prod
runevals --env prod
# Load env/.env.staging
runevals --env staging
Precedência do arquivo de ambiente:
-
.env.local(detectado automaticamente para projetos do Kit de Ferramentas de Agentes) -
.env.local.user(segredos, carregado automaticamente, se presente) -
env/.env.<environment>(especificado por--env) - Variáveis de ambiente do sistema
--init-only
Inicializa o ambiente Python e baixa dependências sem executar avaliações. Essa opção é útil para:
- Pré-aquecendo o cache em pipelines de CI/CD
- Solução de problemas de instalação
- Verificando a instalação antes de executar testes
Exemplo:
runevals --init-only
Para solução de problemas, combine esta opção com --log-level debug:
runevals --init-only --log-level debug
-h, --help
Exibe informações da ajuda sobre comandos e opções disponíveis.
Exemplo:
runevals --help
Comandos de cache
A ferramenta de avaliação usa um cache local para o runtime e as dependências do Python. Esses comandos ajudam a gerenciar o cache.
cache-info
Exibe estatísticas sobre o ambiente Python em cache, incluindo tamanho, localização e pacotes instalados.
Exemplo:
runevals cache-info
Saída:
Cache Information
Location: C:\Users\YourName\.m365-copilot-eval\cache
Size: 245 MB
Python Version: 3.11.5
Packages: 42 installed
Last updated: 2026-04-10 14:23:15
cache-clear
Remove o ambiente Python em cache e todas as dependências baixadas. Use esse comando ao solucionar problemas de instalação ou liberar espaço em disco.
Exemplo:
runevals cache-clear
Acompanhamento:
Depois de limpar o cache, reininicialize:
runevals --init-only
cache-dir
Imprime o caminho absoluto para o diretório de cache. Esse recurso é útil para scripts ou inspeção manual.
Exemplo:
runevals cache-dir
Saída:
C:\Users\YourName\.m365-copilot-eval\cache
Uso em scripts:
# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)
# View cache contents
ls -lah $(runevals cache-dir)
Variáveis de ambiente
A ferramenta lê a configuração de arquivos de ambiente e variáveis do sistema. Para obter instruções passo a passo sobre como obter esses valores, consulte Variáveis de ambiente necessárias.
Variáveis obrigatórias
| Variável | Descrição | Exemplo |
|---|---|---|
TENANT_ID |
ID do locatário do Microsoft Entra | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
AZURE_AI_PROJECT_ENDPOINT |
Ponto de extremidade do projeto Microsoft Foundry para pontuação baseada em LLM. Não é necessário para a avaliação somente determinística. | https://<account>.services.ai.azure.com/api/projects/<project> |
Variáveis opcionais
| Variável | Descrição | Padrão |
|---|---|---|
M365_AGENT_ID |
ID do agente a ser avaliada | Detecção automática de M365_TITLE_ID |
M365_TITLE_ID |
ID do título do agente (Agents Toolkit) | Nenhum |
AZURE_AI_MODEL_NAME |
Modelo para avaliações | gpt-5-mini |
EVALS_SUPPRESS_DIAGNOSTICS |
Defina como true para omitir os diagnósticos retidos. Não redigir prompts, respostas, opções do avaliador ou mensagens de validação nativas. Evidências suprimidas não podem ser reproduzidas. |
Remover definição |
Exemplos
Uso básico
Avalie usando o arquivo de conjunto de dados descoberto automaticamente:
cd /path/to/your-agent-project
runevals
Especificar ambiente
Usar a configuração do ambiente de produção:
runevals --env prod
Arquivo de conjunto de dados personalizado
Use um arquivo de teste específico:
runevals --prompts-file ./tests/regression-tests.json
Teste em linha
Teste rápido com prompts embutidos:
runevals --prompts "What is Microsoft 365?" \
--expected "Microsoft 365 is a cloud-based productivity suite"
Modo interativo
Inserir prompts manualmente:
runevals --interactive
Formato de saída personalizado
Gerar resultados JSON:
runevals --output ./results/eval-$(date +%Y%m%d).json
Modo de depuração
Execute com registro em log detalhado:
runevals --log-level debug --output ./debug-results.json
Somente configuração
Pré-cache do ambiente Python sem executar testes:
runevals --init-only --log-level info
Substituir ID do agente
Teste um agente específico:
runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"
Opções combinadas
Avaliação abrangente com configurações personalizadas:
runevals \
--env staging \
--prompts-file ./evals/full-suite.json \
--output ./reports/staging-eval-$(date +%Y%m%d).html \
--log-level info \
--m365-agent-id "T_my-agent.declarativeAgent"
Códigos de saída
| Código | Significado |
|---|---|
0 |
Sucesso |
1 |
Erro geral |
2 |
Argumentos inválidos |
3 |
Erro de configuração do ambiente |
4 |
Agente não encontrado |
5 |
Falha na autenticação |
10 |
Falha na configuração do ambiente Python |
Solução de problemas
Para problemas comuns com instalação, autenticação, erros de tempo de execução, problemas de cache e configuração de proxy, consulte o artigo de solução de problemas .