Un scorer est une définition abstraite de juge : un modèle, un template de prompt avec des variables et un type de sortie. Il indique comment juger, mais pas quoi juger ni d'où viennent les variables. Cette séparation permet de partager un même juge entre les évaluations hors ligne (notation d'enregistrements d'ensembles de données) et l'évaluation en ligne (notation de spans en production), chaque contexte fournissant ses propres entrées. Dans AI Studio, les scorers sont listés sous Évaluation → Les juges.
Un scorer ne s’exécute pas seul. Associez-le à une évaluation en direct pour noter les spans sélectionnés. L’évaluation en direct utilise une version précise du scorer et définit la correspondance de ses variables.
Le seul type de pipeline public est judge-v1, qui exécute un juge LLM. Le seul type de scorer disponible est llm_judge.
Anatomie
{
"name": "Helpfulness",
"description": "Rates how well the assistant answered.",
"kind": "llm_judge",
"config": {
"model": "mistral-small-latest",
"prompt_template": "You grade customer-support answers.\nScore 1 (useless) to 5 (fully resolves the question).\n\nProduct: {{ product }}",
"output_spec": { "type": "numeric", "min": 1, "max": 5 },
"params": { "temperature": 0, "random_seed": 42 }
}
}| Champ | Règles |
|---|---|
name | 1 à 200 caractères. Transformé en slug <slugified-name>-<8 hex>. |
description | Facultatif, jusqu'à 2 000 caractères. |
config.model | Tout modèle de chat que l'espace de travail peut appeler. |
config.prompt_template | Jinja2, jusqu'à 20 000 caractères. La syntaxe est vérifiée à l'enregistrement. |
config.output_spec | Voir Types de sortie. |
config.params | Facultatif : temperature (0 à 1,5), top_p (0 exclu à 1), max_tokens (≥ 0), random_seed (≥ 0). |
Ce que reçoit le modèle juge
Chaque évaluation correspond à un chat completion avec un seul message utilisateur : le rendu de votre prompt_template. Le juge ne voit que ce que le template rend ; pour juger la conversation, incluez-la via {{ transcript }} ou un mapping vers transcript, input_messages ou output_messages.
La réponse est contrainte par un schéma JSON strict dérivé de la spécification de résultat (output_spec). Le modèle renvoie un score ou un label, ainsi qu'une reason. La raison devient l'explanation du résultat.
Types de sortie
output_spec | Exemple | Champs de résultat |
|---|---|---|
{"type": "categorical", "labels": [...]} | ["good", "bad"] | score_label est l'un des labels. Les labels doivent être uniques et non vides. |
{"type": "numeric", "min": a, "max": b} | min: 1, max: 5 | score_value compris dans [min, max]. min ≤ max. |
{"type": "boolean"} | — | score_label vaut "true" ou "false". |
Pour les dashboards, préférez numeric : avg, p50 et les autres agrégations fonctionnent directement sur score_value. Pour un scorer catégoriel ou booléen, comptez plutôt les résultats groupés par score_label (voir Agrégation).
Variables du template
Chaque variable non déclarée dans le template (par exemple {{ product }}) devient une variable du scorer. La réponse du scorer les liste dans latest_version.variables. Une évaluation en direct décide avec quoi remplir chaque variable, via son mapping.
Certains noms sont toujours disponibles dans le template sans mapping et prennent le pas sur une valeur mappée portant le même nom :
| Nom | Valeur |
|---|---|
transcript | Les messages d'entrée et de sortie formatés, un par ligne, sous la forme role: text. |
attr("key") | La valeur de l'attribut de span key. |
format_input_transcript("key", …) | Formate un attribut de messages sous forme de messages d'entrée. |
format_output_transcript("key", …) | Formate un attribut de messages sous forme de messages de sortie. |
Une variable sans mapping et sans valeur sur le span reste non définie, et le template la rend vide. Utilisez {% if product %}…{% endif %} pour que le prompt reste propre lorsqu'un attribut est facultatif.
Les instructions autorisées sont if, for, set, with, filter, raw et autoescape. include, import, extends et macro ne sont pas disponibles.
Versions
Les scorers sont versionnés. La version 1 est créée en même temps que le scorer. PATCH /scorers/{slug} avec une config crée une nouvelle version uniquement si la config a réellement changé : les configs sont comparées via un hachage SHA-256 de leur JSON canonique. Modifier uniquement name ou description ne crée jamais de version.
:::warning Les évaluations en direct épinglent une version
Quand vous associez un scorer à une évaluation en direct, celle-ci copie la config de cette version du scorer dans sa config de pipeline. Les modifications ultérieures du scorer ne sont pas prises en compte automatiquement. Pour déployer une nouvelle version, mettez de nouveau à jour l'évaluation en direct avec ses definitions (PUT /pipelines/{id}). Le champ pipeline_configs[].scorer_version de la réponse indique quelle version chaque config exécute.
:::
La création d'un scorer n'est pas idempotente. Envoyer deux fois le même corps de requête crée deux scorers avec des slugs différents. Pour rendre un script idempotent, recherchez d'abord le scorer (GET /scorers?q=<name>), puis faites un PATCH.
Écrire un bon prompt de juge
- Indiquez quoi juger et quoi ignorer. « Ne jugez que si le dernier message de l'assistant répond à la dernière question de l'utilisateur ; ignorez le ton. »
- Définissez chaque label ou plage de score dans le prompt. Le schéma impose la forme de la sortie, pas son sens.
- Demandez une raison courte. C'est la seule explication affichée à côté du score.
- Testez-le avant de le déployer. Dans AI Studio, l'éditeur de juge peut exécuter le prompt sur des spans d'exemple avant que vous ne l'associiez à une évaluation en direct.