Azure AI Foundry SDK를 사용하여 온라인으로 평가를 실행하는 방법

아티클
01/23/2025

Important

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

이 문서에서는 Azure AI Foundry SDK를 사용하여 지속적으로 온라인으로 평가를 실행하는 방법을 알아봅니다. 사전 프로덕션 환경에서 평가 는 애플리케이션이 안전하고 성능이 뛰어나며 고품질의 결과를 생성하는 데 필수적입니다. 그러나 애플리케이션을 배포한 후에는 평가가 중지되지 않습니다. 프로덕션 환경에서는 사용자가 애플리케이션에 보내는 쿼리 유형과 같은 다양한 사항이 변경되어 애플리케이션의 성능에 영향을 줄 수 있습니다. 프로덕션 생성 AI 애플리케이션에서 높은 수준의 가시성을 유지하려면 애플리케이션의 데이터를 추적하고 지속적으로 평가하는 것이 중요합니다. 이렇게 하면 애플리케이션의 안전성, 품질 및 성능에 대한 신뢰를 유지할 수 있습니다.

온라인 평가 작동 방식

이 섹션에서는 온라인 평가의 작동 방식, Azure Monitor Application Insights와 통합하는 방법 및 이를 사용하여 생성 AI 애플리케이션의 추적 데이터에 대한 지속적인 평가를 실행하는 방법을 알아봅니다.

Application Insights에 추적 데이터를 보내도록 애플리케이션을 계측한 후 이 데이터를 지속적으로 평가하도록 온라인 평가 일정을 설정합니다. 온라인 평가는 Azure AI 컴퓨팅을 사용하여 구성 가능한 계산기 집합을 지속적으로 실행하는 서비스입니다. Azure AI Foundry SDK를 사용하여 온라인 평가 일정을 설정한 후에는 구성 가능한 일정으로 실행됩니다. 예약된 작업이 실행될 때마다 다음 단계를 수행합니다.

제공된 KQL(Kusto) 쿼리를 사용하여 연결된 Application Insights 리소스에서 애플리케이션 추적 데이터를 쿼리합니다.
추적 데이터에 대해 각 계산기를 실행하고 각 메트릭을 계산합니다(예 : 접지: 3).
표준화된 의미 체계 규칙을 사용하여 각 추적에 평가 점수를 다시 씁니다.

참고 항목

온라인 평가는 Azure AI 평가와 동일한 메트릭을 지원합니다. 평가가 작동하는 방식과 지원되는 평가 메트릭에 대한 자세한 내용은 Azure AI 평가 SDK를 사용하여 생성 AI 애플리케이션 평가를 참조하세요.

예를 들어 매일 많은 고객 질문을 받는 배포된 채팅 애플리케이션이 있다고 가정해 보겠습니다. 애플리케이션에서 응답의 품질을 지속적으로 평가하려고 합니다. 매일 되풀이를 사용하여 온라인 평가 일정을 설정합니다. 평가자(Groundedness, Coherence 및 Fluency)를 구성합니다. 서비스는 매일 이러한 메트릭에 대한 평가 점수를 계산하고 되풀이 기간 동안 수집된 각 추적에 대한 데이터를 Application Insights에 다시 씁니다(이 예제에서는 지난 24시간). 그런 다음, 각 추적에서 데이터를 쿼리하고 Azure AI Foundry 및 Azure Monitor Application Insights에서 액세스할 수 있습니다.

Application Insights 내의 각 추적에 다시 기록된 평가 결과는 다음 규칙을 따릅니다. 각 평가 메트릭에 대한 각 추적에 고유한 범위가 추가됩니다.

속성	Application Insights 테이블	지정된 operation_ID 대한 필드	예제 값
평가 메트릭	traces, AppTraces	`customDimensions[“event.name”]`	`gen_ai.evaluation.relevance`
평가 메트릭 점수	traces, AppTraces	`customDimensions[“gen_ai.evaluation.score”]`	`3`
평가 메트릭 주석(해당하는 경우)	traces, AppTraces	`message`	`{“comment”: “I like the response”}`

이제 온라인 평가의 작동 방식과 Azure Monitor Application Insights에 연결하는 방법을 이해했으므로 다음 단계는 서비스를 설정하는 것입니다.

온라인 평가 설정

이 섹션에서는 배포된 생성 AI 애플리케이션을 지속적으로 모니터링하도록 온라인 평가 일정을 구성하는 방법을 알아봅니다. Azure AI Foundry SDK는 이러한 기능을 통해 제공합니다. Python API는 로컬 평가에서 사용할 수 있는 모든 기능을 지원합니다. 다음 단계를 사용하여 기본 제공 또는 사용자 지정 평가기를 사용하여 데이터에 대한 온라인 평가 일정을 제출합니다.

참고 항목

평가는 AI 지원 위험 및 안전 메트릭과 동일한 지역에서 만 지원됩니다.

필수 조건

다음 필수 구성 요소 단계를 완료하여 필요한 리소스에 대한 환경 및 인증을 설정합니다.

Azure 구독.
평가 지원 지역의 리소스 그룹입니다.
동일한 리소스 그룹 및 지역의 새 사용자 할당 관리 ID 입니다. clientId나중에 필요합니다.
동일한 리소스 그룹 및 지역에 있는 Azure AI Hub입니다.
이 허브의 Azure AI 프로젝트는 Azure AI Foundry 포털에서 프로젝트 만들기를 참조 하세요.
Azure Monitor Application Insights 리소스.
Azure Portal의 허브 페이지로 이동하고 Application Insights 리소스를 추가합니다. Azure 애플리케이션 Insights 및 Azure Container Registry 업데이트를 참조하세요.
예를 들어 gpt-4GPT 모델을 지원하는 chat completionAzure OpenAI 배포.
Connection String Azure AI 프로젝트가 개체를 쉽게 만들 수 있도록 AIProjectClient 합니다. 프로젝트의 개요 페이지에서 프로젝트 세부 정보 아래에 프로젝트 연결 문자열 가져올 수 있습니다.
Azure Portal에서 Application Insights 리소스로 이동하고, 액세스 제어(IAM) 탭을 사용하여 이전에 만든 사용자 할당 관리 ID에 역할을 추가 Log Analytics Contributor 합니다.
사용자가 할당한 관리 ID를 프로젝트에 연결합니다.
Azure Portal에서 Azure AI Services로 이동하고 IAM(액세스 제어) 탭을 사용하여 이전에 만든 사용자 할당 관리 ID에 역할을 추가 Cognitive Services OpenAI Contributor 합니다.

설치 지침

사용자 자격 증명을 사용하여 Azure OpenAI 서비스를 호출할 수 있도록 Azure CLI를 설치하고 로컬 개발 환경에서 로그인합니다.

대부분의 경우 다음 명령을 사용하여 터미널에서 Azure CLI를 설치할 수 있습니다.

winget install -e --id Microsoft.AzureCLI

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

brew update && brew install azure-cli

특정 운영 체제나 설정에서 이러한 명령이 작동하지 않는 경우 Azure CLI 설치 방법 지침을 따를 수 있습니다.

Azure CLI를 설치한 후 az login 명령을 사용하여 로그인하고 브라우저를 사용하여 로그인합니다.

az login

또는 디바이스 코드를 사용하여 브라우저를 통해 수동으로 로그인할 수 있습니다.

az login --use-device-code

새 Python 환경 만들기

먼저 이 자습서에 필요한 패키지를 설치하는 데 사용할 새 Python 환경을 만들어야 합니다. 전역 Python 설치에 패키지를 설치하지 마세요. Python 패키지를 설치할 때 항상 가상 환경 또는 conda 환경을 사용해야 합니다. 그렇지 않으면 Python의 전역 설치가 중단될 수 있습니다.

필요한 경우 Python을 설치합니다.

Python 3.10 이상을 사용하는 것이 좋지만 Python 3.8 이상이 필요합니다. 적합한 Python 버전이 설치되어 있지 않은 경우 운영 체제에 Python을 설치하는 가장 쉬운 방법을 알아보려면 VS Code Python 자습서의 지침을 따릅니다.

가상 환경 만들기

이미 Python 3.10 이상이 설치되어 있는 경우 다음 명령을 사용하여 가상 환경을 만들 수 있습니다.

py -3 -m venv .venv
.venv\scripts\activate

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

Python 환경을 활성화한다는 것은 명령줄에서 python 또는 pip를 실행할 때 애플리케이션의 .venv 폴더에 포함된 Python 인터프리터를 사용하게 된다는 의미입니다.

참고 항목

deactivate 명령을 사용하여 Python 가상 환경을 종료하고 나중에 필요할 때 다시 활성화할 수 있습니다.

다음을 사용하여 conda새 Python 환경을 만들 수도 있습니다.

conda create -n online-evaluation
conda activate online-evaluation

필요한 패키지를 설치합니다.

pip install azure-identity azure-ai-projects azure-ai-ml

팁

필요에 따라 코드에서 기본 제공 계산기의 계산기 ID를 가져오는 코드 우선 환경을 원하는 경우에 사용할 pip install azure-ai-evaluation 수 있습니다. 이 작업을 수행하는 방법을 알아보려면 계산기 라이브러리에서 평가자 지정을 참조 하세요.

생성 AI 애플리케이션에 대한 추적 설정

온라인 평가를 설정하기 전에 먼저 생성 AI 애플리케이션에 대한 추적을 설정해야 합니다.

추적 데이터에 서비스 이름 사용

Application Insights에서 고유 ID를 통해 애플리케이션을 식별하려면 추적 데이터에서 서비스 이름 OpenTelemetry 속성을 사용할 수 있습니다. 이는 여러 애플리케이션에서 동일한 Application Insights 리소스로 데이터를 로깅하는 경우 특히 유용합니다. 예를 들어 동일한 Application Insights 리소스에 데이터를 기록하도록 추적이 구성된 App-1 및 App-2의 두 애플리케이션이 있다고 가정해 보겠습니다. 관련성 및 App-2에서 지속적으로 평가되도록 App-1을 설정하여 Groundedness에서 지속적으로 평가하려고 할 수 있습니다. 서비스 이름을 사용하여 온라인 평가 구성에서 애플리케이션을 구분할 수 있습니다.

서비스 이름 속성을 설정하려면 단계에 따라 애플리케이션 코드에서 직접 수행할 수 있습니다. 리소스가 다른 여러 추적 프로그램 공급자 사용을 참조하세요. 또는 앱을 배포하기 전에 환경 변수 OTEL_SERVICE_NAME 를 설정할 수 있습니다. 서비스 이름을 사용하는 방법에 대한 자세한 내용은 OTEL 환경 변수 및 서비스 리소스 의미 체계 규칙을 참조하세요.

서비스 이름을 사용하여 생성 AI 애플리케이션을 구분하는 방법에 대한 자세한 내용은 추적을 참조하세요.

Application Insights에서 저장된 추적 데이터 쿼리

KQL(Kusto 쿼리 언어)을 사용하여 Application Insights에서 생성 AI 애플리케이션의 추적 데이터를 쿼리하여 지속적인 온라인 평가에 사용할 수 있습니다. Azure AI 추적 패키지를 사용하여 생성 AI 애플리케이션을 추적하는 경우 다음 Kusto 쿼리를 사용할 수 있습니다.

Important

온라인 평가 서비스에서 사용하는 KQL 쿼리는 다음 열을 출력해야 합니다. operation_Idoperation_ParentIdgen_ai_response_id 또한 각 평가자에는 고유한 입력 데이터 요구 사항이 있습니다. KQL 쿼리는 평가자 자체에 대한 입력으로 사용할 이러한 열을 출력해야 합니다. 평가자에 대한 데이터 요구 사항 목록은 기본 제공 평가자에 대한 데이터 요구 사항을 참조 하세요.

let gen_ai_spans = (
    dependencies
    | where isnotnull(customDimensions["gen_ai.system"])
    | extend response_id = tostring(customDimensions["gen_ai.response.id"])
    | project id, operation_Id, operation_ParentId, timestamp, response_id
);
let gen_ai_events = (
    traces
    | where message in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
        or tostring(customDimensions["event.name"]) in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
    | project 
        id = operation_ParentId, 
        operation_Id, 
        operation_ParentId, 
        user_input = iff(
            message == "gen_ai.user.message" or tostring(customDimensions["event.name"]) == "gen_ai.user.message", 
            parse_json(iff(message == "gen_ai.user.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        system = iff(
            message == "gen_ai.system.message" or tostring(customDimensions["event.name"]) == "gen_ai.system.message", 
            parse_json(iff(message == "gen_ai.system.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        llm_response = iff(
            message == "gen_ai.choice", 
            parse_json(tostring(parse_json(tostring(customDimensions["gen_ai.event.content"])).message)).content, 
            iff(tostring(customDimensions["event.name"]) == "gen_ai.choice", parse_json(parse_json(message).message).content, "")
        )
    | summarize 
        operation_ParentId = any(operation_ParentId), 
        Input = maxif(user_input, user_input != ""), 
        System = maxif(system, system != ""), 
        Output = maxif(llm_response, llm_response != "") 
    by operation_Id, id
);
gen_ai_spans
| join kind=inner (gen_ai_events) on id, operation_Id
| project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id

생성 AI 애플리케이션에서 환경 변수를 사용하여 OTEL_SERVICE_NAME 서비스 이름을 설정하는 경우 KQL(Kusto) 쿼리에 cloud_RoleName 다음 줄을 추가하여 온라인 평가 일정 내에서 쿼리할 수 있습니다.

| where cloud_RoleName == "service_name"

필요에 따라 샘플 연산자를 사용하거나 Kusto 쿼리에서 연산자를 가져와 추적의 하위 집합만 반환할 수 있습니다. AI 지원 평가는 대규모로 비용이 많이 들 수 있으므로 이 방법을 사용하면 데이터의 무작위 샘플(또는 n 추적)만 평가하여 비용을 제어할 수 있습니다.

Azure AI Project SDK를 사용하여 온라인 평가 설정

Python API를 통해 Azure AI Project SDK를 사용하여 온라인 평가 예약 작업을 제출할 수 있습니다. 성능 및 품질(AI 지원) 평가자를 사용하여 온라인 평가를 설정하는 방법을 알아보려면 아래 스크립트를 참조하세요. 지원되는 평가기의 포괄적인 목록을 보려면 Azure AI 평가 SDK로 평가를 참조하세요. 사용자 지정 계산기를 사용하는 방법을 알아보려면 사용자 지정 평가자를 참조 하세요.

먼저 필요한 패키지를 가져오고 필요한 변수를 구성합니다.

from azure.ai.projects import AIProjectClient 
from azure.identity import DefaultAzureCredential 
from azure.ai.projects.models import ( 
    ApplicationInsightsConfiguration,
    EvaluatorConfiguration,
    EvaluationSchedule,
    RecurrenceTrigger,
)
from azure.ai.evaluation import CoherenceEvaluator 

# This sample includes the setup for an online evaluation schedule using the Azure AI Project SDK and Azure AI Evaluation SDK
# The schedule is configured to run daily over the collected trace data while running two evaluators: CoherenceEvaluator and RelevanceEvaluator
# This sample can be modified to fit your application's requirements

# Name of your online evaluation schedule
SAMPLE_NAME = "online_eval_name"

# Connection string to your Azure AI Foundry project
# Currently, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
PROJECT_CONNECTION_STRING = "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"

# Your Application Insights resource ID
APPLICATION_INSIGHTS_RESOURCE_ID = "appinsights_resource_id"

# Kusto Query Language (KQL) query to query data from Application Insights resource
# This query is compatible with data logged by the Azure AI Inferencing Tracing SDK (linked in documentation)
# You can modify it depending on your data schema
# The KQL query must output these required columns: operation_ID, operation_ParentID, and gen_ai_response_id
# You can choose which other columns to output as required by the evaluators you are using
KUSTO_QUERY = "let gen_ai_spans=(dependencies | where isnotnull(customDimensions[\"gen_ai.system\"]) | extend response_id = tostring(customDimensions[\"gen_ai.response.id\"]) | project id, operation_Id, operation_ParentId, timestamp, response_id); let gen_ai_events=(traces | where message in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") or tostring(customDimensions[\"event.name\"]) in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") | project id= operation_ParentId, operation_Id, operation_ParentId, user_input = iff(message == \"gen_ai.user.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.user.message\", parse_json(iff(message == \"gen_ai.user.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), system = iff(message == \"gen_ai.system.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.system.message\", parse_json(iff(message == \"gen_ai.system.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), llm_response = iff(message == \"gen_ai.choice\", parse_json(tostring(parse_json(tostring(customDimensions[\"gen_ai.event.content\"])).message)).content, iff(tostring(customDimensions[\"event.name\"]) == \"gen_ai.choice\", parse_json(parse_json(message).message).content, \"\")) | summarize operation_ParentId = any(operation_ParentId), Input = maxif(user_input, user_input != \"\"), System = maxif(system, system != \"\"), Output = maxif(llm_response, llm_response != \"\") by operation_Id, id); gen_ai_spans | join kind=inner (gen_ai_events) on id, operation_Id | project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id"

다음으로, 온라인 평가 일정을 실행하는 데 사용할 클라이언트 및 Azure OpenAI GPT 배포(예: GPT-4)를 정의합니다. 또한 Application Insights 리소스에 연결합니다.

# Connect to your Azure AI Foundry Project
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=PROJECT_CONNECTION_STRING
)

# Connect to your Application Insights resource 
app_insights_config = ApplicationInsightsConfiguration(
    resource_id=APPLICATION_INSIGHTS_RESOURCE_ID,
    query=KUSTO_QUERY
)

# Connect to your Azure OpenAI Service resource. You must use a GPT model deployment for this example.
deployment_name = "gpt-4"
api_version = "2024-08-01-preview"

# This is your Azure OpenAI Service connection name, which can be found in your Azure AI Foundry project under the 'Models + Endpoints' tab.
default_connection = project_client.connections._get_connection(
    "aoai_connection_name"
)

model_config = {
    "azure_deployment": deployment_name,
    "api_version": api_version,
    "type": "azure_openai",
    "azure_endpoint": default_connection.properties["target"]
}

다음으로 사용하려는 평가자를 구성합니다.

# RelevanceEvaluator
# id for each evaluator can be found in your Azure AI Foundry registry - please see documentation for more information
# init_params is the configuration for the model to use to perform the evaluation
# data_mapping is used to map the output columns of your query to the names required by the evaluator
relevance_evaluator_config = EvaluatorConfiguration(
    id="azureml://registries/azureml-staging/models/Relevance-Evaluator/versions/4",
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

# CoherenceEvaluator
coherence_evaluator_config = EvaluatorConfiguration(
    id=CoherenceEvaluator.id,
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

마지막으로 되풀이를 정의하고 일정을 만듭니다.

참고: 필수 구성 요소 단계에서 Application Insights 리소스에 대한 온라인 평가 일정을 인증하기 위해 사용자 할당 관리 ID를 만들었습니다. AzureMSIClientId 클래스의 properties 매개 변수는 EvaluationSchedule 이 ID의 clientId 매개 변수입니다.

# Frequency to run the schedule
recurrence_trigger = RecurrenceTrigger(frequency="day", interval=1)

# Dictionary of evaluators
evaluators = {
    "relevance": relevance_evaluator_config,
    "coherence" : coherence_evaluator_config
}

name = SAMPLE_NAME
description = f"{SAMPLE_NAME} description"
# AzureMSIClientId is the clientID of the User-assigned managed identity created during set-up - see documentation for how to find it
properties = {"AzureMSIClientId": "your_client_id"}

# Configure the online evaluation schedule
evaluation_schedule = EvaluationSchedule(
    data=app_insights_config,
    evaluators=evaluators,
    trigger=recurrence_trigger,
    description=description,
    properties=properties)

# Create the online evaluation schedule 
created_evaluation_schedule = project_client.evaluations.create_or_replace_schedule(name, evaluation_schedule)
print(f"Successfully submitted the online evaluation schedule creation request - {created_evaluation_schedule.name}, currently in {created_evaluation_schedule.provisioning_state} state.")

온라인 평가 일정에 따라 작업 수행

온라인 평가 구성 스크립트에 다음 코드를 추가하여 온라인 평가 일정을 가져와서 나열하고 사용하지 않도록 설정할 수 있습니다.

경고: 온라인 평가 일정을 만들고 API를 실행하는 동안 약간의 시간(~30초)을 get_schedule() 기다립니다.

온라인 평가 일정을 가져옵니다.

name = "<my-online-evaluation-name>"
get_evaluation_schedule = project_client.evaluations.get_schedule(name)

모든 온라인 평가 일정을 나열합니다.

count = 0
for evaluation_schedule in project_client.evaluations.list_schedule():
    count += 1
        print(f"{count}. {evaluation_schedule.name} "
        f"[IsEnabled: {evaluation_schedule.is_enabled}]")
        print(f"Total evaluation schedules: {count}")

온라인 평가 일정을 사용하지 않도록 설정(일시 삭제):

name = "<my-online-evaluation-name>"
project_client.evaluations.disable_schedule(name)

다음을 통해 공유

Azure AI Foundry SDK를 사용하여 온라인으로 평가를 실행하는 방법

온라인 평가 작동 방식

온라인 평가 설정

필수 조건

설치 지침

새 Python 환경 만들기

필요한 경우 Python을 설치합니다.

가상 환경 만들기

필요한 패키지를 설치합니다.

생성 AI 애플리케이션에 대한 추적 설정

추적 데이터에 서비스 이름 사용

Application Insights에서 저장된 추적 데이터 쿼리

Azure AI Project SDK를 사용하여 온라인 평가 설정

온라인 평가 일정에 따라 작업 수행

피드백

추가 리소스

다음을 통해 공유

Azure AI Foundry SDK를 사용하여 온라인으로 평가를 실행하는 방법

온라인 평가 작동 방식

온라인 평가 설정

필수 조건

설치 지침

Azure CLI 설치 및 로그인

새 Python 환경 만들기

필요한 경우 Python을 설치합니다.

가상 환경 만들기

필요한 패키지를 설치합니다.

생성 AI 애플리케이션에 대한 추적 설정

추적 데이터에 서비스 이름 사용

Application Insights에서 저장된 추적 데이터 쿼리

Azure AI Project SDK를 사용하여 온라인 평가 설정

온라인 평가 일정에 따라 작업 수행

관련 콘텐츠

피드백

추가 리소스