Evaluaties online uitvoeren met de Azure AI Foundry SDK

Artikel
01/23/2025

Belangrijk

Items die in dit artikel zijn gemarkeerd (preview) zijn momenteel beschikbaar als openbare preview. Deze preview wordt aangeboden zonder een service level agreement en we raden deze niet aan voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.

In dit artikel leert u hoe u evaluaties online uitvoert met de Azure AI Foundry SDK. Evaluaties in preproductieomgevingen zijn essentieel om ervoor te zorgen dat uw toepassing veilig, goed presteert en resultaten van hoge kwaliteit produceert. Evaluatie stopt echter niet nadat uw toepassing is geïmplementeerd. In productie kunnen verschillende dingen veranderen, zoals de typen query's die gebruikers verzenden naar uw toepassing, wat de prestaties van uw toepassing kan beïnvloeden. Om een hoge mate van waarneembaarheid in uw productiegeneratieve AI-toepassing te behouden, is het belangrijk om de gegevens van uw toepassing te traceren en continu te evalueren. Door dit te doen, kunt u vertrouwen in de veiligheid, kwaliteit en prestaties van uw toepassing behouden.

Hoe online evaluatie werkt

In deze sectie leert u hoe online evaluatie werkt, hoe deze kan worden geïntegreerd met Azure Monitor Application Insights en hoe u deze kunt gebruiken om doorlopende evaluaties uit te voeren over traceringsgegevens van uw generatieve AI-toepassingen.

Nadat uw toepassing is geïnstrueerd om traceringsgegevens naar Application Insights te verzenden, stelt u een onlineevaluatieschema in om deze gegevens continu te evalueren. Online evaluatie is een service die Gebruikmaakt van Azure AI Compute om continu een configureerbare set evaluators uit te voeren. Nadat u een online evaluatieschema hebt ingesteld met de Azure AI Foundry SDK, wordt deze uitgevoerd volgens een configureerbaar schema. Telkens wanneer de geplande taak wordt uitgevoerd, worden de volgende stappen uitgevoerd:

Query's uitvoeren op toepassingstraceringsgegevens uit de verbonden Application Insights-resource met behulp van de opgegeven Kusto-query (KQL).
Voer elke evaluator uit op de traceringsgegevens en bereken elke metrische waarde (bijvoorbeeld geaardheid: 3).
Schrijf evaluatiescores terug naar elke trace met behulp van gestandaardiseerde semantische conventies.

Notitie

Online evaluatie ondersteunt dezelfde metrische gegevens als Azure AI-evaluatie. Zie Uw Generatieve AI-toepassing evalueren met de Azure AI Evaluation SDK voor meer informatie over hoe evaluatie werkt en welke metrische evaluatiegegevens worden ondersteund.

Stel dat u een geïmplementeerde chattoepassing hebt die dagelijks veel vragen van klanten ontvangt. U wilt continu de kwaliteit van de antwoorden van uw toepassing evalueren. U stelt een online evaluatieschema in met een dagelijks terugkeerpatroon. U configureert de evaluators: Groundedness, Coherence en Fluency. Elke dag berekent de service de evaluatiescores voor deze metrische gegevens en schrijft de gegevens terug naar Application Insights voor elke trace die is verzameld tijdens het terugkeertijdvenster (in dit voorbeeld de afgelopen 24 uur). Vervolgens kunnen de gegevens worden opgevraagd vanuit elke tracering en toegankelijk worden gemaakt in Azure AI Foundry en Azure Monitor Application Insights.

De evaluatieresultaten die worden teruggeschreven naar elke tracering binnen Application Insights, volgen de volgende conventies. Er wordt een unieke periode toegevoegd aan elke tracering voor elke metrische evaluatiewaarde:

Eigenschappen	Application Insights-tabel	Velden voor een bepaalde operation_ID	Voorbeeldwaarde
Metrische evaluatiegegevens	traceringen, AppTraces	`customDimensions[“event.name”]`	`gen_ai.evaluation.relevance`
Score voor metrische evaluatiegegevens	traceringen, AppTraces	`customDimensions[“gen_ai.evaluation.score”]`	`3`
Opmerking bij metrische evaluatiegegevens (indien van toepassing)	traceringen, AppTraces	`message`	`{“comment”: “I like the response”}`

Nu u begrijpt hoe online evaluatie werkt en hoe deze verbinding maakt met Azure Monitor Application Insights, is de volgende stap het instellen van de service.

Online evaluatie instellen

In deze sectie leert u hoe u een online evaluatieschema configureert om uw geïmplementeerde generatieve AI-toepassing continu te bewaken. Azure AI Foundry SDK biedt dergelijke mogelijkheden via. Een Python-API en ondersteunt alle functies die beschikbaar zijn in lokale evaluaties. Gebruik de volgende stappen om uw online evaluatieschema in te dienen voor uw gegevens met behulp van ingebouwde of aangepaste evaluators.

Notitie

Evaluaties worden alleen ondersteund in dezelfde regio's als metrische gegevens over ai-ondersteunde risico's en veiligheidsgegevens.

Vereisten

Voer de volgende vereiste stappen uit om uw omgeving en verificatie in te stellen op de benodigde resources:

Een Azure-abonnement.
Een resourcegroep in een regio die wordt ondersteund door evaluatie.
Een nieuwe door de gebruiker toegewezen beheerde identiteit in dezelfde resourcegroep en regio. Noteer de clientId; u hebt deze later nodig.
Een Azure AI Hub in dezelfde resourcegroep en regio.
Een Azure AI-project in deze hub, zie Een project maken in de Azure AI Foundry-portal.
Een Azure Monitor Application Insights-resource.
Navigeer naar de hubpagina in Azure Portal en voeg Application Insights-resource toe. Zie Update Azure-toepassing Insights en Azure Container Registry.
Azure OpenAI-implementatie met GPT-model dat ondersteuning biedt chat completion, bijvoorbeeld gpt-4.
Connection String voor Een Azure AI-project om eenvoudig een object te maken AIProjectClient . U kunt de Project-verbindingsreeks ophalen onder Projectdetails op de pagina Overzicht van het project.
Navigeer naar uw Application Insights-resource in Azure Portal en gebruik het tabblad Toegangsbeheer (IAM) om de Log Analytics Contributor rol toe te voegen aan de door de gebruiker toegewezen beheerde identiteit die u eerder hebt gemaakt.
Koppel de door de gebruiker toegewezen beheerde identiteit aan uw project.
Navigeer naar uw Azure AI Services in Azure Portal en gebruik het tabblad Toegangsbeheer (IAM) om de Cognitive Services OpenAI Contributor rol toe te voegen aan de door de gebruiker toegewezen beheerde identiteit die u eerder hebt gemaakt.

Installatie-instructies

U installeert de Azure CLI en meldt u zich aan vanuit uw lokale ontwikkelomgeving, zodat u uw gebruikersreferenties kunt gebruiken om de Azure OpenAI-service aan te roepen.

In de meeste gevallen kunt u de Azure CLI installeren vanuit uw terminal met behulp van de volgende opdracht:

winget install -e --id Microsoft.AzureCLI

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

brew update && brew install azure-cli

U kunt de instructies volgen voor het installeren van de Azure CLI als deze opdrachten niet werken voor uw specifieke besturingssysteem of installatie.

Nadat u de Azure CLI hebt geïnstalleerd, meldt u zich aan met behulp van de az login opdracht en meldt u zich aan met behulp van de browser:

az login

U kunt zich ook handmatig aanmelden via de browser met een apparaatcode.

az login --use-device-code

Een nieuwe Python-omgeving maken

Eerst moet u een nieuwe Python-omgeving maken om het pakket te installeren dat u nodig hebt voor deze zelfstudie. INSTALLEER GEEN pakketten in uw globale Python-installatie. U moet altijd een virtuele of conda-omgeving gebruiken bij het installeren van Python-pakketten, anders kunt u uw globale installatie van Python verbreken.

Installeer Python indien nodig

U wordt aangeraden Python 3.10 of hoger te gebruiken, maar python 3.8 is vereist. Als u geen geschikte versie van Python hebt geïnstalleerd, kunt u de instructies in de VS Code Python-zelfstudie volgen voor de eenvoudigste manier om Python op uw besturingssysteem te installeren.

Een virtuele omgeving maken

Als Python 3.10 of hoger al is geïnstalleerd, kunt u een virtuele omgeving maken met behulp van de volgende opdrachten:

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

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

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

Als u de Python-omgeving activeert, betekent dit dat wanneer u de opdrachtregel uitvoert python of pip vanaf de opdrachtregel de Python-interpreter gebruikt die zich in de .venv map van uw toepassing bevindt.

Notitie

U kunt de deactivate opdracht gebruiken om de virtuele Python-omgeving af te sluiten en deze later opnieuw te activeren wanneer dat nodig is.

U kunt ook een nieuwe Python-omgeving maken met behulp van conda:

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

Installeer de vereiste pakketten:

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

Tip

U kunt eventueel ook gebruiken als u een code-first-ervaring wilt gebruiken pip install azure-ai-evaluation om de evaluator-id op te halen voor ingebouwde evaluators in code. Zie Voor meer informatie over hoe u dit doet, het opgeven van evaluators uit de evaluatorbibliotheek.

Tracering instellen voor uw generatieve AI-toepassing

Voordat u online evaluatie instelt, moet u eerst tracering instellen voor uw generatieve AI-toepassing.

Servicenaam gebruiken in traceringsgegevens

Als u uw toepassing wilt identificeren via een unieke id in Application Insights, kunt u de eigenschap OpenTelemetry van de servicenaam in uw traceringsgegevens gebruiken. Dit is met name handig als u gegevens van meerdere toepassingen in dezelfde Application Insights-resource wilt vastleggen en u er onderscheid tussen wilt maken. Stel dat u twee toepassingen hebt: App-1 en App-2, waarbij tracering is geconfigureerd om gegevens te registreren bij dezelfde Application Insights-resource. Misschien wilt u App-1 instellen om continu te worden geëvalueerd op relevantie en app-2 om continu te worden geëvalueerd op basis van groundedness. U kunt de servicenaam gebruiken om onderscheid te maken tussen de toepassingen in uw online evaluatieconfiguraties.

Als u de eigenschap servicenaam wilt instellen, kunt u dit rechtstreeks in uw toepassingscode doen door de stappen te volgen. Zie Meerdere tracerproviders met verschillende resources gebruiken. U kunt ook de omgevingsvariabele OTEL_SERVICE_NAME instellen voordat u uw app implementeert. Zie omgevingsvariabelen en Semantische serviceresourceconventies voor meer informatie over het werken met de servicenaam.

Zie tracering voor meer informatie over het gebruik van de servicenaam om onderscheid te maken tussen uw generatieve AI-toepassingen.

Opgeslagen traceringsgegevens opvragen in Application Insights

Met behulp van de Kusto-querytaal (KQL) kunt u query's uitvoeren op de traceringsgegevens van uw AI-toepassing uit Application Insights om te gebruiken voor continue online evaluatie. Als u het Azure AI Tracing-pakket gebruikt om uw generatieve AI-toepassing te traceren, kunt u de volgende Kusto-query gebruiken:

Belangrijk

De KQL-query die door de online evaluatieservice wordt gebruikt, moet de volgende kolommen uitvoeren: operation_Id, operation_ParentIden gen_ai_response_id. Daarnaast heeft elke evaluator zijn eigen vereisten voor invoergegevens. De KQL-query moet deze kolommen uitvoeren om te worden gebruikt als invoer voor de evaluators zelf. Zie de gegevensvereisten voor ingebouwde evaluators voor een lijst met gegevensvereisten voor evaluators.

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

Als u de OTEL_SERVICE_NAME omgevingsvariabele in uw generatieve AI-toepassing gebruikt om de servicenaam in te stellen, kunt u een query uitvoeren op de cloud_RoleName serviceplanning binnen uw online evaluatieschema door de volgende regel toe te voegen aan uw Kusto-query (KQL):

| where cloud_RoleName == "service_name"

U kunt eventueel de voorbeeldoperator gebruiken of operator opnemen in uw Kusto-query, zodat er alleen een subset van traceringen wordt geretourneerd. Omdat ai-ondersteunde evaluaties kostbaar kunnen zijn op schaal, kan deze benadering u helpen bij het beheren van kosten door alleen een willekeurige steekproef (of n traceringen) van uw gegevens te evalueren.

Online evaluatie instellen met Azure AI Project SDK

U kunt een geplande online evaluatietaak indienen met de Azure AI Project SDK via een Python-API. Zie het onderstaande script voor meer informatie over het instellen van online evaluatie met ai-evaluatieprogramma's (prestaties en kwaliteit). Zie Evalueren met de Azure AI Evaluation SDK voor een uitgebreide lijst met ondersteunde evaluators. Zie aangepaste evaluators voor meer informatie over het gebruik van aangepaste evaluators.

Begin met het importeren van de vereiste pakketten en het configureren van de vereiste variabelen:

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"

Definieer vervolgens een client en een Azure OpenAI GPT-implementatie (zoals GPT-4) die wordt gebruikt om uw online evaluatieschema uit te voeren. Maak ook verbinding met uw Application Insights-resource:

# 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"]
}

Configureer vervolgens de evaluators die u wilt gebruiken:

# 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}"}
)

Definieer ten slotte het terugkeerpatroon en maak het schema:

Opmerking: In de vereiste stappen hebt u een door de gebruiker toegewezen beheerde identiteit gemaakt om het online evaluatieschema te verifiëren bij uw Application Insights-resource. De AzureMSIClientId parameter properties van de EvaluationSchedule klasse is de clientId van deze identiteit.

# 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.")

Bewerkingen uitvoeren volgens een online evaluatieschema

U kunt onlineevaluatieschema's ophalen, weergeven en uitschakelen door de volgende code toe te voegen aan uw online evaluatieconfiguratiescript:

Waarschuwing: wacht een kleine hoeveelheid tijd (~30 seconden) tussen het maken van een online evaluatieschema en het uitvoeren van de get_schedule() API.

Download een online evaluatieschema:

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

Alle online evaluatieschema's weergeven:

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}")

Online evaluatieschema uitschakelen (voorlopig verwijderen):

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

Delen via

Evaluaties online uitvoeren met de Azure AI Foundry SDK

Hoe online evaluatie werkt

Online evaluatie instellen

Vereisten

Installatie-instructies

Een nieuwe Python-omgeving maken

Installeer Python indien nodig

Een virtuele omgeving maken

Installeer de vereiste pakketten:

Tracering instellen voor uw generatieve AI-toepassing

Servicenaam gebruiken in traceringsgegevens

Opgeslagen traceringsgegevens opvragen in Application Insights

Online evaluatie instellen met Azure AI Project SDK

Bewerkingen uitvoeren volgens een online evaluatieschema

Feedback

Aanvullende resources

Delen via

Evaluaties online uitvoeren met de Azure AI Foundry SDK

Hoe online evaluatie werkt

Online evaluatie instellen

Vereisten

Installatie-instructies

De Azure CLI installeren en u aanmelden

Een nieuwe Python-omgeving maken

Installeer Python indien nodig

Een virtuele omgeving maken

Installeer de vereiste pakketten:

Tracering instellen voor uw generatieve AI-toepassing

Servicenaam gebruiken in traceringsgegevens

Opgeslagen traceringsgegevens opvragen in Application Insights

Online evaluatie instellen met Azure AI Project SDK

Bewerkingen uitvoeren volgens een online evaluatieschema

Gerelateerde inhoud

Feedback

Aanvullende resources