Eseguire valutazioni nel cloud usando Azure AI Foundry SDK (anteprima)

2025-05-20

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Anche se Azure AI Evaluation SDK supporta l'esecuzione di valutazioni in locale nel proprio computer, potrebbe essere necessario delegare il processo in modalità remota al cloud. Ad esempio, dopo aver eseguito valutazioni locali su dati di test di piccole dimensioni per valutare i prototipi di applicazioni di intelligenza artificiale generativi, ora si passa ai test di pre-distribuzione e sono necessarie valutazioni in un set di dati di grandi dimensioni. La valutazione cloud consente di gestire l'infrastruttura di calcolo locale e di integrare valutazioni come test nelle pipeline CI/CD. Dopo la distribuzione, è possibile valutare continuamente le applicazioni per il monitoraggio post-distribuzione.

Questo articolo illustra come eseguire valutazioni nel cloud (anteprima) nei test di pre-distribuzione in un set di dati di test. Usando Azure AI Projects SDK, i risultati della valutazione verranno registrati automaticamente nel progetto di intelligenza artificiale di Azure per migliorare l'osservabilità. Questa funzionalità supporta tutti gli analizzatori predefiniti curati da Microsoft e i propri analizzatori personalizzati che possono trovarsi nella libreria dell'analizzatore e hanno lo stesso controllo degli accessi in base al ruolo con ambito di progetto.

Passaggi di configurazione dei prerequisiti per i Progetti Foundry di Intelligenza Artificiale di Azure

Progetto Azure AI Foundry nelle stesse aree supportate degli analizzatori di rischi e sicurezza (anteprima). Se non si ha un progetto esistente, seguire la guida Come creare un progetto Azure AI Foundry per crearne uno.
Distribuzione OpenAI di Azure con il modello GPT che supporta chat completion, ad esempio gpt-4.
Assicurarsi di essere prima connessi alla sottoscrizione di Azure eseguendo az login.

Se questa è la prima volta che si eseguono valutazioni e la registrazione nel progetto Azure AI Foundry, potrebbe essere necessario eseguire alcuni passaggi di configurazione aggiuntivi.

Creare e connettere l'account di archiviazione al progetto Azure AI Foundry a livello di risorsa. Questo modello Bicep fornisce e connette un account di archiviazione al progetto Foundry con l'autenticazione tramite chiave.
Assicurarsi che l'account di archiviazione connesso abbia accesso a tutti i progetti.
Se hai collegato l'account di archiviazione a Microsoft Entra ID, assicurati di concedere le autorizzazioni MSI (Microsoft Identity) per "Storage Blob Data Owner" sia al tuo account che alla risorsa del progetto Foundry nel portale di Azure.

Come iniziare

Prima di tutto, installare il client di progetto di Azure AI Foundry SDK che esegue le valutazioni nel cloud

uv install azure-ai-projects azure-identity

Annotazioni

Per informazioni più dettagliate, vedere la documentazione di riferimento dell'API REST. Impostare quindi le variabili di ambiente per le risorse di Azure AI Foundry

import os

# Required environment variables
endpoint = os.environ["PROJECT_ENDPOINT"] # https://<account>.services.ai.azure.com/api/projects/<project>
model_endpoint = os.environ["MODEL_ENDPOINT"] # https://<account>.services.ai.azure.com
model_api_key = os.environ["MODEL_API_KEY"]
model_deployment_name = os.environ["MODEL_DEPLOYMENT_NAME"] # e.g. gpt-4o-mini

# Optional – reuse an existing dataset
dataset_name    = os.environ.get("DATASET_NAME",    "dataset-test")
dataset_version = os.environ.get("DATASET_VERSION", "1.0")

A questo punto è possibile definire un client usato per eseguire le valutazioni nel cloud:

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Create the project client (Foundry project and credentials)
project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

Caricamento dei dati di valutazione

# Upload a local jsonl file (skip if you already have a Dataset registered)
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Per altre informazioni sui formati di dati di input per la valutazione delle applicazioni GenAI, vedere Dati a turno singolo, dati di conversazione e dati di conversazione per immagini e più modalità.

Per altre informazioni sui formati di dati di input per la valutazione degli agenti, vedere Valutazione degli agenti di Intelligenza artificiale di Azure e valutazione di altri agenti.

Specificare i valutatori.

from azure.ai.projects.models import (
    EvaluatorConfiguration,
    EvaluatorIds,
)

# Built-in evaluator configurations
evaluators = {
    "relevance": EvaluatorConfiguration(
        id=EvaluatorIds.RELEVANCE.value,
        init_params={"deployment_name": model_deployment_name},
        data_mapping={
            "query": "${data.query}",
            "response": "${data.response}",
        },
    ),
    "violence": EvaluatorConfiguration(
        id=EvaluatorIds.VIOLENCE.value,
        init_params={"azure_ai_project": endpoint},
    ),
    "bleu_score": EvaluatorConfiguration(
        id=EvaluatorIds.BLEU_SCORE.value,
    ),
}

Inviare una valutazione nel cloud

Infine, inviare l'esecuzione della valutazione remota:

from azure.ai.projects.models import (
    Evaluation,
    InputDataset
)

# Create an evaluation with the dataset and evaluators specified
evaluation = Evaluation(
    display_name="Cloud evaluation",
    description="Evaluation of dataset",
    data=InputDataset(id=data_id),
    evaluators=evaluators,
)

# Run the evaluation 
evaluation_response = project_client.evaluations.create(
    evaluation,
    headers={
        "model-endpoint": model_endpoint,
        "api-key": model_api_key,
    },
)

print("Created evaluation:", evaluation_response.name)
print("Status:", evaluation_response.status)

Specifica di analizzatori personalizzati

Annotazioni

I progetti di Azure AI Foundry non sono supportati per questa funzionalità. Usare invece un progetto hub di intelligenza artificiale di Azure.

Analizzatori personalizzati basati su codice

Registrare gli analizzatori personalizzati nel progetto dell'hub di intelligenza artificiale di Azure e recuperare gli ID dell'analizzatore:

from azure.ai.ml import MLClient
from azure.ai.ml.entities import Model
from promptflow.client import PFClient

# Define ml_client to register custom evaluator
ml_client = MLClient(
       subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"],
       resource_group_name=os.environ["AZURE_RESOURCE_GROUP"],
       workspace_name=os.environ["AZURE_PROJECT_NAME"],
       credential=DefaultAzureCredential()
)

# Load evaluator from module
from answer_len.answer_length import AnswerLengthEvaluator

# Then we convert it to evaluation flow and save it locally
pf_client = PFClient()
local_path = "answer_len_local"
pf_client.flows.save(entry=AnswerLengthEvaluator, path=local_path)

# Specify evaluator name to appear in the Evaluator library
evaluator_name = "AnswerLenEvaluator"

# Finally register the evaluator to the Evaluator library
custom_evaluator = Model(
    path=local_path,
    name=evaluator_name,
    description="Evaluator calculating answer length.",
)
registered_evaluator = ml_client.evaluators.create_or_update(custom_evaluator)
print("Registered evaluator id:", registered_evaluator.id)
# Registered evaluators have versioning. You can always reference any version available.
versioned_evaluator = ml_client.evaluators.get(evaluator_name, version=1)
print("Versioned evaluator id:", registered_evaluator.id)

Dopo aver registrato l'analizzatore personalizzato nel progetto di Intelligenza artificiale di Azure, è possibile visualizzarlo nella libreria dell'analizzatore nella scheda Valutazione nel progetto di Intelligenza artificiale di Azure.

Analizzatori personalizzati basati su prompt

Seguire l'esempio per registrare una compilazione personalizzata FriendlinessEvaluator come descritto in Analizzatori basati su prompt:

# Import your prompt-based custom evaluator
from friendliness.friend import FriendlinessEvaluator

# Define your deployment 
model_config = dict(
    azure_endpoint=os.environ.get("AZURE_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_DEPLOYMENT_NAME"),
    api_version=os.environ.get("AZURE_API_VERSION"),
    api_key=os.environ.get("AZURE_API_KEY"), 
    type="azure_openai"
)

# Define ml_client to register custom evaluator
ml_client = MLClient(
       subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"],
       resource_group_name=os.environ["AZURE_RESOURCE_GROUP"],
       workspace_name=os.environ["AZURE_PROJECT_NAME"],
       credential=DefaultAzureCredential()
)

# # Convert evaluator to evaluation flow and save it locally
local_path = "friendliness_local"
pf_client = PFClient()
pf_client.flows.save(entry=FriendlinessEvaluator, path=local_path) 

# Specify evaluator name to appear in the Evaluator library
evaluator_name = "FriendlinessEvaluator"

# Register the evaluator to the Evaluator library
custom_evaluator = Model(
    path=local_path,
    name=evaluator_name,
    description="prompt-based evaluator measuring response friendliness.",
)
registered_evaluator = ml_client.evaluators.create_or_update(custom_evaluator)
print("Registered evaluator id:", registered_evaluator.id)
# Registered evaluators have versioning. You can always reference any version available.
versioned_evaluator = ml_client.evaluators.get(evaluator_name, version=1)
print("Versioned evaluator id:", registered_evaluator.id)

Dopo aver effettuato la registrazione dell'analizzatore personalizzato nel progetto di Intelligenza artificiale di Azure, è possibile visualizzarlo nella libreria dell'analizzatore nella scheda Valutazione del progetto di Intelligenza artificiale di Azure.