평가는 에이전트에 대한 품질 기준을 설정하고 사용자에게 변경 내용을 릴리스하기 전에 작업 준수 전달 속도와 같은 수용 임계값을 설정할 수 있습니다.
이 작업을 시작하려면 다음이 필요합니다.
각 단계에서는 5개의 경로를 제공합니다. 원하는 항목을 사용합니다.
평가는 배포된 호출 가능한 에이전트에 대해 실행됩니다. 평가를 설정하기 전에 에이전트가 배포되고 사용 가능한지 확인합니다.
프로젝트 디렉터리에서 에이전트가 배포되고 호출 가능한지 확인합니다 azd .
azd ai agent show
테스트 프롬프트 보내기:
azd ai agent invoke "Write a haiku about deploying cloud applications."
몇 초 내에 응답이 표시됩니다.
-
Foundry 포털을 열고 프로젝트로 이동합니다.
- 에이전트를 선택한 다음 , 플레이그라운드 탭을 선택합니다.
- 테스트 프롬프트 보내기(예: )
Write a haiku about deploying cloud applications.
몇 초 내에 응답이 표시됩니다.
Foundry SDK를 설치합니다.
pip install "azure-ai-projects>=2.0.0" azure-identity
두 환경 변수를 설정한 다음 프로젝트 클라이언트를 만듭니다.
FOUNDRY_PROJECT_ENDPOINT를 프로젝트 엔드포인트로, FOUNDRY_MODEL_NAME를 평가 모델로 사용할 채팅 완성용 배포로 설정하세요. 다음 코드 샘플에서는 이 컨텍스트에서 실행된다고 가정합니다.
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment = os.environ["FOUNDRY_MODEL_NAME"]
credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()
배포된 에이전트가 등록되고 사용 가능한지 확인합니다.
<your-agent-name>을 호스팅된 에이전트의 이름으로 대체하세요:
agent = project_client.agents.get("<your-agent-name>")
print(f"Found agent: {agent.name}")
호출이 있으면 에이전트를 반환하거나 이름이 잘못되었거나 에이전트가 배포되지 않은 경우 오류가 발생합니다.
Foundry SDK 및 OpenAI evals 클라이언트를 설치합니다.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package OpenAI
dotnet add package Azure.Identity
두 환경 변수를 설정한 다음 클라이언트를 만듭니다.
FOUNDRY_PROJECT_ENDPOINT를 프로젝트 엔드포인트로, FOUNDRY_MODEL_NAME를 평가 모델로 사용할 채팅 완성용 배포로 설정하세요. 다음 코드 샘플에서는 이 컨텍스트에서 실행된다고 가정합니다.
using System.ClientModel;
using System.Text.Json;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Core;
using Azure.Identity;
using OpenAI;
using OpenAI.Evals;
#pragma warning disable AAIP001, OPENAI001
var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!;
var modelDeployment = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")!;
var credential = new DefaultAzureCredential();
AIProjectClient projectClient = new(new Uri(endpoint), credential);
// OpenAI-compatible evals client bound to the Foundry project endpoint.
// A Microsoft Entra token works as the credential because both use "Authorization: Bearer".
var token = credential.GetToken(new TokenRequestContext(["https://ai.azure.com/.default"])).Token;
EvaluationClient evalClient = new(
new ApiKeyCredential(token),
new OpenAIClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1") });
배포된 에이전트가 등록되고 사용 가능한지 확인합니다.
<your-agent-name>을 호스팅된 에이전트의 이름으로 대체하세요:
ProjectsAgentRecord agent = projectClient.AgentAdministrationClient.GetAgent("<your-agent-name>");
Console.WriteLine($"Found agent: {agent.Name}");
호출이 있으면 에이전트를 반환하거나 이름이 잘못되었거나 에이전트가 배포되지 않은 경우 오류가 발생합니다.
Foundry SDK를 설치합니다.
npm install @azure/ai-projects @azure/identity dotenv
두 환경 변수를 설정한 다음 프로젝트 클라이언트를 만듭니다.
FOUNDRY_PROJECT_ENDPOINT를 프로젝트 엔드포인트로, FOUNDRY_MODEL_NAME를 평가 모델로 사용할 채팅 완성용 배포로 설정하세요. 다음 코드 샘플에서는 이 컨텍스트에서 실행된다고 가정합니다.
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const endpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelDeployment = process.env["FOUNDRY_MODEL_NAME"] || "";
const projectClient = new AIProjectClient(
endpoint,
new DefaultAzureCredential(),
);
const client = projectClient.getOpenAIClient();
배포된 에이전트가 등록되고 사용 가능한지 확인합니다.
<your-agent-name>을 호스팅된 에이전트의 이름으로 대체하세요:
const agent = await projectClient.agents.get("<your-agent-name>");
console.log(`Found agent: ${agent.name}`);
호출이 있으면 에이전트를 반환하거나 이름이 잘못되었거나 에이전트가 배포되지 않은 경우 오류가 발생합니다.
참조: AIProjectClient 클래스
테스트 데이터 세트에 대해 에이전트의 점수를 매기려면 기본 제공 평가자로 시작합니다.
먼저 에이전트에 대한 테스트 쿼리의 JSONL 파일을 만듭니다. 각 줄은 query 필드가 있는 JSON 객체입니다. 다음과 같이 src/<your-agent-name>/tests/queries.jsonl에이전트의 원본 폴더 내에 저장합니다.
{"query": "Write a haiku about deploying cloud applications."}
그런 다음 같은 에이전트 소스 폴더에 eval.yaml 파일을 src/<your-agent-name>/eval.yaml로 만듭니다. 데이터 세트를 가리키고 적용할 기본 제공 평가기를 나열합니다. 경로는 dataset.local_uri 이 폴더를 기준으로 합니다.
<your-agent-name> 을(를) 호스팅된 에이전트 이름으로, <your-chat-completion-deployment>을(를) 판정 모델 배포로 바꾸세요.
name: agent-eval
agent:
name: <your-agent-name>
kind: hosted
dataset:
local_uri: tests/queries.jsonl
evaluators:
- builtin.intent_resolution
- builtin.task_adherence
options:
eval_model: <your-chat-completion-deployment>
max_samples: 15
eval_model 값은 응답을 채점하는 심사 모델이며, 에이전트가 이미 사용 중인 배포를 재사용할 수 있습니다.
-
Foundry 포털에서 에이전트를 열고 평가 탭을 선택한 다음 만들기를 선택합니다.
-
평가 대상 선택에서 에이전트를 선택합니다.
-
평가 범위 선택에서 개별 턴을 선택합니다.
-
데이터 원본 선택에서 기존 데이터 세트를 선택하고 프로젝트의 데이터 자산에서 테스트 쿼리의 CSV 또는 JSONL 파일을 선택합니다.
-
에이전트 구성 단계가 나타나면 에이전트를 검토하고 기본 사용자 프롬프트
{{item.query}}를 수락합니다. 에이전트에 다른 입력 형식이 필요한 경우에만 조정합니다.
-
테스트 조건 선택을 위해 작업 준수 및 의도 확인과 같은 하나 이상의 에이전트 평가자를 선택합니다.
마법사를 열어 두세요. 다음 단계에서 평가를 제출합니다.
먼저 에이전트에 대한 테스트 쿼리의 JSONL 파일을 만듭니다. 각 줄은 query 필드가 있는 JSON 객체입니다.
queries.jsonl으로 저장합니다:
{"query": "Write a haiku about deploying cloud applications."}
프로젝트에서 파일을 데이터 세트로 업로드합니다.
dataset = project_client.datasets.upload_file(
name="agent-test-queries",
version="1",
file_path="./queries.jsonl",
)
다음으로, 기본 제공 평가기를 선택하고 입력을 매핑합니다. 매개 변수는 data_mapping 각 평가자에게 쿼리 및 에이전트 응답을 찾을 위치를 알려줍니다. AI 지원 평가자에는 initialization_parameters의 심사 모델이 필요합니다. 해당 값은 프로젝트의 채팅 완성 배포여야 합니다.
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator
testing_criteria = [
TestingCriterionAzureAIEvaluator(
type="azure_ai_evaluator",
name="Intent Resolution",
evaluator_name="builtin.intent_resolution",
initialization_parameters={"model": model_deployment},
data_mapping={
"query": "{{item.query}}",
"response": "{{sample.output_items}}",
},
),
TestingCriterionAzureAIEvaluator(
type="azure_ai_evaluator",
name="Task Adherence",
evaluator_name="builtin.task_adherence",
initialization_parameters={"model": model_deployment},
data_mapping={
"query": "{{item.query}}",
"response": "{{sample.output_items}}",
},
),
]
평가를 만듭니다. 테스트 데이터 스키마 및 테스트 조건을 정의하고 하나 이상의 실행에 대한 컨테이너 역할을 합니다.
from openai.types.eval_create_params import DataSourceConfigCustom
data_source_config = DataSourceConfigCustom(
type="custom",
item_schema={
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
include_sample_schema=True,
)
evaluation = client.evals.create(
name="Agent Quality Evaluation",
data_source_config=data_source_config,
testing_criteria=testing_criteria,
)
print(f"Evaluation created: {evaluation.id}")
먼저 에이전트에 대한 테스트 쿼리의 JSONL 파일을 만듭니다. 각 줄은 query 필드가 있는 JSON 객체입니다.
queries.jsonl으로 저장합니다:
{"query": "Write a haiku about deploying cloud applications."}
프로젝트에서 파일을 데이터 세트로 업로드합니다.
AIProjectDataset dataset = projectClient.Datasets.UploadFile(
name: "agent-test-queries",
version: "1",
filePath: "./queries.jsonl");
다음으로, 기본 제공 평가기를 선택하고 입력을 매핑합니다. 매개 변수는 data_mapping 각 평가자에게 쿼리 및 에이전트 응답을 찾을 위치를 알려줍니다. AI 지원 평가자에는 initialization_parameters의 심사 모델이 필요합니다. 해당 값은 프로젝트의 채팅 완성 배포여야 합니다.
var testingCriteria = new object[]
{
new
{
type = "azure_ai_evaluator",
name = "Intent Resolution",
evaluator_name = "builtin.intent_resolution",
initialization_parameters = new { model = modelDeployment },
data_mapping = new { query = "{{item.query}}", response = "{{sample.output_items}}" },
},
new
{
type = "azure_ai_evaluator",
name = "Task Adherence",
evaluator_name = "builtin.task_adherence",
initialization_parameters = new { model = modelDeployment },
data_mapping = new { query = "{{item.query}}", response = "{{sample.output_items}}" },
},
};
평가를 만듭니다. 테스트 데이터 스키마 및 테스트 조건을 정의하고 하나 이상의 실행에 대한 컨테이너 역할을 합니다.
var createEvaluation = new
{
name = "Agent Quality Evaluation",
data_source_config = new
{
type = "custom",
item_schema = new
{
type = "object",
properties = new { query = new { type = "string" } },
required = new[] { "query" },
},
include_sample_schema = true,
},
testing_criteria = testingCriteria,
};
ClientResult evaluationResult = evalClient.CreateEvaluation(
BinaryContent.Create(BinaryData.FromObjectAsJson(createEvaluation)));
string evaluationId = JsonDocument.Parse(evaluationResult.GetRawResponse().Content.ToString())
.RootElement.GetProperty("id").GetString()!;
Console.WriteLine($"Evaluation created: {evaluationId}");
먼저 에이전트에 대한 테스트 쿼리의 JSONL 파일을 만듭니다. 각 줄은 query 필드가 있는 JSON 객체입니다.
queries.jsonl으로 저장합니다:
{"query": "Write a haiku about deploying cloud applications."}
프로젝트에서 파일을 데이터 세트로 업로드합니다.
const dataset = await projectClient.datasets.uploadFile(
"agent-test-queries",
"1",
"./queries.jsonl",
);
다음으로, 기본 제공 평가기를 선택하고 입력을 매핑합니다. 매개 변수는 data_mapping 각 평가자에게 쿼리 및 에이전트 응답을 찾을 위치를 알려줍니다. AI 지원 평가자에는 initialization_parameters의 심사 모델이 필요합니다. 해당 값은 프로젝트의 채팅 완성 배포여야 합니다.
const testingCriteria = [
{
type: "azure_ai_evaluator",
name: "Intent Resolution",
evaluator_name: "builtin.intent_resolution",
initialization_parameters: { model: modelDeployment },
data_mapping: {
query: "{{item.query}}",
response: "{{sample.output_items}}",
},
},
{
type: "azure_ai_evaluator",
name: "Task Adherence",
evaluator_name: "builtin.task_adherence",
initialization_parameters: { model: modelDeployment },
data_mapping: {
query: "{{item.query}}",
response: "{{sample.output_items}}",
},
},
];
평가를 만듭니다. 테스트 데이터 스키마 및 테스트 조건을 정의하고 하나 이상의 실행에 대한 컨테이너 역할을 합니다.
const dataSourceConfig = {
type: "custom",
item_schema: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
},
include_sample_schema: true,
};
const evaluation = await client.evals.create({
name: "Agent Quality Evaluation",
data_source_config: dataSourceConfig,
testing_criteria: testingCriteria,
});
console.log(`Evaluation created: ${evaluation.id}`);
배포한 에이전트를 대상으로 테스트 스위트를 실행하세요. 서비스는 각 테스트 쿼리를 에이전트에 보내고, 응답을 캡처하고, 선택한 평가자를 사용하여 점수를 매깁니다.
azd 작업 영역 루트에서 평가를 실행합니다.
azd ai agent eval run --config eval.yaml
참고
azd ai agent eval run는 --config 경로를 현재 디렉터리가 아니라 src/ 아래에 있는 에이전트의 소스 폴더(예: src/<your-agent-name>/eval.yaml)를 기준으로 확인합니다.
eval.yaml 및 이 local_uri가 가리키는 데이터 세트를 해당 폴더 안에 유지하세요.
이 명령은 각 쿼리를 읽고 eval.yaml, 에이전트에 보내고, 응답의 점수를 매기고, 완료 시 요약을 출력합니다.
Eval run started
Eval: eval_b36748dede424e4ba3f8e6c99ca2cf27
Run: evalrun_5f72ef189ad24790a32128e6f230b131
(✓) Done Eval run
Results: 1 total, 1 passed, 0 failed, 0 errored
Per-criteria results:
intent_resolution: 1 passed, 0 failed, 0 errored
task_adherence: 1 passed, 0 failed, 0 errored
-
검토 및 제출 단계에서 평가의 이름을 입력합니다.
- 대상, 범위, 데이터 원본 및 선택한 평가자를 검토합니다.
-
제출을 선택하여 실행을 시작합니다.
각 테스트 쿼리를 에이전트에 보내고 평가자를 적용하는 실행을 만듭니다.
<your-agent-name>을 호스팅된 에이전트의 이름으로 대체하세요:
eval_run = client.evals.runs.create(
eval_id=evaluation.id,
name="Agent Evaluation Run",
data_source={
"type": "azure_ai_target_completions",
"source": {"type": "file_id", "id": dataset.id},
"input_messages": {
"type": "template",
"template": [
{
"type": "message",
"role": "user",
"content": {"type": "input_text", "text": "{{item.query}}"},
}
],
},
"target": {
"type": "azure_ai_agent",
"name": "<your-agent-name>",
# "version": "1", # Optional; omit to use the latest version
},
},
)
print(f"Evaluation run started: {eval_run.id}")
각 테스트 쿼리를 에이전트에 보내고 평가자를 적용하는 실행을 만듭니다.
<your-agent-name>을 호스팅된 에이전트의 이름으로 대체하세요:
var createRun = new
{
name = "Agent Evaluation Run",
data_source = new
{
type = "azure_ai_target_completions",
source = new { type = "file_id", id = dataset.Id },
input_messages = new
{
type = "template",
template = new object[]
{
new { type = "message", role = "user", content = new { type = "input_text", text = "{{item.query}}" } },
},
},
// Add a "version" property to the target to pin a specific agent version; omit to use the latest.
target = new { type = "azure_ai_agent", name = "<your-agent-name>" },
},
};
ClientResult runResult = evalClient.CreateEvaluationRun(
evaluationId, BinaryContent.Create(BinaryData.FromObjectAsJson(createRun)));
string runId = JsonDocument.Parse(runResult.GetRawResponse().Content.ToString())
.RootElement.GetProperty("id").GetString()!;
Console.WriteLine($"Evaluation run started: {runId}");
각 테스트 쿼리를 에이전트에 보내고 평가자를 적용하는 실행을 만듭니다.
<your-agent-name>을 호스팅된 에이전트의 이름으로 대체하세요:
const evalRun = await client.evals.runs.create(evaluation.id, {
name: "Agent Evaluation Run",
data_source: {
type: "azure_ai_target_completions",
source: { type: "file_id", id: dataset.id },
input_messages: {
type: "template",
template: [
{
type: "message",
role: "user",
content: { type: "input_text", text: "{{item.query}}" },
},
],
},
target: {
type: "azure_ai_agent",
name: "<your-agent-name>",
// version: "1", // Optional; omit to use the latest version
},
},
});
console.log(`Evaluation run started: ${evalRun.id}`);
일반적으로 평가는 쿼리 수에 따라 몇 분 안에 완료됩니다.
최근 평가를 나열합니다.
azd ai agent eval list
Eval ID Name Status of last run Runs
------- ---- ------------------ ----
* eval_b36748dede424e4ba3f8e6c99ca2cf27 agent-eval Completed 1
* = active eval in current environment
가장 최근의 평가 및 해당 실행을 표시합니다.
azd ai agent eval show
Eval: eval_b36748dede424e4ba3f8e6c99ca2cf27
Name: agent-eval
Agent: <your-agent-name>
Runs: 1
Recent runs:
Run ID Status Passed Failed Created
------ ------ ------ ------ -------
evalrun_5f72ef189ad24790a32128e6f230b131 Completed 1/1 0 2026-06-17 14:52 UTC
결과를 사용하여 평가된 에이전트 버전과 생성된 평가자 점수를 확인합니다. Foundry 포털에서 평가자별 세부 정보 및 보고서에 대한 링크를 보려면 다음을 실행합니다 azd ai agent eval show <eval-id> --eval-run-id <run-id>.
- 세부 정보 페이지에는 각 평가자에 대한 대상, 데이터 세트, 상태, 토큰 사용량 및 집계 점수가 표시됩니다.
- 각 쿼리, 에이전트 응답, 평가자 점수 및 점수 설명과 같은 행 수준 결과를 보려면 실행 이름을 선택합니다.
완료될 때까지 폴링한 다음, 상태와 Foundry 포털에서 결과를 여는 보고서 URL을 출력합니다.
import time
while True:
run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
if run.status in ["completed", "failed"]:
break
time.sleep(5)
print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")
실행 수준에서 각 평가자에 대한 집계된 통과 및 실패 횟수를 볼 수 있습니다.
print(run.result_counts)
for criteria in run.per_testing_criteria_results:
print(criteria.testing_criteria, "passed:", criteria.passed, "failed:", criteria.failed)
ResultCounts(errored=0, failed=0, passed=1, total=1, skipped=0)
Intent Resolution passed: 1 failed: 0
Task Adherence passed: 1 failed: 0
행 수준 세부 정보를 보려면 출력 항목을 나열합니다. 각 결과에는 평가자 이름, 합격 또는 불합격 여부, 그리고 점수가 포함됩니다.
for item in client.evals.runs.output_items.list(run_id=eval_run.id, eval_id=evaluation.id):
for result in item.results:
print(item.id, result.name, "passed:", result.passed, "score:", result.score)
완료될 때까지 폴링한 다음, 상태와 Foundry 포털에서 결과를 여는 보고서 URL을 출력합니다.
JsonElement run = default;
while (true)
{
ClientResult runStatus = evalClient.GetEvaluationRun(evaluationId, runId, options: null);
run = JsonDocument.Parse(runStatus.GetRawResponse().Content.ToString()).RootElement;
string status = run.GetProperty("status").GetString()!;
if (status is "completed" or "failed") break;
Thread.Sleep(TimeSpan.FromSeconds(5));
}
Console.WriteLine($"Status: {run.GetProperty("status").GetString()}");
Console.WriteLine($"Report URL: {run.GetProperty("report_url").GetString()}");
실행 수준에서 각 평가자에 대한 집계된 통과 및 실패 횟수를 볼 수 있습니다.
Console.WriteLine(run.GetProperty("result_counts").GetRawText());
foreach (JsonElement criteria in run.GetProperty("per_testing_criteria_results").EnumerateArray())
{
Console.WriteLine(
$"{criteria.GetProperty("testing_criteria").GetString()} " +
$"passed: {criteria.GetProperty("passed").GetInt32()} " +
$"failed: {criteria.GetProperty("failed").GetInt32()}");
}
행 수준 세부 정보를 보려면 출력 항목을 나열합니다. 각 결과에는 평가자 이름, 합격 또는 불합격 여부, 그리고 점수가 포함됩니다.
ClientResult outputItems = evalClient.GetEvaluationRunOutputItems(
evaluationId, runId, limit: 100, order: null, after: null, outputItemStatus: null, options: null);
foreach (JsonElement item in JsonDocument.Parse(outputItems.GetRawResponse().Content.ToString())
.RootElement.GetProperty("data").EnumerateArray())
{
foreach (JsonElement result in item.GetProperty("results").EnumerateArray())
{
Console.WriteLine(
$"{item.GetProperty("id").GetString()} {result.GetProperty("name").GetString()} " +
$"passed: {result.GetProperty("passed")} score: {result.GetProperty("score")}");
}
}
완료될 때까지 폴링한 다음, 상태와 Foundry 포털에서 결과를 여는 보고서 URL을 출력합니다.
let run = evalRun;
while (!["completed", "failed"].includes(run.status)) {
run = await client.evals.runs.retrieve(run.id, {
eval_id: evaluation.id,
});
await new Promise((resolve) => setTimeout(resolve, 5000));
}
console.log(`Status: ${run.status}`);
console.log(`Report URL: ${run.report_url}`);
실행 수준에서 각 평가자에 대한 집계된 통과 및 실패 횟수를 볼 수 있습니다.
console.log(JSON.stringify(run.result_counts));
for (const criteria of run.per_testing_criteria_results) {
console.log(
criteria.testing_criteria,
"passed:",
criteria.passed,
"failed:",
criteria.failed,
);
}
{"errored":0,"failed":0,"passed":1,"total":1,"skipped":0}
Intent Resolution passed: 1 failed: 0
Task Adherence passed: 1 failed: 0
행 수준 세부 정보를 보려면 출력 항목을 나열합니다. 각 결과에는 평가자 이름, 합격 또는 불합격 여부, 그리고 점수가 포함됩니다.
for await (const item of client.evals.runs.outputItems.list(run.id, {
eval_id: evaluation.id,
})) {
for (const result of item.results) {
console.log(item.id, result.name, "passed:", result.passed, "score:", result.score);
}
}
이 빠른 시작에서는 Foundry 프로젝트에서 데이터 세트, 평가 및 실행 기록을 등록합니다. 이러한 자산에는 지속적인 비용이 거의 또는 전혀 발생하지 않습니다.
이 빠른 시작에서 당신은 다음을 수행합니다.
평가 워크플로를 계속 개선합니다.
