Microsoft 365 Copilot 평가 CLI 참조

이 문서에서는 패키지의 일부인 명령에 대한 runevals 전체 명령줄 참조를 @microsoft/m365-copilot-eval 제공합니다.

시놉시스

runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir

설명

이 runevals 명령은 테스트 프롬프트를 보내고 Microsoft Foundry 클라우드 평가 및 기본 제공 메트릭을 사용하여 응답에 점수를 매겨 Microsoft 365 Copilot 에이전트를 평가합니다. 이 도구는 JSON 파일, 인라인 프롬프트 및 대화형 테스트에서 일괄 평가를 지원합니다.

CLI v1은 npm latest 태그를 사용합니다. CLI v2는 플러그 인을 사용하는 Copilot 응답을 사용하고 preview 평가합니다. v2에서 구성된 에이전트 ID 없이 실행하면 Microsoft 365 Copilot 채팅을 평가합니다. 미리 보기 설정 및 스키마 v2 예제는 도구 호출 계산기를 참조하세요.

옵션

-V, --version

CLI 도구의 버전 번호를 출력합니다.

예:

runevals --version

출력:

1.15.0

--log-level [level]

로깅 세부 정보 표시 수준을 설정합니다. 사용 가능한 수준: debug, info, warning, error.

  • 기본값: 값이 없는 플래그를 사용하는 경우 기본값은 info.
  • 디버그: API 페이로드를 포함한 자세한 디버깅 정보입니다.
  • 정보: 평가 진행률에 대한 일반 정보입니다.
  • 경고: 경고 메시지만 표시됩니다.
  • 오류: 오류 메시지만 표시됩니다.

예:

# Info level (default when flag is present)
runevals --log-level

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

경고

이 수준에는 debug 콘솔 출력의 원시 API 페이로드 및 응답 데이터가 포함될 수 있습니다. 수정은 패턴 기반이며 모든 PII 또는 자격 증명을 포착하지 못할 수 있습니다. 수동 검토 없이 디버그 출력을 공개적으로 공유하지 마세요.

--prompts <prompts...>

파일을 만들지 않고 빠른 테스트를 위해 명령줄에서 하나 이상의 프롬프트를 직접 지정합니다.

예:

# Single prompt
runevals --prompts "What is Microsoft 365?"

# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"

--expected <responses...>

로 지정된 프롬프트와 함께 예상되는 응답을 제공합니다.--prompts 응답 수는 프롬프트 수와 일치해야 합니다.

예:

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

여러 프롬프트 및 응답:

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

--prompts-file <file>

테스트 프롬프트가 포함된 사용자 지정 JSON 파일을 지정합니다. 이 파일은 자동 검색을 재정의합니다.

예:

runevals --prompts-file ./tests/my-custom-tests.json

파일 형식:

[
  {
    "prompt": "Test question",
    "expected_response": "Expected answer"
  }
]

전체 데이터 세트 스키마는 데이터 세트 스키마 및 테스트 디자인을 참조하세요.

-o, --output <file>

출력 파일 경로 및 형식을 지정합니다. 형식은 파일 확장명에 의해 결정됩니다.

지원되는 형식:

  • .html - HTML 보고서(기본값, 브라우저에서 자동 열림)
  • .json - JSON 결과
  • .csv - CSV 스프레드시트

예:

# HTML output
runevals --output ./reports/results.html

# JSON output
runevals --output ./results/eval-results.json

# CSV output
runevals --output ./data/scores.csv

기본 동작:

가 없으면 --output명령은 결과를 에 저장합니다../.evals/YYYY-MM-DD_HH-MM-SS.html

-i, --interactive

수동 프롬프트 입력 및 테스트를 위한 대화형 모드로 전환합니다.

예:

runevals --interactive

대화형 모드에서는 탐색적 테스트를 수행할 수 있도록 한 번에 하나씩 프롬프트를 입력하라는 메시지가 표시됩니다.

--m365-agent-id <id>

특정 에이전트를 평가하려면 에이전트 ID를 재정의합니다. 이 매개 변수는 여러 에이전트를 테스트하거나 에이전트 ID를 자동으로 검색할 수 없는 경우에 유용합니다.

예:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

에이전트 ID 형식:

  • 사용자 범위: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • 테넌트 범위: T_agent-name.declarativeAgent

v2 미리 보기 플러그인 시나리오의 경우 이 옵션을 생략하고 셸 및 로드된 환경 파일에서 및 레거시 AGENT_ID 를 제거합니다M365_AGENT_ID.

--list-tools <agent-id> (v2 미리 보기)

선언적 에이전트의 작업에 대한 동의 식별자 및 복사 준비 평가자 ID를 나열합니다. 이 옵션은 독립 실행형 플러그 인에는 지원되지 않습니다. 동적으로 검색된 도구는 표시되지 않을 수 있습니다. 평가 후 해당 ID를 diagnostics.tool_calls 확인합니다.

npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

독립 실행형 플러그인 동의 이름 및 세 부분으로 구성된 평가자 ID는 도구 호출 이름 찾기를 참조하세요.

--evaluate-only <file>

프롬프트를 실행하지 않고 저장된 응답과 사용 가능한 진단의 점수를 다시 채점합니다. 각 아이템 또는 턴에는 response. LLM 기반 평가자를 선택하는 경우 심사위를 구성합니다. Microsoft 365 실행 인증은 필요하지 않습니다.

runevals --evaluate-only results\captured-responses.json --output results\rescored.html

도구 호출 재채점에는 CLI v2 미리 보기 및 보존된 도구 호출 증거가 필요합니다. 자세한 내용은 진단 및 저장된 응답 평가를 참조하세요.

--env <environment>

로드할 환경 구성을 지정합니다. 이 매개 변수는 env/.env.<environment>.

기본값: dev (로드 )env/.env.dev

예:

# Load env/.env.dev (default)
runevals --env dev

# Load env/.env.prod
runevals --env prod

# Load env/.env.staging
runevals --env staging

환경 파일 우선 순위:

  1. .env.local (에이전트 도구 키트 프로젝트의 경우 자동 감지됨)
  2. .env.local.user (비밀, 있는 경우 자동 로드됨)
  3. env/.env.<environment> (지정자 --env)
  4. 시스템 환경 변수

--init-only

Python 환경을 초기화하고 평가를 실행하지 않고 종속성을 다운로드합니다. 이 옵션은 다음과 같은 경우에 유용합니다.

  • CI/CD 파이프라인에서 캐시 예열
  • 설치 문제 해결
  • 테스트를 실행하기 전에 설정 확인

예:

runevals --init-only

문제를 해결하려면 이 옵션을 다음과 결합 --log-level debug합니다.

runevals --init-only --log-level debug

-h, --help

사용 가능한 명령 및 옵션에 대한 도움말 정보를 표시합니다.

예:

runevals --help

캐시 명령

평가 도구는 Python 런타임 및 종속성에 로컬 캐시를 사용합니다. 이러한 명령은 캐시를 관리하는 데 도움이 됩니다.

cache-info

크기, 위치 및 설치된 패키지를 포함하여 캐시된 Python 환경에 대한 통계를 표시합니다.

예:

runevals cache-info

출력:

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

캐시된 Python 환경과 다운로드된 모든 종속성을 제거합니다. 설치 문제를 해결하거나 디스크 공간을 확보할 때 이 명령을 사용합니다.

예:

runevals cache-clear

후속 조치:

캐시를 지운 후 다시 초기화합니다.

runevals --init-only

cache-dir

캐시 디렉터리의 절대 경로를 인쇄합니다. 이 기능은 스크립트 또는 수동 검사에 유용합니다.

예:

runevals cache-dir

출력:

C:\Users\YourName\.m365-copilot-eval\cache

스크립트에서의 사용:

# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# View cache contents
ls -lah $(runevals cache-dir)

환경 변수

이 도구는 환경 파일 및 시스템 변수에서 구성을 읽습니다. 이러한 값을 가져오는 단계별 지침은 필수 환경 변수를 참조하세요.

필수 변수

변수 설명 예제
TENANT_ID Microsoft Entra 테넌트 ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT LLM 기반 채점을 위한 Microsoft Foundry 프로젝트 엔드포인트입니다. 결정적 전용 평가에는 필요하지 않습니다. https://<account>.services.ai.azure.com/api/projects/<project>

선택적 변수

변수 설명 기본값
M365_AGENT_ID 평가할 에이전트 ID 다음에서 자동 감지됨 M365_TITLE_ID
M365_TITLE_ID 에이전트 타이틀 ID(에이전트 도구 키트) None
AZURE_AI_MODEL_NAME 평가용 모델 gpt-5-mini
EVALS_SUPPRESS_DIAGNOSTICS 로 설정 true 하여 보존 진단을 생략합니다. 프롬프트, 응답, 평가자 옵션 또는 기본 유효성 검사 메시지를 가리우지 않습니다. 숨겨진 증거는 재생할 수 없습니다. 설정 해제

예제

기본 사용법

자동 검색된 데이터 세트 파일을 사용하여 평가합니다.

cd /path/to/your-agent-project
runevals

환경 지정

프로덕션 환경 구성 사용:

runevals --env prod

사용자 지정 데이터 세트 파일

특정 테스트 파일 사용:

runevals --prompts-file ./tests/regression-tests.json

인라인 테스트

인라인 프롬프트를 사용한 빠른 테스트:

runevals --prompts "What is Microsoft 365?" \
  --expected "Microsoft 365 is a cloud-based productivity suite"

대화형 모드

프롬프트를 수동으로 입력합니다.

runevals --interactive

사용자 지정 출력 형식

JSON 결과 생성:

runevals --output ./results/eval-$(date +%Y%m%d).json

디버그 모드

자세한 로깅과 함께 실행:

runevals --log-level debug --output ./debug-results.json

설정만

테스트를 실행하지 않고 Python 환경 사전 캐시:

runevals --init-only --log-level info

에이전트 ID 재정의

특정 에이전트 테스트:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

결합된 옵션

사용자 지정 설정을 사용한 종합 평가:

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"

종료 코드

코드 의미
0 성공
1 일반 오류
2 잘못된 인수
3 환경 구성 오류
4 에이전트를 찾을 수 없음
5 인증 실패
10 Python 환경 설정 실패

문제 해결

설치, 인증, 런타임 오류, 캐시 문제 및 프록시 설정과 관련된 일반적인 문제는 문제 해결 문서를 참조하세요.