Executar avaliações na nuvem usando o SDK do Microsoft Foundry (clássico)

Exibição no momento:Versão do portal Foundry (clássico) - Alternar para a versão do novo portal Foundry

Neste artigo, você aprenderá a executar avaliações na nuvem (versão prévia) para testes de pré-implantação em um conjunto de dados de teste. O SDK de Avaliação de IA do Azure permite executar avaliações localmente em seu computador e na nuvem. Por exemplo, realize avaliações locais em um pequeno conjunto de dados de teste para avaliar os protótipos de aplicativos de IA generativa e, em seguida, proceda para o teste de pré-implantação para realizar avaliações em um grande conjunto de dados.

Use avaliações de nuvem para a maioria dos cenários, especialmente ao testar em escala, integrar avaliações em pipelines de CI/CD (integração contínua e entrega contínua) ou executar testes de pré-implantação. A execução de avaliações na nuvem elimina a necessidade de gerenciar a infraestrutura de computação local e dá suporte a fluxos de trabalho de teste automatizados em larga escala. Após a implantação, você pode optar por avaliar continuamente seus agentes para monitoramento pós-implantação.

Quando você usa o SDK do Foundry, ele registra os resultados da avaliação em seu projeto do Foundry para melhor observabilidade. Esse recurso dá suporte a todos os avaliadores incorporados da Microsoft. e seus próprios avaliadores personalizados. Seus avaliadores podem estar localizados na biblioteca do avaliador e ter o mesmo controle de acesso baseado em função e no escopo do projeto.

Pré-requisitos

• Um projeto do Foundry.
• Uma implantação Azure OpenAI com um modelo GPT que dá suporte à conclusão do chat (por exemplo, gpt-5-mini).
• Função de Usuário do Azure AI no projeto Foundry.
• Opcionalmente, você pode usar sua própria conta de armazenamento para executar avaliações.

Introdução

1. Instale o cliente de projeto do SDK do Microsoft Foundry para executar avaliações na nuvem:

   pip install azure-ai-projects azure-identity
   

2. Defina variáveis de ambiente para seus recursos do 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-5-mini
   
   # Optional: Reuse an existing dataset.
   dataset_name    = os.environ.get("DATASET_NAME",    "dataset-test")
   dataset_version = os.environ.get("DATASET_VERSION", "1.0")
   

3. Defina um cliente para executar avaliações na nuvem:

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

Preparar dados de entrada

# Upload a local JSONL file. Skip this step 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 saber mais sobre formatos de dados de entrada para avaliar aplicativos de IA generativos, confira:

• Dados de turno único
• Dados de conversa
• Dados conversacionais para imagens e multimodalidades

Para saber mais sobre os formatos de dados de entrada para avaliar agentes, consulte Evaluate Azure agentes de IA e Evaluate outros agentes.

Especificar avaliadores

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

Criar uma avaliação

Por fim, envie a avaliação 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)

Especificar avaliadores personalizados

Avaliadores personalizados baseados em código

Registre seus avaliadores personalizados no projeto do Hub de IA do Azure e busque as IDs do avaliador:

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

# Define ml_client to register the 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 the evaluator from the module.
from answer_len.answer_length import AnswerLengthEvaluator

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

# Specify the evaluator name that appears in the evaluator catalog.
evaluator_name = "AnswerLenEvaluator"

# Register the evaluator to the evaluator catalog.
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)

Depois de registrar o avaliador personalizado, exiba-o no catálogo do avaliador. Em seu projeto do Foundry, selecione Avaliação e, em seguida, selecione o catálogo do avaliador.

Avaliadores personalizados baseados em prompt

Siga este exemplo para registrar um FriendlinessEvaluator personalizado criado conforme descrito nos Avaliadores baseados em 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 the 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 the 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 the evaluator name that appears in the evaluator catalog.
evaluator_name = "FriendlinessEvaluator"

# Register the evaluator to the evaluator catalog.
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)

Depois de registrar o avaliador personalizado, você pode exibi-lo no catálogo do avaliador. Em seu projeto do Foundry, selecione Avaliação e, em seguida, selecione o catálogo do avaliador.

Obter resultados

Solucionando problemas

Conteúdo relacionado

• Avaliar seus aplicativos de IA generativos localmente
• Monitore seus aplicativos de IA generativa
• Saiba mais sobre como simular conjuntos de dados de teste para avaliação
• Confira os resultados da avaliação no portal do Foundry
• Introdução ao Foundry
• Comece com os exemplos de avaliação
• Documentação de referência da API REST