> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Aperçu des évaluations
> Développement d'applications LLM piloté par l'évaluation pour améliorer systématiquement les applications
*Le développement d'applications LLM piloté par l'évaluation* vous aide à améliorer systématiquement vos applications LLM en mesurant leur comportement de manière cohérente à l'aide d'exemples sélectionnés avec soin.
Ce guide vous montre comment configurer et exécuter des évaluations dans Weave afin de mesurer les performances de votre application LLM à l'aide de cas de test reproductibles, de comparer les modifications au fil du temps et d'identifier les régressions. Il s'adresse aux développeurs qui créent des applications LLM et qui veulent dépasser les tests ponctuels pour adopter un flux de travail structuré et mesurable.
Dans Weave, l'*objet `Evaluation`* est au cœur du flux de travail et définit :
* Un [`Dataset`](../core-types/datasets) ou une liste de dictionnaires pour les exemples de test.
* Une ou plusieurs [fonctions de scoring](../evaluation/scorers).
* Une configuration facultative, comme le [prétraitement des entrées](#format-dataset-rows-before-evaluating).
Une fois l'`Evaluation` définie, vous pouvez l'exécuter sur un objet [`Model`](../core-types/models) ou sur toute fonction personnalisée contenant la logique de l'application LLM. Chaque appel à `.evaluate()` déclenche un *run d'évaluation*. Considérez l'objet `Evaluation` comme un plan, et chaque run comme une mesure des performances de votre application dans cette configuration.
Dans Weave, l'*objet `Evaluation`* est au cœur du flux de travail et définit :
* Un [`Dataset`](../core-types/datasets) ou un tableau d'objets pour les exemples de test.
* Une ou plusieurs [fonctions de scoring](../evaluation/scorers).
Une fois l'`Evaluation` définie, vous pouvez l'exécuter sur n'importe quelle fonction encapsulée avec `weave.op`. Chaque appel à `.evaluate()` déclenche un *run d'évaluation*. Considérez l'objet `Evaluation` comme un plan, et chaque run comme une mesure des performances de votre application dans cette configuration.
Le SDK TypeScript utilise des modèles et des scorers basés sur des fonctions. Les types `Model` et `Scorer` basés sur des classes ne sont pas encore disponibles en TypeScript.
Pour commencer avec les évaluations, suivez les étapes suivantes :
1. [Créer un objet `Evaluation`](#create-an-evaluation-object)
2. [Définir un jeu de données d'exemples](#define-a-dataset-of-test-examples)
3. [Définir des fonctions de scoring](#define-scoring-functions)
4. [Définir un modèle ou une fonction à évaluer](#define-a-model-or-function-to-evaluate)
5. [Exécuter l'évaluation](#run-the-evaluation)
Après avoir suivi ces étapes, vous disposerez d'une configuration d'évaluation réutilisable et d'un run d'évaluation dont vous pourrez inspecter les résultats dans l'interface Weave. Pour un exemple complet de code d'évaluation, consultez l'[exemple complet de code d'évaluation](#full-evaluation-code-example). Vous pouvez aussi en apprendre davantage sur les [fonctionnalités avancées d'évaluation](#advanced-evaluation-usage), comme les [vues enregistrées](#saved-views) et les [évaluations impératives](#imperative-evaluations-evaluationlogger).
## Créer un objet `Evaluation`
La création d’un objet `Evaluation` est la première étape pour définir votre configuration d’évaluation. Une `Evaluation` se compose de données d’exemple, d’une logique d’évaluation et d’un prétraitement facultatif. Vous l’utiliserez ensuite pour exécuter une ou plusieurs évaluations.
Weave prend chaque exemple, le fait passer par votre application et attribue un score au résultat à l’aide de plusieurs fonctions de scoring personnalisées. Vous disposez ainsi d’une vue d’ensemble des performances de votre application, ainsi que d’une UI riche pour examiner en détail les résultats et les scores individuels.
Le nommage personnalisé est facultatif, mais il vous aide à distinguer différentes configurations d’évaluation et différents runs dans l’interface Weave. Si vous n’avez qu’une seule évaluation, vous pouvez ignorer cette section.
### Facultatif : nommage personnalisé
Il existe deux types de noms personnalisables dans le flux d’évaluation :
* [*Nom de l’objet `Evaluation`* (`evaluation_name`)](#name-the-evaluation-object) : un libellé persistant pour votre objet `Evaluation` configuré.
* [*Nom d’affichage d’un run d’évaluation* (`__weave["display_name"]`)](#name-individual-evaluation-runs) : un libellé pour une exécution d’évaluation donnée, affiché dans l’interface utilisateur.
#### Nommer l’objet `Evaluation`
Pour nommer l’objet `Evaluation` lui-même, passez un paramètre `evaluation_name` à la classe `Evaluation`. Ce nom vous aide à identifier l’objet `Evaluation` dans le code et dans les listes de l’interface utilisateur.
```python lines theme={null}
evaluation = Evaluation(
dataset=examples, scorers=[match_score1], evaluation_name="My Evaluation"
)
```
#### Nommer des runs d’évaluation individuels
Pour nommer un run d’évaluation spécifique (un appel à `evaluate()`), utilisez le dictionnaire `__weave` avec un `display_name`. Cela détermine ce qui est affiché dans l’interface utilisateur pour ce run.
```python lines theme={null}
evaluation = Evaluation(
dataset=examples, scorers=[match_score1]
)
evaluation.evaluate(model, __weave={"display_name": "My Evaluation Run"})
```
Pour nommer l’objet `Evaluation`, passez un paramètre `id` au constructeur `Evaluation`. Ce nom vous aide à identifier l’objet `Evaluation` dans le code et dans les listes de l’interface utilisateur.
```typescript twoslash lines theme={null}
// @noErrors
const evaluation = new weave.Evaluation({
id: 'my-evaluation',
dataset: dataset,
scorers: [matchScore],
});
```
## Définir un jeu de données d'exemples de test
Commencez par définir un objet [Dataset](../core-types/datasets) ou une liste d'exemples, c'est-à-dire une collection d'exemples à évaluer. Ces exemples correspondent souvent à des cas d'échec que vous souhaitez tester, à la manière de tests unitaires en développement piloté par les tests (TDD).
L'exemple suivant montre un jeu de données défini comme une liste de dictionnaires :
```python lines theme={null}
examples = [
{"question": "What is the capital of France?", "expected": "Paris"},
{"question": "Who wrote 'To Kill a Mockingbird'?", "expected": "Harper Lee"},
{"question": "What is the square root of 64?", "expected": "8"},
]
```
L'exemple suivant montre un jeu de données défini comme un objet `Dataset` avec un tableau de lignes :
```typescript twoslash lines theme={null}
// @noErrors
const dataset = new weave.Dataset({
id: 'my-dataset',
rows: [
{question: 'What is the capital of France?', expected: 'Paris'},
{question: 'Who wrote "To Kill a Mockingbird"?', expected: 'Harper Lee'},
{question: 'What is the square root of 64?', expected: '8'},
],
});
```
## Définir des fonctions de score
Ensuite, créez une ou plusieurs [fonctions de score](../evaluation/scorers). Weave les utilise pour attribuer un score à chaque exemple du `Dataset`.
Chaque fonction de score doit avoir un paramètre `output` et renvoyer un dictionnaire contenant les scores. Vous pouvez aussi inclure d'autres entrées issues de vos exemples.
Les fonctions de score doivent avoir un argument mot-clé `output`, mais les autres arguments sont définis par l'utilisateur et proviennent des exemples du jeu de données. Weave ne prend en compte que les clés nécessaires, à partir d'une clé de dictionnaire basée sur le nom de l'argument.
Si votre scorer attend un argument `output` mais ne le reçoit pas, vérifiez s'il utilise encore l'ancienne clé `model_output`. Pour corriger cela, mettez à jour votre fonction scorer afin d'utiliser `output` comme argument mot-clé.
L'exemple de fonction scorer `match_score1` ci-dessous utilise la valeur `expected` du dictionnaire `examples` pour le scoring :
```python lines theme={null}
import weave
# Rassemblez vos exemples
examples = [
{"question": "What is the capital of France?", "expected": "Paris"},
{"question": "Who wrote 'To Kill a Mockingbird'?", "expected": "Harper Lee"},
{"question": "What is the square root of 64?", "expected": "8"},
]
# Définissez une fonction de score personnalisée
@weave.op()
def match_score1(expected: str, output: dict) -> dict:
# C'est ici que vous définiriez la logique pour évaluer la sortie du modèle
return {'match': expected == output['generated_text']}
```
### Facultatif : Définir une classe `Scorer` personnalisée
Dans certaines applications, vous pouvez vouloir créer des classes `Scorer` personnalisées. Par exemple, une classe `LLMJudge` standardisée peut être créée avec des paramètres spécifiques (par exemple, modèle de chat, prompt), une logique de scoring propre à chaque ligne et un calcul spécifique du score agrégé.
Voir le tutoriel sur la définition d'une classe `Scorer` dans [Model-Based Evaluation of RAG applications](/fr/weave/tutorial-rag#optional-defining-a-scorer-class) pour plus d'informations.
Chaque fonction de score est encapsulée dans `weave.op` et reçoit un objet avec les propriétés `modelOutput` et `datasetRow`.
L'exemple de fonction scorer `matchScore` ci-dessous compare la sortie du modèle à la valeur `expected` de la ligne du jeu de données :
```typescript twoslash lines theme={null}
// @noErrors
import * as weave from 'weave';
// Rassemblez vos exemples dans un jeu de données
const dataset = new weave.Dataset({
id: 'my-dataset',
rows: [
{question: 'What is the capital of France?', expected: 'Paris'},
{question: 'Who wrote "To Kill a Mockingbird"?', expected: 'Harper Lee'},
{question: 'What is the square root of 64?', expected: '8'},
],
});
// Définissez une fonction de score personnalisée
const matchScore = weave.op(
({modelOutput, datasetRow}) => {
return {match: modelOutput === datasetRow.expected};
},
{name: 'matchScore'}
);
```
Les types `Scorer` basés sur des classes ne sont pas encore disponibles en TypeScript. Utilisez des scorers basés sur des fonctions encapsulés dans `weave.op`.
## Définissez un modèle ou une fonction à évaluer
Pour évaluer un `Model`, appelez `.evaluate()` avec une `Evaluation`. Utilisez des objets `Model` lorsque vous avez des paramètres que vous souhaitez tester et capturer dans Weave.
```python lines theme={null}
from weave import Model, Evaluation
import asyncio
class MyModel(Model):
prompt: str
@weave.op()
def predict(self, question: str):
# c'est ici que vous ajouteriez votre appel au LLM et renverriez le résultat
return {'generated_text': 'Hello, ' + self.prompt}
model = MyModel(prompt='World')
evaluation = Evaluation(
dataset=examples, scorers=[match_score1]
)
weave.init('intro-example') # commencer le suivi des résultats avec Weave
asyncio.run(evaluation.evaluate(model))
```
Cela exécute `predict` sur chaque exemple et attribue un score au résultat avec chaque fonction d'évaluation.
### Facultatif : Définissez une fonction à évaluer
Vous pouvez également évaluer une fonction personnalisée suivie avec `@weave.op()` :
```python lines theme={null}
@weave.op
def function_to_evaluate(question: str):
# c'est ici que vous ajouteriez votre appel au LLM et renverriez le résultat
return {'generated_text': 'some response'}
asyncio.run(evaluation.evaluate(function_to_evaluate))
```
En TypeScript, vous évaluez des fonctions encapsulées avec `weave.op`. La fonction reçoit une ligne du jeu de données et renvoie la sortie du modèle.
```typescript twoslash lines theme={null}
// @noErrors
import * as weave from 'weave';
// Initialiser Weave
await weave.init('intro-example');
// Définir la fonction à évaluer
const myModel = weave.op(
async ({question}) => {
// c'est ici que vous ajouteriez votre appel au LLM et renverriez le résultat
return 'Paris';
},
{name: 'myModel'}
);
// Créer l'évaluation
const evaluation = new weave.Evaluation({
id: 'my-evaluation',
dataset: dataset,
scorers: [matchScore],
});
// Exécuter l'évaluation
const results = await evaluation.evaluate({model: myModel});
```
Cela exécute `myModel` sur chaque exemple et attribue un score au résultat avec chaque fonction d'évaluation.
## Lancez l’évaluation
Avec votre objet `Evaluation`, le jeu de données, les évaluateurs et le modèle définis, vous êtes prêt à exécuter l’évaluation et à capturer les résultats dans Weave. Pour lancer une évaluation, appelez `.evaluate()` sur l’objet `Evaluation`.
En supposant un objet `Evaluation` nommé `evaluation` et un objet `Model` à évaluer nommé `model`, le code suivant lance un run d’évaluation.
```python lines theme={null}
asyncio.run(evaluation.evaluate(model))
```
### Facultatif : Exécuter plusieurs essais
Vous pouvez définir le paramètre `trials` sur l’objet `Evaluation` pour exécuter chaque exemple plusieurs fois.
```python lines theme={null}
evaluation = Evaluation(
dataset=examples,
scorers=[match_score],
trials=3
)
```
En supposant un objet `Evaluation` nommé `evaluation` et une fonction de modèle nommée `myModel`, le code suivant lance l’évaluation.
```typescript twoslash lines theme={null}
// @noErrors
const results = await evaluation.evaluate({model: myModel});
```
### Facultatif : Exécuter plusieurs essais
Vous pouvez définir le paramètre `nTrials` lors de l’appel à `evaluate()` pour exécuter chaque exemple plusieurs fois.
```typescript twoslash lines theme={null}
// @noErrors
const results = await evaluation.evaluate({
model: myModel,
nTrials: 3,
});
```
Le run transmet chaque exemple au modèle trois fois, et Weave attribue un score à chaque run et l’affiche indépendamment.
## Exemple complet de code d’évaluation
L’exemple suivant rassemble chacune des étapes précédentes dans un script unique et exécutable. Utilisez-le comme référence lorsque vous adaptez le flux de travail d’évaluation à votre propre application.
L’exemple de code suivant montre un run d’évaluation complet, du début à la fin. La liste `examples` est utilisée par les fonctions de score `match_score1` et `match_score2` pour évaluer `MyModel` à partir de la valeur de `prompt`, ainsi qu’une fonction personnalisée `function_to_evaluate`. Les exécutions d’évaluation du `Model` et de la fonction sont lancées avec `asyncio.run(evaluation.evaluate())`.
```python lines theme={null}
from weave import Evaluation, Model
import weave
import asyncio
weave.init('intro-example')
examples = [
{"question": "What is the capital of France?", "expected": "Paris"},
{"question": "Who wrote 'To Kill a Mockingbird'?", "expected": "Harper Lee"},
{"question": "What is the square root of 64?", "expected": "8"},
]
@weave.op()
def match_score1(expected: str, output: dict) -> dict:
return {'match': expected == output['generated_text']}
@weave.op()
def match_score2(expected: dict, output: dict) -> dict:
return {'match': expected == output['generated_text']}
class MyModel(Model):
prompt: str
@weave.op()
def predict(self, question: str):
# c'est ici que vous ajouteriez votre appel LLM et renverriez le résultat
return {'generated_text': 'Hello, ' + question + self.prompt}
model = MyModel(prompt='World')
evaluation = Evaluation(dataset=examples, scorers=[match_score1, match_score2])
asyncio.run(evaluation.evaluate(model))
@weave.op()
def function_to_evaluate(question: str):
# c'est ici que vous ajouteriez votre appel LLM et renverriez le résultat
return {'generated_text': 'some response' + question}
asyncio.run(evaluation.evaluate(function_to_evaluate("What is the capitol of France?")))
```
L’exemple de code suivant montre un run d’évaluation complet, du début à la fin. Les lignes du jeu de données sont utilisées par la fonction de score `matchScore` pour évaluer `myModel`.
```typescript twoslash lines theme={null}
// @noErrors
import * as weave from 'weave';
// Initialiser Weave
await weave.init('intro-example');
// Regrouper vos exemples dans un dataset
const dataset = new weave.Dataset({
id: 'my-dataset',
rows: [
{question: 'What is the capital of France?', expected: 'Paris'},
{question: 'Who wrote "To Kill a Mockingbird"?', expected: 'Harper Lee'},
{question: 'What is the square root of 64?', expected: '8'},
],
});
// Définir les fonctions de score
const matchScore = weave.op(
({modelOutput, datasetRow}) => {
return {match: modelOutput === datasetRow.expected};
},
{name: 'matchScore'}
);
// Définir la fonction à évaluer
const myModel = weave.op(
async ({question}) => {
// c'est ici que vous ajouteriez votre appel LLM et renverriez le résultat
return 'Paris';
},
{name: 'myModel'}
);
// Créer et exécuter l’évaluation
const evaluation = new weave.Evaluation({
id: 'my-evaluation',
dataset: dataset,
scorers: [matchScore],
});
const results = await evaluation.evaluate({model: myModel});
console.log('Evaluation results:', results);
```
## Utilisation avancée de l’évaluation
Les sections suivantes présentent des fonctionnalités facultatives pour des flux de travail d’évaluation plus complexes, notamment le prétraitement des jeux de données, l’intégration de jeux de données tiers, les vues enregistrées dans l’interface utilisateur et une API de journalisation impérative.
### Formater les lignes du jeu de données avant d’évaluer
Weave applique la fonction `preprocess_model_input` uniquement aux entrées avant leur transmission à la fonction de prédiction du modèle. Les fonctions d’évaluateur reçoivent toujours l’exemple original du jeu de données, sans prétraitement.
Le paramètre `preprocess_model_input` vous permet de transformer les exemples de votre jeu de données avant qu’ils ne soient transmis à votre fonction d’évaluation. Cela est utile lorsque vous devez :
* Renommer des champs pour qu’ils correspondent aux entrées attendues par votre modèle.
* Transformer les données dans le bon format.
* Ajouter ou supprimer des champs.
* Charger des données supplémentaires pour chaque exemple.
Voici un exemple montrant comment utiliser `preprocess_model_input` pour renommer des champs :
```python lines theme={null}
import weave
from weave import Evaluation
import asyncio
# Notre jeu de données contient "input_text" mais notre modèle attend "question"
examples = [
{"input_text": "What is the capital of France?", "expected": "Paris"},
{"input_text": "Who wrote 'To Kill a Mockingbird'?", "expected": "Harper Lee"},
{"input_text": "What is the square root of 64?", "expected": "8"},
]
@weave.op()
def preprocess_example(example):
# Renommer input_text en question
return {
"question": example["input_text"]
}
@weave.op()
def match_score(expected: str, output: dict) -> dict:
return {'match': expected == output['generated_text']}
@weave.op()
def function_to_evaluate(question: str):
return {'generated_text': f'Answer to: {question}'}
# Créer l’évaluation avec prétraitement
evaluation = Evaluation(
dataset=examples,
scorers=[match_score],
preprocess_model_input=preprocess_example
)
# Exécuter l’évaluation
weave.init('preprocessing-example')
asyncio.run(evaluation.evaluate(function_to_evaluate))
```
Dans cet exemple, le jeu de données contient des exemples avec un champ `input_text`, mais la fonction d’évaluation attend un paramètre `question`. La fonction `preprocess_example` transforme chaque exemple en renommant ce champ, ce qui permet à l’évaluation de fonctionner correctement.
La fonction de prétraitement :
1. Reçoit l’exemple brut de votre jeu de données.
2. Renvoie un dictionnaire contenant les champs attendus par votre modèle.
3. S’exécute sur chaque exemple avant que Weave ne le transmette à votre fonction d’évaluation.
Cela est utile lorsque vous travaillez avec des jeux de données externes dont les noms de champs ou les structures diffèrent de ce qu’attend votre modèle.
En TypeScript, vous pouvez utiliser `columnMapping` sur l’objet `Evaluation` pour faire correspondre les noms de colonnes du jeu de données aux noms attendus par vos évaluateurs. Cela est utile lorsque votre jeu de données utilise des noms de champs différents de ceux attendus par vos fonctions d’évaluateur.
L’exemple suivant fait correspondre la colonne `expectedOutputTimesTwo` à la colonne `expected` :
```typescript twoslash lines theme={null}
// @noErrors
const myScorer = weave.op(
({modelOutput, datasetRow}) => {
return modelOutput * 2 === datasetRow.expectedOutputTimesTwo;
},
{name: 'myScorer'}
);
const evaluation = new weave.Evaluation({
id: 'my-evaluation',
dataset: [{expected: 2}],
scorers: [myScorer],
columnMapping: {expectedOutputTimesTwo: 'expected'},
});
```
Le paramètre `preprocess_model_input` n’est pas encore disponible en TypeScript. Utilisez `columnMapping` pour faire correspondre les champs du jeu de données aux attentes des évaluateurs.
### Utiliser des jeux de données HuggingFace avec les évaluations
Vous pouvez utiliser `preprocess_model_input` comme solution de contournement pour utiliser des jeux de données HuggingFace dans les évaluations Weave.
Voir le [cookbook sur l’utilisation de jeux de données HuggingFace dans les évaluations](/fr/weave/cookbooks/hf_dataset_evals) pour plus de détails.
```text theme={null}
Cette fonctionnalité n’est pas disponible en TypeScript.
```
### Vues enregistrées
Vous pouvez enregistrer les configurations, filtres et tris de votre tableau Evals sous forme de *vues enregistrées* afin d'accéder rapidement à la configuration de votre choix. Vous pouvez configurer les vues enregistrées et y accéder dans l'interface utilisateur ainsi qu'avec le SDK Python. Pour plus d'informations, voir [Vues enregistrées](/fr/weave/guides/tools/saved-views).
### Évaluations impératives (`EvaluationLogger`)
Si vous préférez un framework d'évaluation plus souple, voir [`EvaluationLogger`](../evaluation/evaluation_logger) de Weave. `EvaluationLogger` est disponible en Python et en TypeScript, et offre davantage de flexibilité pour les flux de travail complexes, tandis que le framework d'évaluation standard apporte plus de structure et d'encadrement.