Vous pouvez utiliser le module d'évaluation de l'IA générative du SDK Vertex AI pour Python pour évaluer par programmation vos modèles et applications de langage génératif avec l'API Gen AI Evaluation Service. Cette page vous explique comment exécuter des évaluations avec le SDK Vertex AI. Notez que les évaluations à grande échelle ne sont disponibles qu'avec l'API REST.
Avant de commencer
Installez le SDK Vertex AI
Pour installer le module d'évaluation de l'IA générative à partir du SDK Vertex AI pour Python, exécutez la commande suivante :
!pip install -q google-cloud-aiplatform[evaluation]
Pour en savoir plus, consultez la section Installer le SDK Vertex AI pour Python.
Authentifier le SDK Vertex AI
Après avoir installé le SDK Vertex AI pour Python, vous devez vous authentifier. Les rubriques suivantes expliquent comment s'authentifier auprès du SDK Vertex AI si vous travaillez en local et dans Colaboratory :
Si vous développez en local, configurez les identifiants par défaut de l'application dans votre environnement local:
Installez Google Cloud CLI, puis initialisez-la en exécutant la commande suivante :
gcloud initCréez des identifiants d'authentification locaux pour votre compte Google :
gcloud auth application-default loginUn écran de connexion s'affiche. Une fois que vous êtes connecté, vos identifiants sont stockés dans le fichier d'identifiants local utilisé par ADC. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local.
Si vous travaillez dans Colaboratory, exécutez la commande suivante dans une cellule Colab pour vous authentifier :
from google.colab import auth auth.authenticate_user()Cette commande ouvre une fenêtre dans laquelle vous pouvez terminer l'authentification.
Comprendre les comptes de service
Le compte de service est utilisé par le service d'évaluation de l'IA générative pour obtenir des prédictions auprès de l'API Gemini dans Vertex AI pour les métriques d'évaluation basées sur un modèle. Ce compte de service est automatiquement provisionné lors de la première requête adressée au service d'évaluation de l'IA générative.
| Nom | Description | Adresse e-mail | Rôle |
|---|---|---|---|
| Agent de service d'évaluation rapide Vertex AI | Compte de service utilisé pour obtenir des prédictions pour l'évaluation basée sur un modèle. | service-PROJECT_NUMBER@gcp-sa-vertex-eval.iam.gserviceaccount.com |
roles/aiplatform.rapidevalServiceAgent |
Les autorisations associées à l'agent de service d'évaluation rapide sont les suivantes:
| Rôle | Autorisations |
|---|---|
| Agent de service d'évaluation rapide Vertex AI (roles/aiplatform.rapidevalServiceAgent) | aiplatform.endpoints.predict |
Exécuter votre évaluation
Utilisez la classe EvalTask pour exécuter des évaluations dans les cas d'utilisation suivants :
Classe EvalTask
La classe EvalTask vous aide à évaluer des modèles et des applications en fonction de tâches spécifiques. Pour effectuer des comparaisons équitables entre les modèles génératifs, vous devez généralement évaluer à plusieurs reprises de nombreux modèles et modèles de requêtes sur un ensemble de données d'évaluation fixe à l'aide de métriques spécifiques. Il est également important d'évaluer plusieurs métriques simultanément dans une seule exécution d'évaluation.
EvalTask s'intègre également à Vertex AI Experiments pour vous aider à suivre les configurations et les résultats de chaque exécution d'évaluation. Vertex AI Experiments vous aide à gérer et à interpréter les résultats d'évaluation, ce qui vous permet de prendre des décisions éclairées.
L'exemple suivant montre comment instancier la classe EvalTask et exécuter une évaluation :
from vertexai.evaluation import (
EvalTask,
PairwiseMetric,
PairwiseMetricPromptTemplate,
PointwiseMetric,
PointwiseMetricPromptTemplate,
MetricPromptTemplateExamples，
)
eval_task = EvalTask(
dataset=DATASET,
metrics=[METRIC_1, METRIC_2, METRIC_3],
experiment=EXPERIMENT_NAME,
)
eval_result = eval_task.evaluate(
model=MODEL,
prompt_template=PROMPT_TEMPLATE,
experiment_run=EXPERIMENT_RUN,
)
Exécuter l'évaluation avec des métriques basées sur un modèle
Pour les métriques basées sur un modèle, utilisez les classes PointwiseMetric et PairwiseMetric pour définir des métriques adaptées à vos critères spécifiques. Exécutez des évaluations à l'aide des options suivantes :
Utiliser des exemples de métriques basées sur un modèle
Vous pouvez utiliser directement la constante intégrée Metric Prompt Template Examples dans le SDK Vertex AI. Vous pouvez également les modifier et les intégrer dans l'interface de définition de métriques en forme libre.
Pour obtenir la liste complète des exemples de modèles de requête de métrique couvrant la plupart des cas d'utilisation clés, consultez la page Modèles de requête de métrique.
Console
Lorsque vous exécutez des évaluations dans un notebook Colab Enterprise, vous pouvez accéder aux modèles d'invite de métrique directement depuis la console Google Cloud .
Cliquez sur le lien du notebook Gen AI Evaluation Service de votre choix.
Le notebook s'ouvre dans GitHub. Cliquez sur Ouvrir dans Colab Enterprise. Si une boîte de dialogue vous invite à activer des API, cliquez sur Activer.
Cliquez sur l'icône Gen AI Evaluation dans la barre latérale. Le panneau Modèles de métriques prédéfinis s'ouvre.
Sélectionnez des métriques pointwise ou pairwise.
Cliquez sur la métrique que vous souhaitez utiliser, comme Fluidité. L'exemple de code pour la métrique s'affiche.
Cliquez sur Copier pour copier l'exemple de code. Si vous le souhaitez, cliquez sur Personnaliser pour modifier les champs prédéfinis de la métrique.
Collez l'exemple de code dans votre notebook.
SDK Vertex AI
L'exemple du SDK Vertex AI suivant montre comment utiliser la classe MetricPromptTemplateExamples pour définir vos métriques :
# View all the available examples of model-based metrics
MetricPromptTemplateExamples.list_example_metric_names()
# Display the metric prompt template of a specific example metric
print(MetricPromptTemplateExamples.get_prompt_template('fluency'))
# Use the pre-defined model-based metrics directly
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=[MetricPromptTemplateExamples.Pointwise.FLUENCY],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Utiliser une interface modélisée de métrique basée sur un modèle
Personnalisez vos métriques en remplissant des champs tels que Criteria et Rating Rubrics à l'aide des classes PointwiseMetricPromptTemplate et PairwiseMetricPromptTemplate du SDK Vertex AI. Une valeur par défaut est attribuée à certains champs, tels que Instruction, si vous ne fournissez aucune entrée.
Vous pouvez éventuellement spécifier input_variables, qui est une liste de champs de saisie utilisés par le modèle de requête de métrique pour générer des résultats d'évaluation basés sur un modèle. Par défaut, la colonne response du modèle est incluse pour les métriques par point, et les colonnes response et baseline_model_response du modèle candidat sont incluses pour les métriques par paire.
Pour en savoir plus, consultez la section "Structurer un modèle de requête de métrique" dans Modèles de requête de métrique.
# Define a pointwise metric with two custom criteria
custom_text_quality = PointwiseMetric(
metric="custom_text_quality",
metric_prompt_template=PointwiseMetricPromptTemplate(
criteria={
"fluency": "Sentences flow smoothly and are easy to read, avoiding awkward phrasing or run-on sentences. Ideas and sentences connect logically, using transitions effectively where needed.",
"entertaining": "Short, amusing text that incorporates emojis, exclamations and questions to convey quick and spontaneous communication and diversion.",
},
rating_rubric={
"1": "The response performs well on both criteria.",
"0": "The response is somewhat aligned with both criteria",
"-1": "The response falls short on both criteria",
},
input_variables=["prompt"],
),
)
# Display the serialized metric prompt template
print(custom_text_quality.metric_prompt_template)
# Run evaluation using the custom_text_quality metric
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=[custom_text_quality],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Utiliser l'interface du SDK de forme libre de métrique basée sur un modèle
Pour personnaliser plus facilement le modèle de requête de métrique, vous pouvez définir une métrique directement à l'aide de l'interface de forme libre, qui accepte une entrée sous forme de chaîne directe.
# Define a pointwise multi-turn chat quality metric
pointwise_chat_quality_metric_prompt = """Evaluate the AI's contribution to a meaningful conversation, considering coherence, fluency, groundedness, and conciseness.
Review the chat history for context. Rate the response on a 1-5 scale, with explanations for each criterion and its overall impact.
# Conversation History
{history}
# Current User Prompt
{prompt}
# AI-generated Response
{response}
"""
freeform_multi_turn_chat_quality_metric = PointwiseMetric(
metric="multi_turn_chat_quality_metric",
metric_prompt_template=pointwise_chat_quality_metric_prompt,
)
# Run evaluation using the freeform_multi_turn_chat_quality_metric metric
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=[freeform_multi_turn_chat_quality_metric],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Évaluer un modèle de traduction
Pour évaluer votre modèle de traduction, vous pouvez spécifier BLEU, MetricX ou COMET comme métriques d'évaluation lorsque vous utilisez le SDK Vertex AI.
#Prepare the dataset for evaluation.
sources = [
"Dem Feuer konnte Einhalt geboten werden",
"Schulen und Kindergärten wurden eröffnet.",
]
responses = [
"The fire could be stopped",
"Schools and kindergartens were open",
]
references = [
"They were able to control the fire.",
"Schools and kindergartens opened",
]
eval_dataset = pd.DataFrame({
"source": sources,
"response": responses,
"reference": references,
})
# Set the metrics.
metrics = [
"bleu",
pointwise_metric.Comet(),
pointwise_metric.MetricX(),
]
eval_task = evaluation.EvalTask(
dataset=eval_dataset,
metrics=metrics,
)
eval_result = eval_task.evaluate()
Exécuter l'évaluation avec des métriques issues de calculs
Vous pouvez utiliser des métriques issues de calculs de façon autonome ou avec des métriques basées sur un modèle.
# Combine computation-based metrics "ROUGE" and "BLEU" with model-based metrics
eval_task = EvalTask(
dataset=EVAL_DATASET,
metrics=["rouge_l_sum", "bleu", custom_text_quality],
)
eval_result = eval_task.evaluate(
model=MODEL,
)
Exécuter des évaluations à grande échelle
Si vous disposez d'ensembles de données d'évaluation volumineux ou si vous exécutez régulièrement des évaluations dans un environnement de production, vous pouvez utiliser l'API EvaluateDataset dans le service d'évaluation de l'IA générative pour exécuter des évaluations à grande échelle.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_NUMBER : Numéro de votre projet.
- DATASET_URI : chemin d'accès Cloud Storage à un fichier JSONL contenant des instances d'évaluation. Chaque ligne du fichier doit représenter une seule instance, avec des clés correspondant aux champs d'entrée définis par l'utilisateur dans
metric_prompt_template(pour les métriques basées sur des modèles) ou aux paramètres d'entrée requis (pour les métriques basées sur des calculs). Vous ne pouvez spécifier qu'un seul fichier JSONL. L'exemple suivant est une ligne pour une instance d'évaluation par point :{"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."} - METRIC_SPEC : une ou plusieurs spécifications de métriques que vous utilisez pour l'évaluation. Vous pouvez utiliser les spécifications de métriques suivantes lorsque vous exécutez des évaluations à grande échelle :
"pointwise_metric_spec","pairwise_metric_spec","exact_match_spec","bleu_spec"et"rouge_spec". - METRIC_SPEC_FIELD_NAME : champs obligatoires pour la spécification de métrique choisie. Par exemple,
"metric_prompt_template" - METRIC_SPEC_FIELD_CONTENT : contenu du champ pour la spécification de métrique choisie. Par exemple, vous pouvez utiliser le contenu de champ suivant pour une évaluation ponctuelle :
"Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent." - OUTPUT_BUCKET : nom du bucket Cloud Storage dans lequel vous souhaitez stocker les résultats de l'évaluation.
Méthode HTTP et URL :
POST https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset
Corps JSON de la requête :
{
"dataset": {
"gcs_source": {
"uris": "DATASET_URI"
}
},
"metrics": [
{
METRIC_SPEC: {
METRIC_SPEC_FIELD_NAME: METRIC_SPEC_FIELD_CONTENT
}
}
],
"output_config": {
"gcs_destination": {
"output_uri_prefix": "OUTPUT_BUCKET"
}
}
}
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset"
PowerShell
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON semblable à la suivante.
Vous pouvez utiliser l'identifiant OPERATION_ID que vous recevez dans la réponse pour demander l'état de l'évaluation :
curl -X GET \ -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/operations/OPERATION_ID"
Personnalisation supplémentaire des métriques
Si vous devez personnaliser davantage vos métriques, par exemple en choisissant un autre modèle d'évaluation pour les métriques basées sur un modèle, ou en définissant une nouvelle métrique basée sur le calcul, vous pouvez utiliser la classe CustomMetric dans le SDK Vertex AI. Pour en savoir plus, consultez les notebooks suivants :
Exécuter une évaluation basée sur un modèle avec des limites de débit et des quotas plus élevés
Une seule requête d'évaluation pour une métrique basée sur un modèle entraîne plusieurs requêtes sous-jacentes à l'API Gemini dans Vertex AI et consomme le quota du modèle d'évaluation. Vous devez définir une limite de débit de service d'évaluation plus élevée dans les cas d'utilisation suivants :
Volume de données accru : si vous traitez beaucoup plus de données à l'aide des métriques basées sur des modèles, vous risquez d'atteindre le quota de requêtes par minute (RPM) par défaut. L'augmentation du quota vous permet de gérer le volume plus important sans dégradation des performances ni interruption.
Évaluation plus rapide : si votre application nécessite un délai d'évaluation plus court, vous aurez peut-être besoin d'un quota RPM plus élevé. Cela est particulièrement important pour les applications sensibles au temps ou pour celles qui impliquent des interactions en temps réel, où les retards d'évaluation peuvent avoir un impact sur l'expérience utilisateur.
Tâches d'évaluation complexes : un quota RPM plus élevé vous garantit une capacité suffisante pour gérer les évaluations gourmandes en ressources pour les tâches complexes ou les grandes quantités de texte.
Utilisateurs simultanés nombreux : si vous prévoyez qu'un grand nombre d'utilisateurs vont demander simultanément des évaluations basées sur un modèle et des inférences de modèle dans votre projet, il est essentiel d'augmenter la limite de RPM du modèle pour éviter les goulots d'étranglement et maintenir la réactivité.
Si vous utilisez le modèle de juge par défaut gemini-2.0-flash ou des modèles plus récents, nous vous recommandons d'utiliser le débit provisionné pour gérer votre quota.
Pour les modèles plus anciens que gemini-2.0-flash, suivez les instructions ci-dessous pour augmenter le quota de RPM du modèle d'évaluation :
Dans la console Google Cloud , accédez à la page Quotas de IAM et administration.
Dans le champ Filtre, spécifiez la dimension (identifiant du modèle) et la métrique (identifiant de quota pour les modèles Gemini) :
base_model:gemini-2.0-flashetMetric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model.Pour le quota que vous souhaitez augmenter, cliquez sur le bouton du menu Autres actions.
Dans le menu déroulant, cliquez sur Modifier le quota. Le panneau Modifications de quotas s'ouvre.
Sous Modifier le quota, saisissez une nouvelle valeur de quota.
Cliquez sur Envoyer la requête.
Une demande d'augmentation de quota est confirmée par e-mail et est généralement traitée sous deux jours ouvrés.
Pour exécuter une évaluation à l'aide d'un nouveau quota, définissez le paramètre evaluation_service_qps comme suit :
from vertexai.evaluation import EvalTask
# GEMINI_RPM is the requests per minute (RPM) quota for gemini-2.0-flash-001 in your region
# Evaluation Service QPS limit is equal to (gemini-2.0-flash-001 RPM / 60 sec / default number of samples)
CUSTOM_EVAL_SERVICE_QPS_LIMIT = GEMINI_RPM / 60 / 4
eval_task = EvalTask(
dataset=DATASET,
metrics=[METRIC_1, METRIC_2, METRIC_3],
)
eval_result = eval_task.evaluate(
evaluation_service_qps=CUSTOM_EVAL_SERVICE_QPS_LIMIT,
# Specify a retry_timeout limit for a more responsive evaluation run
# the default value is 600 (in seconds, or 10 minutes)
retry_timeout=RETRY_TIMEOUT,
)
Pour en savoir plus sur les quotas et les limites, consultez les pages Quotas de Gen AI Evaluation Service et API Gen AI Evaluation Service.
Étapes suivantes
Recherchez un modèle de métriques basées sur un modèle.
Essayez un exemple de notebook d'évaluation.