Tutoriel : Effectuer une évaluation à l'aide du client GenAI dans le SDK Vertex AI

Cette page vous explique comment évaluer vos modèles et applications d'IA générative pour différents cas d'utilisation à l'aide du client GenAI dans le SDK Vertex AI.

Le client GenAI du SDK Vertex AI pour le service d'évaluation de l'IA générative vous permet de mesurer les performances des requêtes, des modèles de fondation et des agents d'IA complexes par rapport aux critères les plus pertinents. Vous pouvez évaluer un nombre illimité de candidats à la fois pour affiner les requêtes, sélectionner le meilleur modèle ou itérer sur des agents complexes.

Voici ce que vous pouvez faire avec le client GenAI dans le SDK Vertex AI :

  • Comparez plusieurs modèles ou configurations côte à côte en une seule exécution, en utilisant des calculs de taux de victoire pour guider vos décisions.

  • Utilisez l'assistance intégrée pour évaluer et comparer les modèles tiers populaires sans intégrations complexes.

  • Gérez les grands ensembles de données plus efficacement et déchargez les tâches d'évaluation à grande échelle à l'aide de l'évaluation par lot asynchrone.

Exemple de bout en bout

Le client GenAI du SDK Vertex AI utilise un workflow en deux étapes : la génération des réponses du modèle et l'évaluation des réponses. L'exemple de bout en bout suivant montre comment fonctionne le client GenAI dans le SDK Vertex AI :

  1. Installez le SDK Vertex AI pour Python :

    pip install --upgrade google-cloud-aiplatform[evaluation]

  2. Préparez l'ensemble de données d'évaluation :

    import pandas as pd
from vertexai import Client, types

client = Client(project="your-project-id", location="us-central1")

prompts_df = pd.DataFrame({"prompt": ["How does AI work?"]})

  3. Exécutez l'évaluation :

    # Evaluating a single model.
eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
eval_result.show()

  4. Comparer plusieurs propositions :

    # Comparing multiple candidates.
candidate_1 = client.evals.run_inference(
    model="gemini-2.0-flash", src=prompts_df
)
candidate_2 = client.evals.run_inference(
    model="gemini-2.5-flash", src=prompts_df
)
comparison_result = client.evals.evaluate(
    dataset=[candidate_1, candidate_2],
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
comparison_result.show()

Définir votre métrique

Définissez vos métriques comme métriques basées sur un LLM ou métriques basées sur des calculs.

Métriques basées sur les LLM

Les métriques basées sur les LLM utilisent un grand modèle de langage (LLM) comme "juge" pour évaluer des critères nuancés tels que le style ou la qualité de l'écriture, qui sont difficiles à mesurer avec des algorithmes seuls.

Utiliser des métriques gérées basées sur des rubriques

Le client GenAI du SDK Vertex AI fournit diverses métriques basées sur des modèles prêts à l'emploi, comme GENERAL_QUALITY, SAFETY et INSTRUCTION_FOLLOWING. Vous pouvez y accéder via la classe RubricMetric. Les définitions de métriques basées sur des rubriques gérées sont chargées à la demande à partir d'une bibliothèque centralisée pour assurer la cohérence entre les versions de métriques basées sur des rubriques.

# Assumes 'eval_dataset' is an EvaluationDataset object created via run_inference()

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

Pour obtenir des résultats cohérents dans différentes versions du SDK, vous pouvez associer une métrique à une version spécifique. Par défaut, la dernière version est utilisée.

# Pin to a specific version of a pre-built metric
instruction_following_v1 = types.RubricMetric.INSTRUCTION_FOLLOWING(version='v1')

Personnaliser les métriques LLM

Pour les cas d'utilisation nécessitant des critères spécialisés, vous pouvez définir votre propre métrique basée sur un LLM en instanciant la classe LLMMetric. Vous avez ainsi un contrôle total sur le modèle de requête d'évaluation, le modèle d'évaluation et d'autres paramètres.

La classe d'assistance MetricPromptBuilder crée un modèle de requête structuré pour le modèle de juge en vous permettant de définir séparément les éléments instruction, criteria et rating_scores.

# Define a custom metric to evaluate language simplicity
simplicity_metric = types.LLMMetric(
    name='language_simplicity',
    prompt_template=types.MetricPromptBuilder(
        instruction="Evaluate the story's simplicity for a 5-year-old.",
        criteria={
            "Vocabulary": "Uses simple words.",
            "Sentences": "Uses short sentences.",
        },
        rating_scores={
            "5": "Excellent: Very simple, ideal for a 5-year-old.",
            "4": "Good: Mostly simple, with minor complex parts.",
            "3": "Fair: Mix of simple and complex; may be challenging for a 5-year-old.",
            "2": "Poor: Largely too complex, with difficult words/sentences.",
            "1": "Very Poor: Very complex, unsuitable for a 5-year-old."
        }
    )
)
# Use the custom metric in an evaluation
eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[simplicity_metric]
)

Métriques basées sur des calculs et des fonctions personnalisées

Les métriques basées sur des calculs comparent mathématiquement la sortie d'un modèle à une vérité terrain ou à une référence. Ces métriques, calculées avec du code à l'aide de la classe de base Metric, sont compatibles avec des algorithmes prédéfinis basés sur des calculs tels que exact_match, bleu et rouge_1. Pour utiliser une métrique basée sur le calcul, instanciez la classe Metric avec le nom de la métrique. La métrique nécessite une colonne reference dans votre ensemble de données pour la comparaison.

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)

Implémenter une métrique de fonction personnalisée

Vous pouvez également implémenter une logique d'évaluation personnalisée en transmettant une fonction Python personnalisée au paramètre custom_function pour un contrôle total. Le client GenAI du SDK Vertex AI exécute cette fonction pour chaque ligne de votre ensemble de données.

# Define a custom function to check for the presence of a keyword
def contains_keyword(instance: dict) -> dict:
    keyword = "magic"
    response_text = instance.get("response", "")
    score = 1.0 if keyword in response_text.lower() else 0.0
    return {"score": score}

keyword_metric = types.Metric(
    name="keyword_check",
    custom_function=contains_keyword
)


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[keyword_metric]
)

Préparer votre ensemble de données d'évaluation

Le client GenAI du SDK Vertex AI détecte et gère automatiquement plusieurs formats de données courants. Cela signifie que vous pouvez souvent utiliser vos données telles quelles, sans avoir à effectuer de conversions manuelles, que vous génériez de nouvelles réponses avec run_inference ou que vous évaluiez des réponses existantes avec evaluate.

Le client GenAI du SDK Vertex AI est compatible avec les formats suivants :

  • DataFrame pandas (format aplati)

    Pour les évaluations simples, vous pouvez utiliser un pandas.DataFrame. Le client GenAI du SDK Vertex AI recherche les noms de colonnes courants tels que prompt, response et reference. Ce format est entièrement rétrocompatible.

    import pandas as pd

# Simple DataFrame with prompts and ground truth references
prompts_df = pd.DataFrame({
    "prompt": [
        "What is the capital of France?",
        "Who wrote 'Hamlet'?",
    ],
    "reference": [
        "Paris",
        "William Shakespeare",
    ]
})

# Generate responses using the DataFrame as a source
inference_results = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df
)
inference_results.show()

  • Format des prédictions par lots Gemini

    Vous pouvez utiliser directement le résultat d'un job de prédiction par lot Vertex AI, qui se présente généralement sous la forme de fichiers JSONL stockés dans Cloud Storage, où chaque ligne contient un objet request et response. Le client GenAI du SDK Vertex AI analyse automatiquement cette structure pour permettre l'intégration à d'autres services Vertex AI.

    Voici un exemple de ligne dans un fichier jsonl :

    {"request": {"contents": [{"role": "user", "parts": [{"text": "Why is the sky blue?"}]}]}, "response": {"candidates": [{"content": {"role": "model", "parts": [{"text": "The sky appears blue to the human eye as a result of a phenomenon known as Rayleigh scattering."}]}}]}}

    Vous pouvez ensuite évaluer directement les réponses prégénérées d'un job par lot :

    # Cloud Storage path to your batch prediction output file
batch_job_output_uri = "gs://path/to/your/batch_output.jsonl"

# Evaluate the results directly from Cloud Storage
eval_result = client.evals.evaluate(
    dataset=batch_job_output_uri,
    metrics=[
        types.RubricMetric.COHERENCE,
        types.RubricMetric.FLUENCY,
    ]
)
eval_result.show()

  • Format OpenAI Chat Completion

    Pour évaluer des modèles tiers ou les comparer, le client GenAI du SDK Vertex AI est compatible avec le format OpenAI Chat Completion. Vous pouvez fournir un ensemble de données dans lequel chaque ligne est un objet JSON structuré comme une requête de l'API OpenAI. Le client GenAI du SDK Vertex AI détecte automatiquement ce format.

    Voici un exemple de ligne unique dans ce format :

    {"request": {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What's the capital of France?"}], "model": "gpt-4o"}}

    Vous pouvez utiliser ces données pour générer des réponses à partir d'un modèle tiers et évaluer les réponses :

    # Ensure your third-party API key is set
# e.g., os.environ['OPENAI_API_KEY'] = 'Your API Key'

openai_request_uri = "gs://path/to/your/openai_requests.jsonl"

# Generate responses using a LiteLLM-supported model string
openai_responses = client.evals.run_inference(
    model="gpt-4o",
    src=openai_request_uri,
)

# The resulting dataset can then be evaluated
eval_result = client.evals.evaluate(
    dataset=openai_responses,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.FLUENCY,
    ]
)

eval_result.show()

Évaluer

Le client GenAI du SDK Vertex AI utilise le processus client suivant pour exécuter des évaluations :

  1. run_inference() : générez des réponses à partir de votre modèle pour un ensemble donné de requêtes.

  2. evaluate() : calcule les métriques sur les réponses générées.

eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
src="gs://vertex-evaluation-llm-dataset-us-central1/genai_eval_sdk/test_prompts.jsonl",
)
eval_dataset.show()


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.QUESTION_ANSWERING_QUALITY,
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)
eval_result.show()

Pour analyser les performances de plusieurs modèles ou systèmes d'IA dans une même évaluation, générez une réponse pour chaque candidat et transmettez-les dans une liste à la méthode evaluate() :

inference_result_1 = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
)
inference_result_2 = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)

# Compare the responses against each other
comparison_result = client.evals.evaluate(
    dataset=[inference_result_1, inference_result_2],
    metrics=[
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

comparison_result.show()

Évaluation asynchrone et à grande échelle

Pour les grands ensembles de données, le client GenAI du SDK Vertex AI fournit une méthode d'évaluation par lot asynchrone de longue durée. Cette approche est idéale dans les scénarios où vous n'avez pas besoin de résultats immédiats et où vous souhaitez décharger le calcul.

La méthode batch_evaluate() renvoie un objet d'opération que vous pouvez interroger pour suivre sa progression. Les paramètres sont compatibles avec la méthode evaluate().

GCS_DEST_BUCKET = "gs://your-gcs-bucket/batch_eval_results/"

inference_result_saved = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
    config={'dest': GCS_DEST_BUCKET}
)
print(f"Eval dataset uploaded to: {inference_result_saved.gcs_source}")

batch_eval_job  = client.evals.batch_evaluate(
   dataset = inference_result_saved,
   metrics = [
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
        types.RubricMetric.FLUENCY,
        types.Metric(name='bleu'),
    ],
   dest=GCS_DEST_BUCKET
)

Évaluer des modèles tiers

Vous pouvez utiliser le client GenAI dans le SDK Vertex AI pour évaluer et comparer des modèles de fournisseurs tels qu'OpenAI en transmettant la chaîne du nom du modèle à la méthode run_inference. Le client GenAI du SDK Vertex AI utilise la bibliothèque litellm pour appeler l'API Model.

Assurez-vous de définir la clé API requise en tant que variable d'environnement (OPENAI_API_KEY) :

import os

# Set your third-party model API key
os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY'

# Run inference on an OpenAI model
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# You can now evaluate the responses
eval_result = client.evals.evaluate(
    dataset=gpt_response,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)

eval_result.show()

Visualisation

Le client GenAI du SDK Vertex AI vous permet de visualiser vos résultats directement dans votre environnement de développement, comme un notebook Colab ou Jupyter. La méthode .show(), disponible sur les objets EvaluationDataset et EvaluationResult, affiche un rapport HTML interactif pour l'analyse.

Visualiser les résultats de l'inférence

Après avoir généré des réponses avec run_inference(), vous pouvez appeler .show() sur l'objet EvaluationDataset résultant pour inspecter les sorties du modèle en même temps que vos requêtes et références d'origine. Cela permet de vérifier rapidement la qualité avant d'exécuter une évaluation complète.

# First, run inference to get an EvaluationDataset
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# Now, visualize the inference results
gpt_response.show()

Un tableau s'affiche avec chaque requête, sa référence correspondante (le cas échéant) et la réponse nouvellement générée.

Visualiser les résultats de l'inférence

Visualiser les rapports d'évaluation

Lorsque vous appelez .show() sur un objet EvaluationResult, un rapport s'affiche avec deux sections principales :

  • Métriques récapitulatives : vue agrégée de toutes les métriques, affichant le score moyen et l'écart-type pour l'ensemble de l'ensemble de données.

  • Résultats détaillés : une analyse au cas par cas, qui vous permet d'examiner la requête, la référence, la réponse candidate, ainsi que le score et l'explication spécifiques pour chaque métrique.

# First, run an evaluation on a single candidate
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.TEXT_QUALITY]
)

# Visualize the detailed evaluation report
eval_result.show()

Rapport d'évaluation

Le format du rapport s'adapte selon que vous évaluez un seul candidat ou que vous en comparez plusieurs. Pour une évaluation multicandidats, le rapport fournit une vue côte à côte et inclut des calculs du taux de victoire/égalité dans le tableau récapitulatif.

Pour tous les rapports, vous pouvez développer la section Afficher le JSON brut afin d'inspecter les données de toute requête ou réponse structurée.

Comparaison détaillée

Étapes suivantes