데이터 에이전트 평가(미리 보기)

Fabric SDK를 사용해 평가를 통해 데이터 에이전트가 자연어 질문에 얼마나 잘 반응하는지 프로그래밍적으로 테스트할 수 있습니다. 간단한 Python 인터페이스를 사용하면 실제 예시를 정의하고, 평가를 실행하며, 결과를 분석할 수 있습니다—모두 노트북 환경 내에서 이루어집니다. 이 과정은 정확성을 검증하고, 오류를 디버깅하며, 에이전트를 자신 있게 개선한 후 프로덕션에 배포하는 데 도움을 줍니다.

중요합니다

이 기능은 프리뷰 상태입니다.

필수 조건

F2 이상의 유료 Fabric 용량 또는 Power BI 프리미엄(P1 이상) 용량에 Microsoft Fabric이 활성화된 용량.
패브릭 데이터 에이전트 테넌트 설정에 설명된 요구 사항에 따라 AI에 대해 지역 간 처리 및 지역 간 저장을 사용하도록 설정합니다.
적어도 데이터가 있는 다음 데이터 원본 중 하나 이상: 웨어하우스, 레이크하우스, Power BI 의미 체계 모델, KQL 데이터베이스, 미러된 데이터베이스 또는 온톨로지. 데이터 원본에 대한 읽기 권한이 있어야 합니다.

데이터 에이전트 SDK 설치

Fabric 데이터 에이전트를 프로그래밍적으로 평가하기 시작하려면 Fabric 데이터 에이전트 Python SDK를 설치하세요. 이 SDK는 데이터 에이전트와 상호 작용하고, 평가를 실행하고, 결과를 기록하는 데 필요한 도구와 메서드를 제공합니다. Notebook에서 다음 명령을 실행하여 최신 버전을 설치합니다.

%pip install -U fabric-data-agent-sdk

이 단계를 통해 SDK에서 가장 최신의 up-to기능과 수정 사항이 제공됩니다.

정답 데이터 세트를 로드하세요.

Fabric 데이터 에이전트를 평가하려면 샘플 질문과 예상되는 답변이 필요합니다. 이 질문들을 활용해 에이전트가 실제 쿼리에 얼마나 정확하게 응답하는지 검증하세요.

pandas DataFrame을 사용해 코드에서 이 질문들을 직접 정의하세요:

import pandas as pd

# Define a sample evaluation set with user questions and their expected answers.
# You can modify the question/answer pairs to match your scenario.
df = pd.DataFrame(
    columns=["question", "expected_answer"],
    data=[
        ["Show total sales for Canadian Dollar for January 2013", "46,117.30"],
        ["What is the product with the highest total sales for Canadian Dollar in 2013", "Mountain-200 Black, 42"],
        ["Total sales outside of the US", "19,968,887.95"],
        ["Which product category had the highest total sales for Canadian Dollar in 2013", "Bikes (Total Sales: 938,654.76)"]
    ]
)

또는 기존 평가 데이터셋이 있다면, 다음과 같은 열 questionexpected_answer과 다음과 같은 CSV 파일에서 데이터를 불러와보세요:

# Load questions and expected answers from a CSV file
input_file_path = "/lakehouse/default/Files/Data/Input/curated_2.csv"
df = pd.read_csv(input_file_path)

이 데이터 세트는 데이터 에이전트에 대해 자동화된 평가를 실행하여 정확도와 적용 범위를 평가하기 위한 입력 역할을 합니다.

데이터 에이전트 평가 및 분석

다음 단계는 함수 evaluate_data_agent 를 사용하여 평가를 수행하는 것입니다. 이 함수는 에이전트의 응답을 예상 결과와 비교하고 평가 메트릭을 저장합니다.

Note

이 단계는 이미 평가 단계에 공개된 데이터 에이전트가 필요합니다(production 또는 sandbox). 아직 없다면 'Create a Fabric data agent'를 참고하세요.

from fabric.dataagent.evaluation import evaluate_data_agent

# Name of your data agent
data_agent_name = "AgentEvaluation"

# (Optional) Name of the workspace if the data agent is in a different workspace
workspace_name = None

# (Optional) Name of the output table to store evaluation results (default: "evaluation_output")
# Two tables will be created:
# - "<table_name>": contains summary results (e.g., accuracy)
# - "<table_name>_steps": contains detailed reasoning and step-by-step execution
table_name = "demo_evaluation_output"

# Specify the data agent stage: "production" (default) or "sandbox"
data_agent_stage = "production"

# Run the evaluation and get the evaluation ID
try:
    evaluation_id = evaluate_data_agent(
        df,
        data_agent_name,
        workspace_name=workspace_name,
        table_name=table_name,
        data_agent_stage=data_agent_stage
    )
    print(f"Unique ID for the current evaluation run: {evaluation_id}")
except Exception as e:
    print(f"Evaluation failed: {e}")

런이 끝나면 다음과 같은 출력물을 볼 수 있습니다:

Unique ID for the current evaluation run: <evaluation-id>

평가 요약 가져오기

평가를 실행한 후에는 함수 get_evaluation_summary 를 사용하여 결과의 고수준 요약을 얻을 수 있습니다. 이 기능은 데이터 에이전트가 전체 성과를 내는 인사이트를 제공하며, 예상 답변과 일치하는 응답 수와 같은 지표를 포함합니다.

from fabric.dataagent.evaluation import get_evaluation_summary

# Retrieve a summary of the evaluation results
summary_df = get_evaluation_summary(table_name)

기본적으로 이 함수는 라는 이름의 evaluation_output테이블을 찾습니다. 평가 중에 커스텀 테이블 이름을 지정했다면(예: demo_evaluation_output) 그 이름을 인자로 table_name 전달하세요.

반환된 DataFrame에는 정확하거나 잘못되거나 명확하지 않은 응답 수와 같은 집계된 메트릭이 포함됩니다. 이 결과를 통해 에이전트의 정확도를 신속하게 평가하고 개선할 영역을 식별할 수 있습니다.

자세한 평가 결과 검사

데이터 에이전트가 각 개별 질문에 어떻게 응답했는지 더 깊이 들어가고 싶다면, 이 get_evaluation_details 기능을 사용하세요. 이 함수는 실제 에이전트 응답, 예상 답변과 일치하는지 여부, 평가 스레드에 대한 링크(평가를 실행한 사용자만 볼 수 있음)를 포함하여 평가 실행의 자세한 분석을 반환합니다.

from fabric.dataagent.evaluation import get_evaluation_details

# Table name used during evaluation
table_name = "demo_evaluation_output"

# Whether to return all evaluation rows (True) or only failures (False)
get_all_rows = False

# Whether to print a summary of the results
verbose = True

# Retrieve evaluation details for a specific run
eval_details = get_evaluation_details(
    evaluation_id,
    table_name,
    get_all_rows=get_all_rows,
    verbose=verbose
)

평가 프롬프트 사용자 지정

기본적으로 Fabric SDK는 데이터 에이전트의 실제 답변이 기대되는 답변과 일치하는지 평가하기 위해 내장된 프롬프트를 사용합니다. 하지만 매개변수를 사용하여 critic_prompt 더 미묘하거나 도메인 특화된 평가를 위한 자체 프롬프트를 제공할 수 있습니다.

사용자 지정 프롬프트에는 자리 표시자 {query}, {expected_answer}, 및 {actual_answer}가 포함되어야 합니다. 평가 과정은 각 질문마다 이 자리 표시자를 동적으로 대체합니다.

from fabric.dataagent.evaluation import evaluate_data_agent

# Define a custom prompt for evaluating agent responses
critic_prompt = """
    Given the following query, expected answer, and actual answer, please determine if the actual answer is equivalent to expected answer. If they are equivalent, respond with 'yes'.

    Query: {query}

    Expected Answer:
    {expected_answer}

    Actual Answer:
    {actual_answer}

    Is the actual answer equivalent to the expected answer?
"""

# Name of the data agent
data_agent_name = "AgentEvaluation"

# Run evaluation using the custom critic prompt
evaluation_id = evaluate_data_agent(df, data_agent_name, critic_prompt=critic_prompt)

이 기능은 다음 경우에 특히 유용합니다.

무엇을 일치로 간주할지에 대해 더 관대하거나 더 엄격한 기준을 적용하려고 합니다.
기대하는 답변과 실제 답변은 형식이 다를 수 있지만 의미적으로는 동등합니다.
답변을 판단하는 방법에 대한 도메인별 뉘앙스를 캡처해야 합니다.

진단 버튼

진단 버튼을 통해 데이터 에이전트의 구성 및 실행 단계에 대한 전체 스냅샷을 다운로드할 수 있습니다. 이 내보내기에는 데이터 소스 설정, 적용된 지침, 사용된 예시 쿼리, 그리고 데이터 에이전트가 응답을 생성하기 위해 밟은 기본 단계와 같은 세부 사항이 포함됩니다.

Microsoft 지원와 작업하거나 예상치 못한 현상을 해결할 때 이 기능을 사용하세요. 다운로드한 파일을 검토하면 데이터 에이전트가 요청을 어떻게 처리했는지, 어떤 설정이 적용되었는지, 잠재적 문제가 발생한 지점을 정확히 확인할 수 있습니다. 이러한 투명성 수준은 데이터 에이전트의 성능 디버깅과 최적화를 더 쉽게 만듭니다.

Troubleshooting

Issue	원인	해결 방법
데이터 에이전트를 찾지 못했습니다	`data_agent_name` 또는 `workspace_name`이(가) 올바르지 않거나 에이전트가 게시되지 않았습니다.	에이전트 이름과 작업 공간을 확인하고, 에이전트가 지정된 `data_agent_stage`에 게시되었는지 확인하세요.
비어 있거나 누락된 결과	테이블 이름이 `evaluate_data_agent` 중에 사용된 이름과 일치하지 않습니다.	동일한 `table_name`을 `get_evaluation_details` 및 `get_evaluation_summary`에 전달합니다.
`message_url` 접근 불가	평가 스레드는 평가를 실행한 사용자만 볼 수 있습니다.	스레드 링크에 접근하려면 본인 신원으로 평가를 다시 실행하세요.
커스텀 프롬프트는 아무런 효과나 오류가 없습니다	`critic_prompt`에 필수 자리 표시자가 없습니다.	프롬프트에 `{expected_answer}`, `{actual_answer}`, `{query}`를 포함하세요.
권한 또는 용량 오류	F2 이상의 용량이 누락되었거나, 데이터 소스에 대한 읽기 접근 권한이 누락된 경우.	용량과 데이터 소스 읽기 접근권 등 전제 조건을 확인하세요.

다음 단계

피드백

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

Last updated on 2026-09-02