azd CLI를 사용하여 에이전트 평가 실행(미리 보기)

Important

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

azd ai eval 확장을 사용하여 Microsoft Foundry로 빌드된 에이전트에 측정된 품질 루프를 추가합니다. 프로젝트와 나란히 평가용 골격을 만들고, 필요에 따라 데이터 세트와 루브릭 평가기를 생성한 다음, 에이전트를 대상으로 평가를 실행하고, 터미널을 벗어나지 않고 결과를 확인할 수 있습니다.

동일한 평가는 파이프라인에서 실행되고 --fail-on 결과를 빌드 게이트로 변환할 수 있습니다.

이 문서에서는 첫 번째 평가에 대해 설명합니다.azd ai eval initazd ai eval run start

사전 요구 사항

Microsoft Foundry에 액세스할 수 있는 Azure 구독입니다.
Azure 개발자 CLI(azd), 버전 1.27.1 이상. 설치 지침은 Azure 개발자 CLI 설치 참조하세요.
azd ai eval 확장: azd extension install azure.ai.evaluations. 실행 azd extension list --installed 하여 설치된 버전을 확인합니다.
인증된 azd 세션입니다. 인증 상태를 확인하려면 다음을 실행 azd auth status합니다. 로그인되어 있지 않은 경우 azd auth login을 실행하세요.
Foundry 리소스의 Foundry User 역할(이전에는 Azure AI User)입니다. 자세한 내용은 Microsoft Foundry의 역할 기반 접근 제어를 참조하세요.
Foundry 프로젝트 및 평가할 에이전트 init 대상을 검색하려면 에이전트가 프로젝트azure.yaml와 마찬가지로 azd ai agent init 서비스에서 서비스로 선언되어야 합니다. 그렇지 않으면 이름을 .로 --target지정합니다. 호스트된 에이전트는 호스트된 에이전트를 참조하세요.
동일한 프로젝트에서 채팅 완료를 지원하는 모델 배포입니다. 채점자는 그것으로 판단합니다.
선택 사항: generate가 하나를 합성하지 않도록 하려는 경우, 대표적인 예제가 포함된 JSONL 데이터 세트

azd 평가 작동 방식

평가는 읽고 편집하고 커밋할 수 있는 파일 evals/azure.eval.yaml로 설명됩니다. 명령은 해당 파일을 작성하거나 선언한 내용에 따라 작동합니다.

azd ai eval init          # scaffold the configuration. Makes no service calls
azd ai eval generate      # optional: synthesize a dataset and a rubric evaluator
azd ai eval create        # register the eval in the Foundry project
azd ai eval run start     # run it and summarize the results

항목	Description
`init`	에이전트용 `evals/azure.eval.yaml`을 생성하고 평가 서비스를 `azure.yaml`에 추가합니다. 서비스 호출을 하지 않습니다.
`generate`	데이터 세트, 루브릭 계산기 또는 둘 다를 합성하여 다운로드하고 구성에 각각에 대한 카탈로그 항목을 추가합니다. 과금되는 생성 작업을 제출합니다.
`evals/azure.eval.yaml`	평가 레시피: 무엇을 평가하는지, 행의 출처는 어디인지, 그리고 어떤 평가자가 이를 평가하는지.
`create`	선언된 데이터 세트, 계산기 및 eval 자체를 프로젝트에 등록합니다.
`run start`	실행을 시작하고, 기본적으로 완료될 때까지 기다리며 평가자별 요약을 출력합니다.
`run output list`	해당 요약 뒤에 있는 샘플별 결과입니다.
`dataset`, `evaluator`	를 포함하여 `versions list`등록된 데이터 세트 및 평가자를 직접 관리합니다.
`job`	`generate`가 제출한 생성 작업을 확인, 취소 및 삭제합니다.

모든 명령은 -o json 스크립팅 및 --debug 진단을 허용합니다. 를 제외한 init 모든 명령은 수락합니다.--project-endpoint

행의 출처 선택

평가는 행에 점수를 매깁니다. 두 곳 중 한 곳에서 오며, 이것이 첫 번째로 결정할 사항입니다:

--source traces는 에이전트가 생성한 트레이스에서 읽은 내용을 바탕으로 에이전트가 이미 수행한 작업을 평가합니다. 작성할 항목이 없습니다.
--source dataset 는 사용자 또는 생성된 고정된 예제 집합을 평가합니다. 에이전트 버전 간에 반복 가능하고 비교할 수 있습니다.

트레이스에 기반한 평가에는 트레이스를 생성하는 에이전트가 필요합니다. 데이터 세트 원본 평가에는 파일 또는 등록된 데이터 세트가 필요합니다 .jsonl .

평가의 틀을 마련하세요

프로젝트 루트에서 실행 init :

azd ai eval init

플래그 init 가 없으면 에이전트를 선언할 때 azure.yaml 에이전트를 감지하고, 여러 항목을 선언할 때 프롬프트를 표시하고, 채점자가 판단하는 모델 배포와 사용할 평가자를 묻습니다. azure.yaml을 작성하고 평가 서비스를 evals/azure.eval.yaml에 추가합니다. 서비스 호출을 하지 않으므로 배포하기 전에 안전하게 실행할 수 있습니다.

에이전트 서비스가 선언되지 않은 프로젝트에서는 init가 추측하는 대신 중지됩니다.

ERROR: this project declares no agent service to evaluate. Add one, or name an existing agent with --target

이 경우 에이전트 이름을 직접 지정합니다 --target.

스크립트 방식으로 사용할 경우 결정 사항을 직접 전달하세요.

azd ai eval init \
  --source traces \
  --target support-agent \
  --judge-model gpt-4.1-nano \
  --name support-trace-eval \
  --no-prompt

이미 있는 데이터 세트를 평가하려면 다음을 수행합니다.

azd ai eval init \
  --source dataset \
  --target support-agent \
  --dataset ./tests/support-golden.jsonl \
  --evaluator builtin.intent_resolution,builtin.task_adherence \
  --judge-model gpt-4.1-nano

--dataset 는 로컬 .jsonl 경로 또는 등록된 데이터 세트의 이름을 사용합니다. --evaluator 는 반복 가능하고 쉼표로 구분됩니다. builtin.<name> 는 기본 제공 계산기를 참조하고, 맨 이름은 프로젝트에 등록된 사용자 지정 계산기를 참조합니다. 전달 --evaluator 하면 기본값이 대체되므로 루브릭 생성도 옵트아웃합니다.

기본 제공 이름을 검색하려면 다음을 수행합니다.

azd ai eval evaluator list --builtin

데이터 세트 및 계산기 생성

데이터 세트가 없거나 제네릭이 아닌 이 에이전트에 대해 작성된 루브릭을 원하는 경우 다음을 생성합니다.

azd ai eval generate \
  --target support-agent \
  --generation-model gpt-4.1-nano \
  --agent-instruction "Handles support requests. Test triage, policy adherence, and escalation."

기본적으로 데이터 세트와 루브릭 계산기를 모두 생성하고, 아래에 evals/다운로드하고, 각각에 evals/azure.eval.yaml대한 카탈로그 항목을 추가합니다. --dataset 또는 --evaluator로 범위를 좁혀 하나만 생성하도록 하고, --max-samples로 행 수를 제한합니다(15~1000, 기본값 15).

generate는 모델 호출 비용이 드는 작업을 제출합니다. 지침이 중요합니다. 서비스에서 행과 루브릭에 대해 결정하는 데 사용하는 것이므로 에이전트가 수행하는 작업과 테스트해야 하는 작업을 설명합니다.

카탈로그 항목은 아티팩트를 선언합니다. 어떤 평가에서 사용하는지 결정하지 않습니다. generate 후 evals/azure.eval.yaml을 열고, 실행하려는 eval이 앞서 생성된 결과물을 참조하는지 확인하세요. trace-sourced eval은 trace를 읽으므로, 생성된 데이터세트는 eval이 해당 데이터세트를 지정해야만 사용됩니다:

datasets:
    - name: support-agent-dataset
      source: ./datasets/support-agent-dataset.jsonl
evals:
    - name: support-agent-eval
      dataset: support-agent-dataset   # point the eval at the generated dataset

작업을 제출하고 나중에 돌아오려면 다음을 수행합니다.

azd ai eval generate --target support-agent --generation-model gpt-4.1-nano --no-wait
azd ai eval job list --dataset
azd ai eval job show <job-id> --dataset

--evaluator에서 --dataset 및 job은 작업할 컬렉션을 선택하며, 이들 중 하나는 필수입니다.

azure.eval.yaml 검토

init는 읽도록 되어 있는 파일을 작성합니다. 추적 기반 평가는 다음과 같습니다.

evals:
    - name: support-trace-eval
      description: Basic quality evaluation for support-agent
      source:
        type: traces
        max_traces: 20
        agent_name: support-agent
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano

데이터 세트 원본 평가는 추적 원본 대신 데이터 세트의 이름을 지정하고 대상으로 하는 에이전트를 기록합니다.

datasets:
    - name: support-golden
      source: ../tests/support-golden.jsonl
evals:
    - name: support-agent-eval
      description: Basic quality evaluation for support-agent
      dataset: support-golden
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.intent_resolution
          initialization_parameters:
            model: gpt-4.1-nano
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano
      target:
        type: agent
        name: support-agent

아래 source: 경로는 구성 파일을 기준으로 합니다. 생성된 .jsonl 및 계산기 JSON은 일반 파일입니다. 편집한 다음 다시 실행 create 하여 새 버전을 등록합니다.

이 파일을 커밋합니다. 이는 평가의 재현 가능한 부분입니다.

eval을 만들고 실행합니다.

create를 사용해 구성에서 선언한 모든 항목(데이터 세트, 평가자, 평가 자체)을 등록하세요:

azd ai eval create

그런 다음, 다음을 실행합니다.

azd ai eval run start

run start는 기본적으로 실행이 완료될 때까지 기다리며, 통과율과 평균 점수, 그리고 포털에서 해당 실행으로 연결되는 링크가 포함된 평가자별 표를 출력합니다. 제출하고 돌아가려면 --no-wait을(를) 사용하고, 전송되는 행 수를 제한하려면 --max-samples을(를) 사용하세요.

구성에서 eval이 둘 이상 선언된 경우, 지정하려는 eval의 이름을 명시합니다.

azd ai eval run start --eval support-trace-eval

결과 검사

이 요약은 품질이 이동되었는지 여부를 알려줍니다. 샘플별 행은 그 이유를 알려줍니다.

azd ai eval run output list --eval support-trace-eval
azd ai eval run output list --eval support-trace-eval --failed-only

시간 경과에 따른 실행 기록과 서비스에 하나의 eval에 대해 저장된 내용을 보려면 다음을 수행합니다.

azd ai eval list
azd ai eval run list --eval support-trace-eval
azd ai eval show support-trace-eval

show 는 프로젝트에서 eval의 ID(ID, 이름 및 생성 시기)를 반환합니다. eval이 하는 일은 evals/azure.eval.yaml에 있습니다.

run list 는 실행당 한 번의 통과율을 전달합니다. 평가자별 세부 내역은 -o json의 per_testing_criteria_results 아래에 있습니다. 실행마다 서로 다른 평가자가 채점되기 시작하면 평가자별 열은 더 이상 읽기 쉬워지지 않기 때문입니다.

결과를 다른 곳으로 가져가려면 다음을 수행합니다.

azd ai eval run output list --eval support-trace-eval --output-file rows.json
azd ai eval run output export --eval support-trace-eval --format csv --output-file summary.csv

두 항목은 서로 다르며, 그 차이는 중요합니다. run output list --output-file는 샘플별 행을 기록하고, run output export는 실행당 한 줄을 기록합니다. 즉, 요약을 뒷받침하는 총계입니다.

빌드 차단

--fail-on을 전달하면 실행이 확인으로 전환됩니다. 실행이 임계값을 놓치면 0이 아닌 값으로 종료됩니다. 즉, 파이프라인이 품질을 회귀하는 변경에 실패하는 방법입니다.

azd ai eval run start --fail-on pass-rate=0.8
azd ai eval run start --fail-on any-failure

--fail-on가 없으면 실패한 샘플이 있더라도 완료된 실행은 여전히 종료 코드 0으로 종료됩니다. 실패한 샘플은 도구 오류가 아닌 작업 평가의 예상 출력이므로 게이팅은 옵트인입니다.

pass-rate 는 0에서 1 사이의 숫자를 취합니다. 1이 아닌 임계값은 실행이 제출되기 전에 거부되므로, 게이트를 잘못 입력해도 비용이 전혀 들지 않습니다.

--fail-on 에는 완료된 실행이 필요합니다. run show에서는 --wait와 페어링하세요.

프로젝트의 나머지 부분과 함께 평가 배포

init 는 평가 서비스를 azure.yaml추가하므로 eval은 측면 아티팩트가 아닌 프로젝트의 일부입니다.

azd up

이는 프로젝트를 프로비저닝하고 선언된 데이터 세트, 평가자 및 평가를 등록하는 것으로, azd ai eval create가 자체적으로 수행하는 것과 동일한 작업입니다.

에이전트 변경 및 다시 평가

에이전트를 변경하고 다시 배포한 후 동일한 평가를 다시 실행합니다.

azd deploy
azd ai eval run start --eval support-trace-eval

동일한 eval을 다시 사용하면 데이터 세트, 계산기 및 임계값이 고정되어 있으므로 에이전트에 대한 비교가 가능합니다.

평가가 무엇을 측정하는지 변경하려면 evals/azure.eval.yaml 또는 evals/ 아래의 생성된 아티팩트를 편집한 다음 create를 다시 실행하세요. create 는 변경된 모든 항목의 새 버전을 등록하고 이전 실행이 사용된 버전에 고정되도록 합니다.

모범 사례

--source traces 에이전트가 이미 실행되고 추적을 내보내는 경우부터 시작합니다. 발생한 일을 측정하며, 직접 작성할 것은 없습니다.
--source dataset 버전 간에 비교할 수 있는 고정된 사례 집합을 원하는 경우로 이동합니다.
점수를 신뢰하기 전에 생성된 데이터 세트 및 루브릭을 읽습니다. generate 사용자가 제공한 지시를 바탕으로 그 항목들을 생성하므로, 지시가 모호하면 생성되는 행도 모호해집니다.
둘 이상의 평가자를 사용하세요. 단일 조건은 이유를 알려주지 않고 숫자를 이동합니다.
evals/azure.eval.yaml 및 생성된 아티팩트를 커밋하여 평가를 검토할 수 있도록 하세요.
CI에서 --fail-on을 기준으로 게이트를 설정하고, 실제 회귀가 이를 트리거할 수 있는 임계값을 유지하세요.

Limitations

확장은 미리 보기 상태이며 명령 화면이 변경 될 수 있습니다.
generate는 과금된 작업을 제출합니다. 데이터 세트와 평가자는 azd provision에 의해 생성된 것이 아닙니다.
추적 기반 평가는 에이전트가 이미 생성한 추적만 읽을 수 있습니다.
azd 는 확장의 종료 코드를 축소하므로 게이트 위반 및 작동 실패가 모두 0이 아닌 출구로 표시됩니다. 게이트 메시지를 읽고 구분합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-08-21