Ejecución de evaluaciones en la nube mediante el SDK de Azure AI Foundry (versión preliminar)

2025-05-20

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Aunque el SDK de evaluación de Azure AI admite la ejecución de evaluaciones localmente en su propia máquina, es posible que desee delegar el trabajo de forma remota en la nube. Por ejemplo, después de ejecutar evaluaciones locales sobre datos de prueba pequeños para ayudar a evaluar los prototipos de la aplicación de IA generativa, ahora pasa a las pruebas previas a la implementación y necesita ejecutar evaluaciones sobre un conjunto de datos grande. La evaluación en la nube le libera de administrar la infraestructura del proceso local y le permite integrar evaluaciones como pruebas en las canalizaciones de CI/CD. Después de la implementación, es posible que quiera evaluar continuamente las aplicaciones para la supervisión posterior a la implementación.

En este artículo, aprenderá a ejecutar evaluaciones en la nube (versión preliminar) en pruebas previas a la implementación en un conjunto de datos de prueba. Con el SDK de proyectos de Azure AI, los resultados de la evaluación se registrarán automáticamente en el proyecto de Azure AI para mejorar la observabilidad. Esta característica admite todos los evaluadores integrados mantenidos por Microsoft y sus propios evaluadores personalizados que se pueden encontrar en la biblioteca de evaluadores y tienen el mismo RBAC de ámbito de proyecto.

Pasos de configuración de requisitos previos para proyectos de Azure AI Foundry

Proyecto de Azure AI Foundry en las mismasregiones admitidas que los evaluadores de riesgos y seguridad (versión preliminar). Si no tiene un proyecto existente, siga la guía Creación de un proyecto de Azure AI Foundry para crear uno.
Implementación de Azure OpenAI con el modelo GPT compatible con chat completion, por ejemplo gpt-4.
Asegúrese de que ha iniciado sesión primero en la suscripción de Azure ejecutando az login.

Si esta es la primera vez que ejecuta evaluaciones y la registra en el proyecto de Azure AI Foundry, es posible que tenga que realizar algunos pasos de configuración adicionales.

Cree y conecte la cuenta de almacenamiento al proyecto de Azure AI Foundry en el nivel de recurso. Esta plantilla de Bicep aprovisiona y conecta una cuenta de almacenamiento al proyecto Foundry con autenticación de clave.
Asegúrese de que la cuenta de almacenamiento conectada tiene acceso a todos los proyectos.
Si ha conectado la cuenta de almacenamiento con el identificador de Entra de Microsoft, asegúrese de conceder permisos MSI (Identidad de Microsoft) para el propietario de datos de Storage Blob a su cuenta y al recurso del proyecto Foundry en Azure Portal.

Cómo empezar

En primer lugar, instale el cliente del proyecto del SDK de Azure AI Foundry que ejecuta las evaluaciones en la nube.

uv install azure-ai-projects azure-identity

Nota:

Para obtener información más detallada, consulte la documentación de referencia de la API rest. A continuación, establezca las variables de entorno para los recursos de 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")

Ahora puede definir un cliente que se usa para ejecutar las evaluaciones en la nube:

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(),
)

Carga de datos de evaluación

# 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

Para más información sobre los formatos de datos de entrada para evaluar aplicaciones de GenAI, consulte datos de un solo turno, datos de conversación y datos de conversación para imágenes y multimodalidades.

Para más información sobre los formatos de datos de entrada para evaluar agentes, consulte Evaluación de agentes de Azure AI y evaluación de otros agentes.

Especificación de evaluadores

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

Envío de la evaluación en la nube

Por último, envíe la ejecución de evaluación 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)

Especificación de evaluadores personalizados

Nota:

Los proyectos de Azure AI Foundry no están disponibles para esta función. En su lugar, use un proyecto de Azure AI Hub.

Evaluadores personalizados basados en código

Registre los evaluadores personalizados en el proyecto de Azure AI Hub y capture los identificadores del evaluador:

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)

Después de registrar el evaluador personalizado en el proyecto de Azure AI, puede verlo en la biblioteca de evaluadores en la pestaña Evaluación del proyecto de Azure AI.

Evaluadores personalizados basados en mensajes

Siga el ejemplo para registrar un personalizado creado FriendlinessEvaluator como se describe en Evaluadores basados en mensajes:

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

Después de registrar el evaluador personalizado en el proyecto de IA, puede verlo en la biblioteca de evaluadores en la pestaña Evaluación del proyecto de Azure AI.